> ## 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 y el ledger de Midaz.
Lerian SISBAJUD es el riel propiedad de Lerian que cumple órdenes judiciales de bloqueo de activos y protege los datos personales que contienen. 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` | — | Dirección de escucha HTTP principal; no tiene valor predeterminado en el código, así que configúrala explícitamente (el despliegue de referencia usa `:4029`). Los sondeos de liveness, readiness, métricas 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. Si no se configura, queda vacío y se trata como similar a producción, por lo que los controles de seguridad más estrictos se activan en modo fail-closed. |
| `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` | **Obligatorio en modo single-tenant** | UUID del tenant usado en modo single-tenant. No hay un valor de cadena predeterminado efectivo: configura explícitamente un UUID válido para una operación single-tenant utilizable. 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. |
Lerian SISBAJUD expone `/health` (liveness), `/readyz` (readiness), `/version` y `/metrics` en el puerto principal. 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.
## Backend de seguridad
El servicio valida el proveedor de KMS al iniciar. Selecciona el backend que protege los datos de embargo ordenados judicialmente mediante cifrado en sobre. En producción, un valor no configurado o no admitido hace fallar el arranque en modo fail-closed. Fuera de producción, usa `vault` de forma predeterminada.
| Variable | Predeterminado / Obligatorio | Descripción |
| -------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KMS_PROVIDER` | `vault` (fuera de producción) · **Obligatorio en producción** | 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. |
`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. `KMS_PROVIDER` usa `vault` de forma predeterminada cuando no se configura fuera de producción. En producción, debes configurarlo explícitamente o el arranque falla en modo fail-closed.
### 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`, en producción** | Token de servicio para Vault. Sensible. Fuera de producción, 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_DEK_CACHE_MAX_ENTRIES` | `50000` | Límite máximo de primitivas de clave de datos en caché; acota el uso de heap durante un descifrado por lotes grande. |
| `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. Los workers usan los controles de cadencia `*_SCAN_INTERVAL` (segundos) y `*_BATCH_SIZE` donde corresponde.
| 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. |
| `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. |
| `INFORMATION_RETURN_FILE_GENERATION_ENABLED` | `false` | Habilita la generación de archivos de respuesta de información AJUD309. |
| `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` | Entorno regulatorio grabado en los archivos de retorno generados. |
## Almacenamiento de objetos
Lerian SISBAJUD escribe los artefactos de embargo ordenados judicialmente en un almacén de objetos compatible con S3, ya cifrados. La capa de blobs nunca ve texto plano.
| Variable | Predeterminado / Obligatorio | Descripción |
| ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SEAWEEDFS_S3_ENDPOINT` | `http://localhost:8333` | Endpoint del almacén de objetos compatible con S3. Los fallos de conexión del almacenamiento no son fatales: el servicio arranca y el sondeo de readiness reporta el almacén como no disponible. |
| `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` | `sta-files` | Bucket que contiene los objetos de remesa en bruto a los que apunta una notificación de recepción. |
| `STA_FILE_LOCK_TTL` | `5` | TTL del bloqueo de procesamiento por archivo, en minutos. |
## Conector del ledger de Midaz
Lerian SISBAJUD lee saldos y bloqueos a través del ledger de Midaz. `MIDAZ_BASE_URL` es un fallback opcional para todo el servicio. Los metadatos del conector por institución tienen prioridad.
| Variable | Predeterminado / Obligatorio | Descripción |
| --------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `MIDAZ_BASE_URL` | — (alternativa opcional) | URL base del ledger de Midaz. Se usa solo cuando los metadatos por institución no proporcionan una URL. La resolución del conector falla en modo fail-closed únicamente si ninguna de las dos proporciona una URL. |
| `MIDAZ_AUTH_ENABLED` | `false` | Habilita la autenticación máquina a máquina con Midaz. |
| `MIDAZ_AUTH_ADDRESS` | **Obligatorio si está habilitado** | Dirección del servicio de autenticación para emitir tokens de Midaz. |
| `MIDAZ_CLIENT_ID` | **Obligatorio si está habilitado** | Id de cliente OAuth para Midaz. Se ignora en modo multi-tenant (se resuelve por tenant). |
| `MIDAZ_CLIENT_SECRET` | **Obligatorio si está habilitado** | Secreto de cliente OAuth para Midaz. Sensible. Se ignora en modo multi-tenant (se resuelve por tenant). |