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

# Cómo funciona Lerian SLC

> Cómo funciona Lerian SLC: ingesta canónica, construcción del archivo ASLC, firma de custodia ICP-Brasil, transmisión a Nuclea y rastreo del ciclo de vida de liquidación de tarjetas con clave NUliquid.

Lerian SLC ejecuta un solo pipeline de liquidación para cada operación de tarjeta. El pipeline toma una operación y construye su archivo ASLC. La custodia del cliente firma el archivo. Lerian SLC transmite el archivo a Nuclea y correlaciona los retornos. El NUliquid rastrea la operación a lo largo de su ciclo de vida.

## Ingesta

***

Las operaciones ingresan a Lerian SLC a través de dos modos canónicos:

* **API canónica.** Una ingesta REST/JSONL para operaciones en la forma canónica de Lerian. La clave de deduplicación del llamador es `external_id`. Un segundo envío bajo un `external_id` ya en uso devuelve **409 Conflict** y nombra la operación existente. Por eso, un envío reintentado nunca se liquida dos veces.
* **XML ASLC directo.** Una carga de XML ASLC ya listo para los llamadores que ya lo producen.

Un modo de **paso auditado** también acepta artefactos que el cliente ya firmó y los reenvía bajo auditoría.

Hoy envías tres tipos de operación: **CREDIT**, **DEBIT** y **ANTICIPATION**. Una **CANCELLATION** ingresa por su propio camino, porque lleva un código de motivo regulatorio y el identificador de la operación que cancela. Lerian SLC emite **SWEEP** (varredura) por sí mismo como un tipo canónico. Lerian SLC no lo acepta en la ingesta.

## Construir, firmar, transmitir, correlacionar

***

Cada operación fluye a través de un pipeline:

