> ## 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

> Referencia de las variables de entorno que configuran Matcher, agrupadas como las agrupa el código, con cada valor predeterminado y las verificaciones que Matcher aplica al iniciar.

Esta referencia enumera las variables de entorno que configuran **Matcher**, el motor de conciliación. Lerian define estos valores cuando instala o actualiza Matcher. Usa esta página para saber qué hace cada configuración, cuál es su valor predeterminado y qué verifica Matcher al iniciar.

Cuando una variable obligatoria falta o no es válida, Matcher no inicia. Con `ENV_NAME=production`, Matcher aplica verificaciones adicionales. La columna **Obligatoria** marca cada una como "Producción".

Algunas variables solo definen el valor inicial de un documento de runtime. Lerian puede cambiar esos documentos en un Matcher en ejecución mediante [Systemplane](https://docs.lerian.studio/es/reference/platform/systemplane/overview.md). La sección [documentos de runtime](#runtime-documents) enumera esos documentos.

## Aplicación

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `ENV_NAME` | Nombre del entorno. Con `production`, Matcher deshabilita Swagger y rechaza un endpoint inseguro de almacenamiento de objetos. También aplica las verificaciones marcadas como "Producción" en esta página. | `development` | No |
| `LOG_LEVEL` | Nivel de log: `debug`, `info`, `warn`, `error` o `fatal`. Cualquier otro valor detiene el inicio. | `info` | No |
| `DEPLOYMENT_MODE` | Modelo de despliegue: `saas`, `byoc` o `local`, en mayúsculas o minúsculas. Con `saas` o `byoc`, Matcher exige `IDEMPOTENCY_HMAC_SECRET`, rechaza un valor `http` en `PUBLIC_BASE_SCHEMES` y rechaza un `PUBLIC_BASE_HOST` mal formado. La respuesta de `/readyz` también informa el valor. | — | Sí |
| `SHUTDOWN_GRACE_PERIOD_SEC` | Segundos que Matcher espera a que termine el trabajo en curso cuando se detiene. | `12` | No |
| `ALLOW_INSECURE_TLS` | Permite conexiones sin TLS a PostgreSQL, Redis y RabbitMQ. Sin `true`, Matcher rechaza esas conexiones. Los valores predeterminados de esta página no usan TLS. | — | No |

## Servidor HTTP

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `SERVER_ADDRESS` | Dirección de bind de la API. | `:4018` | No |
| `HTTP_READ_TIMEOUT` | Tiempo máximo para leer una solicitud, como una duración del tipo `15m`. También cubre las cargas de archivos en streaming. | `15m` | No |
| `HTTP_BODY_LIMIT_BYTES` | Tamaño máximo del cuerpo, en bytes, para las rutas que guardan la solicitud completa en búfer. | `104857600` | No |
| `CORS_ALLOWED_ORIGINS` | Orígenes CORS permitidos (CSV). | `http://localhost:3000` | Producción: al menos un origen, y no `*` |
| `CORS_ALLOWED_METHODS` | Métodos CORS permitidos (CSV). | `GET,POST,PUT,PATCH,DELETE,OPTIONS` | No |
| `CORS_ALLOWED_HEADERS` | Headers CORS permitidos (CSV). | `Origin,Content-Type,Accept,Authorization,X-Request-ID` | No |
| `SERVER_TLS_CERT_FILE` | Ruta del certificado TLS. Defínela junto con `SERVER_TLS_KEY_FILE`. Un certificado habilita HSTS. | — | No |
| `SERVER_TLS_KEY_FILE` | Ruta de la clave privada TLS. Defínela junto con `SERVER_TLS_CERT_FILE`. | — | No |
| `TLS_TERMINATED_UPSTREAM` | Defínela como `true` cuando un balanceador de carga termina el TLS delante de Matcher. Habilita HSTS. | `false` | No |
| `TRUSTED_PROXIES` | CIDR de proxies de confianza (CSV) para resolver la IP del cliente. Matcher rechaza `*`, `0.0.0.0/0` y `::/0`. | — | Producción |
| `PUBLIC_BASE_HOST` | `host[:port]` público que Matcher pone en las URL de webhook y de callback que emite. Usa el host solo, sin esquema ni ruta. Si está vacía, Matcher usa `SERVER_ADDRESS`. | — | No |
| `PUBLIC_BASE_SCHEMES` | Esquema de esas URL públicas. | `https` | No |
| `SWAGGER_ENABLED` | Sirve la interfaz de Swagger. `ENV_NAME=production` la deshabilita. | `false` | No |

## Autenticación

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Habilita la autenticación de Access Manager. Matcher también acepta el nombre anterior `AUTH_ENABLED`. Cuando los dos nombres tienen valores distintos, Matcher se niega a iniciar. | `false` | No |
| `PLUGIN_AUTH_ADDRESS` | Dirección de Access Manager. Matcher también acepta el nombre anterior `AUTH_SERVICE_ADDRESS`, con la misma regla de conflicto. | — | Cuando el proveedor es `plugin-auth` |
| `AUTH_PROVIDER` | Proveedor de autenticación: `plugin-auth` o `disabled`. Si no está definida, `PLUGIN_AUTH_ENABLED` lo selecciona. Un valor explícito prevalece. Cualquier otro valor detiene el inicio. | — | No |
| `AUTH_REQUIRED` | Con `true` y la autenticación deshabilitada, cada operación en `/v1` que necesita un permiso responde `503`. | `false` | No |
| `AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED` | Con `true` y la autenticación deshabilitada, cada operación en `/v1` que necesita un permiso sigue exigiendo un bearer token y responde `401` sin él. Matcher no llama a Access Manager para esas solicitudes. Sin `AUTH_JWT_VERIFY_CERT` ni `AUTH_JWT_VERIFY_CERT_PATH`, Matcher no verifica la firma del token. | `false` | No |
| `AUTH_M2M_PRODUCT_FORWARD_ENABLED` | Con `true`, Matcher también envía el nombre de su producto a Access Manager cuando verifica un token de aplicación. | `false` | No |
| `AUTH_TIMEOUT` | Tiempo límite de la verificación en Access Manager de una solicitud, con los reintentos incluidos, como una duración del tipo `5s`. | `30s` | No |
| `AUTH_CACHE_TTL` | Tiempo que Matcher guarda cada decisión de Access Manager, como una duración del tipo `60s`. Un cambio de permisos puede tardar ese tiempo en aplicarse. Si no está definida, Matcher no guarda ninguna decisión. | — | No |
| `AUTH_BREAKER_ENABLED` | Habilita un circuit breaker en las llamadas a Access Manager. Después de 5 llamadas fallidas seguidas, detiene las llamadas durante 30 segundos. Mientras tanto, Matcher rechaza cada solicitud que no tiene una aprobación en caché. | `false` | No |
| `AUTH_RETRY_MAX` | Máximo de reintentos de una llamada a Access Manager que falla sin una decisión. `0` deshabilita los reintentos. | `0` | No |
| `AUTH_JWT_VERIFY_CERT` | Una o más claves públicas RSA o certificados X.509 en PEM, separados por saltos de línea. Con una clave cargada, Matcher verifica la firma RS256 y la expiración de cada bearer token, y responde `401` cuando la verificación falla. Tiene precedencia sobre `AUTH_JWT_VERIFY_CERT_PATH`. | — | No |
| `AUTH_JWT_VERIFY_CERT_PATH` | Ruta de un archivo con el mismo contenido. Matcher lo lee solo cuando `AUTH_JWT_VERIFY_CERT` está vacía. | — | No |
| `AUTH_JWT_ISSUER` | Con una clave cargada, Matcher responde `401` a un token cuyo claim `iss` difiere de este valor. | — | No |

## Tenancy

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `DEFAULT_TENANT_ID` | ID del tenant en el modo single-tenant. Debe ser un UUID. | `11111111-1111-1111-1111-111111111111` | No |
| `DEFAULT_TENANT_SLUG` | Slug del tenant en el modo single-tenant. | `default` | No |
| `MULTI_TENANT_ENABLED` | Habilita el modo multi-tenant mediante Tenant Manager. Exige el proveedor `plugin-auth`, un entorno `staging` o `production`, `MULTI_TENANT_URL` y `MULTI_TENANT_SERVICE_API_KEY`. | `false` | No |
| `ENVIRONMENT_NAME` | Nombre del entorno que verifica el modo multi-tenant. Si no está definida, Matcher usa `ENV_NAME`. | — | No |
| `MULTI_TENANT_URL` | Origen de Tenant Manager: `http` o `https`, sin ruta y sin información de usuario. | — | Modo multi-tenant. Producción: `https` |
| `MULTI_TENANT_SERVICE_API_KEY` | Clave de API que Matcher envía a Tenant Manager. Sensible. | — | Modo multi-tenant |
| `MULTI_TENANT_ENVIRONMENT` | Nombre del entorno multi-tenant. Si no está definida, Matcher usa `ENV_NAME`. El modo multi-tenant necesita una de las dos. | — | No |
| `MULTI_TENANT_ALLOW_INSECURE_HTTP` | Permite un origen `http` para Tenant Manager. | `false` | No |
| `MULTI_TENANT_REDIS_HOST` | Host del Redis que transporta los eventos de ciclo de vida de los tenants. | — | No |
| `MULTI_TENANT_REDIS_PORT` | Puerto de ese Redis. | `6379` | No |
| `MULTI_TENANT_REDIS_PASSWORD` | Contraseña de ese Redis. Sensible. | — | No |
| `MULTI_TENANT_REDIS_TLS` | Usa TLS en ese Redis. | `false` | No |
| `MULTI_TENANT_MAX_TENANT_POOLS` | Número máximo de pools de conexión de tenants que Matcher mantiene abiertos. | `100` | No |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Segundos hasta que Matcher cierra un pool de tenant inactivo. | `300` | No |
| `MULTI_TENANT_TIMEOUT` | Timeout, en segundos, de una llamada a Tenant Manager. | `30` | No |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | Llamadas fallidas a Tenant Manager antes de que se abra el circuit breaker. | `5` | No |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | Segundos que el circuit breaker permanece abierto. | `30` | No |
| `MULTI_TENANT_CACHE_TTL_SEC` | Segundos que Matcher guarda en cache la configuración de un tenant. | `120` | No |
| `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | Segundos entre verificaciones de la configuración de conexión de los tenants. | `30` | No |
| `MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT` | Conexiones abiertas por base de datos de tenant. El valor es a la vez el predeterminado y el tope. `0` mantiene los valores predeterminados de la biblioteca. | `0` | No |
| `MULTI_TENANT_MAX_IDLE_CONNS_PER_TENANT` | Conexiones inactivas por base de datos de tenant, con la misma regla. | `0` | No |

## PostgreSQL

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `POSTGRES_HOST` | Host de la base de datos primaria. | `localhost` | No |
| `POSTGRES_PORT` | Puerto de la base de datos primaria. | `5432` | No |
| `POSTGRES_USER` | Usuario de la base de datos primaria. | `matcher` | No |
| `POSTGRES_PASSWORD` | Contraseña de la base de datos primaria. Sensible. El valor predeterminado es un valor de desarrollo. | Valor de desarrollo | Producción: no vacía y distinta de un valor de desarrollo |
| `POSTGRES_DB` | Nombre de la base de datos. | `matcher` | No |
| `POSTGRES_SSLMODE` | `sslmode` de PostgreSQL. | `disable` | No |
| `POSTGRES_TLS_REQUIRED` | Rechaza el inicio cuando `POSTGRES_SSLMODE` es `disable`. | `false` | No |
| `POSTGRES_REPLICA_HOST` | Host de la réplica de lectura. Sin él, Matcher ignora las demás variables de réplica. | — | No |
| `POSTGRES_REPLICA_PORT`, `POSTGRES_REPLICA_USER`, `POSTGRES_REPLICA_PASSWORD`, `POSTGRES_REPLICA_DB`, `POSTGRES_REPLICA_SSLMODE` | Conexión de la réplica de lectura. Cada una usa el valor de la primaria cuando no está definida. La contraseña es sensible. | Valor de la primaria | No |
| `POSTGRES_REPLICA_TLS_REQUIRED` | Misma regla que `POSTGRES_TLS_REQUIRED`, para la réplica. | `false` | No |
| `POSTGRES_MAX_OPEN_CONNS` | Máximo de conexiones abiertas. | `25` | No |
| `POSTGRES_MAX_IDLE_CONNS` | Máximo de conexiones inactivas. | `5` | No |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | Minutos hasta que Matcher reemplaza una conexión. | `30` | No |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | Minutos hasta que Matcher cierra una conexión inactiva. | `5` | No |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | Timeout de conexión, en segundos. | `10` | No |
| `POSTGRES_QUERY_TIMEOUT_SEC` | Timeout de consulta, en segundos. `0` usa el valor predeterminado. | `30` | No |
| `SYSTEMPLANE_POSTGRES_DSN` | Cadena de conexión del almacenamiento de Systemplane. Si no está definida, Matcher la arma a partir de la conexión primaria. Sensible. | — | No |

## Redis

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `REDIS_HOST` | Dirección de Redis. Una dirección selecciona el modo standalone. Una lista CSV selecciona el modo Cluster. Con `REDIS_MASTER_NAME`, la lista indica nodos Sentinel. | `localhost:6379` | No |
| `REDIS_MASTER_NAME` | Nombre del master en Sentinel. | — | No |
| `REDIS_PASSWORD` | Contraseña de Redis. Sensible. | — | Producción |
| `REDIS_DB` | Número de base de datos de Redis. | `0` | No |
| `REDIS_TLS` | Usa TLS en Redis. | `false` | No |
| `REDIS_TLS_REQUIRED` | Rechaza el inicio cuando `REDIS_TLS` es `false`. | `false` | No |
| `REDIS_CA_CERT` | Certificado de la CA para el TLS de Redis. | — | No |
| `REDIS_POOL_SIZE` | Tamaño del pool de conexiones. | `10` | No |
| `REDIS_MIN_IDLE_CONNS` | Mínimo de conexiones inactivas. | `2` | No |
| `REDIS_READ_TIMEOUT_MS` | Timeout de lectura, en milisegundos. | `3000` | No |
| `REDIS_WRITE_TIMEOUT_MS` | Timeout de escritura, en milisegundos. | `3000` | No |
| `REDIS_DIAL_TIMEOUT_MS` | Timeout de marcado, en milisegundos. | `5000` | No |

## RabbitMQ

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `RABBITMQ_URI` | Esquema de conexión: `amqp` o `amqps`. | `amqp` | No |
| `RABBITMQ_HOST` | Host del broker. | `localhost` | No |
| `RABBITMQ_PORT` | Puerto del broker. | `5672` | No |
| `RABBITMQ_USER` | Usuario del broker. | `matcher_admin` | Producción: distinto de `guest` |
| `RABBITMQ_PASSWORD` | Contraseña del broker. Sensible. El valor predeterminado es un valor de desarrollo. | Valor de desarrollo | Producción: distinta de `guest` y de un valor de desarrollo |
| `RABBITMQ_VHOST` | Virtual host. | `/` | No |
| `RABBITMQ_HEALTH_URL` | URL de la API de administración para el health check. | `http://localhost:15672` | No |
| `RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK` | Permite una URL `http` de health check. | `false` | Producción: `false` |
| `RABBITMQ_TLS_REQUIRED` | Rechaza el inicio cuando `RABBITMQ_URI` no es `amqps`. | `false` | No |

## Almacenamiento de objetos

Matcher escribe los archivos de exportación en este almacenamiento compatible con S3.

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `OBJECT_STORAGE_ENDPOINT` | URL del endpoint de almacenamiento. | `http://localhost:8333` | Con el worker de exportación o de limpieza habilitado. Producción: `https` |
| `OBJECT_STORAGE_REGION` | Región del almacenamiento. | `us-east-1` | No |
| `OBJECT_STORAGE_BUCKET` | Bucket de los archivos de exportación. | `matcher-exports` | Con el worker de exportación o de limpieza habilitado |
| `OBJECT_STORAGE_ACCESS_KEY_ID` | ID de la clave de acceso estática. Sin las dos claves estáticas, Matcher usa la cadena predeterminada de credenciales de AWS. | — | No |
| `OBJECT_STORAGE_SECRET_ACCESS_KEY` | Clave secreta de acceso estática. Sensible. | — | No |
| `OBJECT_STORAGE_USE_PATH_STYLE` | Usa direcciones de bucket con estilo de ruta. | `true` | No |
| `OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINT` | Permite un endpoint `http`. Matcher acepta `true` solo cuando `ENV_NAME` es `development`, `dev`, `local` o `test`. | `false` | No |
| `OBJECT_STORAGE_TLS_REQUIRED` | Rechaza el inicio cuando el endpoint no es `https`. | `false` | No |

## Timeouts de infraestructura

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `INFRA_CONNECT_TIMEOUT_SEC` | Total de segundos que Matcher permite para las conexiones con sus dependencias al iniciar. El valor debe ser al menos `1`, y Matcher lo limita a `300`. | `30` | No |
| `HEALTH_CHECK_TIMEOUT_MS` | Timeout, en milisegundos, de cada verificación de readiness. Prevalece sobre `HEALTH_CHECK_TIMEOUT_SEC`. | `800` | No |
| `HEALTH_CHECK_TIMEOUT_SEC` | Timeout, en segundos, de cada verificación de readiness. Matcher la usa solo cuando `HEALTH_CHECK_TIMEOUT_MS` es `0`. | `5` | No |

## Telemetría

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Habilita la exportación de OpenTelemetry. | `false` | No |
| `OTEL_RESOURCE_SERVICE_NAME` | Nombre del servicio en la telemetría. | `matcher` | No |
| `OTEL_LIBRARY_NAME` | Nombre de la biblioteca de instrumentación. | `github.com/LerianStudio/matcher` | No |
| `OTEL_RESOURCE_SERVICE_VERSION` | Versión del servicio en la telemetría. | `1.1.0` | No |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Entorno de despliegue en la telemetría. Con la telemetría habilitada, debe ser `development`, `staging` o `production`. | `development` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del colector OTLP. | `localhost:4317` | No |
| `OTEL_TRACES_SAMPLER` | Sampler de trazas, que lee el SDK de OpenTelemetry. | `parentbased_always_on` | No |
| `OTEL_TRACES_SAMPLER_ARG` | Argumento del sampler, como una proporción. | — | No |
| `ALLOW_INSECURE_OTEL` | Permite un endpoint de colector sin cifrado cuando el entorno de despliegue es `production`. Sin ella, Matcher funciona sin telemetría en ese caso. | — | No |
| `DB_METRICS_INTERVAL_SEC` | Segundos entre muestras de las métricas del pool de la base de datos. | `15` | No |

## Rate limits

Cada límite es un número máximo de solicitudes por ventana. Un máximo debe estar entre `1` y `1000000`. Una ventana debe estar entre `1` y `86400` segundos.

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `RATE_LIMIT_ENABLED` | Habilita los límites de esta sección. Cuando no está definida o es `false`, Matcher no aplica ninguno de ellos, sea cual sea el contenido del documento de runtime `rate_limit`. | `false` | No |
| `ALLOW_RATELIMIT_FAIL_OPEN` | Comportamiento cuando Matcher no puede actualizar un contador de límite en Redis. Con `true`, la solicitud sigue sin límite. Con `false`, Matcher responde `503`. | `false` | No |
| `RATE_LIMIT_REDIS_TIMEOUT_MS` | Milisegundos que puede tardar una actualización de contador en Redis antes de que la solicitud deje de esperarla. | `500` | No |
| `RATE_LIMIT_MAX` | Límite general de la API. | `100` | No |
| `RATE_LIMIT_EXPIRY_SEC` | Ventana general de la API, en segundos. | `60` | No |
| `EXPORT_RATE_LIMIT_MAX` | Límite de las solicitudes de exportación. | `10` | No |
| `EXPORT_RATE_LIMIT_EXPIRY_SEC` | Ventana de exportación, en segundos. | `60` | No |
| `DISPATCH_RATE_LIMIT_MAX` | Límite de las solicitudes de despacho de excepciones. | `50` | No |
| `DISPATCH_RATE_LIMIT_EXPIRY_SEC` | Ventana de despacho, en segundos. | `60` | No |
| `ADMIN_RATE_LIMIT_MAX` | Límite de las rutas de administración `/system`. | `30` | No |
| `ADMIN_RATE_LIMIT_EXPIRY_SEC` | Ventana de administración, en segundos. | `60` | No |

## Idempotencia

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `IDEMPOTENCY_HMAC_SECRET` | Secreto usado como clave de los registros de idempotencia. Debe tener al menos 32 bytes en todos los modos. Un secreto nuevo deja sin disponibilidad los replays en cache anteriores. Sensible. | — | `saas`, `byoc` |
| `IDEMPOTENCY_RETIRED_HMAC_SECRET` | Secreto de la versión anterior. Defínelo cuando cambies `IDEMPOTENCY_HMAC_SECRET` con el puente de transición habilitado. Sensible. | — | No |
| `IDEMPOTENCY_CUTOVER_BRIDGE` | Lee también los registros de idempotencia de la versión anterior, para que un reintento durante una actualización no se ejecute dos veces. | `true` | No |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | Segundos hasta que una solicitud fallida puede volver a ejecutarse con la misma clave. | `300` | No |
| `IDEMPOTENCY_SUCCESS_TTL_HOURS` | Horas que Matcher guarda una respuesta exitosa para replay. | `168` | No |

## Outbox

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `OUTBOX_DISPATCH_INTERVAL_SEC` | Segundos entre ejecuciones de despacho del outbox. | `2` | No |
| `OUTBOX_RETRY_WINDOW_SEC` | Segundos hasta que Matcher reintenta un evento fallido del outbox. | `300` | No |

## Ingesta

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `INGESTION_MAX_UPLOAD_BYTES` | Tamaño máximo de carga, en bytes. El límite se aplica al cuerpo multipart completo. | `1073741824` | No |
| `DEDUPE_TTL_SEC` | Segundos que Matcher guarda una clave de detección de duplicados en Redis. | `3600` | No |

## Coincidencias

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `MATCH_RUN_WORKER_ENABLED` | Ejecuta el worker que procesa las ejecuciones de coincidencia. | `true` | No |
| `MATCH_RUN_WORKER_POLL_INTERVAL_SEC` | Segundos entre consultas de nuevas ejecuciones de coincidencia. | `3` | No |
| `MATCHING_CANDIDATE_BATCH_SIZE` | Candidatos por lote de coincidencia. Matcher lo limita a `100000`. | `10000` | No |
| `SCHEDULER_INTERVAL_SEC` | Segundos entre verificaciones de programaciones vencidas. | `60` | No |
| `BINDING_SCHEDULER_ENABLED` | Ejecuta las extracciones programadas de las fuentes vinculadas. | `false` | No |
| `BINDING_SCHEDULER_INTERVAL_SEC` | Segundos entre verificaciones de extracciones vencidas. | `60` | No |

## Excepciones y webhooks

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `EXCEPTION_DISPUTE_LOCK_TIMEOUT_MS` | Milisegundos que Matcher espera el bloqueo de una disputa. | `2000` | No |
| `WEBHOOK_TIMEOUT_SEC` | Timeout predeterminado, en segundos, de una llamada de webhook saliente. Matcher lo limita a `300`. | `30` | No |
| `CALLBACK_RATE_LIMIT_PER_MIN` | Callbacks por minuto que Matcher acepta de un sistema externo. | `60` | No |

## Exportación y limpieza

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `EXPORT_WORKER_ENABLED` | Ejecuta el worker que escribe los archivos de exportación. | `true` | No |
| `EXPORT_WORKER_POLL_INTERVAL_SEC` | Segundos entre consultas de nuevos jobs de exportación. | `5` | No |
| `EXPORT_WORKER_PAGE_SIZE` | Filas por página de exportación. | `1000` | No |
| `EXPORT_PRESIGN_EXPIRY_SEC` | Segundos que un enlace de descarga de una exportación sigue válido. Matcher lo limita a `604800`. | `3600` | No |
| `CLEANUP_WORKER_ENABLED` | Ejecuta el worker que elimina los archivos de exportación vencidos. | `true` | No |
| `CLEANUP_WORKER_INTERVAL_SEC` | Segundos entre ejecuciones de limpieza. | `3600` | No |
| `CLEANUP_WORKER_BATCH_SIZE` | Archivos por lote de limpieza. | `100` | No |
| `CLEANUP_WORKER_GRACE_PERIOD_SEC` | Segundos después del vencimiento antes de que la limpieza elimine un archivo. | `3600` | No |

## Archivado

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `ARCHIVAL_WORKER_ENABLED` | Ejecuta el worker que archiva las particiones antiguas del log de auditoría. | `false` | No |
| `ARCHIVAL_WORKER_INTERVAL_HOURS` | Horas entre ejecuciones de archivado. | `24` | No |
| `ARCHIVAL_HOT_RETENTION_DAYS` | Retención caliente, en días. | `90` | No |
| `ARCHIVAL_WARM_RETENTION_MONTHS` | Meses hasta que una partición pasa al almacenamiento frío de archivo. Con el worker habilitado, debe ser mayor que la retención caliente dividida por 30. | `24` | No |
| `ARCHIVAL_COLD_RETENTION_MONTHS` | Retención fría, en meses. Con el worker habilitado, debe ser al menos la retención templada. | `84` | No |
| `ARCHIVAL_BATCH_SIZE` | Filas por lote de archivado. | `5000` | No |
| `ARCHIVAL_STORAGE_BUCKET` | Bucket de los archivos archivados. | `matcher-archives` | Con el worker de archivado habilitado |
| `ARCHIVAL_STORAGE_CLASS` | Clase de almacenamiento: `STANDARD`, `STANDARD_IA`, `ONEZONE_IA`, `INTELLIGENT_TIERING`, `GLACIER_IR`, `GLACIER` o `DEEP_ARCHIVE`. | `GLACIER` | No |
| `ARCHIVAL_PARTITION_LOOKAHEAD` | Particiones mensuales futuras que Matcher crea por adelantado. | `3` | No |
| `ARCHIVAL_PRESIGN_EXPIRY_SEC` | Segundos que un enlace de descarga de un archivo archivado sigue válido. | `3600` | No |

Con el worker de archivado habilitado, la retención caliente, el tamaño del lote y la anticipación deben ser cada uno al menos `1`.

## Gobernanza

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `ACTOR_PII_ENCRYPTION_KEY` | Clave que cifra los nombres y las direcciones de correo electrónico de los actores. Base64 estándar de exactamente 32 bytes. Cuando `ENV_NAME` no es `development`, `dev`, `local` ni `test`, los mapeos de actores la necesitan. Sensible. | — | No |

## Motor de extracción

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `APP_ENC_KEY` | Clave maestra que cifra las credenciales de conexión almacenadas. Base64 estándar de al menos 32 bytes. Fuera de producción, Matcher usa una clave temporal cuando no está definida. Sensible. | — | Producción |
| `FETCHER_DISCOVERY_INTERVAL_SEC` | Segundos entre ejecuciones de descubrimiento en el motor de extracción. | `60` | No |
| `FETCHER_SCHEMA_CACHE_TTL_SEC` | Segundos que Matcher guarda en cache un schema descubierto. | `300` | No |
| `FETCHER_EXTRACTION_TIMEOUT_SEC` | Segundos que Matcher espera una extracción. | `600` | No |
| `FETCHER_MAX_EXTRACTION_BYTES` | Tamaño máximo, en bytes, del resultado de una extracción. | `2147483648` | No |

## Conectores

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `PAGBANK_CONNECTOR_BASE_URL` | URL base de la API de PagBank. | `https://api.pagseguro.com` | No |
| `STRIPE_CONNECTOR_BASE_URL` | URL base de la API de Stripe. | `https://api.stripe.com` | No |
| `STRIPE_CONNECTOR_FILES_BASE_URL` | URL base de la API de archivos de Stripe. | `https://files.stripe.com` | No |
| `PIX_CONNECTOR_BASE_URL` | URL base de la API Pix. Sin ella, el conector Pix falla en el primer uso. | — | Para el conector Pix |
| `PLUGGY_CONNECTOR_BASE_URL` | URL base de la API de Pluggy. | `https://api.pluggy.ai` | No |
| `PLUGGY_WEBHOOK_HMAC_SECRET` | Secreto que verifica los webhooks de Pluggy. Prevalece sobre la lista de IP. Sensible. | — | No |
| `PLUGGY_WEBHOOK_ALLOWED_IPS` | IP de origen que Matcher acepta para los webhooks de Pluggy (CSV). | — | No |
| `BELVO_CONNECTOR_BASE_URL` | URL base de la API de Belvo. | `https://api.belvo.com` | No |
| `BELVO_WEBHOOK_HMAC_SECRET` | Secreto que verifica los webhooks de Belvo. Prevalece sobre la lista de IP. Sensible. | — | No |
| `BELVO_WEBHOOK_ALLOWED_IPS` | IP de origen que Matcher acepta para los webhooks de Belvo (CSV). | — | No |

## Funciones de IA

Cada función tiene un control de habilitación, una clave de API y un modelo. La extracción de documentos y las sugerencias de reglas también necesitan el consentimiento en el documento de runtime `ai_gates`. De forma predeterminada, ese consentimiento está deshabilitado.

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `ADVISOR_ENABLED` | Habilita el asistente de mapeo. | `false` | No |
| `ADVISOR_ANTHROPIC_API_KEY` | Clave de API del proveedor de modelo de lenguaje del asistente de mapeo. Sensible. | — | Con el asistente habilitado |
| `ADVISOR_MODEL` | Modelo del asistente de mapeo. | `claude-sonnet-4-6` | No |
| `DOC_EXTRACTION_ENABLED` | Habilita la extracción de documentos. | `false` | No |
| `DOC_EXTRACTION_ANTHROPIC_API_KEY` | Clave de API de la extracción de documentos. Sensible. | — | Con la extracción de documentos habilitada |
| `DOC_EXTRACTION_MODEL` | Modelo de la extracción de documentos. | `claude-sonnet-4-6` | No |
| `RULE_ADVISOR_ENABLED` | Habilita las sugerencias de reglas. | `false` | No |
| `RULE_ADVISOR_ANTHROPIC_API_KEY` | Clave de API de las sugerencias de reglas. Sensible. | — | Con las sugerencias de reglas habilitadas |
| `RULE_ADVISOR_MODEL` | Modelo de las sugerencias de reglas. | `claude-sonnet-4-6` | No |

## Streaming de eventos

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_ENABLED` | Publica los eventos de Matcher en Kafka. | `false` | No |
| `STREAMING_BROKERS` | Brokers de Kafka (CSV). | — | Con el streaming habilitado |
| `STREAMING_CLIENT_ID` | Client ID de Kafka. | `primary` | No |
| `STREAMING_CLOUDEVENTS_SOURCE` | Nombre del origen en cada evento. También da nombre al tema `lerian.streaming.<source>`. Un solo segmento en minúsculas que coincida con `^[a-z0-9][a-z0-9_-]*$`. Matcher verifica el formato incluso con el streaming deshabilitado. | — | Con el streaming habilitado |
| `STREAMING_TLS_ENABLED` | Usa TLS en Kafka. | `false` | Producción, con el streaming habilitado |
| `STREAMING_TLS_CA_CERT` | Certificado de la CA para el TLS de Kafka. | — | No |
| `STREAMING_SASL_MECHANISM` | Mecanismo SASL: `PLAIN`, `SCRAM-SHA-256` o `SCRAM-SHA-512`. | — | No |
| `STREAMING_SASL_USERNAME` | Usuario SASL. | — | Con un mecanismo SASL |
| `STREAMING_SASL_PASSWORD` | Contraseña SASL. Sensible. | — | Con un mecanismo SASL |
| `STREAMING_SASL_ALLOW_PLAINTEXT` | Permite SASL sin TLS. | `false` | No |
| `STREAMING_CB_FAILURE_RATIO` | Proporción de fallas que abre el circuit breaker de publicación. | `0.5` | No |
| `STREAMING_CB_MIN_REQUESTS` | Solicitudes que el breaker necesita antes de poder abrirse. | `10` | No |
| `STREAMING_CB_TIMEOUT_S` | Segundos que el breaker permanece abierto. | `30` | No |
| `STREAMING_CLOSE_TIMEOUT_S` | Segundos que Matcher espera para enviar los eventos pendientes cuando se detiene. | `30` | No |
| `STREAMING_TOPIC_AUTO_PROVISION` | Crea el tema al iniciar cuando no existe. | `true` | No |
| `STREAMING_TOPIC_PARTITIONS` | Particiones de un tema creado. `-1` usa el valor predeterminado del broker. | `-1` | No |
| `STREAMING_TOPIC_REPLICATION_FACTOR` | Factor de replicación de un tema creado. `-1` usa el valor predeterminado del broker. | `-1` | No |

## Documentos de runtime

Matcher mantiene once documentos de runtime en el namespace `matcher` de Systemplane, en `/system`. Las variables de abajo definen el valor inicial de cada documento. Después de que Lerian escribe un documento mediante Systemplane, el documento almacenado prevalece sobre sus variables. El documento `rate_limit` no puede habilitar los límites mientras `RATE_LIMIT_ENABLED` no está definida o es `false`.

| Documento | Variables |
| - | - |
| `http` | `HTTP_BODY_LIMIT_BYTES`, `CORS_ALLOWED_ORIGINS`, `CORS_ALLOWED_METHODS`, `CORS_ALLOWED_HEADERS`, `POSTGRES_QUERY_TIMEOUT_SEC`, `HEALTH_CHECK_TIMEOUT_SEC`, `HEALTH_CHECK_TIMEOUT_MS` |
| `rate_limit` | `RATE_LIMIT_ENABLED`, `RATE_LIMIT_MAX`, `RATE_LIMIT_EXPIRY_SEC`, `EXPORT_RATE_LIMIT_MAX`, `EXPORT_RATE_LIMIT_EXPIRY_SEC`, `DISPATCH_RATE_LIMIT_MAX`, `DISPATCH_RATE_LIMIT_EXPIRY_SEC`, `ADMIN_RATE_LIMIT_MAX`, `ADMIN_RATE_LIMIT_EXPIRY_SEC` |
| `ingestion` | `IDEMPOTENCY_RETRY_WINDOW_SEC`, `IDEMPOTENCY_SUCCESS_TTL_HOURS`, `INGESTION_MAX_UPLOAD_BYTES`, `DEDUPE_TTL_SEC` |
| `fetcher` | `FETCHER_DISCOVERY_INTERVAL_SEC`, `FETCHER_SCHEMA_CACHE_TTL_SEC`, `FETCHER_EXTRACTION_TIMEOUT_SEC`, `FETCHER_MAX_EXTRACTION_BYTES` |
| `exception` | `EXCEPTION_DISPUTE_LOCK_TIMEOUT_MS`, `WEBHOOK_TIMEOUT_SEC`, `CALLBACK_RATE_LIMIT_PER_MIN` |
| `matching` | `MATCH_RUN_WORKER_ENABLED`, `MATCH_RUN_WORKER_POLL_INTERVAL_SEC`, `SCHEDULER_INTERVAL_SEC` |
| `reporting` | `EXPORT_WORKER_ENABLED`, `EXPORT_WORKER_POLL_INTERVAL_SEC`, `EXPORT_WORKER_PAGE_SIZE`, `EXPORT_PRESIGN_EXPIRY_SEC`, `CLEANUP_WORKER_ENABLED`, `CLEANUP_WORKER_INTERVAL_SEC`, `CLEANUP_WORKER_BATCH_SIZE`, `CLEANUP_WORKER_GRACE_PERIOD_SEC` |
| `archival` | `ARCHIVAL_WORKER_ENABLED`, `ARCHIVAL_WORKER_INTERVAL_HOURS`, `ARCHIVAL_HOT_RETENTION_DAYS`, `ARCHIVAL_WARM_RETENTION_MONTHS`, `ARCHIVAL_COLD_RETENTION_MONTHS`, `ARCHIVAL_BATCH_SIZE`, `ARCHIVAL_STORAGE_BUCKET`, `ARCHIVAL_STORAGE_CLASS`, `ARCHIVAL_PARTITION_LOOKAHEAD`, `ARCHIVAL_PRESIGN_EXPIRY_SEC` |
| `object_storage` | `OBJECT_STORAGE_ENDPOINT`, `OBJECT_STORAGE_REGION`, `OBJECT_STORAGE_BUCKET`, `OBJECT_STORAGE_USE_PATH_STYLE`, `OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINT` |
| `tenancy` | `MULTI_TENANT_URL`, `MULTI_TENANT_MAX_TENANT_POOLS`, `MULTI_TENANT_IDLE_TIMEOUT_SEC`, `MULTI_TENANT_TIMEOUT`, `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`, `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC`, `MULTI_TENANT_CACHE_TTL_SEC`, `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` |
| `ai_gates` | Ninguna variable. El documento guarda los consentimientos de IA, denegados de forma predeterminada. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.