> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.esolbay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Arquitectura de Integración

> Flujos push/pull y notificaciones mediante Webhooks para integrar ERP/Middleware con Esolbay

## 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

<Mermaid
  chart={`graph TD;
admin["Usuario Administrador"];
web["Aplicación Web (Next.js)\n(Vercel)"];
db(("InstantDB"));
auth["Clerk (Auth)"];
queue["Inngest (Orquestación)"];
ai["Azure OpenAI (IA)"];
bt["Braintrust (Observability)"];
metrics["PostHog (Analytics)"];
admin -->|HTTPS| web;
web --> auth;
web --> db;
web --> queue;
queue --> web
web --> ai
web --> metrics;
bt --> db;
`}
/>

### 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. |

<Mermaid
  chart={`sequenceDiagram;
actor User as Usuario/Proceso
participant ERP as ERP Cliente
participant MWD as Middleware (Opcional)
participant Esolbay as Esolbay API

rect rgb(245,245,245)
note over User,Esolbay: Sincronización de datos
User->>ERP: Solicita operación sobre entidad
alt Middleware recibe (push)
    ERP->>MWD: Envía datos de entidad (API REST u otro)
    MWD->>Esolbay: Alta/actualización de entidad (API REST)
    Esolbay-->>MWD: Respuesta (éxito/error)
    MWD-->>ERP: Respuesta (opcional)
else Middleware consulta (pull)
    MWD->>ERP: Consulta/lee nuevos datos
    ERP-->>MWD: Respuesta con datos de entidad
    MWD->>Esolbay: Alta/actualización de entidad (API REST)
    Esolbay-->>MWD: Respuesta (éxito/error)
end
end

rect rgb(235,255,235)
note over Esolbay,ERP: Notificación de cambios desde Esolbay
Esolbay-->>MWD: Webhook (notificación de cambio)
Esolbay-->>ERP: Webhook (notificación de cambio)
end
`}
/>

## 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)

<Mermaid
  chart={`graph LR;
req["Requisition"]
tnd["Tender"]
awd["Award"]
bid["Bid"]
ord["Order"]
prov["Provider"]
evl["Evaluation"]

req -- "N..M" --> tnd
tnd -- "1..N" --> awd
bid -- "1..1" --> awd
prov -- "1..N" --> bid
awd -- "N..1" --> prov
awd -- "1..N" --> ord
ord -- "0..N" --> evl
`}
/>

## Recursos útiles

* Guía de inicio: <a href="/get-started">Get started</a>
* Guía de API: <a href="/api-guide">Guía de la API</a>
* Autenticación con API Key: <a href="/authentication">Autenticación</a>
* Webhooks y validación de firmas: <a href="/webhooks">Webhooks</a>