Variables de entorno

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.

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 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.

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 para conocer la forma de la respuesta y el comportamiento de arranque y drenaje.

​Componentes y puertos

​Integración con BTG y mTLS

​Datastores

​Midaz, CRM y Fees

​Webhooks internos y programación

​Ámbito de Pix y del ledger

​Health y readiness

Componentes y puertos

Integración con BTG y mTLS

Datastores

Midaz, CRM y Fees

Webhooks internos y programación

Ámbito de Pix y del ledger

Health y readiness