Variables de entorno

Pix Indirecto, vía BTG alcanza el arreglo Pix a través de BTG como participante directo. Se distribuye como varios componentes —una API más workers de reconciliación, calendario y webhooks entrantes/salientes—, cada uno configurado mediante variables de entorno que DevOps define en el momento del despliegue; cambiar una requiere reiniciar ese componente. Esta página cubre las variables distintivas de este rail; para los ajustes de multi-tenancy, streaming, telemetría y autenticación compartidos por todos los servicios Go de Lerian, consulta la referencia de configuración BYOC.

En las tablas siguientes, la columna Valor por defecto / Requerida muestra el valor por defecto; un calificador en negrita (por ejemplo Requerida) marca las variables que debes definir. — significa que no hay valor por defecto. 🔒 marca un secreto: inyéctalo en el momento del despliegue desde tu almacén de secretos y nunca lo guardes en el repositorio. Esta página solo enumera los nombres de las variables y su comportamiento; no imprime ningún valor secreto.

Este rail no monta la API de administración de systemplane. Sus variables de almacén de datos usan un prefijo DB_* en lugar de la forma compartida POSTGRES_*; consulta Almacenes de datos más abajo.

Componentes y puertos

El componente API escucha en SERVER_PORT (por defecto 4014; SERVER_ADDRESS se deriva de él). Los workers de reconciliación, calendario y webhooks enlazan cada uno un WORKER_PORT para sus sondas de salud y llevan sus propios y extensos ajustes de tuning (tamaños de lote, intervalos de sondeo, concurrencia y circuit breakers) en sus respectivos archivos .env.example. Consulta Puertos de red predeterminados.

Integración con BTG y mTLS

Credenciales y ajustes de TLS mutuo para la conexión con BTG.

Variable	Valor por defecto / Requerida	Descripción
`BTG_BASE_URL`	Requerida	URL base de la API de BTG.
`BTG_CERTIFICATE_URL`	Requerida	Endpoint del que se obtiene el certificado de cliente para mTLS.
`BTG_CLIENT_ID`	Requerida	Client ID de OAuth para la API de BTG.
`BTG_CLIENT_SECRET`	🔒 Requerida	Client secret de OAuth para la API de BTG.
`BTG_WEBHOOK_SECRET`	🔒 Requerida	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. Mantenla en `true` en producción.
`MTLS_ENABLED`	`false`	Habilita el TLS mutuo en la conexión con BTG. Habilítala en producción.
`MTLS_CERTIFICATE_TTL`	`24h`	Cuánto tiempo se cachea un certificado de cliente obtenido antes de refrescarlo.
`MTLS_HTTP_TIMEOUT`	`10s`	Tiempo de espera para la llamada HTTP de obtención del certificado.

Almacenes de datos

Este rail usa un prefijo DB_* (no la forma compartida POSTGRES_*) para su conexión principal a PostgreSQL y una réplica de lectura separada, además de MongoDB y Redis.

Variable	Valor por defecto / Requerida	Descripción
`DB_HOST` · `DB_PORT`	Requerida	Host y puerto principales de PostgreSQL.
`DB_USER` · `DB_PASSWORD`	🔒 Requerida	Credenciales principales de PostgreSQL.
`DB_NAME`	Requerida	Nombre de la base de datos principal.
`DB_SSL_MODE`	`disable`	Modo TLS de libpq. Usa `require` o más estricto en producción.
`DB_REPLICA_HOST` · `DB_REPLICA_PORT` · `DB_REPLICA_NAME` · `DB_REPLICA_USER` · `DB_REPLICA_PASSWORD`	🔒 —	Conexión de réplica de lectura opcional (misma forma que la principal).
`REPLICATION_USER` · `REPLICATION_PASSWORD`	🔒 —	Credenciales para el rol de replicación por streaming.
`MONGO_URI` · `MONGO_HOST` · `MONGO_PORT` · `MONGO_USER` · `MONGO_PASSWORD` · `MONGO_NAME`	🔒 Requerida	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 única cadena de conexión: no son alternativas de URI frente a partes discretas. La contraseña es un secreto.
`MONGO_TLS`	`false`	Habilita el 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 el TLS hacia Redis y aporta un PEM CA codificado en base64.

Midaz, CRM y Fees

Variable	Valor por defecto / Requerida	Descripción
`MIDAZ_ONBOARDING_URL` · `MIDAZ_TRANSACTION_URL`	Requerida	URLs de los servicios de onboarding y transacciones de Midaz.
`MIDAZ_ORGANIZATION_ID` · `MIDAZ_LEDGER_ID`	Requerida	UUIDs de la organización y el ledger de Midaz para las contabilizaciones Pix.
`MIDAZ_CLIENT_ID` · `MIDAZ_CLIENT_SECRET`	🔒 —	Credenciales OAuth para M2M de Midaz.
`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`	—	Tiempo de espera de la petición de tarifas.
`CASHIN_FEE_CALCULATION_TYPE`	—	Cómo se calculan las tarifas de cash-in.

Webhooks internos y programación

La API y los workers intercambian eventos a través de un canal de webhooks interno y ejecutan flujos Pix recurrentes y programados.

Variable	Valor por defecto / Requerida	Descripción
`INTERNAL_WEBHOOK_SECRET`	🔒 Requerida	Secreto HMAC compartido entre la API y los workers para la firma de 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`	—	Tope del payload de webhook entrante y techo de reintentos.
`RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS`	—	Ajustes de programación de Pix recurrente y de manejo de respuestas.
`SCHEDULE_DEFAULT_EXECUTE_HOUR_BRT` · `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS`	—	Ventana y cotas de ejecución de pagos programados.
`RECONCILIATION_INTERNAL_CIDR`	—	Rango CIDR de confianza para las llamadas de reconciliación internas.

Alcance de Pix y del ledger

Variable	Valor por defecto / Requerida	Descripción
`PIX_ISPB`	Requerida	El ISPB (código de participante) bajo el que opera este despliegue.
`ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END`	—	Ventana diaria durante la cual se bloquean las escrituras de entradas del ledger.
`ORGANIZATION_IDS`	Requerida en producción	UUIDs de organización Midaz separados por comas en el alcance de licenciamiento.
`GOOGLE_APPLICATION_CREDENTIALS`	🔒 —	Ruta a un archivo de credenciales de cuenta de servicio de Google, al ejecutarse contra dependencias gestionadas por GCP.

Salud y readiness

Cada componente expone GET /health (liveness) y GET /readyz (readiness) en su puerto; la API también responde /ready. Consulta Salud y readiness para la forma de la respuesta y el comportamiento de arranque/drenaje.

Resumen

Directo vía JD

Indirecto vía BTG

Variables de entorno

Componentes y puertos

Integración con BTG y mTLS

Almacenes de datos

Midaz, CRM y Fees

Webhooks internos y programación

Alcance de Pix y del ledger

Salud y readiness

​Componentes y puertos

​Integración con BTG y mTLS

​Almacenes de datos

​Midaz, CRM y Fees

​Webhooks internos y programación

​Alcance de Pix y del ledger

​Salud y readiness

Componentes y puertos

Integración con BTG y mTLS

Almacenes de datos

Midaz, CRM y Fees

Webhooks internos y programación

Alcance de Pix y del ledger

Salud y readiness