> ## 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 de operações, submissões online e arquivos ASLC, assinatura por custódia, retornos da Núclea, compensação e financiamento, e o ciclo de vida de liquidação identificado pelo NUliquid.

O Lerian SLC executa um único pipeline de liquidação para cada operação de cartão. Ele recebe a operação, a submete à Núclea e correlaciona o veredito e os retornos da Núclea. Um backend de custódia assina cada submissão. O NUliquid rastreia a operação depois que a Núclea a aceita.

## Entrada

***

As operações entram no Lerian SLC pela API de operações:

* **Entrada individual.** Uma operação em JSON. A chave de deduplicação do chamador é `externalId`. Uma submissão reenviada nunca é liquidada duas vezes.
* **Entrada em lote.** NDJSON, uma operação por linha, até 50.000 linhas por padrão. O Lerian SLC conta as linhas e os bytes antes de salvar qualquer coisa, então um lote acima do limite responde **413** e não salva nada. Uma linha inválida é recusada sozinha e não interrompe o lote.

A entrada de arquivos também aceita um artefato que a instituição já assinou. O Lerian SLC registra o checksum e os metadados do artefato para auditoria. Ele não interpreta nem transmite o artefato.

Você submete três tipos de operação: **CREDIT**, **DEBIT** e **ANTICIPATION**. Um **CANCELLATION** segue regras próprias, porque carrega uma categoria de motivo regulatório e o identificador da operação que ele cancela. O Lerian SLC recusa o **SWEEP** na entrada: ele mesmo constrói os arquivos de resumo de sweep (varredura). Você também pode cancelar uma operação localmente enquanto ela está em **CREATED** ou **QUEUED**, antes que a Núclea a receba.

## Submeter, assinar, transmitir, correlacionar

***

O Lerian SLC envia dois tipos de tráfego à Núclea:

