Variables de entorno

El riel de boleto y pago de facturas emite boletos y liquida pagos de facturas e impuestos (DARF) a través de BTG. DevOps define su comportamiento con variables de entorno en el momento del despliegue. Un cambio en una variable requiere reiniciar el servicio. Esta página cubre las variables distintivas de este riel. Para los ajustes compartidos de datastore, telemetría y autenticación, 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. Inyéctalo en el momento del despliegue desde tu almacén de secretos. Nunca lo incluyas 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. Usa la forma compartida de datastore POSTGRES_*. Consulta Datastores.

Servidor y puerto

El servicio escucha en la dirección indicada en SERVER_ADDRESS (predeterminado :8080). Las sondas de liveness, readiness y versión se enlazan a ese mismo puerto. PLUGIN_AUTH_ENABLED tiene el valor predeterminado true, y producción lo fuerza activado. Consulta Puertos de red predeterminados.

Licencia

La licencia es obligatoria en todos los entornos. El arranque falla cuando alguna de las variables está vacía. License Manager describe cómo el producto verifica la licencia.

Variable	Predeterminado / Obligatorio	Descripción
`LICENSE_KEY`	🔒 Obligatorio	La clave de licencia que Lerian emitió para este riel.
`ORGANIZATION_IDS`	Obligatorio	Alcance de la licencia: `global` o una lista de UUID de organizaciones en minúsculas, separados por comas.

Integración con BTG

Estas variables definen los endpoints y las credenciales de la conexión con BTG. También definen los intervalos de actualización en segundo plano del token de acceso de BTG y de las credenciales sincronizadas.

Variable	Predeterminado / Obligatorio	Descripción
`BTG_API_BASE_URL`	Obligatorio	URL base de la API de BTG.
`BTG_AUTH_URL`	Obligatorio	Endpoint del token OAuth de BTG.
`BTG_COMMON_BASE_URL`	—	URL base de la API Common Methods de BTG. Sin ella, el connect del proveedor no verifica la cuenta y responde `account_verified: false`.
`PROVIDER_CLIENT_ID`	Obligatorio	Client ID de OAuth para la API de BTG.
`PROVIDER_CLIENT_SECRET`	🔒 Obligatorio	Client secret de OAuth para la API de BTG.
`BTG_WEBHOOK_HMAC_SECRET`	🔒 Obligatorio en producción	Secreto que autentica los webhooks entrantes de BTG. Al menos 32 caracteres.
`BTG_HTTP_TIMEOUT`	`30s`	Timeout de las llamadas a la API de BTG.
`BTG_TOKEN_REFRESH_INTERVAL`	`2m`	Con qué frecuencia se actualiza el token de acceso de BTG. Los valores mayores que `4m` se limitan a `4m`.
`BTG_CREDENTIAL_SYNC_INTERVAL`	`20h`	Con qué frecuencia se vuelven a sincronizar las credenciales de BTG almacenadas.

Cifrado de credenciales y claves de API internas

El riel cifra las credenciales almacenadas en reposo. Autentica las llamadas internas entre el worker y los pods de la API con una clave de API. Ambas claves admiten un espacio _PREVIOUS para que puedas rotar el valor activo sin caída de servicio.

Variable	Predeterminado / Obligatorio	Descripción
`CREDENTIAL_ENCRYPTION_KEY`	🔒 Obligatorio	Clave usada para cifrar las credenciales almacenadas en reposo.
`CREDENTIAL_ENCRYPTION_KEY_PREVIOUS`	🔒 —	Clave de cifrado anterior, legible durante la rotación.
`INTERNAL_API_KEY`	🔒 Obligatorio	Clave que la API presenta en sus llamadas al worker. Al menos 32 caracteres. Los pods de worker siempre la necesitan; los pods de la API la necesitan en producción.
`INTERNAL_API_KEY_PREVIOUS`	🔒 —	Clave de API interna anterior, aceptada durante la rotación.
`INTERNAL_WORKER_URL`	Obligatorio	URL que la API usa para llegar al worker interno.

Vínculo con el ledger de Midaz

Variable	Predeterminado / Obligatorio	Descripción
`MIDAZ_LEDGER_URL`	Obligatorio	URL del servicio de ledger de Midaz. Para consultar el pagador de pagos de facturas y DARF, este servicio debe ofrecer los endpoints de instrumentos y titulares del CRM en `/v2`.
`MIDAZ_AUTH_ENABLED`	`false`	Autentica las llamadas a Midaz a través de Access Manager. Producción requiere `true`.
`MIDAZ_ALLOW_INSECURE_HTTP`	`false`	Permite una URL `http://` en texto plano de Midaz o de Access Manager. Déjalo en `false` en producción.

