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

> Variables de entorno que JD Courier lee al arrancar: roles, servidor, PostgreSQL, Access Manager, canal SPB de JD, interfaz SOAP, tránsito Pix, drenaje de SPB, licencia, multi-tenancy y telemetría.

JD Courier lee estas variables cuando el proceso arranca. Un cambio surte efecto después de que reinicias el proceso. Cada proceso lee las variables de los roles de `COURIER_ROLES`.

En las tablas, la columna **Obligatoria** marca una variable que debes definir, siempre o en la condición indicada. `—` significa sin valor predeterminado. 🔒 marca un secreto: guárdalo en tu bóveda de secretos.

> [!NOTE]
>
> Con `ENVIRONMENT_NAME=production`, el Courier no arranca a menos que todo esto sea cierto: `PLUGIN_AUTH_ENABLED` es `true`, `POSTGRES_PASSWORD` está definida, `POSTGRES_SSLMODE` no es `disable` y `ALLOW_CORS_WILDCARD` no es `true`. Cada rol agrega sus propias verificaciones, indicadas en las tablas siguientes.

## Servicio y servidor

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `COURIER_ROLES` | Los roles del proceso, separados por comas: `spb-consumer`, `spb-sender`, `pix-ingress`, `admin`. Un rol desconocido o repetido detiene el arranque. `spb-consumer` se ejecuta solo en su proceso. | — | Sí |
| `ENVIRONMENT_NAME` | El entorno. `production` activa las verificaciones de producción. `ENV_NAME` se lee cuando `ENVIRONMENT_NAME` no está definida. | `development` | No |
| `DEPLOYMENT_MODE` | `byoc`, `saas` o `local`. Otro valor detiene el arranque. | `local` | No |
| `LOG_LEVEL` | El nivel de log. | `info` | No |
| `SERVER_ADDRESS` | El puerto HTTP: las sondas, la API del operador, la API de los motores y la dirección Pix. | `:8080` | No |
| `SERVER_TLS_CERT_FILE`, `SERVER_TLS_KEY_FILE` | El certificado y la clave para TLS en el puerto HTTP. Define las dos o ninguna. Un proceso con `spb-sender` o con el tránsito Pix las rechaza, a menos que `TLS_TERMINATED_UPSTREAM` sea `true`. | — | No |
| `TLS_TERMINATED_UPSTREAM` | `true` cuando TLS termina antes del puerto HTTP. | `false` | No |
| `HTTP_BODY_LIMIT_BYTES` | El cuerpo de solicitud más grande en el puerto HTTP, en bytes. | `1048576` | No |
| `SWAGGER_ENABLED` | Sirve el documento OpenAPI en la raíz del puerto HTTP. El Courier la ignora en producción. | `false` | No |
| `SYSTEMPLANE_ENABLED` | Activa la configuración de runtime y su API en `/system`. | `false` | No |
| `INFRA_CONNECT_TIMEOUT_SEC` | El límite de tiempo para conectarse a los datastores en el arranque, en segundos. | `30` | No |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | Cuánto tiempo guarda el Courier la respuesta a una clave `X-Idempotency`, en segundos. | `300` | No |
| `ALLOW_CORS_WILDCARD` | Producción rechaza `true`. | — | No |

