> ## 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](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-operations.md) describe la Mensageria. [Cómo Lerian SISBAJUD executor ejecuta órdenes](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-executor.md) describe qué hace el executor con cada orden. ## Configuración de la institución *** Registra cada institución en la Mensageria y en el executor, con el mismo `institutionId`. [Operar Lerian SISBAJUD](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-operations.md#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. ## Enrutamiento del ledger *** 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. `routing.organizations` acepta `schemaVersion` 1 o 2. Con `schemaVersion` 2, cada entrada de organización tiene sus propias `routes` para cada flujo y sus `ledgers`, los ledgers que registran con esas rutas. El executor entonces no lee `routing.ledger_bindings`, y una escritura en un ledger fuera de `ledgers` sale 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. * Con `schemaVersion` 2, el ledger de cada escritura está en los `ledgers` de su organización. Un ledger fuera de la lista recibe el problema `ledger_not_listed`, y el documento de bindings recibe el estado `ignored`. 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. ## Órdenes que necesitan atención *** | 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](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-operations.md#orders-that-need-attention) describe esa lista. ## Rotación de la clave de credenciales *** `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`. * Con `STREAMING_ENABLED` activo, la rotación publica un evento `kek.rotated` con `keyPurpose` `CREDENTIALS`. * Con AWS KMS en el modo `provided`, el executor no rota tu clave, y la operación devuelve `422`. La rotación puede devolver estos errores: * `SBJ-0007` / **409**: otra rotación de la misma institución está en curso. Envíala de nuevo cuando esa rotación termine. * `SBJ-0012` / **409**: nada rotó, y la misma solicitud falla de nuevo. * **503**: el gestor de claves falló antes de la rotación. Envíala de nuevo más tarde. * `SBJ-0013` / **500**: el resultado de la rotación no se conoce. No envíes la rotación de nuevo. * `SBJ-0014` / **500**: la clave rotó, pero un paso posterior falló. No envíes la rotación de nuevo. Contacta al soporte de Lerian. Con `PLUGIN_AUTH_ENABLED` inactivo, el executor no sirve esta operación. ## Verificación de auditoría *** `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. ## Roles *** 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 executor declara los roles `viewer`, `operator`, `investigator`, `cross-org-reader`, `admin` y `platform-admin`. Cada rol vincula el grupo `plugin-br-sisbajud--group`, y `admin` también vincula `admin-group`. Tu aplicación M2M tiene el rol `admin`. El rol `admin` tiene todos los permisos de esta tabla. Los roles `viewer`, `operator`, `investigator` y `cross-org-reader` tienen `admin:read`. Los permisos `systemplane` de `/system` van a `platform-admin` y a ningún otro rol. ### 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`. ## Listeners *** 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. ## Restricciones de despliegue *** * **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.