> ## 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 definidas en el despliegue para el plugin Bank Transfer — infraestructura, persistencia, integraciones y seguridad.
Estas son variables definidas en el momento del despliegue por DevOps; los cambios requieren reiniciar el servicio. Las configuraciones de runtime y de negocio viven en [Configuración](/es/rails/ted/jd/ted-configuration).
En las tablas a continuación, la columna **Por defecto / Obligatoria** muestra el valor por defecto; un calificador en negrita (p. ej. **Obligatoria**, **Obligatoria en producción**, **Obligatoria si está habilitado**) marca las variables que deben definirse. `—` significa que no hay valor por defecto.
## Configuración de infraestructura
***
Esta sección es para equipos de DevOps. Estas variables se establecen en el momento del despliegue y requieren un reinicio del servicio para tener efecto.
### Aplicación
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ENV_NAME` | `development` | Entorno (`development`, `staging`, `production`) |
| `DEPLOYMENT_MODE` | `byoc` | Sabor de despliegue. `byoc` = Bring Your Own Cloud (single-tenant, gestionado por el operador). Activa comportamientos internos SaaS vs. BYOC. |
| `SERVER_ADDRESS` | `:8080` | Dirección y puerto del servidor HTTP |
| `HTTP_BODY_LIMIT_BYTES` | `1048576` | Tamaño máximo del cuerpo de la solicitud HTTP en bytes |
| `ALLOW_PRIVATE_UPSTREAMS` | `false` | ⚠️ Permite que adaptadores de salida (CRM, Fees, JD, Midaz) resuelvan a IPs RFC1918/loopback. El valor por defecto `false` es fail-closed: producción bloquea el pivot DNS hacia el espacio privado. Habilítelo en dev o en BYOC in-cluster, donde los upstreams legítimamente viven en IPs privadas. Los endpoints de metadatos en cloud permanecen bloqueados independientemente de este flag. |
### TLS
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------- | ------------------------- | -------------------------------------------------------------------------------------------- |
| `SERVER_TLS_CERT_FILE` | — | Ruta al archivo de certificado TLS. Debe definirse junto con `SERVER_TLS_KEY_FILE`. |
| `SERVER_TLS_KEY_FILE` | — | Ruta al archivo de clave privada TLS. Debe definirse junto con `SERVER_TLS_CERT_FILE`. |
| `TLS_TERMINATED_UPSTREAM` | `false` | Establezca en `true` cuando el TLS es terminado por un balanceador de carga o proxy inverso. |
### Headers de proxy
Se utilizan cuando el servicio se ejecuta detrás de un balanceador de carga o proxy inverso. Necesarios para extraer la IP real del cliente para rate limiting y logs de auditoría.
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `SERVER_PROXY_HEADER` | — | Header HTTP que transporta la IP real del cliente (p. ej. `X-Forwarded-For`, `X-Real-IP`). Vacío deshabilita el parseo del header de proxy. |
| `SERVER_TRUSTED_PROXIES` | **Obligatoria si el proxy header está definido** | Lista separada por coma de IPs/CIDRs de proxies confiables. Requerido cuando `SERVER_PROXY_HEADER` está definido para evitar spoofing de IP. |
### Autenticación
Este plugin delega la autorización a `plugin-auth`. Configura la conexión con las variables a continuación.
| Variable | Por defecto / Obligatoria | Descripción |
| --------------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
| `PLUGIN_AUTH_ENABLED` | `false` | Habilita la autorización vía plugin-auth. Establezca en `true` en producción. |
| `PLUGIN_AUTH_ADDRESS` | **Obligatoria si está habilitado** | URL del servicio plugin-auth. Debe usar HTTPS en producción. |
Cuando `PLUGIN_AUTH_ENABLED=true`, `PLUGIN_AUTH_ADDRESS` debe usar HTTPS en entornos de producción. Las direcciones HTTP son rechazadas al inicio.
### Test admin (solo no-producción)
`BTF_TEST_ADMIN_ENABLED` debe permanecer en `false` en producción. Expone endpoints administrativos solo de prueba (p. ej. `POST /admin/test/circuit-breakers/reset`) que no tienen tenant y omiten la autenticación de producción. Solo se habilita en el mock-lane de docker-compose para pruebas E2E; cualquier despliegue con este flag en `true` fuera de una red de pruebas aislada constituye un error de configuración.
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BTF_TEST_ADMIN_ENABLED` | `false` | ⚠️ Expone endpoints administrativos solo de prueba. Debe permanecer en `false` en producción. |
| `BTF_TEST_ADMIN_TOKEN` | **Obligatoria si admin está habilitado** | Token requerido cuando `BTF_TEST_ADMIN_ENABLED=true`. Se envía en el header `X-Test-Admin-Token`. Es intencionalmente independiente de la auth de producción (superficie solo de prueba, sin tenant). |
### Idempotencia
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------- |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | `300` | Ventana de tiempo (en segundos) durante la cual una clave de idempotencia se considera válida. |
### Multi-tenancy
| Variable | Por defecto / Obligatoria | Descripción |
| --------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MULTI_TENANT_ENABLED` | `false` | Habilita multi-tenancy a nivel de infraestructura con bases de datos aisladas por tenant. |
| `ORGANIZATION_ID` | **Obligatoria (single-tenant + JD polling)** | UUID de organización Midaz inyectado en el contexto de los workers en segundo plano (poller de TED IN, reconciliación) en modo single-tenant. Requerido cuando `MULTI_TENANT_ENABLED=false` y `JD_POLLING_ENABLED=true`. Ignorado en modo multi-tenant, donde los vínculos de organización por tenant los resuelve el tenant manager. Las solicitudes HTTP siempre llevan la organización en el header `X-Organization-Id` en su lugar. |
| `AWS_REGION` | **Obligatoria si el backend de secretos es AWS** | Región AWS para lecturas de secretos por tenant en Secrets Manager. Requerido cuando `MULTI_TENANT_ENABLED=true` y el backend de secretos es AWS. |
| `ORGANIZATION_IDS` | **Obligatoria en producción** | Lista separada por coma de UUIDs de organización Midaz en el alcance de licenciamiento. El gateway de licencia valida `LICENSE_KEY` contra estos al inicio. También referenciada en [Licencia](#licencia). |
| `MULTI_TENANT_URL` | **Obligatoria cuando está habilitado** | URL del servicio de la plataforma de multi-tenancy. |
| `MULTI_TENANT_REDIS_HOST` | — | Host Redis para descubrimiento de tenants dirigido por eventos vía Pub/Sub. |
| `MULTI_TENANT_REDIS_PORT` | `6379` | Puerto de Redis para Pub/Sub. |
| `MULTI_TENANT_REDIS_PASSWORD` | — | Contraseña de Redis para Pub/Sub. |
| `MULTI_TENANT_REDIS_TLS` | `false` | Habilita TLS para la conexión Redis Pub/Sub. |
| `MULTI_TENANT_REDIS_CA_CERT` | — | Certificado CA para la conexión TLS de Redis Pub/Sub multi-tenant. |
| `MULTI_TENANT_TIMEOUT` | `30` | Timeout HTTP en segundos para llamadas al servicio de multi-tenancy. |
| `MULTI_TENANT_MAX_TENANT_POOLS` | `100` | Máximo de pools de conexión a base de datos simultáneos por tenant. |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | `300` | Timeout de inactividad en segundos antes de descartar un pool de tenant. |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | `5` | Número de fallos antes de que el circuit breaker se abra. |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | `30` | Timeout de recuperación en segundos del circuit breaker. |
| `MULTI_TENANT_SERVICE_API_KEY` | **Obligatoria cuando está habilitado** | Clave de API para el endpoint `/settings` del servicio de multi-tenancy. |
| `MULTI_TENANT_CACHE_TTL_SEC` | `120` | TTL en segundos del caché in-memory de configuración de tenant. Recargable en caliente vía systemplane API. |
| `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | `30` | Intervalo en segundos para revalidación asíncrona de configuraciones de pool. Solo bootstrap (no recargable en caliente). |
**BYOC single-tenant:**
```bash theme={null}
# Organización inyectada en los workers en segundo plano (requerido cuando el JD polling está habilitado)
ORGANIZATION_ID=
# Alcance de licenciamiento validado contra LICENSE_KEY en producción
ORGANIZATION_IDS=
```
**SaaS multi-tenant:**
```bash theme={null}
MULTI_TENANT_ENABLED=true
MULTI_TENANT_URL=http://tenant-manager:4003
MULTI_TENANT_SERVICE_API_KEY=su-api-key
MULTI_TENANT_REDIS_HOST=redis.example.com
```
### PostgreSQL
| Variable | Por defecto / Obligatoria | Descripción |
| ---------------------------------- | ------------------------------------------- | ----------------------------------------------------- |
| `POSTGRES_HOST` | `localhost` · **Obligatoria** | Host primario de PostgreSQL. |
| `POSTGRES_PORT` | `5432` | Puerto primario de PostgreSQL. |
| `POSTGRES_USER` | `plugin-br-bank-transfer` · **Obligatoria** | Usuario de base de datos. |
| `POSTGRES_PASSWORD` | **Obligatoria** | Contraseña de base de datos. Requerido en producción. |
| `POSTGRES_DB` | `plugin-br-bank-transfer` · **Obligatoria** | Nombre de la base de datos. |
| `POSTGRES_SSLMODE` | `require` | Modo SSL. `disable` es rechazado en producción. |
| `POSTGRES_MAX_OPEN_CONNS` | `25` | Máximo de conexiones abiertas. |
| `POSTGRES_MAX_IDLE_CONNS` | `5` | Máximo de conexiones inactivas. |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | `30` | Tiempo máximo de vida de la conexión en minutos. |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | `5` | Tiempo máximo inactivo de la conexión en minutos. |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | `10` | Timeout de conexión en segundos. |
### Réplica PostgreSQL
Configura una réplica de lectura para descarga de consultas. Todos los campos usan valores primarios como fallback cuando no están definidos.
| Variable | Por defecto / Obligatoria | Descripción |
| --------------------------- | ------------------------- | ---------------------------------------------- |
| `POSTGRES_REPLICA_HOST` | — | Host de la réplica. No definido = sin réplica. |
| `POSTGRES_REPLICA_PORT` | — | Puerto de la réplica. |
| `POSTGRES_REPLICA_USER` | — | Usuario de la réplica. |
| `POSTGRES_REPLICA_PASSWORD` | — | Contraseña de la réplica. |
| `POSTGRES_REPLICA_DB` | — | Nombre de la base de datos de la réplica. |
| `POSTGRES_REPLICA_SSLMODE` | — | Modo SSL de la réplica. |
### MongoDB
MongoDB es necesario para la persistencia de eventos de auditoría de transferencias. El servicio no se iniciará sin una conexión MongoDB válida.
| Variable | Por defecto / Obligatoria | Descripción |
| ----------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MONGO_ENABLED` | `true` · **Obligatoria** | Habilita la conexión MongoDB. Debe ser `true` en todos los entornos. |
| `MONGO_URI` | **Obligatoria** | Cadena de conexión MongoDB (ej: `mongodb://user:pass@host:27017`). Debe incluir credenciales y TLS en producción. |
| `MONGO_DATABASE` | **Obligatoria** | Nombre de la base de datos MongoDB. |
| `MONGO_MAX_POOL_SIZE` | `25` | Tamaño máximo del pool de conexiones. |
| `MONGO_SERVER_SELECTION_TIMEOUT_MS` | `3000` | Timeout de selección de servidor en milisegundos. |
| `MONGO_HEARTBEAT_INTERVAL_MS` | `10000` | Intervalo de heartbeat en milisegundos. |
| `MONGO_TLS_CA_CERT` | — | Certificado CA codificado en base64 para TLS de MongoDB. Úselo cuando MongoDB requiere TLS con CA personalizado (p. ej. Atlas, instancias privadas con certs autofirmados). |
### Redis
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------ | ---------------------------------- | ---------------------------------------------------------- |
| `REDIS_HOST` | `localhost:6379` · **Obligatoria** | Host y puerto de Redis. |
| `REDIS_MASTER_NAME` | — | Nombre del master Redis Sentinel (si usa Sentinel). |
| `REDIS_PASSWORD` | — | Contraseña de Redis (si la autenticación está habilitada). |
| `REDIS_DB` | `0` | Número de base de datos Redis. |
| `REDIS_PROTOCOL` | `3` | Versión del protocolo Redis (2 o 3). |
| `REDIS_TLS` | `false` | Habilita TLS para conexiones Redis. |
| `REDIS_CA_CERT` | — | Certificado CA para TLS Redis. |
| `REDIS_POOL_SIZE` | `10` | Tamaño del pool de conexiones. |
| `REDIS_MIN_IDLE_CONNS` | `2` | Mínimo de conexiones inactivas. |
| `REDIS_READ_TIMEOUT_MS` | `3000` | Timeout de lectura en milisegundos. |
| `REDIS_WRITE_TIMEOUT_MS` | `3000` | Timeout de escritura en milisegundos. |
| `REDIS_DIAL_TIMEOUT_MS` | `5000` | Timeout de conexión en milisegundos. |
Redis es una dependencia obligatoria. Si Redis no está disponible al inicio o se vuelve inalcanzable en tiempo de ejecución, el servicio reportará como DOWN a la sonda de readiness de la orquestación y dejará de aceptar solicitudes. Redis es necesario para el caché de claves de idempotencia y la detección de duplicados.
### Conexión JD SPB
Estas variables son requeridas para despliegues BYOC. En modo SaaS, Lerian gestiona la conexión JD.
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JD_BASE_URL` | **Obligatoria en BYOC** | URL base de la API JD SPB. |
| `JD_SOAP_PATH` | `/soap` | Ruta del endpoint SOAP JD. |
| `JD_LEGACY_CODE` | **Obligatoria en BYOC** | Código legacy JD (máx. 10 caracteres). |
| `JD_USER_CODE` | **Obligatoria en BYOC** | Código de usuario JD (máx. 10 caracteres). |
| `JD_PASSWORD` | **Obligatoria en BYOC** | Contraseña JD (encriptada en reposo). |
| `JD_PRIVATE_KEY_PEM` | **Obligatoria en BYOC** | Contenido PEM de clave privada RSA para firma XML. |
| `JD_PRIVATE_KEY_PEM_FILE` | — | Ruta a un archivo que contiene el PEM de la clave privada RSA. Alternativa a incluir la clave en línea en `JD_PRIVATE_KEY_PEM`; se lee al inicio. |
| `JD_PUBLIC_KEY_PEM` | — | PEM de clave pública para validar firmas en respuestas de JD. |
| `JD_PRIVATE_KEY_KEYINFO` | — | Bloque XML `` embebido en la firma SOAP (p. ej. cert X509 codificado en base64). Requerido para el envoltorio WS-Security cuando JD demanda identificación por certificado. |
| `JD_CERT_PEM` | — | Certificado X.509 codificado en PEM opcional, emparejado con la clave de firma de JD. Lo usa únicamente el gauge de métricas de expiración de certificado, no la ruta de firma; un PEM mal formado es un error de inicio. |
| `JD_SIGNING_MODE` | `local_pem` | Modo de firma SOAP. `local_pem` firma localmente con `JD_PRIVATE_KEY_PEM`; `external_signer` delega a un servicio remoto vía `JD_EXTERNAL_SIGNER_URL`. |
| `JD_EXTERNAL_SIGNER_URL` | **Obligatoria si `JD_SIGNING_MODE=external_signer`** | URL base del servicio de firma externo. |
| `JD_EXTERNAL_SIGNER_AUTH_TOKEN` | — | Bearer token enviado en el header `Authorization` para llamadas al firmador externo. |
| `JD_EXTERNAL_SIGNER_TIMEOUT_MS` | `5000` | Timeout (en milisegundos) para llamadas al firmador externo. |
| `JD_SANDBOX_MODE` | `false` | Habilita modo sandbox JD. Rechazado en producción. |
### Polling JD
| Variable | Por defecto / Obligatoria | Descripción |
| -------------------------- | ------------------------- | ------------------------------------------------------------------- |
| `JD_POLLING_ENABLED` | `false` | Habilita worker de polling TED IN. |
| `JD_POLL_INTERVAL_SECONDS` | `60` | Frecuencia (en segundos) con que el plugin consulta TEDs entrantes. |
`JD_POLLING_ENABLED` está deshabilitado por defecto para despliegues más seguros. En modo single-tenant, configure `ORGANIZATION_ID` antes de habilitarlo — los workers en segundo plano lo inyectan en el contexto para las llamadas downstream a CRM/Midaz. En modo multi-tenant, el gestor del poller de TED IN inicia un poller por cada tenant activo descubierto a través del servicio de la plataforma de multi-tenancy y resuelve la configuración JD de cada tenant mediante el resolvedor de integración del tenant.
### Servicios externos (Midaz)
| Variable | Por defecto / Obligatoria | Descripción |
| ----------------------- | ---------------------------------- | -------------------------------------------------------- |
| `MIDAZ_BASE_URL` | **Obligatoria** | URL base del servicio Midaz. |
| `MIDAZ_TRANSACTION_URL` | **Obligatoria** | URL del servicio de transacciones Midaz. |
| `MIDAZ_TIMEOUT_MS` | `3000` | Timeout de solicitudes Midaz en milisegundos. |
| `MIDAZ_MAX_RETRIES` | `3` | Intentos de reintento al fallar Midaz. |
| `MIDAZ_AUTH_ENABLED` | `false` | Habilita autenticación M2M para Midaz. |
| `MIDAZ_AUTH_ADDRESS` | **Obligatoria si está habilitado** | URL del servicio de autenticación para tokens M2M Midaz. |
| `MIDAZ_CLIENT_ID` | **Obligatoria si está habilitado** | OAuth client ID para M2M Midaz. |
| `MIDAZ_CLIENT_SECRET` | **Obligatoria si está habilitado** | OAuth client secret para M2M Midaz. |
### Servicios externos (CRM)
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------- | ---------------------------------- | ------------------------------------------- |
| `CRM_BASE_URL` | **Obligatoria** | URL del servicio CRM. |
| `CRM_TIMEOUT_MS` | `2000` | Timeout de solicitudes CRM en milisegundos. |
| `CRM_MAX_RETRIES` | `2` | Intentos de reintento al fallar el CRM. |
| `CRM_AUTH_ENABLED` | `false` | Habilita autenticación M2M para CRM. |
| `CRM_CLIENT_ID` | **Obligatoria si está habilitado** | OAuth client ID para M2M CRM. |
| `CRM_CLIENT_SECRET` | **Obligatoria si está habilitado** | OAuth client secret para M2M CRM. |
### Servicios externos (Fees)
`BTF_FEE_ENABLED` es el switch maestro. Cuando es `false` (por defecto), no se construye el adaptador de Fees y cada transferencia procede con tarifa=0 sin llamada HTTP. Las demás variables `FEES_*` solo tienen efecto cuando `BTF_FEE_ENABLED=true`.
| Variable | Por defecto / Obligatoria | Descripción |
| -------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BTF_FEE_ENABLED` | `false` | Switch maestro para la integración con plugin-fees. Cuando es `false`, no se construye el adaptador de Fees y todas las transferencias se ejecutan con tarifa=0 sin llamadas HTTP. Los operadores que ejecutan plugin-fees deben establecer esto explícitamente en `true`. |
| `FEES_BASE_URL` | **Obligatoria si está habilitado** | URL del servicio Fees Engine. |
| `FEES_TIMEOUT_MS` | `2000` | Timeout de solicitudes de tarifas en milisegundos. |
| `FEES_MAX_RETRIES` | `2` | Intentos de reintento al fallar el servicio de tarifas. |
| `FEES_AUTH_ENABLED` | `false` | Habilita autenticación M2M para Fees. |
| `FEES_CLIENT_ID` | **Obligatoria si está habilitado** | OAuth client ID para M2M Fees. |
| `FEES_CLIENT_SECRET` | **Obligatoria si está habilitado** | OAuth client secret para M2M Fees. |
### RabbitMQ
Los eventos de ciclo de vida de transferencia pueden publicarse en RabbitMQ para consumidores downstream.
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `RABBITMQ_ENABLED` | `false` | Habilita publicación de eventos de ciclo de vida de transferencia. |
| `RABBITMQ_URL` | **Obligatoria si está habilitado** | URL de conexión AMQP. Debe usar `amqps://` fuera de desarrollo. |
| `RABBITMQ_HEALTH_CHECK_URL` | — | URL HTTP(S) del endpoint de salud de management de RabbitMQ. El hostname debe coincidir con `RABBITMQ_URL`; debe usar `https://` en producción. |
| `RABBITMQ_EXCHANGE` | `bank_transfer.lifecycle` | Nombre del exchange para eventos de ciclo de vida. |
| `RABBITMQ_EVENT_SIGNING_SECRET` | **Obligatoria si está habilitado** | Secreto HMAC para firmar eventos publicados. Mínimo 32 caracteres. |
### Streaming outbox
El subsistema de streaming publica eventos de transferencia en un broker Redpanda/Kafka a través de un outbox transaccional. Debe estar habilitado para que funcione la entrega saliente de webhooks (`WEBHOOK_ENABLED=true` requiere `STREAMING_ENABLED=true`).
| Variable | Por defecto / Obligatoria | Descripción |
| -------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
| `STREAMING_ENABLED` | `false` | Habilita el subsistema de streaming outbox. Requerido para la entrega de webhooks. |
| `STREAMING_BROKERS` | **Obligatoria si está habilitado** | Lista separada por coma de direcciones de brokers Kafka/Redpanda. |
| `STREAMING_CLIENT_ID` | — | Client ID presentado al broker. |
| `STREAMING_CLOUDEVENTS_SOURCE` | **Obligatoria si está habilitado** | Atributo `source` de CloudEvents establecido en los eventos publicados. |
| `STREAMING_OUTBOX_DISPATCH_INTERVAL_SECONDS` | `30` | Intervalo (en segundos) entre ciclos de despacho del outbox. Debe ser > 0. |
| `STREAMING_CB_FAILURE_RATIO` | `0.5` | Ratio de fallos del circuit breaker que dispara el breaker (debe ser > 0 y ≤ 1). |
| `STREAMING_CB_MIN_REQUESTS` | `10` | Mínimo de solicitudes en una ventana antes de que el circuit breaker pueda dispararse. |
| `STREAMING_CB_TIMEOUT_S` | `30` | Timeout de recuperación del circuit breaker en segundos. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Timeout de apagado controlado (en segundos) para el productor de streaming. |
### Entrega de webhooks
La entrega saliente de webhooks requiere que tanto RabbitMQ como el streaming outbox estén habilitados. El worker de webhook consume eventos de una cola RabbitMQ y los entrega a los endpoints suscriptores.
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WEBHOOK_ENABLED` | `false` | Habilita la entrega saliente de webhooks. Requiere `RABBITMQ_ENABLED=true` y `STREAMING_ENABLED=true`. |
| `WEBHOOK_SIGNING_SECRET` | **Obligatoria si está habilitado** | Secreto HMAC para firmar payloads de webhook. Mínimo 32 caracteres. |
| `WEBHOOK_BROKER_EVENT_SIGNING_SECRET` | — | Secreto HMAC separado para verificar eventos del broker. Usa `WEBHOOK_SIGNING_SECRET` como fallback. |
| `WEBHOOK_QUEUE_NAME` | `transfer.webhook.delivery` | Nombre de la cola RabbitMQ para eventos de webhook. |
| `WEBHOOK_DLQ_NAME` | `transfer.webhook.dlq` | Cola de dead-letter para entregas de webhook fallidas. |
| `WEBHOOK_DLX_EXCHANGE_NAME` | — | Nombre del exchange de dead-letter. Cuando está vacío, el worker deriva `.exchange`. Sobrescríbalo para centralizar el DLX entre plugins. |
| `WEBHOOK_DLQ_MESSAGE_TTL_MS` | `0` | `x-message-ttl` de la DLQ en milisegundos. `0` usa el valor por defecto de la biblioteca (7 días). Los cambios de topología requieren eliminar la DLQ existente antes de redesplegar. |
| `WEBHOOK_DLQ_MAX_LENGTH` | `0` | Conteo máximo de mensajes en la DLQ. `0` usa el valor por defecto de la biblioteca (10000). |
| `WEBHOOK_PREFETCH_COUNT` | `20` | Conteo de prefetch RabbitMQ. |
| `WEBHOOK_DELIVERY_CONCURRENCY` | `8` | Máximo de entregas de webhook concurrentes por worker. |
### Telemetría (OpenTelemetry)
| Variable | Por defecto / Obligatoria | Descripción |
| -------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ENABLE_TELEMETRY` | `false` | Habilita tracing y métricas OpenTelemetry. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `localhost:4317` | Endpoint gRPC del colector OTel. |
| `OTEL_TRACES_SAMPLER_ARG` | — | Ratio de muestreo de traces (0.0–1.0). Sin definir usa el sampler por defecto resuelto en la inicialización de telemetría: `0.1` en producción, `1.0` en otros entornos. Valores fuera de (0,1] se clampean a 1.0 para que un error de configuración no deshabilite silenciosamente el tracing en producción. |
| `BTF_METRICS_PROMETHEUS_ENABLED` | `false` | Expone un endpoint dedicado de scrape de Prometheus para las métricas `btf.*`. Cuando es `true`, se inicia el listener en `BTF_METRICS_PROMETHEUS_ADDRESS`. |
| `BTF_METRICS_PROMETHEUS_ADDRESS` | `127.0.0.1:9090` | Dirección de escucha del endpoint Prometheus `/metrics`. El valor por defecto se enlaza a loopback para que un pod mal configurado no exponga métricas no autenticadas a la red del cluster. Sobrescriba (p. ej. `0.0.0.0:9090`) solo detrás de una NetworkPolicy o sidecar. |
### Licencia
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `LICENSE_KEY` | **Obligatoria en producción** | Clave de licencia. Requerido en entornos de producción. |
| `LICENSE_SERVICE_ADDRESS` | — | URL del servicio de validación de licencia. |
| `ORGANIZATION_IDS` | **Obligatoria en producción** | Misma variable que en [Multi-tenancy](#multi-tenancy). Lista separada por coma de UUIDs de organización Midaz en el alcance de licenciamiento; el gateway de licencia valida `LICENSE_KEY` contra estos al inicio. |
### Encriptación
Encriptación a nivel de campo para datos sensibles en reposo. Cada clave debe ser una clave AES-256 de 32 bytes codificada en base64. Deje en blanco para deshabilitar la encriptación de ese campo.
| Variable | Por defecto / Obligatoria | Descripción |
| ------------------------------------ | ------------------------- | ----------------------------------------------------------------- |
| `JD_INCOMING_RAW_XML_ENCRYPTION_KEY` | — | Clave AES-256 para encriptar payloads XML JD entrantes. |
| `RECIPIENT_DETAILS_ENCRYPTION_KEY` | — | Clave AES-256 para encriptar detalles del destinatario en reposo. |