Skip to main content
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. 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): 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). 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 respondida (C) ainda aceita uma divergência (D).

​
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. 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, com a evidência em reason.
  2. Um segundo operador aprova o fechamento. A requisição termina em FAILED.
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. O status operacional usa o domínio de sete valores de status do SILOC:

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