> ## 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 riel Pix Indirecto vía BTG: mTLS con BTG, datastores DB_*, vínculos con Midaz y CRM, endpoints de webhook y componentes worker en el despliegue.
Pix Indirecto vía BTG llega al arreglo Pix a través de BTG como participante directo. Se distribuye como varios componentes: una API, más los workers de conciliación, de programación y de webhooks entrantes y salientes. DevOps define las variables de entorno de cada componente en el momento del despliegue. Para cambiar una variable, reinicias ese componente. Esta página cubre las variables **distintivas de este riel**. Para los ajustes de multi-tenancy, streaming, telemetría y autenticación compartidos por todos los servicios Go de Lerian, consulta [Aspectos esenciales de configuración BYOC](/es/reference/byoc-configuration).
En las tablas siguientes, la columna **Predeterminado / Obligatorio** muestra el valor predeterminado. Un calificador en negrita (por ejemplo **Obligatorio**) marca las variables que debes definir. `—` significa que no hay valor predeterminado. `🔒` marca un **secreto**. Inyecta cada secreto en el momento del despliegue desde tu almacén de secretos. Nunca incluyas un secreto en un commit. Esta página solo lista nombres de variables y su comportamiento. No imprime valores de secretos.
Este riel **no** monta la API de administración de systemplane. Sus variables de datastore usan el prefijo `DB_*` en lugar de la forma compartida `POSTGRES_*`. Consulta [Datastores](#datastores) más abajo.
## Componentes y puertos
El componente de API escucha en `SERVER_PORT` (predeterminado `4014`). `SERVER_ADDRESS` se deriva de él. Los workers de conciliación, de programación y de webhooks enlazan cada uno un `WORKER_PORT` para sus sondas de salud. Cada worker lleva sus propios parámetros de ajuste (tamaños de lote, intervalos de sondeo, concurrencia y circuit breakers) en su archivo `.env.example`. Consulta [Puertos de red predeterminados](/es/reference/default-network-ports).
## Integración con BTG y mTLS
Estas variables guardan las credenciales y la configuración de TLS mutuo de la conexión con BTG.
| Variable | Predeterminado / Obligatorio | Descripción |
| -------------------------------- | ---------------------------- | ------------------------------------------------------------------------------ |
| `BTG_BASE_URL` | **Obligatorio** | URL base de la API de BTG. |
| `BTG_CERTIFICATE_URL` | **Obligatorio** | Endpoint desde el cual se obtiene el certificado de cliente para mTLS. |
| `BTG_CLIENT_ID` | **Obligatorio** | Client ID de OAuth para la API de BTG. |
| `BTG_CLIENT_SECRET` | 🔒 **Obligatorio** | Client secret de OAuth para la API de BTG. |
| `BTG_WEBHOOK_SECRET` | 🔒 **Obligatorio** | Secreto usado para validar las firmas de los webhooks entrantes de BTG. |
| `BTG_WEBHOOK_VALIDATION_ENABLED` | `true` | Verifica las firmas de los webhooks de BTG. Déjalo en `true` en producción. |
| `MTLS_ENABLED` | `false` | Habilita TLS mutuo en la conexión con BTG. Habilítalo en producción. |
| `MTLS_CERTIFICATE_TTL` | `24h` | Cuánto tiempo se guarda en cache un certificado de cliente antes de renovarlo. |
| `MTLS_HTTP_TIMEOUT` | `10s` | Timeout de la llamada HTTP que obtiene el certificado. |
Datastores
Este riel usa el prefijo `DB_*` para los datastores, no la forma compartida `POSTGRES_*`. Se conecta a un PostgreSQL primario, a una réplica de lectura aparte, a MongoDB y a Redis.
| Variable | Predeterminado / Obligatorio | Descripción |
| ----------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_HOST` · `DB_PORT` | **Obligatorio** | Host y puerto del PostgreSQL primario. |
| `DB_USER` · `DB_PASSWORD` | 🔒 **Obligatorio** | Credenciales del PostgreSQL primario. |
| `DB_NAME` | **Obligatorio** | Nombre de la base de datos primaria. |
| `DB_SSL_MODE` | `disable` | Modo TLS de libpq. Usa `require` o uno más estricto en producción. |
| `DB_REPLICA_HOST` · `DB_REPLICA_PORT` · `DB_REPLICA_NAME` · `DB_REPLICA_USER` · `DB_REPLICA_PASSWORD` | 🔒 — | Conexión opcional a la réplica de lectura (misma forma que la primaria). |
| `REPLICATION_USER` · `REPLICATION_PASSWORD` | 🔒 — | Credenciales del rol de replicación en streaming. |
| `MONGO_URI` · `MONGO_HOST` · `MONGO_PORT` · `MONGO_USER` · `MONGO_PASSWORD` · `MONGO_NAME` | 🔒 **Obligatorio** | Conexión a MongoDB. `MONGO_URI` define el esquema de conexión (`mongodb` o `mongodb+srv`); `MONGO_HOST`, `MONGO_PORT`, `MONGO_USER`, `MONGO_PASSWORD` y `MONGO_NAME` aportan el host, las credenciales y la base de datos. Todas se combinan en una sola cadena de conexión — no son alternativas entre URI y valores discretos. La contraseña es un secreto. |
| `MONGO_TLS` | `false` | Habilita TLS hacia MongoDB. |
| `REDIS_HOST` · `REDIS_PORT` · `REDIS_PASSWORD` | 🔒 — | Endpoint de Redis/Valkey y contraseña de autenticación. |
| `REDIS_TLS` · `REDIS_CA_CERT` | `false` · — | Habilita TLS hacia Redis y entrega una CA en PEM codificada en base64. |
## Midaz, CRM y Fees
| Variable | Predeterminado / Obligatorio | Descripción |
| --------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------- |
| `MIDAZ_ONBOARDING_URL` · `MIDAZ_TRANSACTION_URL` | **Obligatorio** | URL de los servicios de onboarding y de transacciones de Midaz. |
| `MIDAZ_ORGANIZATION_ID` · `MIDAZ_LEDGER_ID` | **Obligatorio** | UUID de la organización y del ledger de Midaz para los registros Pix. |
| `MIDAZ_CLIENT_ID` · `MIDAZ_CLIENT_SECRET` | 🔒 — | Credenciales OAuth para Midaz M2M. |
| `PLUGIN_CRM_BASE_URL` · `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET` | 🔒 — | URL del servicio CRM y credenciales OAuth. |
| `FEE_SERVICE_URL` · `FEE_CLIENT_ID` · `FEE_CLIENT_SECRET` | 🔒 — | URL del servicio Fees Engine y credenciales OAuth. |
| `FEE_SERVICE_TIMEOUT` | — | Timeout de las solicitudes de comisiones. |
| `CASHIN_FEE_CALCULATION_TYPE` | — | Cómo se calculan las comisiones de cash-in. |
## Webhooks internos y programación
La API y los workers intercambian eventos por un canal interno de webhooks. También ejecutan flujos Pix recurrentes y programados.
| Variable | Predeterminado / Obligatorio | Descripción |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------- |
| `INTERNAL_WEBHOOK_SECRET` | 🔒 **Obligatorio** | Secreto HMAC compartido entre la API y los workers para firmar los webhooks internos. |
| `INTERNAL_WEBHOOK_VALIDATION_ENABLED` | `true` | Verifica las firmas de los webhooks internos. |
| `INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE` | — | Desfase de reloj permitido al validar las marcas de tiempo de los webhooks internos. |
| `WEBHOOK_RECEIVER_MAX_PAYLOAD_SIZE` · `WEBHOOK_RECEIVER_MAX_RETRIES` | `10485760` (10 MB) · `3` | Límite del payload de los webhooks entrantes y tope de reintentos. |
| `RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS` | `1` · `720h` · `150ms` · `3` | Ajustes de programación y de manejo de respuestas del Pix recurrente. |
| `SCHEDULE_DEFAULT_EXECUTE_HOUR_BRT` · `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS` | `6` · `2` · `180` · `60` | Ventana de ejecución y límites de los pagos programados. |
| `RECONCILIATION_INTERNAL_CIDR` | — | Rango CIDR de confianza para las llamadas internas de conciliación. |
## Ámbito de Pix y del ledger
| Variable | Predeterminado / Obligatorio | Descripción |
| --------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `PIX_ISPB` | **Obligatorio** | El ISPB (código de participante) con el que opera este despliegue. |
| `ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END` | — | Ventana diaria durante la cual se bloquean las escrituras de asientos del ledger. |
| `ORGANIZATION_IDS` | **Obligatorio en producción** | UUID de organizaciones de Midaz, separados por comas, dentro del ámbito de licenciamiento. |
| `GOOGLE_APPLICATION_CREDENTIALS` | 🔒 — | Ruta a un archivo de credenciales de cuenta de servicio de Google, cuando se ejecuta contra dependencias gestionadas por GCP. |
## Health y readiness
Cada componente expone `GET /health` (liveness) y `GET /readyz` (readiness) en su puerto. Consulta [Health y readiness](/es/reference/health-and-readiness) para conocer la forma de la respuesta y el comportamiento de arranque y drenaje.