orquestador/specs/INTEGRATIONS.md

Integraciones HTTP — T11

El worker utiliza RegisteredWorkerActions: INVOKE_INTEGRATION invoca HTTP y REGISTER_DOCUMENT verifica metadatos y guarda una referencia bajo fencing. NO_OP existe exclusivamente como utilidad de simulación y no está registrado en Spring ni en el worker; la publicación continúa rechazándolo.

Configuración de despliegue

Se necesitan dos archivos confiables, fuera de los eventos/definiciones editables:

• FLOW_CATALOG_PATH: contratos JSON Schema, efectos, perfiles/versiones y políticas documentales.
• INTEGRATION_ROUTES_PATH: endpoint y límites para cada combinación exacta de integración, contrato, perfil y versión.

Los archivos por defecto en config/ tienen registros vacíos: no habilitan llamadas. Los ejemplos de examples/integrations/ describen un protocolo local propuesto, no contratos confirmados de proveedores. Sus dominios .invalid son marcadores. Copiar/adaptar ambos archivos, mantener todas las versiones usadas por solicitudes vigentes y configurar las rutas antes de habilitar WORKER_ENABLED=true. Cambiar un default no modifica las versiones fijadas al publicar. No sustituir el significado de una versión existente: crear otra versión/tupla.

Compose conserva un único servicio y PostgreSQL externo. Monta ./config:/app/config:ro; la ruta predeterminada dentro del contenedor es /app/config/integration-routes.json. Los tokens se referencian por nombre de variable con tokenEnvironment. Declarar explícitamente esa variable en el entorno del servicio Docker (un valor en el .env de Compose no se transmite automáticamente al contenedor). No guardar el token en los JSON, los flujos ni los eventos. Cadena vacía permite un endpoint sin bearer cuando el contrato de despliegue lo requiera.

Protocolo y límites

• POST JSON con inputs resueltos por el worker, validados contra el contrato.
• Headers: Idempotency-Key estable por ejecución/acción, X-Correlation-Id, X-Integration-Profile y X-Profile-Version cuando corresponda; bearer opcional.
• HTTPS; HTTP solo loopback con perfil Spring local o test. Sin redirecciones, userinfo, query o fragment en la URL.
• connectMs positivo; timeoutMs cubre headers y cuerpo completo, máximo 30 s y menor que el lease. maxBytes limita memoria antes de superar 256 KiB.
• Respuesta JSON objeto, UTF-8 estricto, sin claves duplicadas ni coerción de strings a números. Decimales conservan precisión.
• outputMappings mapea campos superiores de salida a JSON Pointers de la respuesta. Vacío significa identidad. La salida normalizada debe cumplir schema.
• Contratos inline: no se resuelven referencias remotas desde el worker.

Un 2xx válido con found=false o status=INVALID es éxito técnico y resultado de negocio negativo. Un 404 es error salvo notFoundOutput explícito, permitido solo para contratos READ_ONLY; ese resultado también se valida. No habilitar esa traducción sin confirmar el contrato real.

Timeout/429/500/502/503/504 son transitorios; con NON_IDEMPOTENT_WRITE se considera efecto incierto. Una salida inválida tras escritura también es incierta. Los códigos internos no exponen cuerpo remoto, URL o token. La clasificación no garantiza idempotencia del proveedor: solo declarar IDEMPOTENT_WRITE si existe garantía contractual para la clave enviada.

T12: el worker programa RETRY_WAIT para fallos transitorios seguros, con backoff/jitter y Retry-After acotados, hasta el máximo publicado de tres intentos por acción. Conserva checkpoints; efectos inciertos requieren conciliación. Consultar RECONCILIATION.md para el endpoint y la semántica de A03.

Documentos

REGISTER_DOCUMENT consulta el protocolo fijo DOCUMENTS_METADATA contrato 1, sin perfil, con documentId/requestId/businessScope. El servicio documental debe responder identidad de documento/solicitud/ámbito, tipo, identificador de storage, MIME, tamaño entero, checksum SHA-256 hexadecimal y scanStatus=CLEAN. El handler compara pertenencia y política; no confía en metadatos enviados por el cliente.

La inserción en document_reference y el checkpoint SUCCEEDED comparten transacción y fencing, con bloqueo de solicitud antes de ejecución. Una referencia existente solo se reutiliza si coincide completamente. Fallo SQL revierte ambas escrituras. No se descargan/suben archivos ni se ejecuta un antivirus: se verifica el dictamen del servicio documental confiable. T13 completa eventos disponibles y tareas de front.

Verificación reproducible

mvnw.cmd test ejecuta mocks HTTP loopback sin PostgreSQL ni proveedores reales. mvnw.cmd clean verify -Pmigration-tests-external agrega PostgreSQL real utilizando MIGRATION_TEST_DB_URL/USER/PASSWORD en el proceso y base exclusiva de pruebas. Sin ese perfil, verify utiliza Testcontainers y requiere Docker.

HttpIntegrationTest prueba transporte y contratos; RegisterDocumentTest verifica metadatos y carga de ejemplos; HttpIntegrationIT conecta publicación, API de solicitudes/eventos, worker, HTTP y PostgreSQL con rollback inducido. Los estados START/END del fixture representan los destinos de A01/A02; los flujos demostrativos con nombres funcionales corresponden a T14. No hay integración real aprobada de clientes, documentos, buró o Keycloak ni despliegue en server02:8787.