> ## 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 suportadas. Ele não mantém posição contábil.

## Janelas de liquidação

***

O SILOC liquida em base líquida multilateral diferida, em dias úteis. A Nuclea 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.

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

* O processamento de SFN de entrada começa quando você configura o descritor completo de conexão MQ do SILOC. Sem um gatilho de conexão, o serviço inicia sem conectividade real com o SILOC. Definir `MQ_HOST`, `MQ_CHANNEL`, `MQ_QUEUE_MANAGER`, `MQ_SEND_QUEUE` ou `MQ_RECEIVE_QUEUE` aciona a validação do descritor completo na inicialização. Fornecer apenas parte do descritor falha de forma fail-closed e impede que o serviço inicie.
* Um envelope que não pode ser decodificado, uma mensagem decodificada sem um `BCMSG.NUOp` não vazio, ou um par não suportado de **(`CodProdt`, `CodMsg`)** falha de forma fail-closed para uma exceção de operador. O serviço suporta `PAG0101` para `OT` e `SLC`: ele mantém o status do participante pendente. O serviço não suporta `LDL0020` e `LDL0006`, e nunca os repassa como funding de liquidação.
* Uma falha de despacho passível de nova tentativa não é confirmada. Com commits de origem seguros por offset, o serviço a lê novamente após um restart, a partir do último offset confirmado. Uma falha transitória persistente pode travar sua partição até o restart.
* 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`** antes do repasse e grava o registro de mensagem processada apenas depois que o repasse é bem-sucedido. Isso não é deduplicação apenas por ID de mensagem e não é uma garantia incondicional de exatamente uma vez de ponta a ponta.

## Conciliação

***

A conciliação roda em várias granularidades para que o estado da conexão nunca se desvie:

* **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 usa `BCMSG.NUOp` e o registra apenas depois de um repasse bem-sucedido. Mensagens não decodificadas e não suportadas não recebem registro de mensagem processada.
* **Feed de auditoria de processamento de mensagens.** O feed de auditoria lista as mensagens SFN suportadas que o serviço despachou.
* **Status por participante e histórico de status.** Cada participante carrega seu status operacional. O serviço mantém toda alteração de status como uma entrada de histórico de evento de status.

## 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, 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`](/pt/reference/rails/siloc/list-cycles) e [`GET /api/v1/siloc/cycles/{cycleId}`](/pt/reference/rails/siloc/get-cycle) listam e inspecionam ciclos. [`GET /api/v1/siloc/cycles/{cycleId}/reconciliation`](/pt/reference/rails/siloc/get-cycle-reconciliation) retorna o resultado da conciliação, e [`GET /api/v1/siloc/cycles/{cycleId}/recalculations`](/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`](/pt/reference/rails/siloc/list-settlement-instructions) e [`GET /api/v1/siloc/settlement-instructions/{instructionId}`](/pt/reference/rails/siloc/get-settlement-instruction) retornam as pernas de obrigação de cada ciclo. [`POST /api/v1/siloc/rocs`](/pt/reference/rails/siloc/ingest-roc) ingere uma revisão semântica de ROC que substitui os valores anteriores do ciclo.
* **Alertas operacionais.** [`GET /api/v1/siloc/alerts`](/pt/reference/rails/siloc/list-alerts) retorna um feed paginado por keyset, apenas com os ativos. Os tipos de alerta incluem `WINDOW_CLOSING` (um prazo de depósito/complemento se aproxima), `RECALCULATION` (um ciclo está em uma rodada de recálculo), `RELAY_DOWN`, `CONNECTION_DOWN`, `CERTIFICATE_EXPIRY` e `SCHEDULE_CHANGE` (um operador registrou um anúncio de contingência de cronograma). Os alertas são encerrados atomicamente quando a condição subjacente é resolvida. Por exemplo, um ciclo que liquida encerra seu alerta `RECALCULATION` no caminho de liquidação. Passe `activeOnly=false` para incluir alertas desativados como histórico.
* **Trilha de auditoria.** [`GET /api/v1/siloc/audit-records`](/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 (valores apenas com data são rejeitados).

## Cronograma e contingência

***

A grade de ciclos do OT e o calendário de dias úteis são artefatos compilados no serviço. A API os projeta literalmente e nunca analisa um wire de cronograma da Núclea.

* **Calendário e janelas.** [`GET /api/v1/siloc/schedule/calendar`](/pt/reference/rails/siloc/get-business-day-calendar) retorna o calendário de dias úteis, e [`GET /api/v1/siloc/schedule/windows`](/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.
* **Alterações de cronograma por contingência.** [`POST /api/v1/siloc/schedule/changes`](/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. 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`](/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" \
  -d '{
    "reason": "Núclea extended the OT window by 30 minutes",
    "origin": "Núclea e-mail ref 2026-07-22/01",
    "effectiveAt": "2026-07-22T18:30:00-03:00",
    "windowSeq": 2
  }'
```