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

# Variables de entorno de Plugin SISBAJUD

> Variables de entorno de Plugin SISBAJUD: runtime, autenticación, licencia, gestión de claves, conexión con la Mensageria, tiempos de ejecución, listener de webhook, Midaz y streaming de eventos.

Esta página lista las variables de entorno del **Plugin SISBAJUD**. [Variables de entorno de la Lerian SISBAJUD Mensageria](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-environment-variables.md) lista las variables de la Mensageria. [Fundamentos de configuración de BYOC](https://docs.lerian.studio/es/reference/byoc-configuration.md) documenta las variables que comparte cada servicio Go de Lerian: servidor, almacenes de datos, telemetría y autenticación de plugins.

En las tablas siguientes, la columna **Predeterminado / Obligatorio** muestra el valor predeterminado. Un calificador en negrita (por ejemplo, **Obligatorio**) marca las variables que debes configurar. `—` significa que no hay valor predeterminado. Una variable marcada como **Sensible** guarda una credencial o material de claves. Inyéctala desde tu gestor de secretos en el momento del despliegue. No hagas commit de su valor.

`EXECUTOR_ENABLED=true` activa el plugin. Con `EXECUTOR_ENABLED` en blanco, una `MENSAGERIA_BASE_URL` no vacía también activa el plugin, y `false` no desactiva el plugin de una Mensageria configurada. Con `EXECUTOR_ENABLED=true` y sin `MENSAGERIA_BASE_URL`, el plugin corre sin la Mensageria, solo para el canal directo. En ese caso exige `EXECUTOR_M2M_SUBJECT`, `RESPONSE_DEADLINE_MARGIN` y `EXECUTOR_HEARTBEAT_EVERY`. No lee las variables de cliente, mTLS ni de listener de webhook de la Mensageria, excepto `EXECUTOR_HUB_WEBHOOK_MAX_HANDLE_ATTEMPTS`, que limita los intentos de cada orden directa.

Para instalar o actualizar el plugin, consulta el [README del chart](https://github.com/LerianStudio/helm/tree/main/charts/plugin-br-sisbajud).

## Servicio y runtime

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `SERVER_ADDRESS` | **Configúrala como `:4029`** | Dirección de escucha de la API principal. La imagen expone el puerto 4029. `/health`, `/readyz` y `/version` usan este puerto. |
| `ENVIRONMENT_NAME` | — | Entorno de ejecución. `local`, `development`, `staging`, `e2e` y `test` son valores de no producción. Cualquier otro valor, y ningún valor, ejecuta las verificaciones de producción. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc` o `saas`. Con `saas`, el arranque rechaza una conexión PostgreSQL o Redis sin TLS. Fuera de `local`, el listener de webhook necesita TLS. |
| `DEFAULT_TENANT_ID` | `11111111-1111-1111-1111-111111111111` | Tenant de un despliegue single-tenant. Debe ser un UUID. |
| `EXECUTOR_ENABLED` | — | `true` o `false`. Cualquier otro valor rechaza el arranque. |
| `SYSTEMPLANE_ENABLED` | `false` | Sirve la API de administración de [Systemplane](https://docs.lerian.studio/es/reference/platform/systemplane/overview.md) en `/system` y los documentos de rutas contables en `/tenant-system`. |

> [!NOTE]
>
> Las verificaciones de producción exigen `POSTGRES_PASSWORD` y rechazan `POSTGRES_SSLMODE=disable`. Con `STREAMING_ENABLED=true`, también exigen `STREAMING_TLS_ENABLED=true`.

## Autenticación

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | `false` | Verifica los bearer tokens de la API principal con el Access Manager. Con `false`, el plugin no sirve la rotación de la clave de credenciales, la resolución de decisión humana, el rearme de resultado, la resolución de intento estacionado, el borrado de órdenes directas ni la previsualización de la depuración, y el canal directo responde `501`. |
| `PLUGIN_AUTH_HOST` | **Obligatorio** | Dirección del Access Manager. El plugin obtiene su token para la Mensageria en esta dirección, también cuando `PLUGIN_AUTH_ENABLED` es `false`. |

## Licencia

[License Manager](https://docs.lerian.studio/es/platform/licensing/license-manager.md) describe cómo el producto verifica la licencia.

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `LICENSE_KEY` | **Obligatorio** | La clave de licencia que Lerian emitió para Plugin SISBAJUD. El arranque rechaza un valor vacío en cualquier entorno. La licencia es global, así que ninguna otra variable define su alcance. |

## Gestión de claves

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `KMS_PROVIDER` | **Obligatorio cuando `ENVIRONMENT_NAME` es `production`** | Gestor de claves: `vault` (HashiCorp Vault Transit) o `aws` (AWS KMS). Cualquier otro valor rechaza el arranque. Con cualquier otro entorno, un valor no configurado significa `vault`. |
| `AWS_REGION` | **Obligatorio con `aws`** | Región de AWS KMS. |
| `KMS_AWS_KEY_MODE` | **Obligatorio con `aws`** | `managed` o `provided`. No tiene valor predeterminado. Cualquier otro valor rechaza el arranque. |
| `KMS_AWS_KEY_ARN` | **Obligatorio con `provided`** | ARN de tu clave de AWS KMS para los datos de la institución, en la región de `AWS_REGION`. Un ARN de alias rechaza el arranque. Con `managed`, déjala vacía. |
| `KMS_AWS_CREDENTIALS_KEY_ARN` | **Obligatorio con `provided`** | ARN de tu clave de AWS KMS para las credenciales de conector almacenadas, con las mismas reglas. Debe ser una clave distinta de `KMS_AWS_KEY_ARN`. |
| `KMS_AWS_ROTATION_CHECK_INTERVAL_SEC` | `3600` | Con `provided`, el intervalo, en segundos, en el que el plugin busca una rotación de tus claves. De `1` a `86400`. |
| `KMS_AWS_TIMEOUT_SEC` | `20` | Timeout de cada llamada a AWS KMS, en segundos. De `1` a `600`. |
| `VAULT_ADDR` | **Obligatorio con `vault`** | Dirección de tu Vault. |
| `VAULT_AUTH_METHOD` | `token` | `token` o `approle`. Cualquier otro valor rechaza el arranque. |
| `VAULT_TOKEN` | **Obligatorio para `token` cuando `ENVIRONMENT_NAME` es `production`** | Token de Vault. Sensible. |
| `VAULT_APPROLE_ROLE_ID` | **Obligatorio para `approle`** | Role ID de AppRole. Sensible. |
| `VAULT_APPROLE_SECRET_ID` | **Obligatorio para `approle`** | Secret ID de AppRole. Sensible. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Ruta de montaje del motor Transit. |
| `VAULT_TIMEOUT_SEC` | `15` | Timeout de cada solicitud a Vault, en segundos. De `1` a `600`. |
| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Renueva el token de Vault en segundo plano. |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Tiempo mínimo entre dos renovaciones, en segundos. |

Con AWS KMS, los dos modos de clave son:

* **`managed`.** El plugin crea dos claves para cada institución: una para sus datos y una para sus credenciales de conector almacenadas. `credential-kek:rotate` rota la clave de credenciales.
* **`provided`.** Tú creas las dos claves. El plugin nunca las crea ni las rota, y `credential-kek:rotate` devuelve `422`. Cuando el custodio de tus claves rota una clave, el plugin registra la nueva versión.

Los requisitos de la clave, las credenciales de AWS, los permisos, excepto `kms:ListAliases`, y el contexto de cifrado son los mismos que en la Mensageria. [AWS KMS en la Mensageria](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-environment-variables.md#aws-kms) los enumera. Elige el proveedor de claves una sola vez. Cuando la base de datos contiene datos que otro proveedor de claves protege, el arranque rechaza.

## Conexión con la Mensageria

El plugin llama a la API de ejecución de la Mensageria. [Integración con Lerian SISBAJUD](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-integration.md#execution-api) la describe.

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `MENSAGERIA_BASE_URL` | **Obligatorio** con la Mensageria | URL base de la API de ejecución de la Mensageria (`SISBAJUD_EXECUTION_ADDRESS` en la Mensageria). Debe ser una URL `https` con host. |
| `MENSAGERIA_MTLS_ENABLED` | `false` | `true` presenta un certificado de cliente. `false` usa TLS unidireccional. Cualquier otro valor rechaza el arranque. |
| `MENSAGERIA_TLS_CA_FILE` | **Obligatorio si `MENSAGERIA_MTLS_ENABLED=true`** | Paquete de CA que verifica la Mensageria. Con TLS unidireccional, es opcional, y un valor vacío usa el almacén de confianza del sistema. |
| `MENSAGERIA_TLS_CLIENT_CERT_FILE` | **Obligatorio si `MENSAGERIA_MTLS_ENABLED=true`** | Certificado de cliente del plugin. |
| `MENSAGERIA_TLS_CLIENT_KEY_FILE` | **Obligatorio si `MENSAGERIA_MTLS_ENABLED=true`** | Clave privada de ese certificado. Sensible. |
| `EXECUTOR_M2M_SUBJECT` | **Obligatorio** | El `sub` del token M2M del plugin. El plugin lo registra como dueño de cada institución que crea. |
| `MENSAGERIA_CLIENT_ID` | **Obligatorio** | Client ID del cliente M2M del plugin. |
| `MENSAGERIA_CLIENT_SECRET` | **Obligatorio** | Client secret de ese cliente. Sensible. El arranque rechaza un par con solo uno de los dos valores. |
| `STREAMING_HUB_TENANT_ID` | **Obligatorio** | Tenant de las sondas canario. |

## Tiempos de ejecución

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `EXECUTOR_TICK_EVERY` | `30s` | Intervalo del ciclo de ejecución. Duración Go mayor que 0. |
| `EXECUTOR_HEARTBEAT_EVERY` | **Obligatorio** | Intervalo de los heartbeats de una escritura cuyo resultado no se conoce. Duración Go mayor que 0. |
| `EXECUTOR_HUMAN_DECISION_AFTER_BEATS` | `3` | Número de heartbeats sin cambio antes de que la orden pase a una decisión humana. |
| `EXECUTOR_RESULT_MAX_ATTEMPTS` | `12` | Número de envíos fallidos de un resultado antes de que el plugin lo estacione, registre una decisión humana y dispare una alarma. `0` significa el valor predeterminado. Un valor negativo rechaza el arranque. Un administrador de la plataforma rearma un resultado estacionado. |
| `RESPONSE_DEADLINE_MARGIN` | **Obligatorio** | Duración Go mayor que 0, por ejemplo `2h`. Antes del plazo de la orden, el plugin mantiene este margen y entrega una escritura no resuelta a una decisión humana. |
| `EXECUTOR_SETTLE_WINDOW` | `1s` | Duración Go. Configúrala con al menos la latencia asíncrona de tu ledger. |
| `EXECUTOR_ORPHAN_RECONCILE_WINDOW` | `48h` | Hasta cuándo, en el pasado, el plugin busca operaciones en cuentas de bloqueo que no escribió. |

## Listener de webhook

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `EXECUTOR_TRANSPORT` | `webhook` | Cómo llegan los avisos de ejecución al plugin. Esta página describe `webhook`. |
| `EXECUTOR_HUB_WEBHOOK_ADDRESS` | `:9082` | Dirección de escucha del listener de webhook. |
| `EXECUTOR_HUB_WEBHOOK_PATH` | `/v1/webhooks/hub` | Ruta del listener de webhook. Debe empezar con `/`. |
| `EXECUTOR_HUB_WEBHOOK_SECRET` | **Obligatorio** | Secret de firma de la suscripción del Streaming Hub. Sensible. |
| `EXECUTOR_HUB_WEBHOOK_SECRET_PREVIOUS` | — | El secret anterior a la última rotación. El listener acepta los dos secrets. Sensible. |
| `EXECUTOR_HUB_WEBHOOK_MAX_SKEW_SEC` | `300` | De `1` a `300`. El listener acepta una entrega fuera de esta diferencia de reloj, con una advertencia en el log. |
| `EXECUTOR_HUB_WEBHOOK_TLS_CERT_FILE` | **Obligatorio fuera de `DEPLOYMENT_MODE=local`, salvo que el TLS termine antes** | Certificado de servidor del listener. Configúralo junto con la clave. |
| `EXECUTOR_HUB_WEBHOOK_TLS_KEY_FILE` | **Obligatorio con el certificado** | Clave privada de ese certificado. Sensible. |
| `EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED` | `false` | Configúrala como `true` cuando el TLS termina delante del listener. |
| `EXECUTOR_HUB_WEBHOOK_MAX_HANDLE_ATTEMPTS` | `5` | Número de intentos para cada entrega aceptada. Debe ser al menos 1 + `EXECUTOR_SETTLE_WINDOW` / `EXECUTOR_TICK_EVERY`, redondeado hacia arriba. |

## Canal directo

El canal directo exige `PLUGIN_AUTH_ENABLED` activado, un tenant y el modo executor. [Cómo Plugin SISBAJUD ejecuta órdenes](https://docs.lerian.studio/es/interfaces/plugin-sisbajud/plugin-sisbajud-how-it-works.md#direct-channel) lo describe.

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `DIRECT_PERMANENT_BLOCK_ENABLED` | `false` | `true` o `false`. Cualquier otro valor rechaza el arranque. Con `false`, el canal rechaza un nuevo bloqueo permanente con `SBJ-0027`. Con `false`, los bloqueos permanentes activos siguen bloqueando nuevos créditos hasta que se cierren. Con `true`, el plugin acepta un nuevo bloqueo permanente, y el arranque exige `STREAMING_ENABLED` `true` y `STREAMING_BROKERS`. `STREAMING_BROKERS` debe llegar a los brokers donde Midaz publica sus eventos de ledger: sin ellos, el plugin no captura ningún crédito posterior. |
| `DIRECT_PERMANENT_REFRESH_EVERY` | `15m` | Cada cuánto el plugin actualiza las cuentas del sujeto de un bloqueo permanente. De `1m` a `15m`. |
| `EXECUTOR_PERMANENT_RESULT_EMITTER_ENABLED` | `false` | `true` o `false`. Con `true`, el plugin escribe un resultado por cada bloqueo posterior de un bloqueo permanente. Exige `DIRECT_PERMANENT_BLOCK_ENABLED` `true`. El plugin retiene un resultado y dispara una alarma cuando `connectorMetadata.permanentProducts` no mapea el tipo de cuenta. |
| `EXECUTOR_ORDER_SWEEP_ENABLED` | `false` | `true` o `false`. Con `true`, el plugin cierra las revisiones terminadas de los dos canales. |
| `EXECUTOR_DIRECT_DRAINER_INFRA_ALARM_THRESHOLD` | `3` | El plugin dispara una alarma cuando una orden directa llega a cada múltiplo de este número de errores de infraestructura consecutivos. Al menos `1`. |
| `EXECUTOR_DIRECT_PURGE_ELIGIBLE_ALARM_AFTER` | `168h` | Go duration mayor que 0. El plugin registra un error en el log cuando la orden directa más antigua que se puede borrar espera este tiempo, para que un administrador la revise. Un valor inválido detiene el plugin al iniciar. |
| `EXECUTOR_DIRECT_PURGE_REFRESH_EVERY` | `15m` | Go duration mayor que 0. Cada cuánto cuenta el plugin las órdenes directas que se pueden borrar. Un valor inválido detiene el plugin al iniciar. |

## Midaz

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `MIDAZ_CRM_MODE` | `legacy` | Superficie de CRM de las instituciones que no definen `crmMode`: `legacy` (el CRM independiente de Midaz en `crmBaseUrl`) o `embedded` (el CRM del ledger Midaz en `baseUrl`). |

El plugin lee la conexión con Midaz de cada institución desde su configuración, no desde variables de entorno. [Operar Plugin SISBAJUD](https://docs.lerian.studio/es/interfaces/plugin-sisbajud/plugin-sisbajud-operations.md#institution-setup) la describe.

## Streaming de eventos

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `STREAMING_ENABLED` | `true` | Publica eventos. Una rotación de la clave de credenciales publica `kek.rotated`. El arranque rechaza `false` cuando `STREAMING_BROKERS` está configurada. |
| `STREAMING_BROKERS` | — | Lista de brokers Kafka separada por comas. |
| `STREAMING_TLS_ENABLED` | **`true` en producción** | Se conecta a los brokers por TLS. |
| `OUTBOX_ENABLED` | `true` | Ruta de entrega duradera de los eventos. `STREAMING_ENABLED=true` la exige. |

## Valores que deben coincidir con la Mensageria

* **`RESPONSE_DEADLINE_MARGIN`.** La Mensageria lee la misma variable. Configura el mismo valor en la Mensageria y en el Plugin SISBAJUD.
* **TLS mutuo.** Configura `MENSAGERIA_MTLS_ENABLED` con el mismo valor que `SISBAJUD_EXECUTION_MTLS_ENABLED` en la Mensageria. Con TLS mutuo activo en la Mensageria e inactivo en el plugin, el handshake TLS falla.
* **Identidad del plugin.** `EXECUTOR_M2M_SUBJECT` es el `sub` del token del cliente M2M en `MENSAGERIA_CLIENT_ID`.


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