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 de datastore, multi-tenancy, telemetría y autenticación compartidos por todos los servicios Go de Lerian, 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. MULTI_TENANCY_ENABLED activa o desactiva el multi-tenancy (observa la grafía MULTI_TENANCY_). La conexión con el 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 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_CLIENT_ID`	Obligatorio	Client ID de OAuth para la API de BTG.
`BTG_CLIENT_SECRET`	🔒 Obligatorio	Client secret de OAuth para la API de BTG.
`BTG_WEBHOOK_SECRET`	🔒 Obligatorio	Secreto usado para validar las firmas de los webhooks entrantes de BTG.
`BTG_HTTP_TIMEOUT`	`30s`	Timeout de las llamadas a la API de BTG.
`BTG_TOKEN_REFRESH_INTERVAL`	`1h`	Con qué frecuencia se actualiza el token de acceso de BTG.
`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 de API que autentica las llamadas internas del worker a la API.
`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.
`MIDAZ_DEFAULT_ORG_ID`	Obligatorio	UUID predeterminado de la organización de Midaz para los registros contables.
`MIDAZ_DEFAULT_LEDGER_ID`	Obligatorio	UUID predeterminado del ledger de Midaz para los registros contables.
`MIDAZ_ALLOW_INSECURE_HTTP`	`false`	Permite una URL de Midaz `http://` en texto plano. 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 en operación single-tenant.

Conciliación

Variable	Predeterminado / Obligatorio	Descripción
`RECONCILIATION_INTERVAL`	`5m`	Con qué frecuencia se ejecuta el ciclo de conciliación.
`RECONCILIATION_LOOKBACK_HOURS`	`24`	Hasta qué punto del pasado revisa cada ciclo de conciliación.
`RECONCILIATION_MAX_BOLETOS_PER_CYCLE`	`100`	Máximo de boletos conciliados por ciclo, por tenant.
`RECONCILIATION_DELAY_MS`	`500`	Espera en milisegundos entre pasos de la conciliación.

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_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.

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. Si habilitas el multi-tenancy, agrega una sonda por tenant protegida por autenticación en GET /readyz/tenant/{id}. Consulta Health y readiness para conocer la forma de la respuesta y el comportamiento de arranque y drenaje.

Resumen

Console

Variables de entorno

Servidor y puerto

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

Migraciones

Health y readiness

​Servidor y puerto

​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

​Migraciones

​Health y readiness

Servidor y puerto

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

Migraciones

Health y readiness