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

# Como funciona o Lerian SLC

> Como funciona o Lerian SLC: entrada canônica, construção do arquivo ASLC, assinatura por custódia ICP-Brasil, transmissão à Nuclea e rastreamento do ciclo de vida de liquidação de cartões por NUliquid.

O Lerian SLC executa um único pipeline de liquidação para cada operação de cartão. O pipeline recebe uma operação e constrói seu arquivo ASLC. A custódia do cliente assina o arquivo. O Lerian SLC transmite o arquivo à Nuclea e correlaciona os retornos. O NUliquid rastreia a operação ao longo do seu ciclo de vida.

## Entrada

***

As operações entram no Lerian SLC por dois modos canônicos:

* **API canônica.** Uma entrada REST/JSONL para operações no formato canônico da Lerian. A chave de deduplicação do chamador é `external_id`. Uma segunda submissão com um `external_id` já em uso retorna **409 Conflict** e nomeia a operação existente. Por isso, uma submissão reenviada nunca é liquidada duas vezes.
* **XML ASLC direto.** Um upload de XML ASLC pronto para chamadores que já o produzem.

Um modo de **repasse auditado** também aceita artefatos que o cliente já assinou e os encaminha sob auditoria.

Hoje você submete três tipos de operação: **CREDIT**, **DEBIT** e **ANTICIPATION**. Um **CANCELLATION** entra pelo seu próprio caminho, porque carrega um código de motivo regulatório e o identificador da operação que ele cancela. O Lerian SLC emite o **SWEEP** (varredura) por conta própria como um tipo canônico. O Lerian SLC não o aceita na entrada.

## Construir, assinar, transmitir, correlacionar

***

Cada operação passa por um único pipeline:

1. **Validar** a operação em relação aos XSDs da Nuclea.
2. **Construir** o arquivo ASLC como UTF-16BE, sem BOM, até um teto de registros configurável cujo padrão é **50.000** registros por arquivo. A construção divide o arquivo automaticamente acima desse teto. Os arquivos de cancelamento são isentos: eles nunca são divididos.
3. **Selar** o arquivo. Primeiro, compacte-o com **GZIP**. Depois, construa o **envelope de segurança SPB**, que a custódia do cliente assina (veja [Orquestração de assinatura](#signing-orchestration) abaixo).
4. **Transmitir** o arquivo à Nuclea pelo canal configurado para o tenant: **Connect:Direct** pela rede privada RSFN, ou **REST** com **mTLS**. O canal REST adiciona uma assinatura **JWS por requisição** porque atravessa a internet pública. O Connect:Direct não precisa de uma, já que o payload já está assinado com SPB e a rede é privada.
5. **Correlacionar** os retornos da Nuclea de volta às operações que os produziram. Cada retorno usa a chave que a contraparte ecoa. Uma linha **RET** usa seu número de controle de 20 posições, a forma de `external_id` preenchida com zeros à esquerda. Uma linha **ASLC023** ou D+1 usa seu **NUliquid**. Um **PRO** em nível de arquivo usa o número de controle do lote transmitido.

   Uma linha cuja chave não corresponde a nada é ignorada como não correlacionada. Os retornos são os arquivos **PRO / ERR / RET** e a mensagem de status **ASLC028**.

### Quando um retorno se contradiz

Um único arquivo de retorno pode declarar dois resultados diferentes para a mesma referência, e os XSDs não conseguem rejeitar esse formato. O Lerian SLC resolve isso por política, não pela ordem em que as linhas aparecem no arquivo:

* um resultado: aplicado como declarado.
* o mesmo resultado repetido: aplicado exatamente uma vez.
* uma aceitação **e** uma recusa para a mesma referência: **a recusa prevalece**, e a aceitação substituída é reportada para conciliação.

O resultado é o mesmo independentemente da ordem em que as duas linhas chegam. O arquivo nunca é abortado: toda outra referência nele continua sendo processada, e o retorno ainda é confirmado.

## Famílias de mensagens

***

| Fluxo                 | Família de mensagens                                      |
| --------------------- | --------------------------------------------------------- |
| Liquidação de crédito | ASLC027 / ASLC028                                         |
| Liquidação de débito  | ASLC029 / ASLC030                                         |
| Antecipação           | ASLC031 / ASLC034                                         |
| Retornos e devoluções | ASLC041 / ASLC042 / ASLC043                               |
| Cancelamento          | ASLC060–ASLC067                                           |
| Sweep (varredura)     | ASLC050 / ASLC051                                         |
| Entrada do domicílio  | ASLC022 / ASLC023 / ASLC024 / ASLC025 / ASLC032 / ASLC033 |

## Fluxos de liquidação

***

* **Crédito (adquirente).** As operações entram pela entrada canônica. O Lerian SLC constrói o arquivo de crédito (**ASLC027**), depois o assina e transmite. Ele correlaciona o status **ASLC028** e os retornos PRO/ERR/RET. O NUliquid rastreia cada operação ao longo do seu ciclo de vida.
* **Débito e antecipação.** O mesmo pipeline de entrada-construção-assinatura-transmissão é executado para as famílias de débito (**ASLC029 / ASLC030**) e antecipação (**ASLC031 / ASLC034**). Os retornos de status e o rastreamento por NUliquid espelham o fluxo de crédito.
* **Cancelamento.** O adquirente informa um cancelamento (crédito **ASLC060**, débito **ASLC064**). O Lerian SLC o repassa à **IF Domicílio** (**ASLC061**). O domicílio retorna seu resultado de processamento (**ASLC062**). O Lerian SLC retorna o resultado ao adquirente (**ASLC063 / ASLC067**). Em seguida, ele emite um evento de cancelamento confirmado pelo domicílio com o NUliquid.

## Entrada da IF Domicílio

***

Como a instituição domicílio, o Lerian SLC recebe os avisos de liquidação de crédito e débito (**ASLC022 / ASLC024 / ASLC032**). Ele os confirma (**ASLC023 / ASLC025 / ASLC033**). Ele emite retornos e devoluções (**ASLC041 / ASLC042 / ASLC043**). Um webhook identificado pelo NUliquid sinaliza o crédito ao lojista e carrega a evidência de retorno.

## Compensação e financiamento para a IF Liquidante

***

Para a instituição liquidante, o Lerian SLC consome as mensagens de compensação de entrada pela RSFN. São a confirmação de recebimento do arquivo (**GEN0015**), a posição de compensação prévia e final (**SLC0001**), a divergência de movimento bilateral (**SLC0002**) e o status operacional do participante (**PAG0101**). O Lerian SLC constrói a **posição de compensação por ciclo de liquidação** e a concilia com as instruções esperadas. Ele analisa e expõe a divergência bilateral **SLC0002**. Ele dispara eventos para prévia disponível, final disponível, depósito necessário e prazo de depósito se aproximando.

## Ciclo de vida da operação

***

O NUliquid rastreia cada operação por um ciclo de vida de **11 estados**.

| Estado            | Significado                                            |
| ----------------- | ------------------------------------------------------ |
| **CREATED**       | A operação foi aceita no Lerian SLC.                   |
| **QUEUED**        | Ela está na fila para a próxima construção de arquivo. |
| **SENT**          | Seu arquivo foi transmitido à Nuclea.                  |
| **ACKNOWLEDGED**  | A Nuclea confirmou o recebimento.                      |
| **ACCEPTED**      | A Nuclea aceitou a operação.                           |
| **REJECTED**      | A Nuclea rejeitou a operação.                          |
| **FORWARDED**     | O aviso de liquidação foi repassado à IF Domicílio.    |
| **CONFIRMED**     | O domicílio confirmou.                                 |
| **SETTLED**       | A operação foi liquidada.                              |
| **D1\_CONFIRMED** | A liquidação é confirmada em D+1.                      |
| **CANCELLED**     | A operação foi cancelada.                              |

Os arquivos têm seu próprio ciclo de vida de **10 estados**, da construção até a transmissão e a correlação de retorno.

<h2 id="signing-orchestration">
  Orquestração de assinatura
</h2>

***

O Lerian SLC materializa o XML ASLC não assinado e então **delega a assinatura a um backend de custódia escolhido por tenant**. A chave privada nunca sai da custódia do cliente, e a Lerian nunca assina em nome do cliente.

| Backend de custódia   | Onde a chave fica                                     |
| --------------------- | ----------------------------------------------------- |
| **Chave de software** | Uma chave mantida em software no ambiente do cliente. |
| **PKCS#11 HSM**       | Um módulo de segurança de hardware.                   |
| **Cloud KMS**         | Um serviço de gerenciamento de chaves na nuvem.       |

Os deployments SaaS travam a custódia em um cloud KMS por meio de **importação de chave encapsulada no lado do cliente**. O cliente encapsula e importa sua própria chave. O serviço armazena apenas o certificado público e uma referência de chave, nunca o material privado.

## Transporte

***

O Lerian SLC submete as operações online à Nuclea pelo **REST**. O **mTLS** e uma assinatura **JWS por requisição** protegem esse canal (a série online SLC0908 / SLC0912 / SLC0915). Os retornos de entrada são consultados por polling e confirmados pelo mesmo canal REST.

A transmissão de arquivos é a única superfície com escolha por tenant: **REST** ou **Connect:Direct** pela RSFN privada. O REST adiciona o JWS por requisição porque atravessa a internet pública. O Connect:Direct não precisa disso, já que o payload já carrega sua assinatura SPB e a rede é privada.

<Note>
  O cliente de transporte do Connect:Direct ainda não está provisionado. Um tenant configurado para ele falha de forma fechada com um erro de transporte tipado. Ele não recorre silenciosamente ao REST, então o REST é o único canal que transporta arquivos hoje.
</Note>