## PostgreSQL

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `POSTGRES_HOST` | El host primario. | `localhost` | No |
| `POSTGRES_PORT` | El puerto primario. | `5432` | No |
| `POSTGRES_USER` | El usuario de la base de datos. | `jd-courier` | No |
| `POSTGRES_PASSWORD` | 🔒 La contraseña de la base de datos. | — | En producción |
| `POSTGRES_NAME` | El nombre de la base de datos. | `jd-courier` | No |
| `POSTGRES_SSLMODE` | El modo TLS de libpq. Con `disable`, el Courier no arranca, a menos que `ALLOW_INSECURE_TLS` sea `true`. Producción rechaza `disable`. Usa `verify-full` en producción. | `require` | No |
| `POSTGRES_REPLICA_HOST`, `POSTGRES_REPLICA_PORT`, `POSTGRES_REPLICA_USER`, `POSTGRES_REPLICA_PASSWORD`, `POSTGRES_REPLICA_NAME`, `POSTGRES_REPLICA_SSLMODE` | Una réplica de lectura opcional. Un valor que no defines toma el valor del primario. Cuando defines cualquiera de ellas, `POSTGRES_REPLICA_HOST` es obligatoria. Producción rechaza `POSTGRES_REPLICA_SSLMODE=disable`. | — | No |
| `POSTGRES_MAX_OPEN_CONNS` | El mayor número de conexiones abiertas. | `25` | No |
| `POSTGRES_MAX_IDLE_CONNS` | El mayor número de conexiones inactivas. | `5` | No |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | La mayor duración de una conexión, en minutos. | `30` | No |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | El mayor tiempo inactivo de una conexión, en minutos. | `5` | No |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | El límite de tiempo para abrir una conexión, en segundos. | `10` | No |
| `ALLOW_INSECURE_TLS` | `true` permite que las conexiones a los datastores funcionen sin TLS. | `false` | No |

## Access Manager

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Verifica el token y el permiso de Access Manager en cada llamada. `false` necesita `ALLOW_AUTH_DISABLED_LOCAL_ONLY=true`. Producción y el modo multi-tenant rechazan `false`. | `true` | No |
| `PLUGIN_AUTH_HOST` | La dirección de tu Access Manager. | — | Cuando `PLUGIN_AUTH_ENABLED` es `true` |
| `ALLOW_AUTH_DISABLED_LOCAL_ONLY` | Permite que `PLUGIN_AUTH_ENABLED=false` arranque, solo en la máquina de un desarrollador. | `false` | No |
| `AUTH_M2M_INVERSION_ENABLED` | Vincula cada llamada de motor a la identidad que Access Manager verificó. Con `false`, el Courier rechaza cada credencial de motor con `401`, y un proceso de producción con el rol `admin` no arranca. | `true` | No |
| `AUTH_M2M_PRODUCT_FORWARD_ENABLED` | Envía el nombre de producto del Courier a Access Manager cuando autoriza una llamada de motor. | `true` | No |
| `AUTH_TIMEOUT`, `AUTH_CACHE_TTL`, `AUTH_RETRY_MAX`, `AUTH_BREAKER_ENABLED`, `AUTH_REQUIRED`, `AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED`, `AUTH_JWT_VERIFY_CERT`, `AUTH_JWT_VERIFY_CERT_PATH`, `AUTH_JWT_ISSUER` | La configuración del cliente de Access Manager. Un valor que no es válido detiene el arranque. | Los valores predeterminados del cliente | No |
| `IDP_DECLARATION_ENABLED` | En modo single-tenant, `true` publica en tu Access Manager los permisos del Courier y su adhesión a socios. Sin valor o `false`, publica solo la adhesión a socios. | — | No |
| `IDP_HOST` | La dirección del servicio de identidad de Access Manager, donde el Courier los publica. | — | Para la publicación |
| `IDP_M2M_CLIENT_ID` | El client ID de la aplicación que los publica. | — | Para la publicación |
| `IDP_M2M_CLIENT_SECRET` | 🔒 El secret de esa aplicación. | — | Para la publicación |

