Operando o Lerian SISBAJUD executor

Esta página descreve como configurar e operar o executor. Operando o Lerian SISBAJUD descreve a Mensageria. Como o Lerian SISBAJUD executor executa ordens descreve o que o executor faz com cada ordem.

Configuração da instituição

Registre cada instituição na Mensageria e no executor, com o mesmo institutionId. Operando o Lerian SISBAJUD descreve a requisição da Mensageria. POST /v1/institutions registra uma instituição no executor. O corpo tem estes campos:

Campo	Significado
`institutionId`	O UUID da instituição. Use o mesmo valor da Mensageria.
`connectorType`	O conector do ledger. Defina-o como `midaz`.
`institutionCode`	A raiz do CNPJ da instituição, com 8 dígitos.
`enabled`	Se a instituição está ativa. Envie `true`.
`connectorMetadata`	A configuração do Midaz da instituição. As tabelas abaixo a descrevem.
`retryPolicyConfig`	Opcional. A política de retentativa, em JSON.
`branchFormat`	Opcional. Uma expressão regular Go RE2, com no máximo 64 caracteres, para o número da agência que um tribunal pode indicar em uma restrição de bloqueio.
`accountFormat`	Opcional. Uma expressão regular Go RE2, com no máximo 64 caracteres, para o número da conta que um tribunal pode indicar em uma restrição de bloqueio.

A requisição também cria o keyset de tokenização e o keyset de auditoria da instituição. Uma segunda requisição com o mesmo institutionId retorna 409. 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.

Metadados do conector

Chave	Obrigatório	Significado
`organizations`	Sim	Uma lista de entradas `{organizationId, ledgers}`: as organizações do Midaz em que o executor procura as contas de um sujeito. Sem `ledgers`, o executor procura em todos os ledgers da organização.
`baseUrl`	Sim	A URL base do ledger Midaz da instituição.
`authAddress`	Quando há credenciais gravadas	O endereço do Access Manager que emite o token do Midaz da instituição.
`blockableBalances`	Sim	As chaves de saldo do Midaz que um bloqueio pode usar, por exemplo `default`. São chaves de saldo, não os valores `available` ou `onHold`.
`blockableAccountTypes`	Sim	Os tipos de conta que um bloqueio pode usar.
`salaryAccountTypes`	Sim	Os tipos de conta que são contas salário. Envie `["NONE"]` quando a instituição não tem tipo de conta salário.
`crmMode`	Não	`legacy` ou `embedded`. Sem valor, a instituição usa `MIDAZ_CRM_MODE`.
`crmBaseUrl`	Não	A URL base do CRM autônomo do Midaz, para `legacy`. Com `embedded`, deixe-a vazia: o executor lê o CRM pelo `baseUrl`.
`executorLedger`	Para executar ordens	O ledger em que o executor escreve. A próxima tabela o descreve.

Ledger do executor

Chave	Significado
`organizationId`	A organização do Midaz das escritas.
`ledgerId`	O ledger do Midaz das escritas.
`asset`	Defina-o como `BRL`, exatamente.
`judicialDepositAccountAlias`	O alias da conta de depósito judicial. Ele deve seguir a regra de alias do Midaz.

O executor recusa uma requisição de instituição cujo executorLedger está presente e não é válido, com 400. Na inicialização, o executor deixa fora do seu roteamento do ledger uma instituição que não tem executorLedger válido.

Credenciais do conector

PUT /v1/institutions/{institutionId}/connector-credentials grava as credenciais do Midaz da instituição:

ledger_client_id e ledger_client_secret são sempre obrigatórios.
crm_client_id e crm_client_secret são obrigatórios com crmMode legacy. Com embedded, não os envie.

O executor criptografa as credenciais antes de gravá-las. PATCH /v1/institutions/{institutionId} recusa um corpo com credenciais. Uma nova credencial não revoga a anterior no Access Manager, então revogue-a lá. O executor obtém o token do Midaz da instituição em {authAddress}/v1/login/oauth/access_token. Quando a instituição não tem credenciais gravadas, o executor não envia header Authorization ao Midaz.

Alterar a configuração

PATCH /v1/institutions/{institutionId} altera os campos da instituição. Um connectorMetadata no corpo substitui o pacote inteiro, exceto as credenciais gravadas.
PUT /v1/institutions/{institutionId}/connector-config substitui connectorType e connectorMetadata. Ele mantém as credenciais gravadas e recusa um corpo com credenciais.
GET /v1/institutions/{institutionId} retorna a configuração sem as credenciais.

O executor lê a configuração das suas instituições na inicialização. Depois de criar uma instituição ou alterar a sua configuração, reinicie o executor.

Roteamento do ledger

Com SYSTEMPLANE_ENABLED ligado, o executor serve os documentos de tenant das suas rotas contábeis em /tenant-system. O executor lê dois deles: routing.organizations liga as rotas contábeis de cada organização, e routing.ledger_bindings guarda as rotas. Com SYSTEMPLANE_ENABLED desligado, o executor escreve sem rotas. GET /v1/admin/ledger-routing/preflight verifica a configuração de roteamento em relação ao ledger da instituição. Ele não escreve nada. Um executor single-tenant precisa do parâmetro de consulta institutionId. O relatório cobre estas verificações:

As rotas de transação e as rotas de operação existem e correspondem às escritas do executor.
Um ledger que valida tipos de conta tem sisbajud_block registrado.
A conta de depósito judicial em executorLedger existe no ledger e não está bloqueada.

