Pular para o conteúdo principal
O Plugin SISBAJUD executa ordens judiciais no ledger Midaz da instituição. As ordens vêm da Mensageria ou, no canal direto, do sistema da própria instituição. Esta página descreve como o plugin recebe uma ordem, o que cada operação escreve e como o plugin informa o resultado. Operando o Plugin SISBAJUD descreve a configuração. Como funciona o Lerian SISBAJUD mostra como uma ordem passa da Mensageria para o Plugin SISBAJUD.

​
Ciclo de vida da ordem

  1. Aviso. O Streaming Hub envia um aviso de execução ao listener de webhook do plugin. O aviso traz o ID da ordem e a revisão da ordem, não a ordem.
  2. Verificação. O plugin verifica a assinatura HMAC da entrega. Ele grava cada aviso assinado antes de responder.
  3. Busca. O plugin obtém a ordem com GET /v1/sisbajud/execution/orders/{orderId} na API de execução da Mensageria.
  4. Verificação do dono. Antes da sua primeira escrita, o plugin verifica que é dono da instituição da ordem.
  5. Execução. No seu próximo ciclo, o plugin executa a operação no Midaz.
  6. Resultado. O plugin envia o resultado com POST /v1/sisbajud/execution/orders/{orderId}/execution-results.

​
Respostas do webhook

O plugin aceita uma entrega com timestamp fora de EXECUTOR_HUB_WEBHOOK_MAX_SKEW_SEC e registra um aviso no log.

​
Respostas da busca

​
Verificação do dono

O plugin escreve no ledger somente para as instituições das quais é dono. Quando cria uma instituição, ele registra o seu próprio subject M2M (EXECUTOR_M2M_SUBJECT) como dono.
  • Se outra identidade é dona da instituição, o plugin não escreve nada e dispara um alarme.
  • Se a instituição não tem configuração neste plugin, a ordem vai para uma decisão humana.

​
Ciclo de execução

O plugin executa um ciclo a cada EXECUTOR_TICK_EVERY. O padrão é 30s. Cada ciclo executa três etapas nesta ordem:
  1. Ingestão. Executa os avisos aceitos.
  2. Verificação de órfãs. Procura operações nas contas de bloqueio que o plugin não escreveu.
  3. Monitoramento. Envia um heartbeat para cada escrita que não tem resultado conhecido.
Uma etapa com falha não interrompe as outras etapas. O plugin drena os resultados que esperam no outbox em um loop separado para cada canal, então um canal lento não segura o ciclo nem outro canal.

​
Resultados

O plugin grava cada resultado em um outbox antes de enviá-lo. Cada envio traz o header X-Idempotency. Quando um envio falha com um erro transitório, o plugin envia o mesmo resultado de novo depois de uma espera, até EXECUTOR_RESULT_MAX_ATTEMPTS tentativas. O padrão é 12. Depois da última tentativa, o plugin estaciona o resultado, registra uma decisão humana e dispara um alarme. Ele não envia de novo um resultado estacionado, e as versões posteriores da mesma ordem esperam atrás dele. Um administrador da plataforma rearma o resultado. Operando o Plugin SISBAJUD descreve a rota. O reasonCode de cada operação está nas seções abaixo.

​
Operações

O bloqueio e o desbloqueio escrevem no Midaz. A requisição de informação somente lê.

​
Bloqueio (BLOQUEIO)

  1. O plugin lê as contas ativas do sujeito. Um sujeito sem conta ativa recebe NONE com NO_CLIENT.
  2. Ele aplica a restrição de agência e conta da ordem. Restrição de agência e conta dá as regras.
  3. Ele bloqueia uma conta salário somente quando a ordem permite contas salário.
  4. Ele bloqueia somente recursos próprios. Uma conta no cheque especial conta como 0.
  5. Ele envia uma escrita ao Midaz. A escrita tem uma perna para cada conta de origem, e todas as pernas vão para a conta de bloqueio da ordem.
Uma ordem de bloqueio pode trazer um valor mínimo. Quando o total que o plugin pode bloquear fica abaixo desse mínimo, ele não escreve nada e passa a ordem para uma decisão humana.

