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

# Operando o Lerian SILOC

> Operação do Lerian SILOC: janelas de liquidação do BACEN, certificados ICP-Brasil, processamento de SFN configurado via MQ, deduplicação durável, monitoramento, alertas e auditoria.

O SILOC liquida em base de líquido diferido, por dia útil. Com a conexão MQ do SILOC configurada, o serviço mantém a conexão do gateway aberta e despacha suas mensagens aceitas. Ele não mantém posição contábil.

## Licença

***

O Lerian SILOC precisa de uma licença da Lerian em todos os ambientes, definida em `LICENSE_KEY` (veja [Variáveis de ambiente](https://docs.lerian.studio/pt/rails/siloc/siloc-environment-variables.md)). Sem ela, o serviço recusa iniciar. Toda rota sob `/api/v1/siloc` passa pelo portão de licença. Uma requisição que a licença recusa responde 403 com um código `LCS-`. `/health`, `/readyz` e `/version` ficam abertos. `/readyz` reporta uma verificação `license` que nunca aparece como down, descrita na [página de variáveis de ambiente](https://docs.lerian.studio/pt/rails/siloc/siloc-environment-variables.md#health-and-readiness).

## Janelas de liquidação

***

O SILOC liquida em base líquida multilateral diferida, em dias úteis. A Núclea define as janelas diárias de liquidação para os produtos de boleto e cartão. O Lerian SILOC registra e aplica as mensagens de ordem de transferência que abrem, avançam, conciliam e fecham o estado do ciclo. Ele não calcula a posição líquida monetária.

## Certificados regulados

***

Você registra os certificados do gateway como um certificado público mais uma referência de custódia externa. O serviço não guarda nenhuma chave privada. Quando você registra um certificado, o serviço analisa seu subject, serial e janela de validade. Você revoga o certificado pela API quando o desativa. Um estado de **credencial desabilitada** interrompe o gateway. Um certificado desabilitado ou revogado aplica fail-close à conexão em vez de funcionar com credenciais inválidas. Enquanto o certificado de assinatura ou o certificado da câmara está revogado ou fora da validade, um serviço em execução continua em rotação e recusa cada nova requisição de saída com 503 `SILOC-0024`. Ele não armazena nada.

## Contingência e recuperação

***

O caminho de ingestão do SFN tem resultados definidos em caso de falha. Ele não promete reter todo frame. Também não promete que toda operação tenha um único efeito de ponta a ponta:

* Uma mensagem decodificada sem um `BCMSG.NUOp` não vazio, ou um par não aceito de **(`CodProdt`, `CodMsg`)** falha de forma fail-closed para uma exceção de operador. O serviço não oferece suporte a `LDL0020` e `LDL0006`, e nunca os repassa como funding de liquidação.
* O repasse do SLC é **pelo menos uma vez**. Para um frame de funding do SLC decodificado com sucesso, o serviço verifica a deduplicação durável por **`BCMSG.NUOp`** e número de parte (`NumSeq`) antes do repasse. Ele grava o registro de mensagem processada apenas depois que o repasse é bem-sucedido. Isso não é uma garantia incondicional de exatamente uma vez de ponta a ponta.
* **Mensagens estacionadas e recusadas.** [`GET /api/v1/siloc/dlq/deferred`](https://docs.lerian.studio/pt/reference/rails/siloc/list-parked-deferred-inbound-messages) lista as mensagens de entrada estacionadas para replay. Filtre com `status=SEMANTIC_REJECTED` para ver as mensagens que o serviço recusou pelo conteúdo e nunca aplica.
* **Frames em quarentena.** [`GET /api/v1/siloc/dlq/quarantine`](https://docs.lerian.studio/pt/reference/rails/siloc/list-quarantined-inbound-frames) lista os frames que o serviço recusou mais de `MQ_BACKOUT_THRESHOLD` vezes e estacionou em seu banco de dados. Cada entrada retorna os bytes do frame em `frame`. Depois de tratar o frame, [resolva o frame](https://docs.lerian.studio/pt/reference/rails/siloc/resolve-a-quarantined-inbound-frame.md). O feed então deixa de retorná-lo. O serviço não o reenvia ao processamento, e encerra `INBOUND_QUARANTINED` quando não resta nenhum frame não resolvido.
* **Indisponibilidade da Núclea.** Enquanto o queue manager do SILOC da Núclea não está acessível, o serviço continua em rotação e mantém as leituras disponíveis. Ele recusa cada nova requisição de saída com 503 `SILOC-0024` e não armazena nada. Quando o queue manager recusa a configuração deste ambiente, `detail` nomeia a configuração a corrigir. Envie a requisição de novo com o mesmo `X-Idempotency` depois que a conexão voltar.
* **Falhas de repasse.** [`GET /api/v1/siloc/dlq/relay-failures`](https://docs.lerian.studio/pt/reference/rails/siloc/list-relay-failures) lista os frames de funding estacionados durante uma indisponibilidade do repasse. [Reprocesse um frame](https://docs.lerian.studio/pt/reference/rails/siloc/replay-relay-failure.md) depois que o repasse se recuperar. Um replay de uma parte de mensagem já repassada resolve o frame sem um segundo repasse.

## Conciliação

***

A conciliação roda em várias granularidades:

* **Ledger de deduplicação de mensagens processadas.** Para frames de funding do SLC decodificados com sucesso e com um NUOp não vazio, o ledger identifica cada parte de mensagem por `BCMSG.NUOp` e `NumSeq`. Ele registra uma parte apenas depois de um repasse bem-sucedido. Mensagens não decodificadas e não aceitas não recebem registro de mensagem processada.
* **Feed de auditoria do repasse.** O feed de repasse lista as mensagens de funding que o serviço repassou ao Lerian SLC.
* **Status por participante e histórico de status.** Cada participante carrega seu status operacional por produto. O serviço registra cada alteração de status como uma entrada de histórico de evento de status.
* **Conciliação de ciclos OT.** Com `RECONCILE_ENABLED=true`, o serviço compara a obrigação de cada ciclo com o resultado multilateral `GEN0015` mais recente da câmara. Um ciclo só liquida quando o resultado corresponde, a obrigação tem sua prova do STR e seu período de depósito tem seu `PAG0103`.

## Monitoramento, alertas e auditoria

***

O Lerian SILOC expõe uma superfície de operador para observar os ciclos de liquidação do OT, a saúde da conexão e do repasse, as requisições de saída e o status do participante. As superfícies de ciclo e conciliação informam o estado registrado e os conjuntos de conciliação. Elas não calculam valores agregados de posição na leitura.

* **Ciclos de liquidação do OT.** [`GET /api/v1/siloc/cycles`](https://docs.lerian.studio/pt/reference/rails/siloc/list-cycles) e [`GET /api/v1/siloc/cycles/{cycleId}`](https://docs.lerian.studio/pt/reference/rails/siloc/get-cycle) listam e inspecionam ciclos. Ambas as leituras trazem o objeto `reconciliation` do ciclo quando existe uma conciliação. Ele nomeia o resultado comparado em `resultNoticeId` e o lado desse resultado em `clearingSide`. [`GET /api/v1/siloc/cycles/{cycleId}/recalculations`](https://docs.lerian.studio/pt/reference/rails/siloc/get-cycle-recalculations) retorna a cadeia de rodadas de recálculo do ciclo, incluindo o fechamento da janela de complemento/depósito de cada rodada.
* **Instruções de liquidação.** [`GET /api/v1/siloc/settlement-instructions`](https://docs.lerian.studio/pt/reference/rails/siloc/list-settlement-instructions) e [`GET /api/v1/siloc/settlement-instructions/{instructionId}`](https://docs.lerian.studio/pt/reference/rails/siloc/get-settlement-instruction) retornam as pernas de obrigação de cada ciclo. Um débito traz `depositAdvisoryId`, o aviso que o comando de depósito do Lerian SPB recebe. Um depósito recusado deixa o débito aberto para um novo depósito. Um depósito que o Lerian SPB encerra sem resposta do STR, porque a grade dele fechou, o dia de movimento terminou ou dois operadores o encerraram, também deixa o débito aberto. A obrigação então registra o motivo em `lastFundingAck.refusal.railClose` (`GRADE_CLOSED`, `DAY_ENDED` ou `OPERATORS_CLOSED`) e não tem `lastFundingAck.refusal.messageCode`. Um `PAG0101` que exclui esta instituição do ciclo encerra seus débitos não depositados.
* **Resultados multilaterais.** [`GET /api/v1/siloc/ot-multilateral-results`](https://docs.lerian.studio/pt/reference/rails/siloc/list-the-siloc-camaras-official-multilateral-results) lista os resultados multilaterais que a câmara envia no `GEN0015`, do mais recente ao mais antigo, como a câmara os enviou. [`GET /api/v1/siloc/ot-multilateral-results/{noticeId}`](https://docs.lerian.studio/pt/reference/rails/siloc/get-the-multilateral-result-one-gen0015-carried) retorna o resultado armazenado de uma notificação `GEN0015`, como a que o `resultNoticeId` de um ciclo nomeia. Uma notificação sem resultado legível responde 404 `SILOC-0007`.
* **Requisições de saída.** [`GET /api/v1/siloc/outbound/messages`](https://docs.lerian.studio/pt/reference/rails/siloc/list-outbound-messages-of-every-code) lista as requisições que a instituição enviou, das mais recentes para as mais antigas. Filtre por `status`: para uma requisição `FAILED`, `lastError` informa o motivo. Ou ela nunca saiu para a Núclea, ou dois operadores a encerraram porque a Núclea nunca respondeu. Uma requisição `REFUSED` voltou da Núclea com um erro. Uma requisição `SLC0004` também termina `REFUSED` quando sua resposta `SLC0004R1` traz uma situação diferente de sucesso, e `lastError` informa `SitLancSLC=<code>`. Filtre por `held=true` para as requisições retidas à espera de uma resposta que a Núclea nunca enviou. [Como o Lerian SILOC funciona](https://docs.lerian.studio/pt/rails/siloc/how-siloc-works.md) descreve o fechamento por dois operadores.
* **Alertas operacionais.** [`GET /api/v1/siloc/alerts`](https://docs.lerian.studio/pt/reference/rails/siloc/list-alerts) retorna um feed paginado por keyset, apenas com os ativos. Passe `activeOnly=false` para incluir alertas desativados como histórico. Os tipos de alerta são:
  * Ciclo de liquidação: `WINDOW_CLOSING` (um prazo de depósito/complemento se aproxima), `RECALCULATION` (um ciclo está em uma rodada de recálculo), `SCHEDULE_CHANGE` (um operador registrou um anúncio de contingência de cronograma) e `OT_CYCLE_NOT_SETTLED`. `OT_CYCLE_NOT_SETTLED` indica um ciclo ainda aberto 60 minutos depois do seu `PAG0103`.
  * Conexão e workers: `CONNECTION_DOWN`, `RELAY_DOWN`, `CERTIFICATE_EXPIRY`, `OUTBOUND_DISPATCHER_DOWN`, `OT_REPLAY_DOWN` e `XSD_VALIDATOR_DOWN`.
  * Avisos da câmara: `CAMARA_CLOSED`, `CAMARA_INTERRUPTED`, `COLLATERAL_REQUIRED`, `COLLATERAL_SUBSTITUTION` e `ELIGIBLE_ASSETS_CHANGED`.
  * Mensagens de entrada e requisições: `INBOUND_QUARANTINED`, `INBOUND_SEMANTIC_REJECTED`, `MULTILATERAL_RESULT_UNREADABLE` (um `GEN0015` da câmara traz um resultado que o serviço não consegue ler) e `UNANSWERED_REQUEST`.
* **Reconhecimento de alertas.** [`POST /api/v1/siloc/alerts/{id}/acknowledge`](https://docs.lerian.studio/pt/reference/rails/siloc/acknowledge-an-operational-alert) registra que um operador viu o alerta, com uma nota opcional de até 500 caracteres, e move o alerta para o histórico. Ele não encerra a condição. Quando o serviço verifica um alerta periodicamente, como `RELAY_DOWN`, ele gera o alerta novamente enquanto sua condição persiste. Um alerta que já está inativo responde 409. `INBOUND_SEMANTIC_REJECTED` e `MULTILATERAL_RESULT_UNREADABLE` só são encerrados por reconhecimento. Um alerta de condição, como `RELAY_DOWN` ou `RECALCULATION`, também é encerrado quando sua condição é resolvida. Por exemplo, um ciclo que liquida encerra seu alerta `RECALCULATION` no caminho de liquidação.
* **Cenários de homologação.** [`GET /api/v1/siloc/homologation/scenarios`](https://docs.lerian.studio/pt/reference/rails/siloc/list-homologation-scenarios) lista os cenários de certificação e o status de cada um. [Executar um cenário](https://docs.lerian.studio/pt/reference/rails/siloc/run-a-homologation-scenario.md) verifica seu critério de aprovação contra o próprio estado do trilho e registra a evidência. Ele não envia nada à Núclea.
* **Trilha de auditoria.** [`GET /api/v1/siloc/audit-records`](https://docs.lerian.studio/pt/reference/rails/siloc/list-audit-records) retorna uma leitura paginada e literal da trilha de auditoria, por exemplo para exportar o registro de uma ação de operador ou de uma alteração de status de participante. Os limites `from` e `to` são instantes RFC3339 (o serviço rejeita valores apenas com data).

## Cronograma e contingência

***

A grade canônica de janelas do OT e o calendário de dias úteis são artefatos compilados no serviço. O serviço projeta literalmente as grades de horários e os avisos de sessão que a Núclea envia.

* **Calendário e janelas.** [`GET /api/v1/siloc/schedule/calendar`](https://docs.lerian.studio/pt/reference/rails/siloc/get-business-day-calendar) retorna o calendário de dias úteis, e [`GET /api/v1/siloc/schedule/windows`](https://docs.lerian.studio/pt/reference/rails/siloc/list-schedule-windows) retorna a grade canônica compilada de janelas do OT. A grade é um artefato estático, não uma leitura por dia, e o serviço a retorna mesmo quando o datastore está fora do ar.
* **Grades e sessão da câmara.** [`GET /api/v1/siloc/schedule/grids`](https://docs.lerian.studio/pt/reference/rails/siloc/list-schedule-grids) retorna as grades de horários que a Núclea enviou, a partir dos seus avisos de alteração e das respostas às consultas de horários da instituição. [`GET /api/v1/siloc/schedule/camara-session`](https://docs.lerian.studio/pt/reference/rails/siloc/get-the-camara-s-last-session-announcements) retorna os avisos mais recentes de abertura, fechamento, interrupção e retomada.
* **Alterações de cronograma por contingência.** [`POST /api/v1/siloc/schedule/changes`](https://docs.lerian.studio/pt/reference/rails/siloc/record-schedule-change) registra um anúncio de contingência que o operador recebeu fora de banda da Núclea. O corpo carrega `reason` (≤500 caracteres), `origin` (o canal do anúncio ou a referência upstream, ≤256 caracteres), `effectiveAt`, o instante RFC 3339 anunciado em que a mudança entra em vigor, e um `windowSeq` opcional nomeando a janela canônica afetada. Com `windowSeq` 1 ou 2, `effectiveAt` passa a ser o fechamento de depósito dessa janela para `WINDOW_CLOSING`. Ele deve cair na data de São Paulo da janela, não antes de ela abrir. Com `windowSeq` 3, `effectiveAt` é o fechamento LBTR posterior que a Núclea anuncia quando estende a grade. `effectiveAt` deve cair depois das 17h30 do dia de movimento e antes das 06h40 do dia seguinte, então um fechamento depois da meia-noite estende o dia anterior. Uma alteração com `windowSeq` 3 para um dia de movimento que não é dia útil responde 422 `SILOC-0022`, porque o ciclo LBTR desse dia fica fechado o dia todo. As mensagens `LTR0002`, `LTR0008` e `SLC0004` desse dia ficam abertas até esse fechamento em vez de até as 17h30, e as demais requisições do dia ficam abertas até ele em vez de até a meia-noite. Um fechamento registrado depois das 17h30 não reabre o que já falhou. O registro é **append-only**: um anúncio posterior nunca reescreve um anterior. O anúncio mais recente se torna o único alerta `SCHEDULE_CHANGE` ativo. Registrar um anúncio encerra o alerta anterior e gera um novo, cujo prazo é `effectiveAt` literal. [`GET /api/v1/siloc/schedule/changes`](https://docs.lerian.studio/pt/reference/rails/siloc/list-schedule-changes) retorna as alterações registradas, das mais recentes para as mais antigas.

Registre uma alteração de cronograma por contingência:

```bash theme={null}
curl -X POST https://siloc.example.com/api/v1/siloc/schedule/changes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency: 2026-07-22-window-2-extension" \
  -d '{
    "reason": "Núclea extended the OT window by 30 minutes",
    "origin": "Núclea e-mail ref 2026-07-22/01",
    "effectiveAt": "2026-07-22T16:20:00-03:00",
    "windowSeq": 2
  }'
```


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