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

> Variables de entorno de despliegue para Lerian SISBAJUD: backend de KMS, almacenamiento de objetos S3, claves de cifrado en sobre, workers, intercambio de archivos por STA y el ledger de Midaz.

Lerian SISBAJUD cifra los datos personales que guarda en su propia base de datos y bucket. Estas variables se configuran en el momento del despliegue. Solo entran en vigor después de reiniciar el servicio. [Fundamentos de configuración de BYOC](/es/reference/byoc-configuration) documenta la base universal que comparte cada servicio Go de Lerian: servidor, almacenes de datos, multi-tenancy, telemetría, autenticación de plugins y licenciamiento. Esta página cubre solo las variables propias de Lerian SISBAJUD.

En las tablas siguientes, la columna **Predeterminado / Obligatorio** muestra el valor predeterminado. Un calificador en negrita (por ejemplo, **Obligatorio** o **Obligatorio si está habilitado**) marca las variables que debes configurar. `—` significa que no hay valor predeterminado. Cualquier variable marcada como **Sensible** contiene credenciales o material de claves. Inyéctala desde tu gestor de secretos en el momento del despliegue. Nunca hagas commit de un valor.

## Servicio y runtime

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `SERVER_ADDRESS` | `:8080` | Dirección de escucha HTTP principal. La configuración de ejemplo usa `:4029`. Los sondeos de liveness, readiness y versión se enlazan a este mismo puerto. |
| `ENVIRONMENT_NAME` | — | Entorno de runtime: `local`, `development`, `staging`, `e2e`, `test` o `production`. Se acepta `ENV_NAME` como nombre alternativo. Un valor sin configurar o desconocido ejecuta las verificaciones de configuración de producción. |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita la API de administración de configuración en runtime de [Systemplane](/es/reference/platform/systemplane/overview) bajo el prefijo `/system` en el puerto principal. Deshabilitada de forma predeterminada (modo solo variables de entorno). |
| `DEFAULT_TENANT_ID` | `11111111-1111-1111-1111-111111111111` | UUID del tenant usado en modo single-tenant. El tenant es el límite de aislamiento de la base de datos y puede contener varias instituciones; cada institución se enruta por su propio identificador dentro del tenant. Con la autenticación deshabilitada, el riel también recurre a este UUID como su única institución configurada. |

<Note>
  Lerian SISBAJUD expone `/health` (liveness), `/readyz` (readiness) y `/version` en el puerto principal. Expone `/metrics` solo cuando `ENVIRONMENT_NAME` es `local` o `development`. Cuando habilitas multi-tenancy, también expone `GET /readyz/tenant/{id}`. Consulta [Estado de salud y disponibilidad](/es/reference/health-and-readiness) para conocer el contrato de los sondeos.
</Note>

## Backend de seguridad

Un valor no admitido de `KMS_PROVIDER` hace fallar el arranque en todos los entornos.

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `KMS_PROVIDER` | `vault` · **Obligatorio cuando `ENVIRONMENT_NAME` es `production`** | Gestor de claves de cifrado en sobre: `vault` (HashiCorp Vault Transit) o `aws` (AWS KMS). Se lee una sola vez al iniciar; no admite recarga en caliente. No existe un proveedor en memoria. |

<Note>
  `KMS_PROVIDER=vault` requiere las variables de Vault que se muestran a continuación. `KMS_PROVIDER=aws` requiere la `AWS_REGION` compartida. Las credenciales del conector por institución están selladas dentro de los metadatos de configuración de la institución bajo una KEK de clase credenciales. Ningún selector de entorno elige su almacenamiento.
</Note>

