Variables de entorno

Configura el riel de boleto y pago de facturas vía BTG: OAuth de BTG, cifrado de credenciales con rotación de claves, ledger de Midaz, conciliación, lotes y cuotas de boletos y webhooks.

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). El puerto principal sirve GET /health y GET /version. PLUGIN_AUTH_ENABLED tiene el valor predeterminado true, y producción lo fuerza activado. Consulta Puertos de red predeterminados.

Variable	Predeterminado / Obligatorio	Descripción
HEALTH_PORT	—	Puerto del listener de sondas. Sin valor, el proceso no inicia el listener de sondas.
HTTP_BODY_LIMIT_BYTES	4194304 (4 MiB)	Mayor cuerpo de solicitud que acepta el puerto principal, en bytes. Un valor mayor lee 4194304, con una advertencia al arrancar. Este valor y los dos timeouts de abajo no se aplican a HEALTH_PORT.
HTTP_RECEIVE_TIMEOUT_SEC	30	Cuánto tiempo puede tardar una solicitud en llegar al puerto principal, en segundos. Un valor que no es positivo lee el valor predeterminado.
HTTP_IDLE_TIMEOUT_SEC	120	Cuánto tiempo queda abierta una conexión keep-alive inactiva en el puerto principal, en segundos. Un valor que no es positivo lee el valor predeterminado.
TRUSTED_PROXIES	—	Rangos CIDR, separados por comas, del ingress o del balanceador de carga delante del servicio. Cuando está definida, el rate limiter usa la dirección del llamador real, y el servicio envía esa dirección a Access Manager. Cuando no está definida, todo llamador detrás del proxy comparte un único bucket de rate limit. Una entrada que sea una dirección suelta, un rango más amplio que /8 (IPv4) o /48 (IPv6), o un rango no válido se descarta con una línea de log de error, y el arranque continúa.
REQUEST_TIMEOUT_SEC	el mayor entre 180 y cuatro veces BTG_HTTP_TIMEOUT	Plazo de cada solicitud de negocio, en segundos. Una dependencia que no responde dentro de él hace que la solicitud falle con 503. Las solicitudes GET y HEAD corren con el menor entre este valor y 30 segundos. El arranque falla con un valor por debajo de cuatro veces BTG_HTTP_TIMEOUT.

Declaración de permisos

El servicio publica los permisos de Payments en Access Manager solo cuando IDP_DECLARATION_ENABLED es true. Viene desactivado por defecto.

Variable	Predeterminado / Obligatoria	Descripción
IDP_DECLARATION_ENABLED	false	Publica la declaración de permisos de Payments al iniciar. Acepta solo true o false. La declaración también permite que Payments acepte socios. En modo single-tenant, sin ella Access Manager rechaza un permiso de socio en Payments.
IDP_HOST	—	Host de identidad de Access Manager. Obligatoria con la declaración activada.
IDP_M2M_CLIENT_ID	—	Id de la credencial de máquina usada para publicar. Obligatoria con la declaración activada.
IDP_M2M_CLIENT_SECRET	—	Secreto de la credencial de máquina. 🔒 Obligatoria con la declaración activada.

La declaración también exige PLUGIN_AUTH_ENABLED en true y un host de autenticación en PLUGIN_AUTH_HOST o PLUGIN_AUTH_ADDRESS. Un valor ausente detiene el arranque.

Licencia

La licencia es obligatoria en todos los entornos. El arranque falla cuando LICENSE_KEY y LICENSE_FILE_PATH están ambas vacías. Si el servicio de licencia no responde al arrancar, el servicio sigue en pie, no listo, y sigue intentando. La licencia es válida para todo el despliegue, así que la clave debe ser global. License Manager describe cómo el producto verifica la licencia.

Variable	Predeterminado / Obligatorio	Descripción
LICENSE_KEY	🔒 Obligatorio, salvo que LICENSE_FILE_PATH esté definida	La clave de licencia global que Lerian emitió para este riel. El servicio obtiene con ella un archivo de licencia firmado y lo mantiene en memoria.
LICENSE_FILE_PATH	—	Ruta de un archivo de licencia firmado que Lerian emite. Cuando está definida, el servicio usa el archivo e ignora LICENSE_KEY.

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, que el servicio usa para descubrir la cuenta de BTG que emite. Sin ella, el connect del proveedor no verifica la cuenta y responde account_verified: false. Todo boleto híbrido, y todo boleto, ítem de lote o serie de cuotas que lleva un nosso número elegido, se rechaza con 422 PBP-0017. En modo multi-tenant, sin ella el connect del proveedor no registra en BTG la nueva URL de webhook ni la clave de firma, y responde webhook_subscription_registered: 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 y, en todo entorno, en un pod que atiende la API	Secreto que autentica los webhooks entrantes de BTG en modo single-tenant. Al menos 32 caracteres. En modo multi-tenant, cada conexión de proveedor firma con su propia clave, y el servicio sigue necesitando esta variable.
WEBHOOK_PUBLIC_BASE_URL	Obligatorio en modo multi-tenant en un pod que atiende la API	URL base pública de este servicio. El connect del proveedor arma la URL de webhook de cada tenant a partir de ella. En modo multi-tenant el servicio no inicia sin ella. Usa una URL https:// en producción.
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, y para el beneficiario final de todo boleto, 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.

Rutas contables

