> ## 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 o Lerian SILOC funciona > Ciclo de vida da conexão de gateway, processamento SFN configurado por MQ, despacho de mensagens aceitas, entrega pelo menos uma vez com deduplicação durável, requisições de saída e tratamento de certificados. O Lerian SILOC expõe operações tipadas sobre a superfície `/api/v1/siloc`. Por uma única conexão com a Núclea, ele recebe mensagens do SILOC e roteia cada uma, e envia as requisições da própria instituição. O serviço também mantém os registros de participante, certificado e cobertura que dão suporte a esse trabalho. ## Ciclo de vida da conexão de gateway *** Um descritor de conexão MQ do SILOC completo ativa o processamento SFN de entrada. O serviço então abre e mantém uma conexão de gateway de mensageria com o SILOC da Núclea pela rede do sistema financeiro nacional. Quatro proteções protegem a conexão: * um **circuit breaker** que abre após falhas repetidas, * **reconexão automática** com backoff limitado, * uma **parada por credencial desabilitada** que interrompe o gateway após uma revogação de certificado, e * uma **sonda de readiness** que informa a conexão e a saúde do gateway. Sem o descritor, o serviço inicia sem conectividade SILOC ativa, e um descritor parcial impede o serviço de iniciar. Consulte [Variáveis de ambiente](https://docs.lerian.studio/pt/rails/siloc/siloc-environment-variables.md). Com o descritor completo configurado, o serviço descriptografa e decodifica as mensagens de entrada a partir do envelope regulado antes de roteá-las. ## Despacho SFN de entrada *** Após a decodificação, a ingestão seleciona uma rota a partir de uma política fechada **(`CodProdt`, `CodMsg`)**: | Mensagens | Produto | Rota | | - | - | - | | **PAG0102**, **LDL0021**, **PAG0103** | SLC | Repasse ao Lerian SLC | | **PAG0101** | OT ou SLC | Status de participante, por produto | | **PAG0102**, **LDL0021**, **PAG0103** | OT | Abertura de ciclo, instrução de depósito e encerramento de ciclo | | **LDL0024**, **LDL0028** a **LDL0031** | OT | Grade de horários e avisos de sessão da câmara | | **LDL0001**, **LDL0007**, **LDL0010**, **LDL0013**, **LDL1018**, **LDL1026**, **LDL1027** | Nenhum | Avisos da câmara | | **LDL1001**, **LDL1011**, **LDL1014** | Nenhum | Avisos de colateral | | **LTR0001**, **LTR0007**, **LTR0012**, **SLC0001**, **SLC0002R2**, **SLC0003**, **SLC0005**, **SLC0004R2** | Nenhum | Avisos de cartão, repassados ao Lerian SLC | | **PAG0200** | Nenhum | Saldos bilaterais | | O aviso `R2` de uma transferência PAG | Nenhum | Aviso de crédito de transferência | | **GEN0015** | Nenhum | Aviso de arquivo disponível e o resultado multilateral da câmara | | Uma resposta ou recusa a uma requisição que a instituição enviou | O produto da requisição | Resposta à requisição | O repasse ao SLC age na chegada. O serviço estaciona toda outra mensagem roteada e a aplica depois: `PAG0101` quando `STATUS_REPLAY_ENABLED=true`, e as demais quando `OT_REPLAY_ENABLED=true`. `LDL0020`, `LDL0006` e todo outro par produto/código falham de forma fechada para uma exceção de operador, e o serviço nunca os repassa como funding de liquidação. Uma mensagem com `BCMSG.NUOp` em branco segue o mesmo caminho de falha fechada. ## Despacho pelo menos uma vez com deduplicação durável *** A origem pode reenviar uma mensagem, então o repasse ao SLC é **pelo menos uma vez**. Para um frame de funding do SLC decodificado com sucesso e com `BCMSG.NUOp` não em branco, o serviço verifica a deduplicação durável antes do repasse. A chave é a parte da mensagem: seu **`BCMSG.NUOp`** e seu número de parte, `NumSeq`. Uma mensagem enviada inteira é a parte 1. O serviço grava o registro de mensagem processada apenas após um repasse bem-sucedido e antes de confirmar o recebimento à origem. Ele não cria esse registro para uma mensagem não decodificada ou não aceita. Uma falha antes de o serviço gravar esse registro pode deixar a mensagem elegível para outra entrega. Não trate esse comportamento como uma garantia incondicional de exatamente uma vez de ponta a ponta. ## Resultados de falha *** * Uma falha **sujeita a nova tentativa**, como uma indisponibilidade de datastore, devolve o frame à fila de recebimento, e o serviço o recebe novamente após `MQ_BACKOUT_DELAY`. O serviço estaciona em seu banco de dados, para um operador, um frame recusado mais de `MQ_BACKOUT_THRESHOLD` vezes, e gera `INBOUND_QUARANTINED`. O frame sai da fila de recebimento somente depois que o serviço o estaciona. * Uma falha **não sujeita a nova tentativa**, como um par (`CodProdt`, `CodMsg`) não aceito, falha de forma fechada para uma exceção de operador durável. O serviço confirma a mensagem apenas após o commit desse registro de exceção. * Quando o repasse ao Lerian SLC está fora do ar, o serviço estaciona o frame de funding como uma falha de repasse e gera `RELAY_DOWN`. Um operador o reprocessa depois que o repasse se recupera. * Antes de aplicar uma mensagem estacionada, o serviço a valida contra o XSD oficial. O serviço nunca aplica uma mensagem que o schema recusa, e gera `INBOUND_SEMANTIC_REJECTED`. Enquanto o validador não dá resposta, a mensagem aguarda e o serviço gera `XSD_VALIDATOR_DOWN`. * O registro de mensagem processada protege apenas as mensagens decodificadas com sucesso e aceitas descritas acima. Ele não garante a retenção de todo frame nem efeitos de exatamente uma vez em todo sistema downstream. ## Observabilidade da ingestão *** * **Listar mensagens repassadas**: o feed de auditoria das mensagens de funding que o serviço repassou ao Lerian SLC. * **Ler status do repasse**: a saúde do repasse (`HEALTHY`, `DEGRADED` ou `DOWN`), se a liquidação de cartão está bloqueada, e o timestamp do último repasse. ## Requisições de saída *** O serviço envia as requisições da própria instituição à Núclea: transferências, movimentações de colateral, consultas, confirmações e alterações de status de participante. Uma requisição ainda `DISPATCHED` após seu prazo de resposta gera `UNANSWERED_REQUEST`. Depois que o gateway aceita uma mensagem de saída na fila, o Lerian SILOC registra sua transição de `SUBMITTED` para `DISPATCHED` no banco de dados. Uma falha de despacho que permite nova tentativa a mantém em `SUBMITTED` para outra tentativa, até que o prazo dela acabe. O dia de movimento de uma requisição é o `DtMovto` que o documento dela carrega, e uma requisição não sai depois que esse dia termina. Uma consulta é a exceção: o `DtMovto` dela pode nomear um dia passado, e o dia de movimento dela é o dia em que você a envia. * `LTR0002`, `LTR0008` e `SLC0004` pertencem ao ciclo LBTR do seu dia de movimento. O ciclo vai das 06h40 de Brasília às 17h30, ou até o fechamento posterior que um operador registrou para esse dia (veja [Operando o Lerian SILOC](https://docs.lerian.studio/pt/rails/siloc/siloc-operations.md)). Uma mensagem armazenada antes das 06h40 espera sem ser enviada até o ciclo abrir. `lastError` informa que ela espera, e nenhuma tentativa é contada. Um dia que não é dia útil não tem ciclo: o Lerian SILOC recusa com 422 `SILOC-0025` um `LTR0002` ou `LTR0008` que você envia para ele, e um comando do Lerian SLC termina em `FAILED` com o motivo `lbtr_closed`. * Os outros códigos expiram quando o dia de movimento deles termina, à meia-noite de Brasília, ou no fechamento posterior que um operador registrou para esse dia. Uma requisição não enviada que expira passa a `FAILED`, e `lastError` informa o motivo. Um `LTR0002` ou `LTR0008` para uma operação cuja resposta anterior está `SUBMITTED`, `DISPATCHED` ou `ANSWERED` não aceita uma segunda resposta: ele é recusado com 409 `SILOC-0026`, e nada é armazenado. Uma resposta anterior que terminou em `FAILED` ou `REFUSED` reabre a operação, e uma confirmação `LTR0002` ou `LTR0008` respondida (`C`) ainda aceita uma resposta `D` para a mesma operação. ### Requisições retidas à espera de resposta Quando o prazo acaba, uma requisição que pode já ter chegado à Núclea não é marcada como falha nem enviada de novo. Ela fica em `SUBMITTED` com `heldForAnswer` igual a `true`. Um `LTR0002` ou `LTR0008` em `DISPATCHED` cujo ciclo LBTR terminou sem `R1` é retido do mesmo modo e continua em `DISPATCHED`. Liste essas requisições com `GET /api/v1/siloc/outbound/messages?held=true`. Se a Núclea responde, a resposta é aplicada como de costume. Se a Núclea nunca responde, dois operadores diferentes encerram a requisição: 1. O primeiro operador [pede o fechamento](https://docs.lerian.studio/pt/reference/rails/siloc/ask-to-close-a-held-outbound-message-or-to-declare-its-outcome.md), com a evidência em `reason`. 2. Um segundo operador [aprova o fechamento](https://docs.lerian.studio/pt/reference/rails/siloc/approve-the-close-of-a-held-outbound-message-as-failed.md). A requisição termina em `FAILED`, e um alerta `UNANSWERED_REQUEST` aberto para ela é encerrado. Enquanto um fechamento posterior registrado para o dia mantém aberto o ciclo LBTR de uma requisição `DISPATCHED`, os dois passos respondem 409 `SILOC-0009`. Somente pessoas podem fazer isso. Uma credencial de máquina recebe 403, e o operador que pediu não pode aprovar. Se a resposta da Núclea chega à requisição antes da aprovação, o pedido de fechamento termina como substituído e a requisição fica como a resposta a deixou. Uma resposta da Núclea retida para a requisição bloqueia o fechamento simples. Quando o serviço recusou essa resposta pelo conteúdo, os dois operadores declaram o resultado que a resposta informa, e o primeiro operador a nomeia em `parkedAnswerId`: * `FAILED`, para a resposta `E` da requisição. A requisição termina em `REFUSED`. * `SETTLED` com `settledAt`, para a resposta `R1` de um `LTR0002`, de um `LTR0008` ou de uma transferência PAG. A requisição termina em `ANSWERED`. Para uma transferência PAG, o primeiro operador também digita `numCtrl` (`NumCtrlPAG`) e `situation` (`SitLancPAG`), e `settledAt` é o `DtHrSit` da resposta. O aprovador digita os mesmos valores. As outras respostas não podem ser declaradas. Cada leitura da requisição mostra `closeRequest` e as respostas retidas em `parkedAnswers`, cada uma com sua mensagem em base64. ## Diretório de participantes *** O Lerian SILOC mantém um diretório dos participantes do SILOC para os quais ele liquida. Você **registra**, **lista**, **consulta** e **atualiza** um participante, e lê o **status** de um participante. Cada participante carrega seu ISPB e seu papel. O serviço mantém o status operacional de um participante por produto, e as mensagens `PAG0101` da câmara o definem. Registrar ou atualizar um participante, ou uma alteração do seu status, emite um fato de participante. As gravações de registro são idempotentes por meio do header `X-Idempotency`, então um registro repetido não cria uma duplicata. | Papel | Significado | | - | - | | **Direto** | Um participante direto do SILOC. | | **Indireto** | Um participante que liquida por meio de outra instituição. | | **Instituição liquidante** | A instituição que liquida em nome dos participantes indiretos. | O status operacional usa o domínio de sete valores de status do SILOC: | Valor | Status | | - | - | | 1 | Participando | | 2 | Excluído do ciclo | | 3 | Excluído do SILOC | | 6 | No ciclo, excluído do SILOC | | 7 | Suspenso | | 8 | Suspenso, excluído do ciclo | | 9 | Inoperante (regime especial) | ## Certificados regulados *** O serviço mantém os certificados regulados da conexão como referências, não como segredos. Você **registra** um certificado público junto com uma **referência de custódia externa**. O serviço extrai do certificado seu assunto, número de série e janela de validade, e não armazena nenhuma chave privada. Você então **lista**, **consulta** e **revoga** certificados pela mesma superfície. ## Cobertura de capacidades *** Uma **listagem de capacidades** somente leitura descreve as capacidades de cobertura de liquidação como uma superfície de transparência. Para cada tipo de mensagem, ela informa a direção, o estado de implementação e a disposição. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.