Arquitectura de Integración - Esolbay Docs

Visión general

La integración con Esolbay admite dos patrones para sincronización de datos (push y pull) y un canal de notificación mediante Webhooks.

Arquitectura y Componentes

Detalle de Contenedores

Contenedor	Rol funcional
Aplicación Web (Next.js)	Monolito full‑stack desplegado en Vercel; renderizado híbrido (SSR/CSR/ISR), CDN global y caché en el edge para tiempos de respuesta <100 ms en la UE.
InstantDB	Base de datos serverless; aislamiento por organización, backups horarios, cifrado at‑rest AES‑256 y alta disponibilidad multi‑AZ.
Clerk	Identidad y autenticación (JWT RS256, MFA opcional, SSO SAML/OIDC); sesiones revocables y cumplimiento SOC 2 Tipo II.
Inngest	Orquestador de eventos y jobs con reintentos automáticos; coordina el envío de correos, cierre de licitaciones y otras operaciones críticas incluso ante fallos temporales.
Azure OpenAI	Servicios de IA.
Braintrust	Observabilidad de workflows e IA; captura trazas detalladas, métricas de rendimiento y feedback para mejora continua.
PostHog	Analítica de uso y métricas de comportamiento (EU hosted); datos anonimizados, cumplimiento RGPD y exportación para auditoría.
Gateway de Correo	Maneja notificaciones transaccionales y recepción de correos entrantes mediante webhooks firmados; almacena adjuntos de forma segura y dispara eventos internos para su procesamiento.

Patrones de integración

Push (evento desde ERP): el ERP publica cambios hacia un Middleware (opcional) que consolida y llama a la API de Esolbay.
Pull (lectura periódica): el Middleware consulta al ERP cambios recientes y los sincroniza con Esolbay.
Webhooks (outbound): Esolbay notifica cambios relevantes (p. ej. creación/actualización de órdenes) a tus endpoints.

Seguridad de Webhooks y API

Autenticación de Webhooks: cabeceras x-api-key, x-esolbay-event-id y x-esolbay-timestamp para idempotencia y mitigación de replay.
Autenticación de API: header x-api-key por organización (ver Autenticación).
Transporte seguro: TLS 1.2+ obligatorio.

Integraciones y APIs Externas

Mecanismo	Descripción	Seguridad
REST API	Endpoints bajo `/api/v1/**` que exponen entidades de dominio (p. ej. `/requisitions`, `/bids`, `/awards`). Métodos `GET/POST/PUT/PATCH/DELETE`. Respuestas JSON y versionado semántico en la URL.	Autenticación mediante cabecera `X-Api-Key` vinculada a la organización. TLS 1.2+ obligatorio.
Webhooks	Notificaciones salientes en tiempo real para eventos de dominio (p. ej. `award.confirmed`, `tender.closed`, `order.created`). Retries exponenciales hasta 24 h.	Firma HMAC‑SHA256 en cabecera `X-Esolbay-Signature` (`sha256=...`) usando secreto compartido por organización. Validación de `timestamp` para mitigar replay attacks.

Diagrama de dominio (vista simplificada)

Recursos útiles

Guía de inicio: Get started
Guía de API: Guía de la API
Autenticación con API Key: Autenticación
Webhooks y validación de firmas: Webhooks