Caso de estudio
Plataforma de integraciones educativas
Servicios en FastAPI que mantienen Zoho CRM sincronizado con sistemas académicos, servicios SOAP y bases de datos heredadas
Un servicio en FastAPI por institución conecta Zoho CRM con los sistemas que esa institución ya tiene, desde Oracle PeopleSoft Campus Solutions por SOAP hasta bases SQL Server detrás de una VPN. Yo los construyo, los despliego y los vigilo.
El problema
Universidades y escuelas de negocios de Latinoamérica y España gestionan las admisiones en Zoho CRM, mientras los programas, precios, pagos y matrículas viven en sus sistemas académicos. Sin una integración, los equipos de admisiones copian esos datos a mano y el CRM se aleja de lo que de verdad pasó.
No hay dos instituciones con el mismo stack. Una expone Oracle PeopleSoft Campus Solutions por SOAP con WS-Security, otra una base SQL Server a la que solo se llega por VPN, otras dejan archivos CSV cada noche en un FTP u ofrecen APIs REST.
Restricciones
- Zoho CRM impone límites a su API, y sus trabajos masivos terminan de forma asíncrona.
- Los sistemas de origen son de las instituciones. No los puedo cambiar, y a algunos solo se llega por VPN.
- Tres personas en la organización de GitHub operan más de 20 servicios.
- Los datos son de aspirantes y estudiantes de varios países, entre ellos España.
Lo que construí
- Un servicio en FastAPI por institución sobre un estándar común, con routers sin lógica, controladores de módulo que normalizan y componen, y una sola capa de acceso por cada sistema externo.
- Las sincronizaciones largas responden 202 Accepted y corren como trabajos en segundo plano. Cada corrida tiene un ID, un estado que pasa de pendiente a finalizado o fallido, y un registro en el CRM con su desenlace, su duración y su reporte.
- Las escrituras en Zoho van por la Bulk API o por llamadas REST en lotes. Los registros de cada corrida se buscan con COQL, porque el índice de búsqueda tarda en ver los registros nuevos y crearía duplicados.
- Los logs tienen cinco niveles, y el nivel puede subir hasta volcados completos de SOAP y HTTP en caliente, sin reiniciar el contenedor.
- Cada servicio sale como imagen Docker endurecida en GHCR y se despliega con Docker Compose desde GitHub Actions. Las trazas de OpenTelemetry van a Tempo, las métricas a Prometheus y los logs a Loki.
Arquitectura
Cómo se conectan los servicios
Los datos van en ambos sentidos entre columnas vecinas. La fila de abajo corre bajo todos los servicios.
Sistemas de cada institución
- PeopleSoft Campus Solutions por SOAP con WS-Security
- Bases SQL Server por VPN
- Archivos CSV nocturnos por FTP
- APIs REST y webhooks
Un servicio en FastAPI por institución
- Routers, controladores de módulo y una capa por sistema externo
- Trabajos en segundo plano que responden 202 Accepted
- Un registro de cada corrida en el CRM
Zoho CRM
- OAuth 2.0
- Bulk API y REST en lotes
- Búsquedas con COQL
Operación
- GitHub Actions, imágenes en GHCR y Docker Compose
- Trazas de OpenTelemetry en Tempo, métricas en Prometheus, logs en Loki
- Alertas de Grafana a Telegram
Decisiones y sus costos
Un servicio por institución
No hay dos instituciones con el mismo stack, y cada una tiene sus propias credenciales.
202 Accepted en vez de esperar
Sincronizar un catálogo puede tardar minutos, más de lo que espera una función del CRM o un navegador.
La deuda por escrito
El primer servicio es anterior al estándar, y los servicios nuevos podían copiar sus diferencias.
Resultados
- Más de 20 servicios en producción para más de 15 instituciones de Latinoamérica y España.
- Los servicios más recientes implementan el estándar completo, con claves de idempotencia, un límite de concurrencia con reintentos escalonados cuando Zoho responde 429, trabajos persistidos en PostgreSQL y secretos cifrados con AES-256-GCM.
- Un mismo stack de observabilidad los vigila a todos, con 4 tableros de Grafana, 18 sondas de disponibilidad y 12 reglas de alerta que llegan a Telegram.
Pendientes
- Llevar los servicios antiguos al estándar, empezando por las claves de idempotencia y los reintentos escalonados.
- Pruebas de contrato para cada sistema externo en CI. Hoy solo los servicios más recientes tienen suite de pruebas.
- Publicar el volumen sincronizado y la disponibilidad de cada servicio a partir de los datos de Prometheus.
Stack
Elige una tecnología para ver qué proyectos la usan.
