> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 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 de datastore, multi-tenancy, telemetría y autenticación compartidos por todos los servicios Go de Lerian, consulta [Aspectos esenciales de configuración BYOC](/es/reference/byoc-configuration).

<Note>
  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.
</Note>

<Note>
  Este riel **no** monta la API de administración de systemplane. Usa la forma compartida de datastore `POSTGRES_*`. Consulta [Datastores](/es/reference/byoc-configuration#datastores).
</Note>

## 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](/es/reference/byoc-configuration#multi-tenancy) y [Puertos de red predeterminados](/es/reference/default-network-ports).

## 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](/es/reference/health-and-readiness) para conocer la forma de la respuesta y el comportamiento de arranque y drenaje.