Outbox interno de Midaz

El riel siempre inicializa un outbox interno en PostgreSQL para las operaciones asíncronas del ledger de Midaz. Es una cola de trabajo interna, no un catálogo externo de CloudEvents ni de Streaming Hub. El arranque valida en conjunto los presupuestos de reintento y de tiempo de procesamiento, y rechaza las combinaciones inseguras.

Variable	Predeterminado / Obligatorio	Descripción
`OUTBOX_DISPATCH_INTERVAL_SEC`	`2`	Intervalo en segundos entre sondeos del despachador.
`OUTBOX_BATCH_SIZE`	`50`	Máximo de filas reclamadas por sondeo.
`OUTBOX_PUBLISH_MAX_ATTEMPTS`	`1`	Intentos del handler dentro de un envío de fila reclamada. Mantenlo bajo porque las llamadas a Midaz ya reintentan internamente.
`OUTBOX_PUBLISH_BACKOFF_MS`	`200`	Backoff en milisegundos entre intentos del handler.
`OUTBOX_RETRY_WINDOW_SEC`	`180`	Espera antes de que una fila fallida pueda enviarse de nuevo.
`OUTBOX_MAX_DISPATCH_ATTEMPTS`	`10`	Máximo de intentos de envío externos antes de que la fila quede inválida.
`OUTBOX_PROCESSING_TIMEOUT_SEC`	`120`	Timeout de procesamiento en segundos para una fila reclamada.
`OUTBOX_MAX_FAILED_PER_BATCH`	`25`	Máximo de filas fallidas atendidas en un lote.
`OUTBOX_INCLUDE_TENANT_METRICS`	`false`	Incluye identificadores de tenant en las métricas del outbox.
`OUTBOX_PRIORITY_EVENT_TYPES`	—	Déjalo vacío. Cualquier valor no vacío hace fallar el arranque.
`OUTBOX_ALLOW_EMPTY_TENANT`	`true`	Permite filas del outbox interno sin identificador de tenant.

Conciliación

Variable	Predeterminado / Obligatorio	Descripción
`RECONCILIATION_INTERVAL`	`90s`	Con qué frecuencia se ejecuta el ciclo de conciliación.
`RECONCILIATION_MAX_MONEY_ITEMS_PER_CYCLE`	`100`	Máximo de ítems de pago y de liquidación conciliados por ciclo.
`RECONCILIATION_MAX_BOLETOS_PER_CYCLE`	`40`	Máximo de boletos conciliados por ciclo.
`RECONCILIATION_DELAY_MS`	`500`	Espera en milisegundos entre pasos de la conciliación.
`RECONCILIATION_PAYMENT_GRACE_PERIOD`	`5m`	Edad que un pago debe alcanzar antes de que la conciliación consulte a BTG sobre él. Los valores por debajo de `2m` valen `2m`.
`PAYMENT_UNCONFIRMED_DISPATCH_GRACE`	`5m`	Edad mínima antes de que la conciliación haga fallar un pago `UNCONFIRMED` que nunca se envió a BTG. No se pagó nada, y cualquier reserva se cancela. El arranque falla por debajo de `5m`.
`PAYMENT_UNCONFIRMED_ABSENCE_WINDOW`	`30m`	Cuánto tiempo BTG debe estar sin registro de un pago de factura o de servicio público enviado antes de que la conciliación lo haga fallar con `PBP-0211` y libere los fondos. El arranque falla por debajo de `10m`.
`PAYMENT_UNCONFIRMED_BATCH_SIZE`	`50`	Máximo de pagos `UNCONFIRMED` leídos por ciclo. Los valores por encima de `100` valen `100`.
`RECONCILIATION_BOLETO_GRACE_PERIOD`	`5m`	Edad que un boleto debe alcanzar antes de que la conciliación consulte a BTG sobre él. Los valores por debajo de `2m` valen `2m`.
`RECONCILIATION_BOLETO_PROCESSING_CEILING`	`24h`	Edad, según la hora de creación en BTG, a partir de la cual un boleto que BTG todavía responde como `PROCESSING` o `ERROR` deja de contar como un registro en curso. Debe ser mayor que `RECONCILIATION_BOLETO_GRACE_PERIOD`, o la conciliación no arranca. Los valores por debajo de `15m` valen `15m`.
`RECONCILIATION_BOLETO_RESERVATION_GRACE_PERIOD`	`30m`	Edad mínima antes de que la conciliación consulte a BTG sobre una emisión de boleto que reserva un nosso número y no tiene identificador de BTG.
`RECONCILIATION_WEBHOOK_SILENCE_WINDOW`	`30m`	Cuánto tiempo puede pasar el riel sin recibir ningún webhook de BTG antes de que la conciliación informe el silencio como un error. Solo lo informa cuando un boleto que BTG aceptó antes del inicio de la ventana todavía espera su webhook de registro. Los valores por debajo de `10m` valen `10m`.
`RECONCILIATION_WEBHOOK_CLAIM_LEASE`	`2h`	Cuánto tiempo una réplica conserva su reclamo exclusivo sobre un lote de webhooks de BTG que procesa. Auméntalo cuando aumentes `RECONCILIATION_MAX_MONEY_ITEMS_PER_CYCLE`. Los valores por debajo de `1h` valen `1h`.