### Vault (cuando `KMS_PROVIDER=vault`)

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `VAULT_ADDR` | **Obligatorio para el proveedor Vault** | Dirección del Vault del cliente. |
| `VAULT_AUTH_METHOD` | `token` | Método de autenticación: `token` (`VAULT_TOKEN` estático) o `approle` (ids de rol y secreto de AppRole). |
| `VAULT_TOKEN` | **Obligatorio si es `token` y `ENVIRONMENT_NAME` es `production`** | Token de servicio para Vault. Sensible. Con cualquier otro valor de entorno, un token sin configurar recurre a un token de desarrollo. |
| `VAULT_APPROLE_ROLE_ID` | **Obligatorio si es `approle`** | Id de rol de AppRole. Sensible. |
| `VAULT_APPROLE_SECRET_ID` | **Obligatorio si es `approle`** | Id de secreto de AppRole. Sensible. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Ruta de montaje del motor Transit usado para el cifrado en sobre. |
| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Ejecuta un renovador en segundo plano que actualiza el token de Vault antes de que expire su lease. |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Piso, en segundos, entre intentos de renovación. |
| `VAULT_TIMEOUT_SEC` | `15` | Tiempo de espera por solicitud, en segundos, para cada ida y vuelta a Vault. |

### AWS (cuando `KMS_PROVIDER=aws`)

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `AWS_REGION` | **Obligatorio con `KMS_PROVIDER=aws`** | Región para el adaptador de AWS KMS. El arranque falla en modo fail-closed cuando `KMS_PROVIDER=aws` y está vacía. Las credenciales se resuelven mediante la cadena predeterminada del SDK de AWS. |
| `AWS_ENDPOINT_URL` | — | Anulación de endpoint compatible con AWS. Déjala sin configurar en entornos reales de AWS para que el SDK use sus endpoints predeterminados. |

## Ciclo de vida de las claves criptográficas

El cifrado en sobre usa una clave de datos por registro, sellada bajo la clave maestra de la institución, más un índice ciego para búsquedas de coincidencia exacta en identificadores fiscales.

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `SISBAJUD_DEK_CACHE_TTL` | `5m` | Duración de una clave de cifrado de datos desenvuelta en la caché en memoria antes de solicitar al KMS que la desenvuelva de nuevo. Cadena de duración de Go. |
| `SISBAJUD_HMAC_COEXISTENCE_WINDOW` | `720h` | Ventana durante la cual los hashes de índice ciego de la versión anterior de la clave HMAC siguen siendo consultables durante una rotación de claves. Cadena de duración de Go. |
| `KEK_REWRAP_BACKFILL_ENABLED` | `false` | Habilita el barrido en segundo plano que actualiza las filas de clave de datos rezagadas a la versión activa de la clave maestra después de una rotación. |
| `REHASH_BACKFILL_ENABLED` | `false` | Habilita el barrido en segundo plano que vuelve a aplicar hash a las filas rezagadas de índice ciego con la nueva versión primaria de la clave HMAC. |

## Workers de dominio

