Saltar a contenido

04 — Integraciones

Todas las integraciones entran/salen por el módulo de integraciones del core (adapters), traducidas al lenguaje del dominio — nunca tocan entidades directamente. Los efectos salientes van por outbox (ver doc 03).

Moodle (LMS del colegio — ya operativo)

El colegio ya tiene Moodle; nos integramos contra su instancia vía web services REST (requiere usuario de servicio + token con permisos admin, gestionado con el colegio). Nuestro sistema es la fuente de verdad de personas y estructura.

Alcance: 1. Aprovisionamiento: al matricular/asignar en nuestro sistema se crean/actualizan usuarios, cursos y enrolments en Moodle (idempotente, con mapeo uuid ↔ moodle_id persistido). 2. Calificaciones: lectura del gradebook de Moodle para que el docente pueda volcar notas de actividades hacia las calificaciones oficiales (siempre con confirmación del docente — Moodle no escribe notas oficiales solo). 3. Enlaces profundos: la app y el panel muestran el acceso directo al curso Moodle correspondiente.

Sin SSO (decisión): credenciales Moodle separadas. Mitigación: al matricular se generan ambas credenciales juntas para entregarse en un solo documento. El SSO (OIDC) queda como mejora futura sin cambios estructurales.

Email transaccional

  • Proveedor transaccional (SES/Resend o similar) con dominio del colegio verificado (SPF/DKIM) — crítico para que credenciales y comunicados no caigan en spam.
  • Adapter MailSender configurable por env; plantillas versionadas en el repo.

Push (FCM)

  • Firebase Cloud Messaging hacia la app Flutter (proyecto Firebase por flavor/colegio).
  • Registro de token por dispositivo al iniciar sesión; limpieza de tokens inválidos en cada envío.
  • Usos: comunicados, alertas de inasistencia, publicación de notas, vencimientos de pago.

Excel (importación/exportación)

Palanca principal de adopción. Plantillas oficiales descargables + validación fila a fila con reporte de errores (nunca importación parcial silenciosa: o se importa el lote validado, o se rechaza con detalle).

  • Importar: matrícula masiva, histórico básico (promedios finales de años previos), pagos/obligaciones, notas (para migraciones).
  • Exportar: listados, actas, estado de cuenta, reportes académicos.
  • Procesamiento en cola (pg-boss) con progreso visible.

API pública de integración

  • /api/v1/integration/* en el BFF, autenticada con API keys por sistema externo (revocables, con scopes: p. ej. solo pagos).
  • Primer caso de uso: sistemas contables externos registran pagos / leen estado de cuenta.
  • Contrato documentado con OpenAPI/Swagger generado desde los DTOs.