Envío de webhooks e idempotencia

Variable	Predeterminado / Obligatorio	Descripción
`WEBHOOK_DISPATCHER_BATCH_SIZE`	`50`	Cantidad de eventos de webhook enviados por lote.
`WEBHOOK_DISPATCHER_INTERVAL`	`10s`	Intervalo entre ciclos de envío de webhooks.
`WEBHOOK_DISPATCHER_CLAIM_LEASE`	`15m`	Cuánto tiempo una réplica conserva su reclamo exclusivo sobre un lote de entregas de webhook que envía. Auméntalo cuando aumentes `WEBHOOK_DISPATCHER_BATCH_SIZE`. Los valores por debajo de `5m` valen `5m`.
`WEBHOOK_CONSUMER_INTERVAL`	`5s`	Intervalo entre los ciclos que procesan los webhooks que BTG envía al riel. Los valores por debajo de `1s` valen `1s`.
`WEBHOOK_CONNECTION_GRACE_WINDOW_SEC`	`1800`	Cuánto tiempo, en segundos, la URL de webhook y la clave de firma anteriores siguen autenticando entregas después de que un connect del proveedor las rota. El arranque falla con un valor por debajo de `1200` o con un valor que no sea un entero positivo. Déjala sin definir para mantener el valor predeterminado.
`WEBHOOK_SKIP_URL_VALIDATION`	`false`	Omite la validación de la URL del suscriptor. Déjalo en `false` en producción.
`IDEMPOTENCY_RECORD_TTL_HOURS`	`48`	Cuánto tiempo se conservan los registros de idempotencia, en horas.
`ACCOUNT_VALIDATION_DISABLED`	`false`	Deshabilita la validación de cuentas. Déjalo en `false` en producción.

Consulta de facturas

Estas variables configuran POST /v1/payments/consult. El rate limit cuenta las consultas por quien llama, y cada réplica lleva su propio conteo.

Variable	Predeterminado / Obligatorio	Descripción
`CONSULT_RATE_LIMIT_MAX`	`100`	Máximo de consultas por quien llama en una ventana. `0` o un valor negativo vale `100`.
`CONSULT_RATE_LIMIT_WINDOW_SEC`	`60`	Duración de la ventana, en segundos. `0` o un valor negativo vale `60`.
`CONSULT_AUDIT_HMAC_KEY`	🔒 Obligatorio	La clave que el servicio usa para generar la huella de la línea de pago en cada registro de auditoría de la consulta. Usa al menos 32 caracteres, sin espacios al inicio ni al final. Un pod que sirve la API de pagos no inicia sin ella. En producción, el servicio rechaza el valor de ejemplo de la plantilla de configuración.

Migraciones

Variable	Predeterminado / Obligatorio	Descripción
`MIGRATION_TIMEOUT_SEC`	`300`	Timeout en segundos para una ejecución de migración de base de datos.
`MIGRATION_LOCK_TIMEOUT_MS`	`10000`	Timeout en milisegundos para obtener el bloqueo de migración.

Health y readiness

El riel expone GET /health (liveness) y GET /readyz (readiness) en el puerto principal. Consulta Health y readiness para conocer la forma de la respuesta.

Introducción

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Variables de entorno

Servidor y puerto

Licencia

Integración con BTG

Cifrado de credenciales y claves de API internas

Vínculo con el ledger de Midaz

Outbox interno de Midaz

Conciliación

Envío de webhooks e idempotencia

Consulta de facturas

Migraciones

Health y readiness

​Servidor y puerto

​Licencia

​Integración con BTG

​Cifrado de credenciales y claves de API internas

​Vínculo con el ledger de Midaz

​Outbox interno de Midaz

​Conciliación

​Envío de webhooks e idempotencia

​Consulta de facturas

​Migraciones

​Health y readiness

Servidor y puerto

Licencia

Integración con BTG

Cifrado de credenciales y claves de API internas

Vínculo con el ledger de Midaz

Outbox interno de Midaz

Conciliación

Envío de webhooks e idempotencia

Consulta de facturas

Migraciones

Health y readiness