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

# Operação do Lerian SPB

> Operação do Lerian SPB: janelas de funcionamento do STR do BACEN (GEN0021), rotação do certificado de assinatura ICP-Brasil, contingência e conciliação de liquidação caso a caso.

O Lerian SPB opera dentro de duas realidades operacionais do STR. O STR abre apenas dentro das janelas de funcionamento do BACEN. A liquidação é sempre assíncrona. O trilho persiste cada mensagem antes de despachá-la, então nunca envia uma mensagem não registrada.

## Janelas de funcionamento

***

O BACEN anuncia as grades de janela de funcionamento do STR pelo GEN0021. O trilho as persiste, e você consulta as grades atuais com o STR0001. O trilho também envia, de segunda a sexta-feira, um STR0001 para as grades do dia. Uma visão de agenda ao vivo lista os horários de abertura e de fechamento por data de referência. O último anúncio para uma data de referência prevalece.

O trilho não impõe uma rejeição genérica de cada envio fora de uma janela de funcionamento. A sua regra explícita de admissão ligada à agenda é a RLPI0007: durante a janela de aporte adicional, ele rejeita um aporte para uma Conta PI de terceiros. Aportes para a Conta PI da própria instituição e resgates continuam permitidos.

O trilho fecha uma mensagem que não saiu até o fechamento da sua grade do STR no seu dia de movimento. A mensagem termina `FAILED` sem ser enviada. Uma transferência, uma movimentação ou uma perna LTR0003 ou LTR0006 informa `settlement.failed`. Qualquer outra perna LDL ou LTR informa o seu fato de falha `spb.ldl`, cujo `refusal.railClose` é `GRADE_CLOSED` ou `DAY_ENDED`. Quando o trilho não tem o horário de fechamento dessa grade nesse dia, ele fecha a mensagem quando o dia de movimento termina.

Uma mensagem que um envio pode ter entregado não fecha dessa forma. O trilho a marca como `SENT` e não a envia de novo depois da sua grade. A mensagem aguarda a resposta do BACEN ou que operadores a fechem como falha.

## Rotação de certificados

***

O trilho faz hot reload do certificado ICP-Brasil e da chave da identidade SFN dele sem reiniciar. Uma rotação carrega a nova chave da custódia que `SPB_SIGNER_KIND` define, e grava evidência de auditoria. Depois, o trilho assina com a nova chave. Até o próximo reinício, ele descriptografa com a nova chave e com a anterior, então as mensagens que o BACEN criptografou para o certificado anterior ainda abrem.

Uma ativação anuncia o novo certificado ao BACEN pelo GEN0006. O trilho lê o código do certificador da ativação a partir do emissor do certificado e o registra na rotação. Uma ativação responde `SPB-0003` quando o registro do certificado não tem código do certificador. Rotacione o certificado de novo para registrá-lo. As respostas nunca expõem o caminho da chave privada nem qualquer material de chave. Avisos de certificado aparecem nas visões de readiness e de resumo antes de o certificado expirar.

Depois de uma rotação, defina `PROCESS_CERT_PATH` e a configuração de chave da sua custódia com o novo certificado e a nova chave antes do próximo reinício. O trilho se recusa a iniciar com um certificado que vence antes do certificado rotacionado.

O BACEN anuncia um novo certificado próprio pelo GEN0018. O trilho aceita mensagens de entrada assinadas com esse certificado assim que o GEN0018 chega. A partir de 00:00 no horário de Brasília da data de ativação, ele criptografa as mensagens de saída para o novo certificado. `BACEN_PUBLIC_CERT_PATH` não precisa de mudança, e o trilho não precisa reiniciar.

## Contingência e durabilidade

***

* **Persistir antes de enviar** garante que o trilho não despacha nenhuma mensagem não registrada.
* Uma **varredura de despacho** reenvia uma mensagem que não saiu, sem limite de tentativas. `DISPATCH_RETRY_BACKOFF_CEILING` define a espera mais longa entre dois envios.
* Enquanto a conexão com o queue manager está fora do ar, o trilho recusa cada requisição que enviaria uma nova mensagem STR com `503` e `SPB-1001`. Ele não armazena nada para essa requisição. As leituras e as demais requisições continuam funcionando. A verificação `ibm-mq` do `/readyz` aparece como fora do ar, e essa verificação sozinha não faz o `/readyz` falhar. Quando o queue manager recusa a configuração do trilho, o `/readyz` falha.

## Conciliação

***

O trilho abre um caso de conciliação para uma operação que precisa de revisão, como uma que está travada ou tem um resultado incerto. Um operador resolve um caso registrando uma ação sobre ele. O trilho resolve um caso que um envio com falha ou incerto abriu quando a mensagem deixa de aguardar o envio. Um caso terminal não aceita mais ações. Um caso é registrado na família da mensagem a que se refere, por exemplo liquidez, redesconto ou compulsório.

## Invariantes de liquidação

***

Dois invariantes valem o tempo todo:

* **Um envio é despacho, não confirmação.** `SUBMITTED` (um TED) ou `PENDING` (uma movimentação de Conta PI ou SME) significa que o trilho aceitou o despacho. A perna R de entrada move a mensagem STR do TED para `CONFIRMED` ou `REJECTED`. Essa perna R carrega os campos de liquidação do BACEN, por exemplo `numCtrlSTR` e `sitLancSTR`, projetados literalmente.
* **O trilho é neutro em relação ao dinheiro.** Ele encaminha os valores declarados exatamente e não calcula posição nem saldo. O seu consumidor de ledger registra qualquer posição contábil.


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