Variables de entorno

Variables de entorno para el rail de boleto y pago de cuentas vía BTG: integración con BTG, cifrado de credenciales, ledger Midaz y reconciliación.

El rail de boleto y pago de cuentas emite boletos y liquida pagos de cuentas e impuestos (DARF) a través de BTG. DevOps define su comportamiento mediante 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 rail. Para los ajustes de almacén de datos, multi-tenancy, 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. 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. Usa la forma de almacén de datos compartida POSTGRES_* — consulta Almacenes de datos.

​

Servidor y puerto

El servicio escucha en la dirección de SERVER_ADDRESS (por defecto :8080). Las sondas de liveness, readiness y versión se enlazan a este mismo puerto. MULTI_TENANCY_ENABLED activa la multi-tenancy (fíjate en la grafía MULTI_TENANCY_). La conexión al Tenant Manager usa las variables compartidas MULTI_TENANT_*. Consulta Multi-tenancy y Puertos de red predeterminados.

​

Integración con BTG

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

Variable	Valor por defecto / Requerida	Descripción
BTG_API_BASE_URL	Requerida	URL base de la API de BTG.
BTG_AUTH_URL	Requerida	Endpoint del token OAuth de BTG.
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_HTTP_TIMEOUT	30s	Tiempo de espera para las llamadas a la API de BTG.
BTG_TOKEN_REFRESH_INTERVAL	1h	Con qué frecuencia se refresca el token de acceso de BTG.
BTG_CREDENTIAL_SYNC_INTERVAL	20h	Con qué frecuencia se resincronizan las credenciales de BTG almacenadas.

​

Cifrado de credenciales y claves de API internas

El rail cifra las credenciales almacenadas en reposo. Autentica las llamadas internas entre los pods de worker y de API con una clave de API. Ambas claves admiten un slot _PREVIOUS para que puedas rotar el valor activo sin downtime.

Variable	Valor por defecto / Requerida	Descripción
CREDENTIAL_ENCRYPTION_KEY	🔒 Requerida	Clave usada para cifrar las credenciales almacenadas en reposo.
CREDENTIAL_ENCRYPTION_KEY_PREVIOUS	🔒 —	Clave de cifrado anterior, mantenida legible durante la rotación.
INTERNAL_API_KEY	🔒 Requerida	Clave de API que autentica las llamadas internas worker a API.
INTERNAL_API_KEY_PREVIOUS	🔒 —	Clave de API interna anterior, aceptada durante la rotación.
INTERNAL_WORKER_URL	Requerida	URL que la API usa para alcanzar el worker interno.

​

Vínculo con el ledger Midaz

Variable	Valor por defecto / Requerida	Descripción
MIDAZ_LEDGER_URL	Requerida	URL del servicio del ledger Midaz.
MIDAZ_DEFAULT_ORG_ID	Requerida	UUID de organización Midaz por defecto para las contabilizaciones.
MIDAZ_DEFAULT_LEDGER_ID	Requerida	UUID del ledger Midaz por defecto para las contabilizaciones.
MIDAZ_ALLOW_INSECURE_HTTP	false	Permite una URL de Midaz http:// en texto claro. Déjala en false en producción.

​

Reconciliación

Variable	Valor por defecto / Requerida	Descripción
RECONCILIATION_INTERVAL	5m	Con qué frecuencia se ejecuta el ciclo de reconciliación.
RECONCILIATION_LOOKBACK_HOURS	24	Cuánto retrocede cada ciclo de reconciliación.
RECONCILIATION_MAX_BOLETOS_PER_CYCLE	100	Máximo de boletos reconciliados por ciclo, por tenant.
RECONCILIATION_DELAY_MS	500	Retardo en milisegundos entre pasos de reconciliación.

​

Despacho de webhooks e idempotencia

Variable	Valor por defecto / Requerida	Descripción
WEBHOOK_DISPATCHER_BATCH_SIZE	50	Número de eventos de webhook despachados por lote.
WEBHOOK_DISPATCHER_INTERVAL	10s	Intervalo entre ciclos de despacho de webhooks.
WEBHOOK_SKIP_URL_VALIDATION	false	Omite la validación de la URL del suscriptor. Mantenla 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	Desactiva la validación de cuentas. Mantenla en false en producción.

​

Migraciones

Variable	Valor por defecto / Requerida	Descripción
MIGRATION_TIMEOUT_SEC	300	Tiempo de espera en segundos para una ejecución de migración de base de datos.
MIGRATION_LOCK_TIMEOUT_MS	10000	Tiempo de espera en milisegundos para adquirir el lock de migración.

​

Salud y readiness

El rail expone GET /health (liveness) y GET /readyz (readiness) en el puerto principal. Si activas la multi-tenancy, añade una sonda por tenant protegida por autenticación en GET /readyz/tenant/{id}. Consulta Salud y readiness para la forma de la respuesta y el comportamiento de arranque/drenaje.