​
Restrição de agência e conta

O plugin lê a agência e o número de cada conta nos instrumentos do CRM do sujeito. Com crmMode embedded, a agência é bankingDetails.branch e o número da conta é bankingDetails.account. Com crmMode legacy, o CRM não traz nenhum dos dois.
  • Uma ordem que indica uma agência vai para uma decisão humana quando uma conta que pode ser a indicada tem agência desconhecida ou ambígua.
  • Uma ordem que indica um número de conta bloqueia as contas cujo número coincide. Ela também bloqueia uma conta de número desconhecido ou ambíguo, até o valor da ordem, porque essa conta pode ser a que o tribunal indicou. As contas cujo número coincide vêm primeiro. Com crmMode legacy, nenhum número é conhecido, então toda conta que passa na regra de agência pode ser bloqueada.
  • Uma ordem com número de conta e sem agência vai para uma decisão humana quando duas ou mais contas coincidem.
  • Com um número de conta, o resultado é NONE quando todos os números de conta são conhecidos e nenhum coincide.

​
Desbloqueio (DESBLOQUEIO)

O desbloqueio libera recursos de uma ordem de bloqueio pai, identificada por parentOrderId. O plugin usa a conta de origem registrada do bloqueio pai como destino da liberação. Se não consegue determinar um único destino com segurança, exige uma decisão humana em vez de adivinhar.
  • Sem uma ordem pai, o resultado é NONE com PARENT_UNRESOLVED, e o plugin não escreve nada.
  • Quando a ordem pai ainda não tem efeito conhecido, o plugin espera. No prazo da ordem menos RESPONSE_DEADLINE_MARGIN, a ordem vai para uma decisão humana. Se a ordem não tem prazo, ela vai para uma decisão humana na hora.
  • O plugin lê a conta de bloqueio da ordem pai quando executa a ordem. Ele libera o menor de três valores: o valor que a ordem pede, o saldo restante da ordem pai e o saldo da conta de bloqueio.
  • Quando o valor a liberar é 0, o resultado é NOTHING_TO_RELEASE.
  • Quando uma conta do sujeito é uma conta salário, a ordem vai para uma decisão humana.

​
Requisição de informação (REQUISICAO_INFORMACAO)

O plugin lê os saldos do sujeito e não escreve nada no ledger. Se o sujeito é cliente, mas não é titular da conta especificada, o plugin exige uma decisão humana em vez de informar que o sujeito não é cliente.
  • Um sujeito com pelo menos uma conta ativa recebe FULL com INFO_FULFILLED.
  • Um sujeito sem conta ativa recebe NONE com INFO_NON_CLIENT.
  • Uma ordem que indica uma agência vai para uma decisão humana.
Quando a ordem pede o saldo (searchBalance), o resultado traz dois totais: o total bloqueável e o total bloqueável das contas salário. Um sujeito sem conta ativa recebe 0.00 nos dois.

​
Canal direto

No canal direto, o sistema da própria instituição envia ordens judiciais ao plugin, e a Mensageria não participa. O plugin guarda cada ordem, executa no Midaz e guarda os resultados. A instituição lê os resultados e responde ao tribunal ela mesma. O plugin serve o canal direto apenas quando roda em modo executor, com um tenant, e com PLUGIN_AUTH_ENABLED ligado. Caso contrário, as cinco rotas diretas respondem 501. Um administrador da plataforma passa uma instituição para o canal direto com PUT /v1/institutions/{institutionId}/channel. A troca exige tudo isto:
  • O plugin é o dono da instituição.
  • O código da instituição guardado é a raiz de 8 caracteres do CNPJ do agrupamento responsável.
  • A instituição não tem ordem aberta, e nenhum bloqueio da instituição ainda retém dinheiro.