* **Submissões online.** As operações de crédito, débito e antecipação vão para a Núclea como submissões JSON: **SLC0914** para um crédito, **SLC0913** para um débito e **SLC0912** para uma antecipação. O Lerian SLC consulta a **SLC0915** por polling para obter o veredito da Núclea sobre cada submissão.
* **Arquivos ASLC.** Os cancelamentos, os encaminhamentos à IF Domicílio, os repasses de status à credenciadora e os resumos de sweep trafegam como arquivos ASLC. O Lerian SLC constrói cada arquivo como UTF-16BE sem BOM e valida esses bytes finais contra o XSD da mensagem antes de montar o envelope de segurança. Ele compacta o arquivo com **GZIP** e o envolve no **envelope de segurança SPB**, que um backend de custódia assina (veja [Orquestração de assinatura](#signing-orchestration)).

O Lerian SLC correlaciona cada retorno com a operação que o produziu, pela chave que a contraparte ecoa. Uma linha **RET** usa o número de controle de 20 posições derivado do `externalId` da operação, preenchido com zeros à esquerda quando mais curto. Uma linha **ASLC023** ou D+1 usa seu **NUliquid**. Um **PRO** em nível de arquivo, e um **RET** de **ASLC060** ou **ASLC064**, usam o número de controle do arquivo transmitido. Uma linha cuja chave não corresponde a nada é ignorada como não correlacionada.

### Quando um retorno se contradiz

Um único arquivo de retorno pode declarar dois resultados diferentes para a mesma referência. O Lerian SLC resolve isso por política, independentemente da ordem das linhas 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 o Lerian SLC registra em log e conta a aceitação substituída.

O resultado é o mesmo independentemente da ordem em que as duas linhas chegam. O arquivo nunca é abortado: todas as outras referências nele continuam sendo processadas, e o retorno ainda é confirmado.

## Famílias de mensagens

***

| Fluxo | Mensagens |
| - | - |
| Submissão (crédito / débito / antecipação) | SLC0914 / SLC0913 / SLC0912, veredito SLC0915 |
| Encaminhamento à IF Domicílio | ASLC022 / ASLC024 / ASLC032 |
| Resposta da IF Domicílio | ASLC023 / ASLC025 / ASLC033 |
| Repasse de status à credenciadora | ASLC028 / ASLC030 / ASLC034 |
| Resultado D+1 | ASLC041 / ASLC042 / ASLC043 |
| Cancelamento | ASLC060–ASLC067 |
| Sweep (varredura) | ASLC050 / ASLC051 |

## Fluxos de liquidação

***

* **Crédito, débito e antecipação.** O Lerian SLC submete a operação e lê o veredito da Núclea. Depois que a Núclea a aceita, o Lerian SLC encaminha o aviso de liquidação à IF Domicílio por meio da Núclea. Ele lê a resposta da IF Domicílio e a repassa à credenciadora. O resultado D+1 da IF Domicílio encerra o ciclo de vida.
* **Cancelamento.** A credenciadora informa um cancelamento (crédito **ASLC060**, débito **ASLC064**). O Lerian SLC o encaminha à IF Domicílio (**ASLC061**, **ASLC065**) e lê a resposta (**ASLC062**, **ASLC066**). Quando a IF Domicílio confirma o cancelamento, o Lerian SLC emite `cancellation.confirmed_by_domicile`.

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

***

Para a instituição liquidante, o Lerian SLC consome as mensagens de compensação da Núclea pela RSFN: a posição de compensação prévia e final (**SLC0001**) e a divergência de movimento bilateral (**SLC0002**). A **GEN0015** informa um arquivo disponível para retirada, e a **PAG0101** carrega o status operacional de um participante. Do [Lerian SILOC](https://docs.lerian.studio/pt/rails/siloc/what-is-lerian-siloc.md), ele recebe a abertura (**PAG0102**) e o fechamento (**PAG0103**) do ciclo e o valor do depósito (**LDL0021**).

O Lerian SLC mantém a posição de compensação por ciclo de liquidação. Quando um ciclo fecha, ele compara a instrução de liquidação de cada participante com a posição final e marca o ciclo como conciliado quando elas coincidem. Ele gera um evento `clearing.*` para cada etapa.

1. O Lerian SLC repassa o valor do depósito à instituição como `clearing.deposit_required`.
2. A instituição faz o depósito pela sua própria conexão com o STR. O Lerian SLC não envia a mensagem de depósito.
3. A instituição registra o resultado com a confirmação de depósito, `SENT` ou `FAILED`. `SENT` confirma a instrução de liquidação. `FAILED` é registrado, deixa a instrução em aberto e gera `funding.deposit_failed`.
4. Uma operação de crédito ou débito passa de **CONFIRMED** para **SETTLED** quando as duas confirmações existem: a confirmação de depósito da instituição e o fechamento do ciclo da Núclea.

Uma antecipação é liquidada fora do ciclo multilateral. Ela passa de **CONFIRMED** para **SETTLED** com a confirmação da IF Domicílio, sem confirmação de depósito e sem fechamento de ciclo.

## Liquidação bruta (LBTR)

***

Do Lerian SILOC, o Lerian SLC recebe os avisos de liquidação bruta: um resultado de liquidação (**LTR0001**), uma operação entre dois não liquidantes da própria instituição (**LTR0007**) e o cancelamento de um resultado (**LTR0012**). A instituição responde pelo Lerian SILOC:

* A **LTR0002** confirma um resultado ou diverge dele.
* A **LTR0008** confirma ou rejeita uma operação de não liquidante.
* A **LTR0009** solicita a posição LBTR da instituição.

Um comando passa de **REQUESTED** para **ACCEPTED** e depois para **ANSWERED**, **REFUSED** ou **FAILED**. **ACCEPTED** significa que o Lerian SILOC colocou o comando na fila. Não significa que algo foi liquidado. O Lerian SLC não calcula a posição LBTR. A câmara de compensação responde à consulta de posição.

O Lerian SLC entrega esses comandos ao Lerian SILOC pelo produtor de streaming do Lerian SLC. Enquanto `STREAMING_ENABLED` é `false`, o Lerian SLC não os entrega.

## Ciclo de vida da operação

***

Cada operação segue um ciclo de vida de onze estados. A Núclea atribui seu NUliquid quando a operação é aceita.

| Estado | Significado |
| - | - |
| **CREATED** | O Lerian SLC aceitou a operação. Ela permanece em CREATED até que um operador a reenfileire. |
| **QUEUED** | A operação aguarda sua janela na fila de envio. |
| **SENT** | O Lerian SLC submeteu a operação à Núclea. |
| **ACKNOWLEDGED** | A Núclea confirmou o recebimento. |
| **ACCEPTED** | A Núclea aceitou a operação. |
| **REJECTED** | A Núclea recusou a operação, ou a IF Domicílio a recusou antes da liquidação ou em D+1, depois da liquidação. |
| **FORWARDED** | O Lerian SLC encaminhou o aviso de liquidação à IF Domicílio. |
| **CONFIRMED** | A IF Domicílio confirmou. |
| **SETTLED** | O Lerian SLC registrou o sinal de liquidação: as etapas de financiamento acima, para um crédito ou débito, ou a confirmação da IF Domicílio, para uma antecipação. |
| **D1\_CONFIRMED** | A IF Domicílio confirmou a operação liquidada em D+1. |
| **CANCELLED** | A operação foi cancelada localmente, a partir de **CREATED** ou **QUEUED**. |

## Orquestração de assinatura

***

O Lerian SLC constrói o payload não assinado e delega a assinatura a um backend de custódia. Cada certificado registrado indica seu backend.

| Backend de custódia | Onde a chave fica |
| - | - |
| **Chave de software** | Um arquivo de chave no ambiente do cliente. |
| **PKCS#11 HSM** | Um módulo de segurança de hardware. |
| **AWS KMS** | Uma chave no AWS Key Management Service. |

Os deploys SaaS travam a custódia no AWS KMS. O Lerian SLC nunca recebe a chave privada de assinatura em texto claro: o cliente encapsula o material da sua chave localmente com um token de importação, e o serviço importa o material encapsulado para uma chave KMS desse tenant e participante. O serviço armazena o certificado público e uma referência de chave.

## Transporte

***

O Lerian SLC envia suas submissões online e seus arquivos ASLC à Núclea por **REST**, protegido por **mTLS** e por uma assinatura **JWS por requisição**. Ele consulta por polling e confirma os retornos da Núclea pelo mesmo canal.

> [!NOTE]
>
> Você define o transporte de saída em runtime, e o REST é o padrão. Um tenant configurado para **Connect:Direct** falha de forma fechada com um erro de transporte tipado. Ele não recorre ao REST.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.