Integración con Lerian CCS

Lerian CCS expone una API REST bajo /v1. Cada ruta de negocio requiere un token bearer.

Superficie de la API

Área	Operación	Propósito
Configuración	`GET /v1/configurations`	Lee la configuración actual.
Configuración	`POST /v1/configurations`	Crea una configuración.
Configuración	`GET /v1/configurations/{id}`	Lee una configuración.
Configuración	`PATCH /v1/configurations/{id}`	Actualiza una configuración.
Configuración	`POST /v1/configs/{configId}/conglomerate-members`	Agrega un miembro.
Configuración	`GET /v1/configs/{configId}/conglomerate-members`	Lista los miembros.
Configuración	`DELETE /v1/configs/{configId}/conglomerate-members/{memberId}`	Elimina un miembro.
Lote	`POST /v1/batches`	Genera el lote para una fecha de movimiento.
Lote	`GET /v1/batches`	Lista los lotes.
Lote	`GET /v1/batches/{id}`	Lee un lote.
Lote	`POST /v1/batches/{id}/approve`	Aprueba e inicia el render.
Lote	`POST /v1/batches/{id}/submit`	Alias de aprobar.
Lote	`POST /v1/batches/{id}/reject`	Rechaza un lote en revisión.
Lote	`GET /v1/batches/{id}/items`	Lista los elementos de línea.
Lote	`GET /v1/batches/{id}/items/{itemId}/errors`	Lista los errores de los elementos.
Lote	`POST /v1/batches/resend`	Reenvía desde un lote terminal.
Lote	`POST /v1/batches/{id}/reprocess-last-event`	Administrador. Vuelve a emitir el último evento.
Lote	`POST /v1/batches/{id}/drain-parked-response`	Administrador. Aplica un ACCS003 en espera.
Lote	`POST /v1/batches/reconcile-partial-applies`	Administrador. Repara un veredicto contradictorio.
Lote	`POST /v1/batches/recompute-mirror`	Administrador. Recalcula el espejo.
Lote	`POST /v1/batches/backfill-sta-transfer-id`	Administrador. Restaura una identidad perdida.
Solicitud de detalle	`GET /v1/detail-requests`	Lista las solicitudes de detalle.
Solicitud de detalle	`GET /v1/detail-requests/{id}`	Lee una solicitud de detalle.
Solicitud de detalle	`POST /v1/detail-requests/{id}/cancel`	Cancela una solicitud de detalle.
Orden judicial	`POST /v1/injunctions`	Registra un bloqueo o desbloqueo.
Orden judicial	`GET /v1/injunctions`	Lista las órdenes judiciales.
Orden judicial	`GET /v1/injunctions/{id}`	Lee una orden judicial.
Orden judicial	`POST /v1/injunctions/{id}/revoke`	Revoca una orden judicial.
Conciliación	`POST /v1/reconciliations`	Inicia una ejecución contra un ACCS004.
Conciliación	`GET /v1/reconciliations`	Lista las ejecuciones.
Conciliación	`GET /v1/reconciliations/{id}`	Lee una ejecución.
Conciliación	`GET /v1/reconciliations/{id}/divergences`	Lista las divergencias.
Transferencia	`POST /v1/transfers`	Crea una transferencia.
Transferencia	`GET /v1/transfers`	Lista las transferencias.
Transferencia	`GET /v1/transfers/{id}`	Lee una transferencia con sus tramos.
Auditoría	`GET /v1/audit/entries`	Lista las entradas de auditoría.
Auditoría	`POST /v1/audit/verify-chain`	Verifica la cadena de auditoría.

Los endpoints de operador están fuera de /v1.

Endpoint	Propósito
`GET /health`	Liveness. Responde 503 mientras falla la propia sonda.
`GET /readyz`	Readiness de todas las dependencias.
`GET /readyz/tenant/{id}`	Readiness de una institución.
`GET /version`	Versión de compilación.
`GET /metrics`	Métricas de readiness, en texto Prometheus.
`GET /streaming`	El manifiesto de eventos.
`/system/{namespace}`	Configuración en tiempo de ejecución.
`/swagger/*`	La especificación de la API, cuando `SWAGGER_ENABLED=true`.

