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

# Integración con Lerian CCS

> La superficie de la API de Lerian CCS, su modelo de autenticación y tenencia, la idempotencia, el contrato de errores, y los eventos que publica.

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](/es/platform/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](/es/platform/streaming-hub/how-streaming-hub-works), 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/platform/streaming-hub/what-is-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](/es/rails/ccs/how-ccs-works) cubre estos flujos.