A mesma rota devolve a instituição para a Mensageria. Uma instituição que não está no canal direto recebe 422 SBJ-0025 em uma ordem direta. O feed de resultados entrega cada resultado pelo menos uma vez. Remova duplicatas por orderId, orderRevision e executionVersion. Envie um desbloqueio ou uma transferência apenas depois do 202 do seu bloqueio pai. O canal direto aceita BLOCK, UNBLOCK, TRANSFER, INFO e INTERRUPT. Uma transferência move recursos da conta de bloqueio da ordem pai para a conta de depósito judicial da instituição. Uma interrupção para um bloqueio permanente e mantém o que o bloqueio já retém. DIRECT_PERMANENT_BLOCK_ENABLED decide se o canal aceita um novo bloqueio permanente. Com o padrão, ele recusa um com 422 SBJ-0027. Um bloqueio permanente continua bloqueando novos créditos do sujeito, até o valor da ordem. O plugin lê esses créditos dos eventos do ledger Midaz. Ele dura um ano a partir do recebimento, ou até a data do tribunal quando a ordem informa uma, e nunca mais que um ano. Quando o prazo termina, o bloqueio deixa de aceitar novos créditos e mantém o que já retém. Uma interrupção, uma transferência ou um desbloqueio do restante, ou um cancelamento o encerra. Quando um bloco posterior de um bloqueio permanente continua falhando, o plugin estaciona a tentativa, levanta um alarme e deixa de tomar novos créditos desse bloqueio até que um administrador da plataforma resolva a tentativa. Uma ordem direta que falha em todas as tentativas, ou que chega ao seu corte enquanto o ledger falha, também é estacionada. A leitura dela mostra parked true. Os papéis de máquina order-submitter e result-reader chamam essas rotas. Operando o Plugin SISBAJUD descreve os papéis.

​
Apagar uma ordem do canal direto

Um administrador da plataforma apaga uma ordem concluída do canal direto com POST /v1/admin/direct/orders/{orderId}/erase, por um pedido do titular dos dados sob a LGPD ou no fim da retenção. POST /v1/admin/direct/purge lista as ordens que já podem ser apagadas e não muda nada. As duas operações exigem um token de usuário sem tenant e só respondem numa instalação de um tenant só. Depois do apagamento, ninguém lê de novo o conteúdo enviado com a ordem: o corpo da ordem e o número do documento da pessoa ou empresa que a ordem atinge. O apagamento não tem volta. O seu clientOrderId e o seu externalReference viram tokens. Uma busca pelo externalReference original ainda encontra a ordem apagada, com o conteúdo oculto. O apagamento não remove:
  • o protocolo do tribunal e os números de sequência da ordem;
  • o diário de lançamentos do plugin, com os valores, e as transações no Midaz;
  • os resultados que já estão no feed de resultados, e o que o seu sistema já leu dele;
  • o registro de auditoria do apagamento;
  • os backups feitos antes do apagamento. Depois de restaurar um backup, apague a ordem de novo.
O plugin nunca apaga uma ordem sozinho. O apagamento recusa uma ordem ainda aberta, que ainda retém dinheiro ou que tem uma ordem filha aberta. Ele também recusa uma ordem de bloqueio com menos de um ano desde o primeiro lançamento no ledger, e um bloqueio permanente antes da data de fim. Quando uma ordem fica apta ao apagamento por mais tempo que EXECUTOR_DIRECT_PURGE_ELIGIBLE_ALARM_AFTER (padrão 168h), o plugin registra um erro no log para um administrador revisar.

​
Semântica do ledger

​
Conta de bloqueio

O alias da conta de bloqueio tem o prefixo @block_sisbajud_ e depois os 32 dígitos hexadecimais minúsculos do ID da ordem de bloqueio. Um desbloqueio encontra a conta pelo seu parentOrderId. O tipo de conta de uma conta de bloqueio é sisbajud_block. Se o seu ledger valida tipos de conta, registre sisbajud_block como tipo de conta.

​
Direções

  • Um bloqueio diminui as contas do sujeito e aumenta a conta de bloqueio.
  • Uma transferência diminui a conta de bloqueio da ordem pai e aumenta a conta de depósito judicial.
  • Um desbloqueio diminui a conta de bloqueio. A escrita dele tem uma perna de origem: a conta de bloqueio. Ele libera os recursos para a conta de origem registrada ou exige uma decisão humana quando não é possível determinar um único destino seguro.
Um bloqueio move o valor do saldo disponível de cada conta do sujeito para o saldo disponível da conta de bloqueio.