El procesamiento de órdenes judiciales se ejecuta como un conjunto de crons en segundo plano por institución. Todos están deshabilitados de forma predeterminada, excepto el reaper de bloqueos de procesamiento, que se ejecuta de forma predeterminada.

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `EXECUTION_ENABLED` | `false` | Interruptor maestro del motor de ejecución de órdenes. Cuando está deshabilitado, el orquestador FIFO y el despacho downstream permanecen inactivos. |
| `ORCHESTRATOR_LOCK_TTL` | `30` | Lease del bloqueo de ejecución por sujeto, en segundos. |
| `ORCHESTRATOR_RENEW_INTERVAL` | `10` | Cadencia, en segundos, con la que el worker propietario renueva el bloqueo. Debe permanecer estrictamente por debajo de `ORCHESTRATOR_LOCK_TTL` o el arranque falla en modo fail-closed. |
| `PROCESSING_LOCK_REAPER_ENABLED` | `true` | Habilita el reaper en segundo plano que elimina las filas de bloqueo de procesamiento vencidas de cada tenant. |
| `PROCESSING_LOCK_REAPER_INTERVAL_SEC` | `300` | Cadencia de barrido del reaper en segundos. Cuando esta variable no está configurada o no es positiva, el servicio usa 300 segundos. |
| `UNBLOCK_EXECUTION_SCAN_INTERVAL` | `60` | Cadencia de barrido de desbloqueos pendientes en segundos. Comparte el control de `EXECUTION_ENABLED`. |
| `UNBLOCK_EXECUTION_BATCH_SIZE` | `500` | Órdenes de desbloqueo pendientes procesadas por cada pasada de tenant. |
| `INFORMATION_REQUEST_ENABLED` | `false` | Habilita el worker que procesa las órdenes de solicitud de información pendientes. |
| `MONITORING_EXPIRY_ENABLED` | `false` | Habilita el escaneo diario que cierra las órdenes en monitoreo no permanentes al final de su ventana de monitoreo. |
| `PERMANENT_BLOCK_EXPIRY_ENABLED` | `false` | Habilita el escaneo diario que vence los bloqueos permanentes que superaron su plazo. |
| `RECONCILIATION_ENABLED` | `false` | Habilita el escaneo que concilia las órdenes en monitoreo contra el ledger y persiste las discrepancias detectadas. |
| `RETURN_FILE_GENERATION_ENABLED` | `false` | Habilita la generación de archivos de retorno de SISBAJUD para órdenes terminales sin retornar. |
| `RETURN_FILE_GENERATION_SCAN_INTERVAL` | `3600` | Cadencia de generación de archivos de retorno, en segundos. |
| `INFORMATION_RETURN_FILE_GENERATION_ENABLED` | `false` | Habilita la generación de archivos de respuesta de información AJUD309. |
| `INFORMATION_RETURN_FILE_GENERATION_SCAN_INTERVAL` | `3600` | Cadencia de generación de respuestas de información, en segundos. |
| `SLA_ALERT_ENABLED` | `false` | Habilita el evaluador que clasifica las órdenes activas por banda de riesgo de SLA y emite las bandas como métricas. |
| `RETURN_FILE_ENVIRONMENT` | `HOMOLOGATION` | `PRODUCTION` o `HOMOLOGATION`. Un archivo de retorno generado toma el entorno del archivo de remesa detrás de sus órdenes. Este valor se aplica solo cuando ningún archivo de remesa respalda esas órdenes. Un valor no válido desactiva la generación de archivos de retorno. |
| `SISBAJUD_REMITTANCE_LAYOUTS` | `v111,v2026` | Layouts de remesa que acepta el servicio, separados por comas: `v111` (CNJ v1.11) y `v2026`. El servicio rechaza en la recepción un archivo en cualquier otro layout. Un valor no válido hace fallar el arranque. |
| `SISBAJUD_RESPONSE_LAYOUT` | `auto` | Layout de la respuesta de bloqueo. `auto` responde a cada remesa en el layout en que llegó. `v111` o `v2026` fuerza un solo layout. Un valor no válido hace fallar el arranque. |

## Almacenamiento de objetos

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `SEAWEEDFS_S3_ENDPOINT` | `http://localhost:8333` | Endpoint del almacén de objetos compatible con S3. Con `STA_TRANSFERS_ENABLED` desactivado, los fallos de conexión del almacenamiento no son fatales: el servicio arranca y el sondeo de readiness reporta la verificación del almacén como `n/a`. |
| `SEAWEEDFS_BUCKET` | `sisbajud` | Bucket para los artefactos de remesa y retorno (ya cifrados). |
| `SEAWEEDFS_REGION` | `us-east-1` | Etiqueta de región de S3 requerida por el SDK de AWS. |
| `SEAWEEDFS_ACCESS_KEY` | — | Clave de acceso del almacén de objetos. Sensible. Déjala en blanco cuando el almacén no requiera autenticación. |
| `SEAWEEDFS_SECRET_KEY` | — | Clave secreta del almacén de objetos. Sensible. Déjala en blanco cuando el almacén no requiera autenticación. |
| `STA_INBOUND_BUCKET` | **Obligatorio** | Bucket que contiene los objetos de remesa en bruto a los que apunta una notificación de recepción o un evento de Lerian STA. El arranque falla cuando está vacío. |
| `STA_FILE_LOCK_TTL` | `5` | TTL del bloqueo de procesamiento por archivo, en minutos. |

## Streaming de eventos

Lerian SISBAJUD publica sus eventos de negocio y recibe los eventos de saldo de Midaz por Kafka.

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `STREAMING_ENABLED` | `true` | Publica los eventos de negocio del servicio. Requiere `OUTBOX_ENABLED`. Con ella desactivada, un `STREAMING_BROKERS` configurado hace fallar el arranque. |
| `STREAMING_BROKERS` | — | Lista de brokers de Kafka. Inicia el disparador de cambio de saldo para los reintentos de bloqueo permanente. Sin ella, solo el barrido de 5 segundos reintenta. `STA_CONSUMER_ENABLED` también la requiere. |
| `OUTBOX_ENABLED` | `true` | Ruta de entrega duradera de los eventos emitidos. `STREAMING_ENABLED` y `STA_TRANSFERS_ENABLED` la requieren. |

