Pular para o conteúdo principal
Esta página descreve como operar a Mensageria. Operando o Lerian SISBAJUD executor descreve o executor.

​
Instituições

POST /v1/institutions registra uma instituição na Mensageria. O corpo tem estes campos: A requisição cria o keyset de tokenização e o keyset de auditoria da instituição. Uma segunda requisição com o mesmo institutionId retorna 409. PATCH /v1/institutions/{institutionId} altera institutionCode, retryPolicyConfig ou enabled.

​
Registre a instituição nos dois componentes

Registre cada instituição na Mensageria e no executor:
  1. Envie POST /v1/institutions à Mensageria com o institutionId da instituição e "enabled": true.
  2. Envie POST /v1/institutions ao executor com o mesmo institutionId e "enabled": true. O corpo do executor também traz a configuração do seu conector do Midaz e aceita os campos opcionais branchFormat e accountFormat. Operando o Lerian SISBAJUD executor descreve essa requisição.
O executor se registra como dono da instituição, a partir da sua própria identidade M2M (EXECUTOR_M2M_SUBJECT). Nenhum campo de requisição define o dono, e um PATCH não o altera. O executor escreve no ledger somente para as instituições das quais é dono.

​
Um cliente por instalação

Cada instalação da Mensageria atende um cliente. Uma instalação pode ter muitas instituições.

​
Ordens que precisam de atenção

GET /v1/institutions/{institutionId}/orders e GET /v1/institutions/{institutionId}/files listam as ordens e os arquivos. As operações de detalhe retornam uma ordem ou um arquivo.

​
Janelas de resposta

O SISBAJUD define o prazo da resposta de bloqueio pelo horário de envio de cada remessa. Uma remessa enviada até as 13:00 BRT vence às 19:00 BRT do mesmo dia. Uma remessa enviada depois das 13:00 BRT vence às 12:00 BRT do próximo dia útil. A Mensageria gera arquivos de resposta em intervalos, não em horários fixos. Defina RETURN_FILE_GENERATION_SCAN_INTERVAL e INFORMATION_RETURN_FILE_GENERATION_SCAN_INTERVAL para que cada ciclo termine dentro da janela do BACEN. Os dois valores são em segundos, e os dois têm padrão de uma hora.

​
Correções de arquivos de resposta

  • POST /v1/institutions/{institutionId}/return-file/generate executa uma geração de arquivo de resposta agora.
  • POST /v1/institutions/{institutionId}/return-file/{id}/reconsolidate libera as ordens de um arquivo de resposta FAILED, para que uma geração posterior possa respondê-las. O arquivo continua FAILED.
  • POST /v1/institutions/{institutionId}/return-file/{id}/resolve-transmission aplica uma correção a um envio que nenhum caminho automático consegue concluir: probe_now, attach_transfer, force_fail ou cancel_now. O reason vai para a trilha de auditoria como foi escrito, então não coloque dados pessoais nem valores nele.
force_fail só segue quando a última tentativa de envio tem pelo menos 5 minutos e o Lerian STA não tem uma transferência do arquivo que ainda possa chegar ao BACEN. Caso contrário, ele retorna 422. Cada correção retorna 503 quando a Mensageria não consegue acessar o Lerian STA.

​
Rotação de chaves

A rotação de chaves é executada por instituição:
  • Chave de criptografia de chaves (KEK). POST /v1/institutions/{institutionId}/security/kek:rotate rotaciona a KEK da instituição. A resposta mostra a versão anterior e a nova versão da KEK. A rotação publica um evento kek.rotated. Com KEK_REWRAP_BACKFILL_ENABLED ativado, um job em segundo plano reenvolve as chaves de dados com a nova versão da KEK. Ele vem desativado por padrão. Com o AWS KMS no modo provided, a Mensageria não rotaciona a sua chave, e a operação retorna 422.
  • Keyset de tokenização. POST /v1/institutions/{institutionId}/security/keyset:rotate adiciona uma nova chave primária ao keyset de tokenização da instituição. Uma instituição sem keyset ativo retorna 422.
Uma rotação de KEK pode retornar estes erros:
  • SBJ-0007 / 409: outra rotação da mesma chave para a mesma instituição está em andamento. Envie-a novamente depois que essa rotação terminar.
  • SBJ-0012 / 409: nada foi rotacionado, e a mesma requisição falha de novo.
  • SBJ-0005 / 404: a instituição não tem chave.
  • SBJ-0008 / 503: o gerenciador de chaves falhou antes da rotação. Envie-a novamente mais tarde.
  • SBJ-0013 / 500: o resultado da rotação não é conhecido. Não envie a rotação novamente. A Mensageria reconcilia o seu registro de chaves quando reinicia.
  • SBJ-0014 / 500: a chave foi rotacionada, mas uma etapa posterior falhou. Não envie a rotação novamente. Fale com o suporte da Lerian.

​
Proteção de dados

  • Criptografia por envelope. A Mensageria criptografa campos sensíveis com AES-256-GCM sob uma chave de dados (DEK). Uma KEK envolve a chave de dados, no HashiCorp Vault Transit ou no AWS KMS. Os dados autenticados adicionais vinculam cada texto cifrado à sua instituição, tabela, registro e campo.
  • Tokenização pesquisável. Um blind index guarda um token do CPF/CNPJ e do número do processo. O token vem de uma chave HMAC-SHA256 da instituição. Ele permite busca por correspondência exata.
  • Leituras mascaradas. O detalhe da ordem e o detalhe do arquivo mascaram campos sensíveis, a menos que o chamador tenha admin:read_pii. A Mensageria registra na trilha de auditoria uma leitura de ordem em texto claro.
  • Trilha de auditoria. GET /v1/institutions/{institutionId}/audit/verify verifica um intervalo do log de auditoria por índice de folha, sem descriptografar nenhum payload. Ele informa adulterações e entradas excluídas.
  • LGPD. POST /v1/institutions/{institutionId}/lgpd/requests abre uma requisição de acesso ou portabilidade. .../resolve registra a decisão. GET /v1/institutions/{institutionId}/lgpd/subject-data exporta os registros de um titular de dados.

​
Papéis

A Mensageria declara quatro papéis de negócio: operator, investigator, compliance-officer e admin. Cada permissão vai para estes papéis: Um papel vale para todas as instituições da instalação. A Mensageria não tem concessão por instituição.

​
Superfície HTTP

As ordens chegam somente como arquivos, então nenhuma operação aceita uma ordem. A API principal escuta em SERVER_ADDRESS. O padrão é :4031. Ela atende estes grupos de operações:
  • Instituições: criar, ler e atualizar.
  • Ordens e arquivos: listas, detalhes, ordens que precisam de atenção, status de SLA e estatísticas.
  • Verificação de auditoria.
  • Requisições LGPD.
  • Justificativas de não conformidade.
  • Correções de arquivos de resposta.
  • Rotação de chaves.
  • Confirmação de dead letter do Lerian STA.
Ela também atende /health, /readyz, /version e as rotas de administração do Systemplane em /system. A API de execução tem seu próprio listener. PLUGIN_AUTH_ENABLED precisa ser true ou false. A Mensageria aceita false somente quando ENV_NAME é development, develop, dev, local ou test, e DEPLOYMENT_MODE não é saas. Com false, as operações protegidas ainda exigem um bearer token. A Mensageria pula somente a verificação do Access Manager.