​
Idempotência

Cada escrita traz o header X-Idempotency e X-TTL: 604800, que são sete dias. O Midaz guarda a chave de idempotência de uma escrita por esse tempo. A chave é orderId:orderRevision, então uma reentrega da mesma revisão da ordem envia a mesma chave.

​
Escritas incertas

Quando o Midaz responde a uma escrita sem prova do seu efeito, o resultado é INDETERMINATE. O plugin lê o ledger de novo antes de cada heartbeat. Ele envia um resultado de heartbeat à Mensageria a cada EXECUTOR_HEARTBEAT_EVERY, até que a Mensageria responda que a revisão da ordem foi substituída. A ordem vai para uma decisão humana no primeiro de dois limites:
  • EXECUTOR_HUMAN_DECISION_AFTER_BEATS heartbeats sem mudança. O padrão é 3.
  • O prazo da ordem menos RESPONSE_DEADLINE_MARGIN.
O plugin então registra uma decisão humana. Na lista de decisões humanas, ela tem humanDisposition HELD_MONEY_MOVED. Os heartbeats continuam, com executionState e effect ambos INDETERMINATE.

​
Ledger fora do ar no corte

O corte de uma ordem é o seu prazo menos RESPONSE_DEADLINE_MARGIN. Quando o Midaz falha para uma ordem da Mensageria no corte ou depois dele, e nenhum resultado judicial dessa revisão espera no outbox, o plugin para as suas tentativas. Ele registra uma decisão humana e não envia resultado. Verifique o ledger e responda ao tribunal você mesmo antes do prazo. Caso contrário, a Mensageria registra uma não resposta.

​
Depois que uma pessoa responde

Considere uma revisão que foi passada a uma pessoa no seu corte, ou que uma pessoa resolveu como efeito reconhecido ou sem efeito comprovado. Quando a sua escrita chega ao Midaz depois, o plugin não envia resultado FULL nem PARTIAL para ela. Ele registra o efeito e dispara um alarme. O tribunal recebe apenas a resposta da pessoa, então concilie você mesmo um efeito tardio no ledger.

​
Operações que o plugin não escreveu

A verificação de órfãs lê as operações de cada conta de bloqueio ao longo de EXECUTOR_ORPHAN_RECONCILE_WINDOW. O padrão é 48h. O plugin informa uma operação como órfã quando a sua transação não tem metadata.code, ou tem um código que o plugin não registrou. Esta etapa somente detecta. Ela não muda nada no ledger.

​
Rotas contábeis

As rotas contábeis são opcionais, por organização. O plugin as lê dos documentos de tenant routing.organizations e routing.ledger_bindings no Systemplane. Com SYSTEMPLANE_ENABLED desligado, o plugin escreve sem rotas. Com routing.organizations em schemaVersion 2, cada organização tem as suas próprias rotas para cada fluxo e a lista de ledgers que lançam com elas. O plugin então não lê routing.ledger_bindings. Uma escrita em um ledger que não está na lista da sua organização sai sem rotas. Quando uma escrita não pode sair por causa da sua configuração, o plugin a adia. O Midaz não aplicou nada, então a ordem espera, e uma entrega posterior envia a mesma escrita com a mesma chave de idempotência. Estas condições adiam uma escrita:
  • O plugin não consegue resolver as rotas contábeis da escrita.
  • O Midaz recusa as rotas contábeis da escrita: 422 com código 0113, 0114, 0116, 0117, 0118, 0119, 0152 ou 0157, ou 404 com código 0105.
Corrija a configuração antes do prazo da ordem. GET /v1/admin/ledger-routing/preflight verifica a configuração antes de você ligar as rotas.

​
Chamadas ao Midaz

O plugin chama o ledger Midaz no baseUrl de cada instituição, com o token dessa instituição. Dê às credenciais da instituição acesso a estas operações: O plugin encontra as contas de um sujeito pelo CRM do Midaz. Com crmMode legacy, ele chama GET /v1/aliases?document= em crmBaseUrl. Com crmMode embedded, ele chama GET /v2/organizations/{organizationId}/instruments?document= em baseUrl.