Autenticación y tenencia

Cada ruta /v1 toma un token bearer de OAuth2 de Lerian Access Manager. Configura PLUGIN_AUTH_ENABLED=true y PLUGIN_AUTH_HOST para activar la puerta. Producción requiere ambos. Cada institución mantiene su propio esquema de base de datos. El servicio lee la identidad de la institución del token validado, nunca de un cuerpo de solicitud, un header o un parámetro de ruta.

Idempotencia

Lerian CCS acepta un header Idempotency-Key. El header es obligatorio en POST /v1/batches y opcional en la ruta de cancelación. Un middleware almacena en caché la primera respuesta y la repite ante una repetición de la misma clave. Las claves pertenecen a una institución, y la retención predeterminada es de 7 días.

Errores

Cada cuerpo de error es un documento de problema RFC 9457 con el tipo de medio application/problem+json. Cada cuerpo lleva un código de producto. Los valores de código son un contrato congelado, así que un cliente compara con el código, no con el texto del mensaje.

Código	Estado	Cuándo
`CCS-0001`	409	Ya existe una configuración.
`CCS-0004`	404	La configuración no existe.
`CCS-0010`	409	Un lote no terminal ocupa esa fecha de movimiento.
`CCS-0012`	400	La fecha de movimiento está fuera de la ventana.
`CCS-0020`	404	El lote no existe.
`CCS-0024`	422	El lote rechaza esa transición.
`CCS-0050`	400	La transferencia nombra a la propia institución.
`CCS-0061`	409	Una orden judicial ya cubre ese documento.
`CCS-0064`	404	La solicitud de detalle no existe.
`CCS-0066`	409	La ventana cancelable se cerró.
`CCS-0074`	409	Una conciliación ya está en curso.
`MYS-0008`	503	Un upstream o la plantilla no está disponible.

Una ruta cuyos colaboradores fallan al conectarse responde 501.

Eventos

Lerian CCS publica un evento de negocio en su propio tema, con un tema dead-letter correspondiente. El tema y el tipo de evento siguen la regla de nomenclatura de Streaming Hub, con el source de CloudEvents de este servicio como espacio de nombres.

Evento	Significado
Lote enviado	El lote ACCS001 fue enviado a Lerian STA.

Lleva la postura de entrega crítica. El servicio lo escribe en el outbox transaccional en la misma transacción que el cambio de estado. El streaming está desactivado por defecto. Mientras está desactivado, el servicio conecta un emisor sin operación y no publica nada. Lerian Streaming Hub es la capa de entrega. Lerian CCS también publica notificaciones en el exchange nombrado por RABBITMQ_EXCHANGE.

Routing key	Significado
`ccs.events.batch`	Un lote cambió de estado.
`ccs.events.batch.generation_failed`	La generación del lote falló.
`ccs.events.detail_request.received`	Llegó una solicitud de detalle.
`ccs.events.detail_request.cancelled`	Una solicitud de detalle pasó a cancelada.
`ccs.events.reconciliation.divergence`	Una ejecución encontró una divergencia.
`ccs.outbox.dlq`	Un mensaje del outbox agotó sus intentos.

Los documentos en esos payloads están enmascarados.

Convenciones de integración

Headers. CORS_ALLOWED_HEADERS no lleva un valor por defecto. Mientras permanezca sin definir, una respuesta de preflight repite los headers que pidió el navegador. Un valor que configures reemplaza ese comportamiento con una lista fija, así que nombra cada header que envíe tu cliente de navegador.
Paginación. Cada ruta de listado limita su propio tamaño de página. Un limit de 100 o menos se mantiene dentro del límite de cada ruta.
Límites de tasa. El limitador cubre solo /v1. Las rutas de exportación y despacho llevan niveles más estrictos.
Referencias de archivo. El XML regulatorio permanece en almacenamiento de objetos. Solo las referencias de archivo viajan por la red.

Cómo funciona Lerian CCS cubre estos flujos.

​Superficie de la API

​Autenticación y tenencia

​Idempotencia

​Errores

​Eventos

​Convenciones de integración