Consulta [Access Manager](https://docs.lerian.studio/es/interfaces/jd-courier/jd-courier-deployment.md#access-manager) para lo que hace la publicación.

## Canal SPB de JD

Los roles `spb-consumer` y `spb-sender` leen estas variables.

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `JD_BASE_URL` | La dirección del servicio SPB de JD. Usa https en producción. | — | En producción, en modo single-tenant |
| `JD_SOAP_PATH` | La ruta del servicio SOAP de JD. | `/soap` | No |
| `JD_LEGACY_CODE` | La credencial JD que ya tienes. Como máximo 10 bytes. | — | En producción, en modo single-tenant |
| `JD_USER_CODE` | La credencial JD que ya tienes. Como máximo 10 bytes. | — | En producción, en modo single-tenant |
| `JD_PASSWORD` | 🔒 La credencial JD que ya tienes. Como máximo 20 bytes. | — | En producción, en modo single-tenant |
| `SPB_VENDOR_TIMEOUT` | Cuánto tiempo espera el Courier a JD. Debe ser mayor que cero y menor que `8s`. | `7s` | No |
| `JD_ALLOW_PRIVATE_NETWORK` | `true` permite que el Courier se conecte a JD en una dirección de red privada, para el canal SPB y la cabina SPI. Producción la acepta. | `false` | No |
| `JD_PRIVATE_KEY_PEM` | No debe estar presente en producción. El Courier no firma nada. | — | No |

## Interfaz SOAP

El rol `spb-sender` lee estas variables.

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `SOAP_SERVER_ADDRESS` | El puerto SOAP. | `:8081` | No |
| `SOAP_MAX_BODY_BYTES` | El cuerpo de solicitud SOAP más grande, en bytes. | `10485760` | No |
| `SOAP_TLS_CERT_FILE`, `SOAP_TLS_KEY_FILE` | El certificado y la clave para TLS en el puerto SOAP. Define las dos o ninguna. La versión mínima de TLS es 1.2. | — | En producción, a menos que `SOAP_TLS_TERMINATED_UPSTREAM` sea `true` |
| `SOAP_TLS_TERMINATED_UPSTREAM` | `true` cuando TLS termina antes del puerto SOAP. | `false` | No |
| `SPB_CHANNEL_CREDENTIAL_ROTATION_OVERLAP` | Cuánto tiempo siguen funcionando las credenciales SOAP y del tránsito Pix anteriores de un motor después de que el operador emite una nueva. El rol `admin` la lee cuando emite una credencial. `spb-sender` rechaza un valor que no es positivo. | `24h` | No |

## Tránsito Pix

El rol `admin` lee estas variables.

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `PIX_TRANSIT_SERVER_ADDRESS` | La dirección del tránsito Pix. Cuando está vacía, el Courier no sirve tránsito. | — | Para el tránsito |
| `PIX_TRANSIT_TLS_CERT_FILE`, `PIX_TRANSIT_TLS_KEY_FILE` | El certificado y la clave para TLS en el tránsito. Define las dos o ninguna. La versión mínima de TLS es 1.2. | — | En producción, a menos que `PIX_TRANSIT_TLS_TERMINATED_UPSTREAM` sea `true` |
| `PIX_TRANSIT_TLS_TERMINATED_UPSTREAM` | `true` cuando TLS termina antes del tránsito. | `false` | No |
| `JD_SPI_BASE_URL` | En modo single-tenant, la dirección de la cabina SPI de JD. Usa https en producción. | — | Para el tránsito |
| `JD_SPI_CLIENT_ID` | En modo single-tenant, el client ID de la credencial de la cabina SPI de tu institución. | — | Para el tránsito |
| `JD_SPI_CLIENT_SECRET` | 🔒 En modo single-tenant, el secret de esa credencial. | — | Para el tránsito |
| `JD_SPI_USE_SERVICE_SEGMENTS` | `true` cuando JD sirve la cabina SPI por las rutas de su gateway: el Courier entonces pide su token en `/auth` y envía los resultados de las validaciones de cuenta en `/spi-api`. | `false` | No |

## Drenaje de SPB

El rol `spb-consumer` lee estas variables. `SPB_TAKE_BUDGET_SEC` más el mayor entre `SPB_IDLE_INTERVAL_SEC` y `SPB_EMPTY_BACKOFF_CAP_SEC` debe quedar por debajo de `SPB_LEASE_TTL_SEC`.

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `POD_NAME` | El nombre del titular del lease de lectura. Cuando está vacío, el Courier usa el nombre del host. | — | No |
| `SPB_LEASE_TTL_SEC` | Cuánto dura el lease de lectura sin una renovación, en segundos. | `30` | No |
| `SPB_TAKE_BUDGET_SEC` | El mayor tiempo para tomar un mensaje de JD, en segundos. Debe ser al menos `SPB_VENDOR_TIMEOUT`. | `15` | No |
| `SPB_IDLE_INTERVAL_SEC` | La espera mientras el drenaje no lee, en segundos. | `5` | No |
| `SPB_EMPTY_BACKOFF_CAP_SEC` | La mayor espera después de que JD informa una cola vacía, en segundos. | `10` | No |
| `SPB_PERSIST_TIMEOUT_SEC` | El límite de tiempo de un intento de guardar un mensaje, en segundos. | `60` | No |
| `SPB_TENANT_REFRESH_SEC` | Con qué frecuencia el drenaje lee de nuevo la lista de tenants, en segundos. | `30` | No |
| `SPB_MESSAGE_SIZE_ALERT_BYTES` | Un mensaje más grande que esto escribe una advertencia. El Courier lo guarda. | `1048576` | No |

## Pix y credenciales de los motores

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `AWS_REGION` | La región de AWS de AWS Secrets Manager, donde el Courier lee las credenciales que usa en los motores. | `us-east-1` | No |

Consulta [Credenciales de los motores](https://docs.lerian.studio/es/interfaces/jd-courier/jd-courier-deployment.md#engine-credentials).

## Licencia

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `LICENSE_KEY` | 🔒 Tu clave de licencia de Lerian. | — | Sí |
| `ORGANIZATION_IDS` | El ID de tu organización. | — | No |
| `APPLICATION_NAME` | El nombre de producto que usa la verificación de la licencia. Déjala sin valor: el Courier entonces usa su propio nombre de producto. | — | No |

## Multi-tenancy

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `MULTI_TENANT_ENABLED` | Activa el modo multi-tenant. | `false` | No |
| `MULTI_TENANT_URL` | La dirección del Tenant Manager. | — | En modo multi-tenant |
| `MULTI_TENANT_SERVICE_API_KEY` | 🔒 La clave del Courier en el Tenant Manager. | — | En modo multi-tenant |
| `MULTI_TENANT_REDIS_HOST` | El host Redis de la caché de tenants. | — | En modo multi-tenant |
| `MULTI_TENANT_REDIS_PORT` | El puerto Redis. | `6379` | No |
| `MULTI_TENANT_REDIS_PASSWORD` | 🔒 La contraseña de Redis. | — | No |
| `MULTI_TENANT_REDIS_TLS` | Conecta a Redis con TLS. | `false` | No |
| `MULTI_TENANT_MAX_TENANT_POOLS` | El mayor número de pools de conexión de tenant. | `100` | No |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Cuánto tiempo queda abierto un pool de tenant inactivo, en segundos. | `300` | No |
| `MULTI_TENANT_TIMEOUT` | El límite de tiempo de una llamada al Tenant Manager, en segundos. | `30` | No |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | Las fallas que abren el circuit breaker del Tenant Manager. | `5` | No |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | Cuánto tiempo queda abierto el circuit breaker, en segundos. | `30` | No |
| `MULTI_TENANT_CACHE_TTL_SEC` | Cuánto tiempo guarda el Courier la configuración de un tenant, en segundos. | `120` | No |
| `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | Con qué frecuencia el Courier verifica las conexiones de tenant, en segundos. | `30` | No |

## Telemetría

| Variable | Descripción | Predeterminado | Obligatoria |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Activa OpenTelemetry. | `true` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | La dirección del colector OTLP. | `localhost:4317` | No |
| `OTEL_RESOURCE_SERVICE_NAME` | El nombre del servicio en la telemetría. | `jd-courier` | No |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | El nombre del entorno en la telemetría. | `development` | No |
| `OTEL_LIBRARY_NAME` | El nombre de la biblioteca de instrumentación en la telemetría. | El nombre del módulo del Courier | No |
| `OTEL_TRUST_INBOUND_TRACE_CONTEXT` | Continúa el trace que envía un llamador. Define `true` solo detrás de un gateway en el que confías. | `false` | No |


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