# 🔌 Guía de Integración y Conectividad para Desarrolladores Externos

Bienvenido al portal de desarrollo de **Eduplanner**. Si eres un desarrollador externo, administrador de TI, o estás integrando un Sistema de Gestión de Aprendizaje (LMS) como **Moodle, Canvas, Blackboard o Google Classroom**, esta guía te explicará cómo conectar tus sistemas con el motor pedagógico y los datos de Eduplanner.

---

## 🔑 1. Autenticación y Credenciales

Toda petición realizada a los endpoints de la API de Eduplanner o directamente a la base de datos debe estar autenticada. Eduplanner utiliza **tokens JWT (JSON Web Tokens)** gestionados por Supabase para asegurar que cada petición pertenezca a un docente o institución válidos.

### Cómo obtener tus credenciales de integración:
1. **Acceso Institucional**: Si tu escuela cuenta con un plan institucional, tu administrador de TI puede generar un token de integración desde el panel de **Ajustes de Desarrollador** en Eduplanner.
2. **Acceso de Socio / API Key**: Si necesitas un acceso dedicado para un desarrollo a gran escala, ponte en contacto con nuestro equipo técnico en [soporte@plannners.com.mx](mailto:soporte@plannners.com.mx) para dar de alta tu aplicación y recibir tus credenciales sandbox y de producción.

### Formato de Autenticación
Debes incluir el token obtenido en la cabecera HTTP de cada petición utilizando el esquema `Bearer`:

```http
Authorization: Bearer <TU_JWT_TOKEN>
```

---

## 🛰️ 2. Arquitectura de Conexión: APIs Híbridas

Para ofrecer el máximo rendimiento y flexibilidad, Eduplanner implementa un modelo de integración híbrido:

```mermaid
graph TD
    A[Tu Aplicación / LMS] -->|POST Generación IA| B[Eduplanner REST API v1]
    A -->|GET / CRUD Datos Estructurados| C[Supabase Direct REST API]
    B -->|Procesa con Vertex AI| D[Modelos Gemini 2.5]
    C -->|Políticas RLS en Tiempo Real| E[(Base de Datos Postgres)]
    B -->|Guarda Resultados| E
```

### A. Servicios de Generación Pedagógica (Eduplanner API)
* **Base URL**: `https://eduplanner.vercel.app/api`
* Se utiliza exclusivamente para flujos que requieren **inteligencia artificial** (ej. crear planeaciones, exámenes estructurados, rúbricas analíticas, Kahoot y reportes SEP).
* Estos endpoints procesan tus datos pedagógicos, los enriquecen mediante modelos avanzados (como **Gemini 2.5 Pro**) y devuelven el contenido listo para guardarse.

### B. Consulta de Datos y CRUD (Supabase Direct API)
* **Base URL**: `https://[TU_PROJECT_ID].supabase.co/rest/v1`
* Para recuperar listas de planeaciones guardadas, expedientes de alumnos, rúbricas creadas y configuraciones de grupos, te conectarás **directamente a la API de base de datos**.
* **Ventajas**: Consultas ultrarrápidas (sub-100ms), soporte nativo de filtros, paginación y ordenamiento sin capas intermedias, protegidos por **Row Level Security (RLS)** usando el mismo token del usuario.

---

## 💻 3. Ejemplos de Implementación

### A. Generar una Planeación Didáctica (NEM/CIME) mediante IA
Realiza una petición `POST` al endpoint `/v1/planeaciones` (o `/v1/ai/execute` para flujos dinámicos).

#### Petición en cURL:
```bash
curl -X POST https://eduplanner.vercel.app/api/v1/planeaciones \
  -H "Authorization: Bearer <TU_TOKEN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fracciones equivalentes para tercer grado de primaria",
    "metodologia": "NEM",
    "nivelDetalle": "detallado",
    "tipoSecuencia": "semanal",
    "contexto": {
      "grado": "3"
    }
  }'
```

#### Respuesta de la API (JSON Estructurado):
```json
{
  "data": {
    "titulo": "Explorando las Fracciones Equivalentes",
    "metodologia": "NEM",
    "proposito": "Que los alumnos identifiquen y representen fracciones equivalentes...",
    "secuencia": [
      {
        "sesion": 1,
        "actividades": "Introducción con material concreto...",
        "recursos": ["Hojas de colores", "Tijeras"],
        "evaluacion": "Observación directa y rúbrica formativa"
      }
    ]
  }
}
```

---

### B. Recuperar Planeaciones Guardadas (Directo desde la Base de Datos)
Para obtener el historial de planeaciones creadas por el docente autenticado, puedes consumir directamente la API REST del cliente Supabase.

#### Petición en JavaScript (usando el SDK de Supabase):
```javascript
import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://[PROJECT_ID].supabase.co', '[ANON_KEY]')

// La biblioteca enviará automáticamente las cabeceras RLS
async function obtenerPlaneaciones(tokenUsuario) {
  const { data, error } = await fetch('https://[PROJECT_ID].supabase.co/rest/v1/planeaciones?select=*&order=created_at.desc', {
    headers: {
      'Authorization': `Bearer ${tokenUsuario}`,
      'apikey': '[ANON_KEY]'
    }
  }).then(res => res.json());

  return data;
}
```

---

## 🛠️ 4. Códigos de Estado y Errores

Nuestra API se adhiere a los códigos de estado estándar de HTTP:

| Código | Estado | Descripción |
| :--- | :--- | :--- |
| `200` | **OK** | La solicitud fue exitosa y los datos son devueltos. |
| `400` | **Bad Request** | La estructura del cuerpo (JSON) es incorrecta o faltan parámetros obligatorios. |
| `401` | **Unauthorized** | El token JWT proporcionado es inválido, expiró o no se incluyó. |
| `403` | **Forbidden** | El token es válido, pero no tienes permisos para acceder a este recurso institucional. |
| `429` | **Too Many Requests** | Has superado el límite de peticiones por minuto de tu plan de API. |
| `500` | **Internal Server Error** | Ocurrió un error inesperado en nuestro servidor o en el motor de IA. |

---

## 📞 5. Soporte y Comunidad

Si experimentas problemas al conectar tu plataforma, necesitas aumentar los límites de cuota de API, o requieres asistencia personalizada para mapear los campos a tu LMS (Canvas, Moodle, etc.):

* **Correo de Soporte**: [soporte@plannners.com.mx](mailto:soporte@plannners.com.mx)
* **Tiempo de Respuesta**: Menor a 24 horas para desarrolladores e instituciones asociadas.
* **Estado del Sistema**: [https://eduplanner.vercel.app/status](https://eduplanner.vercel.app/status) (Simulado)

*¡Gracias por construir el futuro de la educación con Eduplanner!*