O campo ready informa se a configuração está pronta. O relatório mostra o executorLedger gravado. O executor em execução usa a configuração que leu na inicialização.

Ordens que precisam de atenção

Operação	O que retorna
`GET /v1/institutions/{institutionId}/executor/failed-orders`	As revisões de ordem que o executor falhou ou abandonou. Cada item tem o ID da ordem, a revisão, um token de motivo e o ID da sua entrada no journal. Ele não lista as revisões cujo resultado ainda não é conhecido.
`GET /v1/institutions/{institutionId}/executor/human-decisions`	As revisões de ordem que o executor parou em uma decisão humana.

Cada decisão humana tem um humanDisposition:

GAVE_UP: o executor não tentou nenhuma escrita no ledger e respondeu EXECUTOR_GAVE_UP.
HELD_MONEY_MOVED: o executor tentou uma escrita. O dinheiro pode ter se movido, e o executor não enviou resposta.

A Mensageria também lista as ordens das quais o executor desistiu. Operando o Lerian SISBAJUD descreve essa lista.

Rotação da chave de credenciais

POST /v1/institutions/{institutionId}/security/credential-kek:rotate rotaciona a chave que envolve as credenciais do Midaz gravadas da instituição. Essa chave não é a chave de dados da instituição que a Mensageria rotaciona.

A rotação move as credenciais gravadas para a nova versão da chave. Os valores das credenciais não mudam. Para substituir uma credencial, use PUT /v1/institutions/{institutionId}/connector-credentials.
A resposta mostra a versão anterior e a nova versão da chave.
Uma instituição sem credenciais gravadas retorna 404.
Enquanto outra rotação da mesma instituição está em andamento, uma rotação retorna 409.
Com o HashiCorp Vault como provedor de chaves e STREAMING_ENABLED ligado, a rotação publica um evento kek.rotated com keyPurpose CREDENTIALS.

Com PLUGIN_AUTH_ENABLED desligado, o executor não serve esta operação.

Verificação de auditoria

GET /v1/admin/audit/verify verifica um intervalo do log de auditoria da instituição, de fromIndex a toIndex. Ele não descriptografa nenhum payload. Ele informa adulterações e entradas apagadas.

Papéis

Cada operação precisa de uma permissão:

Operação	Permissão
Criar ou atualizar uma instituição, a sua configuração de conector ou as suas credenciais	`institution_config:write`
Ler uma instituição, as ordens com falha, as decisões humanas ou a verificação de auditoria	`admin:read`
Rotação da chave de credenciais	`credential_kek:rotate`
Preflight do roteamento do ledger, e leituras em `/tenant-system`	`tenant_policy:read`
Escritas em `/tenant-system`	`tenant_policy:write`

O papel admin tem todas as permissões desta tabela. Os papéis operator, investigator e compliance-officer têm admin:read. As permissões systemplane de /system vão para o papel M2M editor, e para nenhum papel de negócio.

O executor na Mensageria

O executor chama a API de execução da Mensageria com o seu próprio cliente M2M. Defina o cliente em MENSAGERIA_CLIENT_ID e MENSAGERIA_CLIENT_SECRET. O executor obtém o seu token do Access Manager em PLUGIN_AUTH_HOST. Na Mensageria, o cliente tem o papel br-sisbajud-executor-role. Integrando com o Lerian SISBAJUD descreve as suas permissões.

Listeners

O executor tem dois listeners:

API principal, em SERVER_ADDRESS. Defina-o como :4029, a porta que a imagem expõe. Ela serve as operações da referência da API. Ela também serve /health, /readyz e /version. Com SYSTEMPLANE_ENABLED ligado, ela serve /system e /tenant-system. Com SWAGGER_ENABLED ligado, ela serve /swagger.
Listener de webhook, em EXECUTOR_HUB_WEBHOOK_ADDRESS. O padrão é :9082. Ele tem uma rota, POST em EXECUTOR_HUB_WEBHOOK_PATH, cujo padrão é /v1/webhooks/hub. Exponha essa porta ao Streaming Hub e use o endereço do seu ingress mais esse caminho como URL da assinatura.

O listener de webhook não tem autenticação de aplicação. Ele aceita uma entrega somente quando a assinatura HMAC é válida com o secret da assinatura ou com o secret anterior. Fora de DEPLOYMENT_MODE=local, o listener precisa do seu próprio certificado TLS. Como alternativa, termine o TLS na frente dele e defina EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED=true. /readyz inclui duas verificações do executor:

hub_webhook: o listener de webhook.
executor_institutions: o número de instituições das quais o executor é dono e quantas delas têm roteamento do ledger. Esta verificação não reprova a prontidão.

Restrições de deploy

Um tenant por processo. O executor não inicia quando a sua lista de tenants tem mais de um tenant.
O seu próprio banco de dados. O executor roda no seu próprio banco PostgreSQL vazio. As suas migrações recusam um banco que já tem outro histórico de migrações.
Reinício após mudanças de configuração. O executor lê as suas instituições na inicialização.
Período de encerramento. Defina o terminationGracePeriodSeconds do pod como pelo menos 90.

​Configuração da instituição

​Metadados do conector

​Ledger do executor

​Credenciais do conector

​Alterar a configuração

​Roteamento do ledger

​Ordens que precisam de atenção

​Rotação da chave de credenciais

​Verificação de auditoria

​Papéis

​O executor na Mensageria

​Listeners

​Restrições de deploy