Skip to main content
Esta página describe cómo configurar y operar el executor. Operar Lerian SISBAJUD describe la Mensageria. Cómo Lerian SISBAJUD executor ejecuta órdenes 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 describe la solicitud de la Mensageria. POST /v1/institutions registra una institución en el executor. El cuerpo tiene estos campos: 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

​
Ledger del executor

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

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 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: El executor declara los roles viewer, operator, investigator, cross-org-reader, admin y platform-admin. Cada rol vincula el grupo plugin-br-sisbajud-<role>-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.