> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Operando o Lerian SISBAJUD executor

> Configure e opere o Lerian SISBAJUD executor: instituições e o seu conector do Midaz, roteamento do ledger, ordens que precisam de atenção, rotação da chave de credenciais, papéis, listeners e restrições de deploy.

Esta página descreve como configurar e operar o **executor**. [Operando o Lerian SISBAJUD](/pt/rails/sisbajud/sisbajud-operations) descreve a Mensageria. [Como o Lerian SISBAJUD executor executa ordens](/pt/rails/sisbajud/sisbajud-executor) descreve o que o executor faz com cada ordem.

<h2 id="institution-setup">
  Configuração da instituição
</h2>

***

Registre cada instituição na Mensageria e no executor, com o mesmo `institutionId`. [Operando o Lerian SISBAJUD](/pt/rails/sisbajud/sisbajud-operations#institutions) 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.

<h2 id="ledger-routing">
  Roteamento do ledger
</h2>

***

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.

<h2 id="orders-that-need-attention">
  Ordens que precisam de atenção
</h2>

***

| 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](/pt/rails/sisbajud/sisbajud-operations#orders-that-need-attention) descreve essa lista.

<h2 id="credential-key-rotation">
  Rotação da chave de credenciais
</h2>

***

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

<h2 id="audit-verification">
  Verificação de auditoria
</h2>

***

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

<h2 id="roles">
  Papéis
</h2>

***

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](/pt/rails/sisbajud/sisbajud-integration#execution-api) descreve as suas permissões.

<h2 id="listeners">
  Listeners
</h2>

***

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.

<h2 id="deploy-constraints">
  Restrições de deploy
</h2>

***

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.