Variable	Predeterminado / Obligatorio	Descripción
ACCOUNTING_ROUTES_ENABLED	false	Pone las rutas contables de Payments del ledger en las transacciones que Payments crea. Un ledger sin ninguna de estas rutas recibe transacciones sin rutas. Un ledger con solo parte de ellas, o una consulta de ruta que falla, rechaza un pago nuevo, y el crédito de un boleto pagado espera hasta que las rutas se resuelvan.
ACCOUNTING_ROUTES_CACHE_TTL_SEC	900	Segundos que las rutas de una organización quedan en caché. 0 o menos apaga la caché.
ACCOUNTING_ROUTES_FETCH_TIMEOUT_SEC	60	Límite de tiempo de una consulta de rutas, en segundos. 0 o menos usa el valor predeterminado.

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.

Solo una réplica a la vez recorre el ciclo del outbox de un tenant, así que más réplicas no aumentan la tasa de despacho al ledger de un tenant. Cada ciclo mantiene un lock de sesión de PostgreSQL en la base primaria del tenant. Accede a esa base sin un pooler de conexiones en modo de transacción.

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 no tiene identificador de BTG: una que reserva un nosso número, o un boleto individual sin él cuya respuesta de BTG se perdió. Los valores por debajo de 15m valen 15m, y el valor nunca queda por debajo de cuatro veces BTG_HTTP_TIMEOUT.
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.

Serie de cuotas

Estas variables definen cómo la conciliación envía a BTG los boletos de una serie de cuotas, uno por vez.

Variable	Predeterminado / Obligatorio	Descripción
RECONCILIATION_INSTALLMENT_CLAIM_LEASE	10m	Cuánto tiempo una réplica conserva su reclamo exclusivo sobre una cuota mientras la envía a BTG. Un valor inválido vale 10m. El valor nunca queda por debajo de cuatro veces BTG_HTTP_TIMEOUT más un minuto, ni por debajo de 3m.
RECONCILIATION_INSTALLMENT_DISCOUNT_CUTOFF_MARGIN	30m	Cuánto del día debe quedar antes de la medianoche en Brasilia para que se envíe una cuota cuya fecha límite de descuento es hoy. Los valores por encima de 6h valen 6h. Un valor cero, negativo o inválido vale 30m.
RECONCILIATION_INSTALLMENT_RECOVERY_ALERT_AGE	1h	Cuánto tiempo una cuota puede esperar su título en BTG antes de que el servicio genere una alerta. Los valores por debajo de 15m valen 15m. La alerta no cambia la cuota.
RECONCILIATION_INSTALLMENT_RECOVERY_ESCALATION_AGE	24h	La edad en que esa alerta sube de severidad. Un valor que no sea mayor que la edad de la alerta se reemplaza en el arranque por 24h, o por el doble de la edad de la alerta cuando 24h no es mayor. El servicio no lo rechaza.
RECONCILIATION_INSTALLMENT_ACCOUNT_DISCOVERY_ALERT_AGE	1h	Cuánto tiempo una cuota aún no intentada de una serie sin cuenta en BTG puede esperar antes de que el servicio genere una alerta. Los valores por debajo de 15m valen 15m.

Lotes de boletos

Estas variables definen cómo el servicio envía a BTG los ítems de un lote de boletos.

Variable	Predeterminado / Obligatorio	Descripción
BTG_BULK_MAX_BODY_BYTES	7680	Presupuesto de bytes del cuerpo de un envío de lote a BTG. El arranque falla con un valor cero, negativo o inválido.
BOLETO_BATCH_INLINE_SUBMIT_BUDGET	8s	Cuánto tiempo la solicitud de creación del lote espera sus envíos antes de responder. Limita solo esa espera, nunca la llamada a BTG. Un valor cero, negativo o inválido vale 8s.
RECONCILIATION_BATCH_SUBMISSION_CLAIM_LEASE	3m	Cuánto tiempo una réplica conserva su reclamo exclusivo sobre un envío de lote. Un valor inválido vale 3m. El valor nunca queda por debajo de cuatro veces BTG_HTTP_TIMEOUT más un minuto.
RECONCILIATION_BATCH_SUBMISSIONS_PER_CYCLE	10	Máximo de envíos de lote que la conciliación envía por tenant en cada ciclo. Un valor cero o negativo vale 10.
BOLETO_BATCH_UNKNOWN_ATTEMPTS_BEFORE_SEARCH	3	Cuántos resultados desconocidos consecutivos admite un envío de lote antes de que el servicio busque sus boletos en BTG. Un valor cero o negativo vale 3.
BOLETO_BATCH_ITEM_OVERDUE_AFTER	30m	Cuánto tiempo un ítem de lote puede quedar sin resultado, desde su primer intento de envío o, si no hubo, desde su creación, antes de que el lote lo lea como atrasado. Un valor cero, negativo o inválido vale 30m.
RECONCILIATION_BATCH_RECOVERY_ALERT_AGE	1h	Cuánto tiempo un ítem de lote en recuperación puede quedar sin resultado antes de que el servicio genere una alerta. La alerta no cambia el ítem.
BOLETO_BATCH_CANCEL_CONCURRENCY	5	Cuántos ítems de un lote cancela una cancelación en BTG a la vez. Un valor cero o negativo vale 5.

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. Un valor por encima de 3600 lee 3600, con una advertencia al arrancar. 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

GET /readyz (readiness) y, en modo multi-tenant, GET /readyz/tenant/:id responden en el puerto de HEALTH_PORT. La readiness queda en 503 hasta que se acepta una licencia. Consulta Health y readiness para conocer la forma de la respuesta.