## Intercambio de archivos por STA

Lerian SISBAJUD intercambia archivos judiciales con el BACEN a través de [Lerian STA](/es/rails/sta/what-is-lerian-sta).

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `STA_CONSUMER_ENABLED` | `false` | Recibe archivos de entrada a partir de los eventos que publica Lerian STA. Requiere `STREAMING_BROKERS`. |
| `STA_TRANSFERS_ENABLED` | `false` | Envía los archivos de retorno generados a Lerian STA para su transmisión al BACEN. Requiere `PLUGIN_AUTH_HOST`. |
| `STA_SOURCE_PRODUCT` | **Obligatorio si alguno de los interruptores está activado** | Nombre de producto de origen que Lerian STA registra para este riel. Usa el valor de tu configuración de Lerian STA. |
| `STA_OBJECT_STORAGE_ENDPOINT` | **Obligatorio si alguno de los interruptores está activado** | Endpoint del almacén de objetos que usa Lerian STA. Debe apuntar al mismo almacén que `SEAWEEDFS_S3_ENDPOINT`. |
| `STA_BACEN_SYSTEM_CODE` | **Obligatorio si el consumidor está activado** | Código de sistema del BACEN de los archivos que se aceptan: `JUD` para SISBAJUD. |
| `STA_EXPECTED_TENANT_ST` | **Obligatorio si el consumidor está activado** | Tenant que Lerian STA estampa en sus eventos en modo single-tenant. Configura el `DEFAULT_TENANT_ID` de tu despliegue de Lerian STA. La variable debe existir, pero un valor vacío es válido. |
| `STA_MAX_INBOUND_SIZE_BYTES` | **Obligatorio si el consumidor está activado** | Archivo de entrada más grande, en bytes, que descarga el consumidor. Debe ser mayor que 0. La configuración de ejemplo usa `52428800`. |
| `STA_TRANSFERS_BASE_URL` | **Obligatorio si el envío está activado** | URL base de la API de Lerian STA. |
| `STA_DOCUMENT_TYPE_AJUD302` | **Obligatorio si el envío está activado** | Tipo de documento de Lerian STA para la respuesta de bloqueo. La configuración de ejemplo usa `AJUD302`. |
| `STA_DOCUMENT_TYPE_AJUD309` | **Obligatorio si el envío está activado** | Tipo de documento de Lerian STA para la respuesta de información. La configuración de ejemplo usa `AJUD309`. |
| `TRANSFER_OBJECT_STORAGE_BUCKET` | **Obligatorio si el envío está activado** | Bucket compartido con Lerian STA para los archivos de retorno de salida. Debe nombrar el mismo bucket que `STA_INBOUND_BUCKET`. |
| `STA_CLIENT_ID` | **Obligatorio si el envío está activado** | Id de cliente OAuth que obtiene el token para Lerian STA. |
| `STA_CLIENT_SECRET` | **Obligatorio si el envío está activado** | Secreto de cliente OAuth para Lerian STA. Sensible. |

## Conector del ledger de Midaz

Lerian SISBAJUD lee saldos y bloqueos a través del ledger de Midaz. La configuración de cada institución define la dirección de Midaz, la dirección de autorización y las credenciales. Ninguna variable de entorno las define.

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `MIDAZ_CRM_MODE` | `legacy` | Superficie de CRM que el conector consulta para encontrar las cuentas de un demandado: `legacy` o `embedded` (el CRM dentro del ledger de Midaz). El `crmMode` propio de una institución la reemplaza. Cualquier otro valor hace fallar el arranque. |
| `MIDAZ_BALANCE_DEFAULT_ACCOUNT_TYPE` | `deposit` | Tipo de cuenta que el servicio usa para un evento de saldo cuando la cuenta bloqueada no tiene un tipo registrado. |


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