> ## 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
> Configura el plugin Bank Transfer vía JD en tiempo de despliegue: aplicación, TLS y encabezados de proxy, persistencia, integración con JD SPB y variables de seguridad.
DevOps define estas variables en tiempo de despliegue. Un cambio requiere reiniciar el servicio. Los ajustes de tiempo de ejecución y de negocio están en [Configuración](/es/interfaces/ted-jd/ted-configuration).
En las tablas de abajo, la columna **Predeterminado / Obligatorio** muestra el valor predeterminado. Un calificador en negrita (por ejemplo **Obligatorio**, **Obligatorio en producción**, **Obligatorio si está habilitado**) marca una variable que debes definir. `—` significa que no hay valor predeterminado.
## Configuración de infraestructura
***
Esta sección es para los equipos de DevOps. DevOps define estas variables en tiempo de despliegue. Un cambio se aplica solo después de reiniciar el servicio.
### Aplicación
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ENV_NAME` | `development` | Entorno (`development`, `staging`, `production`) |
| `DEPLOYMENT_MODE` | `byoc` | Tipo de despliegue. `byoc` = Bring Your Own Cloud (un solo tenant, administrado por el operador). Alterna entre los comportamientos de SaaS interno y de 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 los adaptadores salientes (CRM, Fees, JD, Midaz) resuelvan a IPs RFC1918/loopback. El valor predeterminado `false` es fail-closed: producción bloquea el pivoteo por DNS hacia el espacio privado. Habilítalo en desarrollo o en BYOC dentro del clúster, donde los upstreams viven de forma legítima en IPs privadas. Los endpoints de metadatos de la nube siguen bloqueados sin importar este indicador. |
### TLS
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------- |
| `SERVER_TLS_CERT_FILE` | — | Ruta al archivo del certificado TLS. Debe definirse junto con `SERVER_TLS_KEY_FILE`. |
| `SERVER_TLS_KEY_FILE` | — | Ruta al archivo de la clave privada TLS. Debe definirse junto con `SERVER_TLS_CERT_FILE`. |
| `TLS_TERMINATED_UPSTREAM` | `false` | Defínela en `true` cuando el TLS termina en un balanceador de carga o proxy inverso. |
### Encabezados de proxy
Defínelos cuando el servicio corre detrás de un balanceador de carga o un proxy inverso. Permiten que el servicio lea la IP real del cliente para el rate limit y los logs de auditoría.
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SERVER_PROXY_HEADER` | — | Encabezado HTTP que lleva la IP real del cliente (p. ej. `X-Forwarded-For`, `X-Real-IP`). Vacío deshabilita la lectura del encabezado de proxy. |
| `SERVER_TRUSTED_PROXIES` | **Obligatorio si se define el encabezado de proxy** | Lista separada por comas de IPs/CIDRs de proxies de confianza. Obligatoria cuando `SERVER_PROXY_HEADER` está definida, para evitar la suplantación de IP. |
### Autenticación
Este plugin delega la autorización a `plugin-auth`. Configura la conexión con las variables de abajo.
| Variable | Predeterminado / Obligatorio | Descripción |
| --------------------- | ---------------------------------- | --------------------------------------------------------------------------- |
| `PLUGIN_AUTH_ENABLED` | `false` | Habilita la autorización vía plugin-auth. Defínela en `true` en producción. |
| `PLUGIN_AUTH_ADDRESS` | **Obligatorio 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 los entornos de producción. El servicio rechaza una dirección HTTP al arrancar.
### Admin de pruebas (solo fuera de producción)
`BTF_TEST_ADMIN_ENABLED` debe permanecer en `false` en producción. Expone endpoints de administración solo para pruebas (por ejemplo `POST /admin/test/circuit-breakers/reset`) que no llevan tenant y saltan la autenticación de producción. Solo el carril mock de docker-compose lo habilita, para las pruebas E2E. Cualquier despliegue con este indicador en `true` fuera de una red de pruebas cerrada es un error de configuración.
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BTF_TEST_ADMIN_ENABLED` | `false` | ⚠️ Expone endpoints de administración solo para pruebas. Debe permanecer en `false` en producción. |
| `BTF_TEST_ADMIN_TOKEN` | **Obligatorio si el admin está habilitado** | Token obligatorio cuando `BTF_TEST_ADMIN_ENABLED=true`. Se envía en el encabezado `X-Test-Admin-Token`. Separado a propósito de la autenticación de producción (superficie solo de pruebas, sin tenant). |
### Idempotencia
| Variable | Predeterminado / Obligatorio | 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 | Predeterminado / Obligatorio | Descripción |
| --------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MULTI_TENANT_ENABLED` | `false` | Habilita el multi-tenancy en el nivel de la infraestructura con bases de datos aisladas por tenant. |
| `ORGANIZATION_ID` | **Obligatorio (un solo tenant + polling de JD)** | UUID de la organización de Midaz que se inyecta en el contexto de los workers en segundo plano (poller de TED IN, conciliación) en modo de un solo tenant. Obligatorio cuando `MULTI_TENANT_ENABLED=false` y `JD_POLLING_ENABLED=true`. Se ignora en modo multi-tenant, donde el tenant manager resuelve las asociaciones de organización de cada tenant. Las solicitudes HTTP siempre llevan la organización en el encabezado `X-Organization-Id` en su lugar. |
| `AWS_REGION` | **Obligatorio si el backend de secretos es AWS** | Región de AWS para las lecturas de secretos por tenant desde Secrets Manager. Obligatoria cuando `MULTI_TENANT_ENABLED=true` y el backend de secretos es AWS. |
| `ORGANIZATION_IDS` | **Obligatorio en producción** | Lista separada por comas de UUIDs de organizaciones de Midaz en el ámbito de la licencia. El gateway de licencias valida `LICENSE_KEY` contra ellos al arrancar. También aparece en [Licencia](#license). |
| `MULTI_TENANT_URL` | **Obligatorio cuando está habilitado** | URL del servicio de la plataforma de multi-tenancy. |
| `MULTI_TENANT_REDIS_HOST` | — | Host de Redis para el descubrimiento de tenants por eventos 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 Pub/Sub de Redis. |
| `MULTI_TENANT_REDIS_CA_CERT` | — | Certificado de CA para la conexión TLS de Redis Pub/Sub multi-tenant. |
| `MULTI_TENANT_TIMEOUT` | `30` | Timeout HTTP en segundos para las llamadas al servicio de multi-tenancy. |
| `MULTI_TENANT_MAX_TENANT_POOLS` | `100` | Número máximo de pools de conexiones a bases de datos de tenants en paralelo. |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | `300` | Timeout de inactividad en segundos antes de descartar el pool de un tenant. |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | `5` | Número de fallas antes de que el circuit breaker se abra. |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | `30` | Timeout de recuperación en segundos para el circuit breaker. |
| `MULTI_TENANT_SERVICE_API_KEY` | **Obligatorio cuando está habilitado** | Clave de API para el endpoint `/settings` del servicio de multi-tenancy. |
| `MULTI_TENANT_CACHE_TTL_SEC` | `120` | TTL en segundos de la caché en memoria de la configuración de tenants. Recargable en caliente con la API del systemplane. |
| `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | `30` | Intervalo asíncrono en segundos para revalidar los ajustes de los pools. Solo en el arranque (no recargable en caliente). |
**BYOC con un solo tenant:**
```bash theme={null}
# Organization injected into background workers (required when JD polling is enabled)
ORGANIZATION_ID=
# Licensing scope validated against LICENSE_KEY in production
ORGANIZATION_IDS=
```
**SaaS multi-tenant:**
```bash theme={null}
MULTI_TENANT_ENABLED=true
MULTI_TENANT_URL=http://tenant-manager:4003
MULTI_TENANT_SERVICE_API_KEY=your-api-key
MULTI_TENANT_REDIS_HOST=redis.example.com
```
### PostgreSQL
| Variable | Predeterminado / Obligatorio | Descripción |
| ---------------------------------- | ------------------------------------------- | ---------------------------------------------------------- |
| `POSTGRES_HOST` | `localhost` · **Obligatorio** | Host principal de PostgreSQL. |
| `POSTGRES_PORT` | `5432` | Puerto principal de PostgreSQL. |
| `POSTGRES_USER` | `plugin-br-bank-transfer` · **Obligatorio** | Usuario de la base de datos. |
| `POSTGRES_PASSWORD` | **Obligatorio** | Contraseña de la base de datos. Obligatoria en producción. |
| `POSTGRES_DB` | `plugin-br-bank-transfer` · **Obligatorio** | Nombre de la base de datos. |
| `POSTGRES_SSLMODE` | `require` | Modo SSL. `disable` se rechaza en producción. |
| `POSTGRES_MAX_OPEN_CONNS` | `25` | Número máximo de conexiones abiertas. |
| `POSTGRES_MAX_IDLE_CONNS` | `5` | Número máximo de conexiones inactivas. |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | `30` | Vida máxima de una conexión en minutos. |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | `5` | Tiempo máximo de inactividad de una conexión en minutos. |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | `10` | Timeout de conexión en segundos. |
### Réplica de PostgreSQL
Configura una réplica de lectura para descargar consultas. Todos los campos recurren a los valores del principal cuando no se definen.
| Variable | Predeterminado / Obligatorio | Descripción |
| --------------------------- | ---------------------------- | ---------------------------------------------- |
| `POSTGRES_REPLICA_HOST` | — | Host de la réplica. Sin definir = 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
El servicio requiere MongoDB para guardar los eventos de auditoría de las transferencias. No arranca sin una conexión válida a MongoDB.
| Variable | Predeterminado / Obligatorio | Descripción |
| ----------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MONGO_ENABLED` | `true` · **Obligatorio** | Habilita la conexión a MongoDB. Debe ser `true` en todos los entornos. |
| `MONGO_URI` | **Obligatorio** | Cadena de conexión de MongoDB (p. ej. `mongodb://user:pass@host:27017`). Debe incluir credenciales y TLS en producción. |
| `MONGO_DATABASE` | **Obligatorio** | Nombre de la base de datos de 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 de CA codificado en base64 para el TLS de MongoDB. Úsalo cuando MongoDB requiere TLS con una CA propia (p. ej. Atlas, instancias privadas con certificados autofirmados). |
### Redis
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------ | ---------------------------------- | ---------------------------------------------------------- |
| `REDIS_HOST` | `localhost:6379` · **Obligatorio** | Host y puerto de Redis. |
| `REDIS_MASTER_NAME` | — | Nombre del master de Redis Sentinel (si usas Sentinel). |
| `REDIS_PASSWORD` | — | Contraseña de Redis (si la autenticación está habilitada). |
| `REDIS_DB` | `0` | Número de la base de datos de Redis. |
| `REDIS_PROTOCOL` | `3` | Versión del protocolo de Redis (2 o 3). |
| `REDIS_TLS` | `false` | Habilita TLS para las conexiones a Redis. |
| `REDIS_CA_CERT` | — | Certificado de CA para el TLS de Redis. |
| `REDIS_POOL_SIZE` | `10` | Tamaño del pool de conexiones. |
| `REDIS_MIN_IDLE_CONNS` | `2` | Número 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. Guarda en caché las claves de idempotencia y detecta duplicados. Si Redis no está disponible al arrancar, o deja de ser alcanzable en tiempo de ejecución, el servicio se reporta como DOWN a la sonda de readiness. Entonces deja de aceptar solicitudes.
### Conexión con JD SPB
Debes definir estas variables para los despliegues BYOC. En modo SaaS, Lerian administra la conexión con JD.
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JD_BASE_URL` | **Obligatorio para BYOC** | URL base de la API de JD SPB. |
| `JD_SOAP_PATH` | `/soap` | Ruta del endpoint SOAP de JD. |
| `JD_LEGACY_CODE` | **Obligatorio para BYOC** | Código del sistema heredado de JD (máx. 10 caracteres). |
| `JD_USER_CODE` | **Obligatorio para BYOC** | Código de usuario de JD (máx. 10 caracteres). |
| `JD_PASSWORD` | **Obligatorio para BYOC** | Contraseña de JD (cifrada en reposo). |
| `JD_PRIVATE_KEY_PEM` | **Obligatorio para BYOC** | Contenido PEM de la clave privada RSA para la firma XML. |
| `JD_PRIVATE_KEY_PEM_FILE` | — | Ruta a un archivo con el PEM de la clave privada RSA. Alternativa a incluir la clave en `JD_PRIVATE_KEY_PEM`; se lee al arrancar. |
| `JD_PUBLIC_KEY_PEM` | — | PEM de la clave pública para validar las firmas de las respuestas de JD. |
| `JD_PRIVATE_KEY_KEYINFO` | — | Bloque XML `` incrustado en la firma SOAP (p. ej. certificado X509 codificado en base64). Obligatorio para el sobre WS-Security cuando JD exige identificación por certificado. |
| `JD_CERT_PEM` | — | Certificado X.509 opcional codificado en PEM, emparejado con la clave de firma de JD. Lo usa solo el gauge de métricas de expiración del certificado, no la ruta de firma; un PEM mal formado es un error de arranque. |
| `JD_SIGNING_MODE` | `local_pem` | Modo de firma SOAP. `local_pem` firma de forma local con `JD_PRIVATE_KEY_PEM`; `external_signer` delega en un servicio remoto a través de `JD_EXTERNAL_SIGNER_URL`. |
| `JD_EXTERNAL_SIGNER_URL` | **Obligatorio si `JD_SIGNING_MODE=external_signer`** | URL base del servicio de firma externo. |
| `JD_EXTERNAL_SIGNER_AUTH_TOKEN` | — | Token bearer que se envía en el encabezado `Authorization` de las llamadas al firmante externo. |
| `JD_EXTERNAL_SIGNER_TIMEOUT_MS` | `5000` | Timeout (en milisegundos) de las llamadas al firmante externo. |
| `JD_SANDBOX_MODE` | `false` | Habilita el modo sandbox de JD. Se rechaza en producción. |
### Polling de JD
| Variable | Predeterminado / Obligatorio | Descripción |
| -------------------------- | ---------------------------- | -------------------------------------------------------------------------- |
| `JD_POLLING_ENABLED` | `false` | Habilita el worker de polling de TED IN. |
| `JD_POLL_INTERVAL_SECONDS` | `60` | Con qué frecuencia (en segundos) el plugin consulta si hay TEDs entrantes. |
`JD_POLLING_ENABLED` tiene el valor predeterminado `false` para despliegues más seguros. En modo de un solo tenant, define `ORGANIZATION_ID` antes de habilitarlo. Los workers en segundo plano inyectan ese valor en el contexto para las llamadas posteriores a CRM y Midaz. En modo multi-tenant, el gestor del poller de TED IN encuentra cada tenant activo a través del servicio de la plataforma de multi-tenancy. Luego arranca un poller por tenant y resuelve la configuración de JD de cada tenant.
### Servicios externos (Midaz)
| Variable | Predeterminado / Obligatorio | Descripción |
| ----------------------- | ---------------------------------- | --------------------------------------------------------------- |
| `MIDAZ_BASE_URL` | **Obligatorio** | URL del servicio base de Midaz. |
| `MIDAZ_TRANSACTION_URL` | **Obligatorio** | URL del servicio de transacciones de Midaz. |
| `MIDAZ_TIMEOUT_MS` | `3000` | Timeout de las solicitudes a Midaz en milisegundos. |
| `MIDAZ_MAX_RETRIES` | `3` | Intentos de reintento ante una falla de Midaz. |
| `MIDAZ_AUTH_ENABLED` | `false` | Habilita la autenticación M2M para Midaz. |
| `MIDAZ_AUTH_ADDRESS` | **Obligatorio si está habilitado** | URL del servicio de autenticación para los tokens M2M de Midaz. |
| `MIDAZ_CLIENT_ID` | **Obligatorio si está habilitado** | ID de cliente OAuth para el M2M de Midaz. |
| `MIDAZ_CLIENT_SECRET` | **Obligatorio si está habilitado** | Secreto de cliente OAuth para el M2M de Midaz. |
### Servicios externos (CRM)
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------- | ---------------------------------- | -------------------------------------------------- |
| `CRM_BASE_URL` | **Obligatorio** | URL del servicio de CRM. |
| `CRM_TIMEOUT_MS` | `2000` | Timeout de las solicitudes al CRM en milisegundos. |
| `CRM_MAX_RETRIES` | `2` | Intentos de reintento ante una falla del CRM. |
| `CRM_AUTH_ENABLED` | `false` | Habilita la autenticación M2M para el CRM. |
| `CRM_CLIENT_ID` | **Obligatorio si está habilitado** | ID de cliente OAuth para el M2M del CRM. |
| `CRM_CLIENT_SECRET` | **Obligatorio si está habilitado** | Secreto de cliente OAuth para el M2M del CRM. |
### Servicios externos (Fees)
`BTF_FEE_ENABLED` es el interruptor principal. Cuando está en `false` (valor predeterminado), el plugin no construye ningún adaptador de Fees y cada transferencia sigue con fee=0 y sin llamadas HTTP. Las demás variables `FEES_*` se aplican solo cuando `BTF_FEE_ENABLED=true`.
| Variable | Predeterminado / Obligatorio | Descripción |
| -------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BTF_FEE_ENABLED` | `false` | Interruptor principal de la integración con plugin-fees. Cuando está en `false`, no se construye ningún adaptador de Fees y todas las transferencias corren con fee=0 sin llamadas HTTP. Los operadores que ejecutan plugin-fees deben definirlo en `true` de forma explícita. |
| `FEES_BASE_URL` | **Obligatorio si está habilitado** | URL del servicio Fees Engine. |
| `FEES_TIMEOUT_MS` | `2000` | Timeout de las solicitudes de comisión en milisegundos. |
| `FEES_MAX_RETRIES` | `2` | Intentos de reintento ante una falla del servicio de comisiones. |
| `FEES_AUTH_ENABLED` | `false` | Habilita la autenticación M2M para Fees. |
| `FEES_CLIENT_ID` | **Obligatorio si está habilitado** | ID de cliente OAuth para el M2M de Fees. |
| `FEES_CLIENT_SECRET` | **Obligatorio si está habilitado** | Secreto de cliente OAuth para el M2M de Fees. |
### RabbitMQ
Cuando el streaming está habilitado, el plugin puede hacer fan-out de los eventos del ciclo de vida de las transferencias a RabbitMQ para los consumidores posteriores.
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RABBITMQ_ENABLED` | `false` | Agrega RabbitMQ como destino de fan-out del ciclo de vida de las transferencias. La publicación requiere `STREAMING_ENABLED=true`. |
| `RABBITMQ_URL` | **Obligatorio si está habilitado** | URL de conexión AMQP. Debe usar `amqps://` fuera de desarrollo. |
| `RABBITMQ_HEALTH_CHECK_URL` | — | URL HTTP(S) del endpoint de health de la administración de RabbitMQ. El hostname debe coincidir con `RABBITMQ_URL`; debe usar `https://` en producción. |
| `RABBITMQ_EXCHANGE` | `bank_transfer.lifecycle` | Nombre del exchange para los eventos del ciclo de vida. |
| `RABBITMQ_EVENT_SIGNING_SECRET` | **Obligatorio si está habilitado** | Secreto HMAC para firmar los eventos publicados. Mínimo 32 caracteres. |
### Outbox de streaming
El subsistema de streaming publica los eventos de transferencia en el único tema de la aplicación, `lerian.streaming.plugin-br-bank-transfer`, en un broker de Redpanda/Kafka a través de un outbox transaccional. Debes habilitarlo para la entrega saliente de webhooks (`WEBHOOK_ENABLED=true` requiere `STREAMING_ENABLED=true`).
| Variable | Predeterminado / Obligatorio | Descripción |
| -------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STREAMING_ENABLED` | `false` | Habilita el subsistema de outbox de streaming. Obligatorio para la entrega de webhooks. |
| `STREAMING_BROKERS` | **Obligatorio si está habilitado** | Lista separada por comas de direcciones de brokers de Kafka/Redpanda. |
| `STREAMING_CLIENT_ID` | — | ID de cliente que se presenta al broker. |
| `STREAMING_CLOUDEVENTS_SOURCE` | `plugin-br-bank-transfer` | Reemplazo opcional del `source` de CloudEvents. Déjalo sin definir para usar `plugin-br-bank-transfer`; si lo defines, debe coincidir con ese valor exactamente, incluso con el streaming deshabilitado. |
| `STREAMING_OUTBOX_DISPATCH_INTERVAL_SECONDS` | `30` | Intervalo (en segundos) entre los ciclos de envío del outbox. Debe ser > 0. |
| `STREAMING_CB_FAILURE_RATIO` | `0.5` | Proporción de fallas del circuit breaker que lo dispara (debe ser > 0 y ≤ 1). |
| `STREAMING_CB_MIN_REQUESTS` | `10` | Número 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 ordenado (en segundos) del productor de streaming. |
### Entrega de webhooks
La entrega saliente de webhooks requiere tanto RabbitMQ como el outbox de streaming. El worker de webhooks consume los eventos de una cola de RabbitMQ y los entrega a los endpoints suscritos.
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WEBHOOK_ENABLED` | `false` | Habilita la entrega saliente de webhooks. Requiere `RABBITMQ_ENABLED=true` y `STREAMING_ENABLED=true`. |
| `WEBHOOK_SIGNING_SECRET` | **Obligatorio si está habilitado** | Secreto HMAC para firmar los payloads de los webhooks. Mínimo 32 caracteres. |
| `WEBHOOK_BROKER_EVENT_SIGNING_SECRET` | — | Secreto HMAC aparte para verificar los eventos del broker. Recurre a `WEBHOOK_SIGNING_SECRET`. |
| `WEBHOOK_QUEUE_NAME` | `transfer.webhook.delivery` | Nombre de la cola de RabbitMQ para los eventos de webhook. |
| `WEBHOOK_DLQ_NAME` | `transfer.webhook.dlq` | Cola dead-letter para las entregas de webhook fallidas. |
| `WEBHOOK_DLX_EXCHANGE_NAME` | — | Nombre del exchange dead-letter. Cuando está vacío, el worker deriva `.exchange`. Reemplázalo para centralizar el DLX entre plugins. |
| `WEBHOOK_DLQ_MESSAGE_TTL_MS` | `0` | `x-message-ttl` de la DLQ en milisegundos. `0` deja el valor predeterminado de la librería (7 días). Los cambios de topología requieren borrar la DLQ existente antes de volver a desplegar. |
| `WEBHOOK_DLQ_MAX_LENGTH` | `0` | Número máximo de mensajes en la DLQ. `0` deja el valor predeterminado de la librería (10000). |
| `WEBHOOK_PREFETCH_COUNT` | `20` | Conteo de prefetch de RabbitMQ. |
| `WEBHOOK_DELIVERY_CONCURRENCY` | `8` | Número máximo de entregas de webhook en paralelo por worker. |
### Telemetría (OpenTelemetry)
| Variable | Predeterminado / Obligatorio | Descripción |
| -------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ENABLE_TELEMETRY` | `false` | Habilita el tracing y las métricas de OpenTelemetry. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `localhost:4317` | Endpoint gRPC del colector de OTel. |
| `OTEL_TRACES_SAMPLER_ARG` | — | Proporción de muestreo de trazas (0.0–1.0). Sin definir usa el sampler predeterminado que se resuelve al iniciar la telemetría: `0.1` en producción, `1.0` en el resto. Los valores fuera de (0,1] se ajustan a 1.0, para que un error de configuración no pueda deshabilitar el tracing de producción en silencio. |
| `BTF_METRICS_PROMETHEUS_ENABLED` | `false` | Expone un endpoint de scrape de Prometheus dedicado para las métricas `btf.*`. Cuando está en `true`, arranca el listener en `BTF_METRICS_PROMETHEUS_ADDRESS`. |
| `BTF_METRICS_PROMETHEUS_ADDRESS` | `127.0.0.1:9090` | Dirección de escucha del endpoint `/metrics` de Prometheus. El valor predeterminado se asocia a loopback, para que un pod mal configurado no exponga métricas sin autenticación a la red del clúster. Reemplázalo (p. ej. `0.0.0.0:9090`) solo detrás de una NetworkPolicy o un sidecar. |
Licencia
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LICENSE_KEY` | **Obligatorio en producción** | Clave de licencia. Obligatoria en los entornos de producción. |
| `LICENSE_SERVICE_ADDRESS` | — | URL del servicio de validación de licencias. |
| `ORGANIZATION_IDS` | **Obligatorio en producción** | La misma variable que en [Multi-tenancy](#multi-tenancy). Lista separada por comas de UUIDs de organizaciones de Midaz en el ámbito de la licencia; el gateway de licencias valida `LICENSE_KEY` contra ellos al arrancar. |
### Cifrado
Cifrado en el nivel de campo para los datos sensibles en reposo. Cada clave debe ser una clave AES-256 de 32 bytes codificada en hexadecimal (64 caracteres hexadecimales). Deja una clave vacía para deshabilitar el cifrado de ese campo.
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------------------ | ---------------------------- | ----------------------------------------------------------- |
| `JD_INCOMING_RAW_XML_ENCRYPTION_KEY` | — | Clave AES-256 para cifrar los payloads XML entrantes de JD. |
| `RECIPIENT_DETAILS_ENCRYPTION_KEY` | — | Clave AES-256 para cifrar los datos del receptor en reposo. |