Skip to main content
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). 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.

​
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 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 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. 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 lista os frames de funding estacionados durante uma indisponibilidade do repasse. Reprocesse um frame 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 e GET /api/v1/siloc/cycles/{cycleId} 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 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 e GET /api/v1/siloc/settlement-instructions/{instructionId} 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 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} 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 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 descreve o fechamento por dois operadores.
  • Alertas operacionais. GET /api/v1/siloc/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 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 lista os cenários de certificação e o status de cada um. Executar um cenário 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 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 retorna o calendário de dias úteis, e GET /api/v1/siloc/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 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 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 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 retorna as alterações registradas, das mais recentes para as mais antigas.
Registre uma alteração de cronograma por contingência: