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.
Requerimiento	`POST /v1/pending-requisition-queries`	Pregunta a BACEN qué requerimientos siguen sin respuesta.
Requerimiento	`GET /v1/pending-requisition-queries/gaps`	Lista los requerimientos sin respuesta.
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.
Transferencia	`GET /v1/transfers-in`	Lista las transferencias recibidas.
Transferencia	`GET /v1/transfers-in/{id}`	Lee una transferencia recibida.
Transferencia	`POST /v1/transfers-in/{id}/confirm`	Confirma una transferencia recibida.
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.
Streaming	`GET /v1/streaming/manifest`	Lee el manifiesto de eventos. Con el streaming apagado, la ruta no se monta.

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

Endpoint	Propósito
`GET /health`	Liveness.
`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.
`/swagger/*`	La especificación de la API, cuando `SWAGGER_ENABLED=true` fuera de producción.

Autenticación y tenencia

Cada ruta /v1 toma un token bearer de OAuth2 de Lerian Access Manager. Con PLUGIN_AUTH_ENABLED=true y PLUGIN_AUTH_HOST, Lerian Access Manager autoriza cada solicitud. Solo un ENV_NAME de desarrollo fuera de saas acepta false. Cada institución mantiene su propio esquema de base de datos.

Idempotencia

Lerian CCS acepta un header X-Idempotency opcional en la mayoría de las rutas que cambian estado. Un middleware almacena en caché la primera respuesta y la repite ante una repetición de la misma clave. Una repetición con otro cuerpo responde 422, y una repetición mientras la primera solicitud se ejecuta responde 409. Las claves pertenecen a una institución, y la retención predeterminada es de 7 días.

Errores

Un error de negocio responde con un documento de problema RFC 9457, con el tipo de medio application/problem+json y 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-0074`	409	Una conciliación ya está en curso.
`MYS-0008`	503	Un upstream o la plantilla no está disponible.

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. Con RABBITMQ_ENABLED=true, Lerian CCS también publica notificaciones en el exchange nombrado por RABBITMQ_EXCHANGE.

Routing key	Significado
`ccs.events.batch`	Un lote terminó su generación y espera revisión.
`ccs.events.batch.generation_failed`	La generación del lote falló.
`ccs.events.reconciliation.divergence`	Una ejecución encontró una divergencia.

Los documentos en esos payloads están enmascarados.

Convenciones de integración

Headers. Mientras CORS_ALLOWED_HEADERS permanezca sin definir, aplica una lista fija por defecto, y esa lista no incluye X-Idempotency. Un valor que configures reemplaza esa lista, 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 tamaño de página de 100 o menos se mantiene dentro del límite de cada ruta.
Límites de tasa. El limitador cubre solo /v1. Las solicitudes que cambian estado y las lecturas pesadas, como las consultas de auditoría, llevan niveles más estrictos.
Referencias de archivo. El XML regulatorio permanece en almacenamiento de objetos. La API y los mensajes del broker solo llevan referencias de archivo.

Cómo funciona Lerian CCS cubre estos flujos.

​Superficie de la API

​Autenticación y tenencia

​Idempotencia

​Errores

​Eventos

​Convenciones de integración