Variables de entorno

Variables de entorno para el rail Pix Indirecto vía BTG: integración con BTG y mTLS, DB_*, vínculos Midaz/CRM/Fee, webhooks internos y workers.

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 los workers de reconciliación, calendario y 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 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. Inyecta cada secreto en el momento del despliegue desde tu almacén de secretos. Nunca guardes un secreto 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. Cada worker lleva sus propios ajustes de tuning —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 contienen las credenciales y los 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_* para los almacenes de datos, no la forma compartida POSTGRES_*. Se conecta a un PostgreSQL principal, una réplica de lectura separada, 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. También 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	10485760 (10 MB) · 3	Tope del payload de webhook entrante y techo de reintentos.
RECURRING_SCHEDULE_LEAD_DAYS · RECURRING_ANTISPAM_WINDOW · RECURRING_REPLY_BACKOFF · RECURRING_REPLY_MAX_ATTEMPTS	1 · 720h · 150ms · 3	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	6 · 2 · 180 · 60	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. Consulta Salud y readiness para la forma de la respuesta y el comportamiento de arranque y drenaje.