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

# Operar Lerian SISBAJUD executor

> Configura y opera Lerian SISBAJUD executor: instituciones y su conector de Midaz, enrutamiento del ledger, órdenes que necesitan atención, rotación de la clave de credenciales, roles, listeners y restricciones de despliegue.

Esta página describe cómo configurar y operar el **executor**. [Operar Lerian SISBAJUD](/es/rails/sisbajud/sisbajud-operations) describe la Mensageria. [Cómo Lerian SISBAJUD executor ejecuta órdenes](/es/rails/sisbajud/sisbajud-executor) describe qué hace el executor con cada orden.

<h2 id="institution-setup">
  Configuración de la institución
</h2>

***

Registra cada institución en la Mensageria y en el executor, con el mismo `institutionId`. [Operar Lerian SISBAJUD](/es/rails/sisbajud/sisbajud-operations#institutions) describe la solicitud de la Mensageria.

`POST /v1/institutions` registra una institución en el executor. El cuerpo tiene estos campos:

| Campo | Significado |
| - | - |
| `institutionId` | El UUID de la institución. Usa el mismo valor que en la Mensageria. |
| `connectorType` | El conector del ledger. Configúralo como `midaz`. |
| `institutionCode` | La raíz del CNPJ de la institución, de 8 dígitos. |
| `enabled` | Si la institución está activa. Envía `true`. |
| `connectorMetadata` | La configuración de Midaz de la institución. Las tablas siguientes la describen. |
| `retryPolicyConfig` | Opcional. La política de reintentos, en JSON. |
| `branchFormat` | Opcional. Una expresión regular Go RE2, de 64 caracteres como máximo, para el número de sucursal que un tribunal puede indicar en una restricción de bloqueo. |
| `accountFormat` | Opcional. Una expresión regular Go RE2, de 64 caracteres como máximo, para el número de cuenta que un tribunal puede indicar en una restricción de bloqueo. |

La solicitud también crea el keyset de tokenización y el keyset de auditoría de la institución. Una segunda solicitud con el mismo `institutionId` devuelve `409`.

El executor se registra como dueño de la institución, a partir de su propia identidad M2M (`EXECUTOR_M2M_SUBJECT`). Ningún campo de la solicitud define el dueño, y un `PATCH` no lo cambia.

### Metadatos del conector

| Clave | Obligatorio | Significado |
| - | - | - |
| `organizations` | Sí | Una lista de entradas `{organizationId, ledgers}`: las organizaciones de Midaz en las que el executor busca las cuentas de un sujeto. Sin `ledgers`, el executor busca en todos los ledgers de la organización. |
| `baseUrl` | Sí | La URL base del ledger Midaz de la institución. |
| `authAddress` | Cuando hay credenciales guardadas | La dirección del Access Manager que emite el token de Midaz de la institución. |
| `blockableBalances` | Sí | Las claves de saldo de Midaz que un bloqueo puede usar, por ejemplo `default`. Son claves de saldo, no los montos `available` u `onHold`. |
| `blockableAccountTypes` | Sí | Los tipos de cuenta que un bloqueo puede usar. |
| `salaryAccountTypes` | Sí | Los tipos de cuenta que son cuentas salario. Envía `["NONE"]` cuando la institución no tiene un tipo de cuenta salario. |
| `crmMode` | No | `legacy` o `embedded`. Sin valor, la institución usa `MIDAZ_CRM_MODE`. |
| `crmBaseUrl` | No | La URL base del CRM independiente de Midaz, para `legacy`. Con `embedded`, déjala vacía: el executor lee el CRM por `baseUrl`. |
| `executorLedger` | Para ejecutar órdenes | El ledger en el que escribe el executor. La siguiente tabla lo describe. |

### Ledger del executor

| Clave | Significado |
| - | - |
| `organizationId` | La organización de Midaz de las escrituras. |
| `ledgerId` | El ledger de Midaz de las escrituras. |
| `asset` | Configúralo como `BRL`, exactamente. |
| `judicialDepositAccountAlias` | El alias de la cuenta de depósito judicial. Debe seguir la regla de alias de Midaz. |

El executor rechaza una solicitud de institución cuyo `executorLedger` está presente y no es válido, con `400`. Al iniciar, el executor deja fuera de su enrutamiento del ledger una institución que no tiene un `executorLedger` válido.

### Credenciales del conector

`PUT /v1/institutions/{institutionId}/connector-credentials` escribe las credenciales de Midaz de la institución:

* `ledger_client_id` y `ledger_client_secret` son siempre obligatorios.
* `crm_client_id` y `crm_client_secret` son obligatorios con `crmMode` `legacy`. Con `embedded`, no los envíes.

El executor cifra las credenciales antes de guardarlas. `PATCH /v1/institutions/{institutionId}` rechaza un cuerpo con credenciales. Una credencial nueva no revoca la anterior en el Access Manager, así que revócala allí.

El executor obtiene el token de Midaz de la institución en `{authAddress}/v1/login/oauth/access_token`. Cuando la institución no tiene credenciales guardadas, el executor no envía el header `Authorization` a Midaz.

### Cambiar la configuración

* `PATCH /v1/institutions/{institutionId}` cambia los campos de la institución. Un `connectorMetadata` en el cuerpo reemplaza el paquete completo, excepto las credenciales guardadas.
* `PUT /v1/institutions/{institutionId}/connector-config` reemplaza `connectorType` y `connectorMetadata`. Mantiene las credenciales guardadas y rechaza un cuerpo con credenciales.
* `GET /v1/institutions/{institutionId}` devuelve la configuración sin las credenciales.

El executor lee la configuración de sus instituciones al iniciar. Después de crear una institución o cambiar su configuración, reinicia el executor.

<h2 id="ledger-routing">
  Enrutamiento del ledger
</h2>

***

Con `SYSTEMPLANE_ENABLED` activo, el executor sirve los documentos de tenant de sus rutas contables en `/tenant-system`. El executor lee dos de ellos: `routing.organizations` activa las rutas contables de cada organización, y `routing.ledger_bindings` guarda las rutas. Con `SYSTEMPLANE_ENABLED` inactivo, el executor escribe sin rutas.

`GET /v1/admin/ledger-routing/preflight` verifica la configuración de enrutamiento frente al ledger de la institución. No escribe nada. Un executor single-tenant necesita el parámetro de consulta `institutionId`. El informe cubre estas verificaciones:

* Las rutas de transacción y las rutas de operación existen y coinciden con las escrituras del executor.
* Un ledger que valida tipos de cuenta tiene `sisbajud_block` registrado.
* La cuenta de depósito judicial en `executorLedger` existe en el ledger y no está bloqueada.

El campo `ready` indica si la configuración está lista. El informe muestra el `executorLedger` guardado. El executor en ejecución usa la configuración que leyó al iniciar.

<h2 id="orders-that-need-attention">
  Órdenes que necesitan atención
</h2>

***

| Operación | Qué devuelve |
| - | - |
| `GET /v1/institutions/{institutionId}/executor/failed-orders` | Las revisiones de orden que el executor falló o abandonó. Cada elemento tiene el ID de la orden, la revisión, un token de motivo y el ID de su entrada en el journal. No lista las revisiones cuyo resultado todavía no se conoce. |
| `GET /v1/institutions/{institutionId}/executor/human-decisions` | Las revisiones de orden que el executor detuvo en una decisión humana. |

Cada decisión humana tiene un `humanDisposition`:

* `GAVE_UP`: el executor no intentó ninguna escritura en el ledger y respondió `EXECUTOR_GAVE_UP`.
* `HELD_MONEY_MOVED`: el executor intentó una escritura. El dinero puede haberse movido, y el executor no envió respuesta.

La Mensageria también lista las órdenes en las que el executor desistió. [Operar Lerian SISBAJUD](/es/rails/sisbajud/sisbajud-operations#orders-that-need-attention) describe esa lista.

<h2 id="credential-key-rotation">
  Rotación de la clave de credenciales
</h2>

***

`POST /v1/institutions/{institutionId}/security/credential-kek:rotate` rota la clave que envuelve las credenciales de Midaz guardadas de la institución. Esta clave no es la clave de datos de la institución que rota la Mensageria.

* La rotación mueve las credenciales guardadas a la nueva versión de la clave. Los valores de las credenciales no cambian. Para reemplazar una credencial, usa `PUT /v1/institutions/{institutionId}/connector-credentials`.
* La respuesta muestra la versión anterior y la nueva versión de la clave.
* Una institución sin credenciales guardadas devuelve `404`.
* Mientras otra rotación de la misma institución está en curso, una rotación devuelve `409`.
* Con HashiCorp Vault como proveedor de claves y `STREAMING_ENABLED` activo, la rotación publica un evento `kek.rotated` con `keyPurpose` `CREDENTIALS`.

Con `PLUGIN_AUTH_ENABLED` inactivo, el executor no sirve esta operación.

<h2 id="audit-verification">
  Verificación de auditoría
</h2>

***

`GET /v1/admin/audit/verify` verifica un rango del log de auditoría de la institución, de `fromIndex` a `toIndex`. No descifra ningún payload. Informa alteraciones y entradas borradas.

<h2 id="roles">
  Roles
</h2>

***

Cada operación necesita un permiso:

| Operación | Permiso |
| - | - |
| Crear o actualizar una institución, su configuración de conector o sus credenciales | `institution_config:write` |
| Leer una institución, las órdenes fallidas, las decisiones humanas o la verificación de auditoría | `admin:read` |
| Rotación de la clave de credenciales | `credential_kek:rotate` |
| Preflight del enrutamiento del ledger, y lecturas en `/tenant-system` | `tenant_policy:read` |
| Escrituras en `/tenant-system` | `tenant_policy:write` |

El rol `admin` tiene todos los permisos de esta tabla. Los roles `operator`, `investigator` y `compliance-officer` tienen `admin:read`. Los permisos `systemplane` de `/system` van al rol M2M `editor`, y a ningún rol de negocio.

### El executor en la Mensageria

El executor llama a la API de ejecución de la Mensageria con su propio cliente M2M. Configura el cliente en `MENSAGERIA_CLIENT_ID` y `MENSAGERIA_CLIENT_SECRET`. El executor obtiene su token del Access Manager en `PLUGIN_AUTH_HOST`. En la Mensageria, el cliente tiene el rol `br-sisbajud-executor-role`. [Integración con Lerian SISBAJUD](/es/rails/sisbajud/sisbajud-integration#execution-api) describe sus permisos.

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

***

El executor tiene dos listeners:

* **API principal**, en `SERVER_ADDRESS`. Configúrala como `:4029`, el puerto que expone la imagen. Sirve las operaciones de la referencia de la API. También sirve `/health`, `/readyz` y `/version`. Con `SYSTEMPLANE_ENABLED` activo, sirve `/system` y `/tenant-system`. Con `SWAGGER_ENABLED` activo, sirve `/swagger`.
* **Listener de webhook**, en `EXECUTOR_HUB_WEBHOOK_ADDRESS`. El valor predeterminado es `:9082`. Tiene una ruta, `POST` en `EXECUTOR_HUB_WEBHOOK_PATH`, cuyo valor predeterminado es `/v1/webhooks/hub`. Expón este puerto al Streaming Hub y usa la dirección de tu ingress más esta ruta como URL de la suscripción.

El listener de webhook no tiene autenticación de aplicación. Acepta una entrega solo cuando la firma HMAC es válida con el secret de la suscripción o con el secret anterior. Fuera de `DEPLOYMENT_MODE=local`, el listener necesita su propio certificado TLS. Como alternativa, termina el TLS delante de él y configura `EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED=true`.

`/readyz` incluye dos verificaciones del executor:

* `hub_webhook`: el listener de webhook.
* `executor_institutions`: el número de instituciones de las que el executor es dueño y cuántas de ellas tienen enrutamiento del ledger. Esta verificación no hace fallar la disponibilidad.

<h2 id="deploy-constraints">
  Restricciones de despliegue
</h2>

***

* **Un tenant por proceso.** El executor no inicia cuando su lista de tenants tiene más de un tenant.
* **Su propia base de datos.** El executor se ejecuta en su propia base de datos PostgreSQL vacía. Sus migraciones rechazan una base de datos que ya tiene otro historial de migraciones.
* **Reinicio después de cambios de configuración.** El executor lee sus instituciones al iniciar.
* **Período de terminación.** Configura el `terminationGracePeriodSeconds` del pod en al menos 90.


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