1. **Validar** la operación contra los XSD de Nuclea.
2. **Construir** el archivo ASLC como UTF-16BE, sin BOM, hasta un tope configurable de registros que por defecto es de **50,000** registros por archivo. La construcción divide el archivo automáticamente por encima de ese tope. Los archivos de cancelación están exentos: nunca se dividen.
3. **Sellar** el archivo. Primero comprímelo con **GZIP**. Luego construye el **envelope de seguridad SPB**, que la custodia del cliente firma (consulta [Orquestación de la firma](#signing-orchestration) más abajo).
4. **Transmitir** el archivo a Nuclea a través del canal configurado para el tenant: **Connect:Direct** sobre la red RSFN privada, o **REST** con **mTLS**. El canal REST agrega una firma **JWS por solicitud** porque cruza la internet pública. Connect:Direct no necesita una, ya que el payload ya está firmado con SPB y la red es privada.
5. **Correlacionar** los retornos de Nuclea de vuelta con las operaciones que los produjeron. Cada costura de retorno usa la clave que la contraparte repite. Una línea **RET** usa su número de control de 20 posiciones, la forma con ceros a la izquierda de tu `external_id`. Una línea **ASLC023** o D+1 usa su **NUliquid**. Un **PRO** a nivel de archivo usa el número de control del segmento transmitido.

   Una línea cuya clave no coincide con nada se omite como no correlacionada. Los retornos son los archivos **PRO / ERR / RET** y el mensaje de estado **ASLC028**.

### Cuando un retorno se contradice a sí mismo

Un solo archivo de retorno puede indicar dos resultados diferentes para la misma referencia, y los XSD no pueden rechazar esa forma. Lerian SLC lo resuelve por política, no por el orden en que las líneas aparecen en el archivo:

* un resultado: se aplica tal como se indica.
* el mismo resultado repetido: se aplica exactamente una vez.
* una aceptación **y** un rechazo para la misma referencia: **el rechazo gana**, y la aceptación desplazada se reporta para conciliación.

El resultado es el mismo sin importar en qué orden lleguen las dos líneas. El archivo nunca se aborta: cada otra referencia en él sigue procesándose, y el retorno se sigue confirmando.

## Familias de mensajes

***

| Flujo                   | Familia de mensajes                                       |
| ----------------------- | --------------------------------------------------------- |
| Liquidación de crédito  | ASLC027 / ASLC028                                         |
| Liquidación de débito   | ASLC029 / ASLC030                                         |
| Anticipo                | ASLC031 / ASLC034                                         |
| Retornos y devoluciones | ASLC041 / ASLC042 / ASLC043                               |
| Cancelación             | ASLC060–ASLC067                                           |
| Sweep (varredura)       | ASLC050 / ASLC051                                         |
| Domicilio entrante      | ASLC022 / ASLC023 / ASLC024 / ASLC025 / ASLC032 / ASLC033 |

## Flujos de liquidación

***

* **Crédito (adquirente).** Las operaciones ingresan a través de la ingesta canónica. Lerian SLC construye el archivo de crédito (**ASLC027**), luego lo firma y lo transmite. Correlaciona el estado **ASLC028** y los retornos PRO/ERR/RET. El NUliquid rastrea cada operación a lo largo de su ciclo de vida.
* **Débito y anticipo.** El mismo pipeline de ingesta-construcción-firma-transmisión se ejecuta para las familias de débito (**ASLC029 / ASLC030**) y anticipo (**ASLC031 / ASLC034**). Los retornos de estado y el rastreo por NUliquid reflejan el flujo de crédito.
* **Cancelación.** El adquirente informa una cancelación (crédito **ASLC060**, débito **ASLC064**). Lerian SLC la retransmite a la **IF Domicílio** (**ASLC061**). El domicilio devuelve su resultado de procesamiento (**ASLC062**). Lerian SLC devuelve el resultado al adquirente (**ASLC063 / ASLC067**). Luego emite un evento cancellation-confirmed-by-domicile con el NUliquid.

## IF Domicílio entrante

***

Como institución domiciliaria, Lerian SLC recibe avisos de liquidación de crédito y débito (**ASLC022 / ASLC024 / ASLC032**). Los confirma (**ASLC023 / ASLC025 / ASLC033**). Emite retornos y devoluciones (**ASLC041 / ASLC042 / ASLC043**). Un webhook indexado por el NUliquid señala el crédito al comercio y lleva la evidencia del retorno.

## Compensación y financiamiento para la IF Liquidante

***

Para la institución liquidante, Lerian SLC consume los mensajes de compensación entrantes a través de la RSFN. Estos son el acuse de recibo del archivo (**GEN0015**), la posición de compensación preliminar y final (**SLC0001**), la divergencia de movimiento bilateral (**SLC0002**), y el estado operacional del participante (**PAG0101**). Lerian SLC construye la **posición de compensación por ciclo de liquidación** y la concilia contra las instrucciones esperadas. Analiza y expone la divergencia bilateral **SLC0002**. Genera eventos para preview-available, final-available, deposit-required y deposit-deadline-approaching.

## Ciclo de vida de la operación

***

El NUliquid rastrea cada operación a lo largo de un ciclo de vida de **11 estados**.

| Estado            | Significado                                                  |
| ----------------- | ------------------------------------------------------------ |
| **CREATED**       | La operación ha sido aceptada en Lerian SLC.                 |
| **QUEUED**        | Está en cola para la próxima construcción de archivo.        |
| **SENT**          | Su archivo ha sido transmitido a Nuclea.                     |
| **ACKNOWLEDGED**  | Nuclea ha confirmado la recepción.                           |
| **ACCEPTED**      | Nuclea ha aceptado la operación.                             |
| **REJECTED**      | Nuclea ha rechazado la operación.                            |
| **FORWARDED**     | El aviso de liquidación ha sido reenviado a la IF Domicílio. |
| **CONFIRMED**     | El domicilio ha confirmado.                                  |
| **SETTLED**       | La operación se ha liquidado.                                |
| **D1\_CONFIRMED** | La liquidación se confirma en D+1.                           |
| **CANCELLED**     | La operación ha sido cancelada.                              |

Los archivos tienen su propio ciclo de vida de **10 estados**, desde la construcción hasta la transmisión y la correlación de retornos.

<h2 id="signing-orchestration">
  Orquestación de la firma
</h2>

***

Lerian SLC materializa el XML ASLC sin firmar y luego **delega la firma a un backend de custodia elegido por tenant**. La clave privada nunca sale de la custodia del cliente, y Lerian nunca firma en nombre del cliente.

| Backend de custodia | Dónde vive la clave                                         |
| ------------------- | ----------------------------------------------------------- |
| **Software key**    | Una clave mantenida por software en el entorno del cliente. |
| **PKCS#11 HSM**     | Un módulo de seguridad de hardware.                         |
| **Cloud KMS**       | Un servicio de gestión de claves en la nube.                |

Los despliegues SaaS fijan la custodia a un KMS en la nube mediante **importación de clave envuelta del lado del cliente**. El cliente envuelve e importa su propia clave. El servicio almacena solo el certificado público y una referencia de clave, nunca el material privado.

## Transporte

***

Lerian SLC envía las operaciones en línea a Nuclea a través de **REST**. **mTLS** y una firma **JWS por solicitud** protegen ese canal (la serie en línea SLC0908 / SLC0912 / SLC0915). Los retornos entrantes se sondean y se confirman a través del mismo canal REST.

La transmisión de archivos es la única superficie con una elección por tenant: **REST** o **Connect:Direct** sobre la RSFN privada. REST agrega el JWS por solicitud porque cruza la internet pública. Connect:Direct no lo necesita, ya que el payload ya lleva su firma SPB y la red es privada.

<Note>
  El cliente de conexión Connect:Direct aún no está provisionado. Un tenant configurado para usarlo falla de forma segura con un error de transporte tipado. No recae silenciosamente en REST, así que REST es el único canal que transporta archivos hoy.
</Note>