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

# Variáveis de ambiente

> Referência das variáveis de ambiente que configuram o Matcher, agrupadas como o código as agrupa, com cada padrão e as verificações que o Matcher aplica na inicialização.

Esta referência lista as variáveis de ambiente que configuram o **Matcher**, o motor de conciliação. A Lerian define esses valores quando instala ou atualiza o Matcher. Use esta página para saber o que cada configuração faz, qual é o seu padrão e o que o Matcher verifica na inicialização.

Quando uma variável obrigatória está ausente ou é inválida, o Matcher não inicia. Com `ENV_NAME=production`, o Matcher aplica verificações extras. A coluna **Obrigatório** indica cada uma como "Produção".

Algumas variáveis definem apenas o valor inicial de um documento de runtime. A Lerian pode alterar esses documentos em um Matcher em execução por meio do [Systemplane](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md). A seção [documentos de runtime](#runtime-documents) lista esses documentos.

## Aplicação

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ENV_NAME` | Nome do ambiente. Com `production`, o Matcher desabilita o Swagger e recusa um endpoint inseguro de armazenamento de objetos. Ele também aplica as verificações marcadas como "Produção" nesta página. | `development` | Não |
| `LOG_LEVEL` | Nível de log: `debug`, `info`, `warn`, `error` ou `fatal`. Qualquer outro valor interrompe a inicialização. | `info` | Não |
| `DEPLOYMENT_MODE` | Modelo de deploy: `saas`, `byoc` ou `local`, em maiúsculas ou minúsculas. Com `saas` ou `byoc`, o Matcher exige `IDEMPOTENCY_HMAC_SECRET`, recusa um valor `http` em `PUBLIC_BASE_SCHEMES` e recusa um `PUBLIC_BASE_HOST` malformado. A resposta de `/readyz` também informa o valor. | — | Sim |
| `SHUTDOWN_GRACE_PERIOD_SEC` | Segundos que o Matcher espera o trabalho em andamento terminar quando ele para. | `12` | Não |
| `ALLOW_INSECURE_TLS` | Permite conexões sem TLS com PostgreSQL, Redis e RabbitMQ. Sem `true`, o Matcher recusa essas conexões. Os padrões desta página não usam TLS. | — | Não |

## Servidor HTTP

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `SERVER_ADDRESS` | Endereço de bind da API. | `:4018` | Não |
| `HTTP_READ_TIMEOUT` | Tempo máximo para ler uma requisição, como uma duração do tipo `15m`. Também cobre uploads de arquivo em streaming. | `15m` | Não |
| `HTTP_BODY_LIMIT_BYTES` | Tamanho máximo do corpo, em bytes, para as rotas que armazenam a requisição inteira em buffer. | `104857600` | Não |
| `CORS_ALLOWED_ORIGINS` | Origens CORS permitidas (CSV). | `http://localhost:3000` | Produção: pelo menos uma origem, e não `*` |
| `CORS_ALLOWED_METHODS` | Métodos CORS permitidos (CSV). | `GET,POST,PUT,PATCH,DELETE,OPTIONS` | Não |
| `CORS_ALLOWED_HEADERS` | Headers CORS permitidos (CSV). | `Origin,Content-Type,Accept,Authorization,X-Request-ID` | Não |
| `SERVER_TLS_CERT_FILE` | Caminho do certificado TLS. Defina junto com `SERVER_TLS_KEY_FILE`. Um certificado habilita o HSTS. | — | Não |
| `SERVER_TLS_KEY_FILE` | Caminho da chave privada TLS. Defina junto com `SERVER_TLS_CERT_FILE`. | — | Não |
| `TLS_TERMINATED_UPSTREAM` | Defina como `true` quando um load balancer termina o TLS na frente do Matcher. Habilita o HSTS. | `false` | Não |
| `TRUSTED_PROXIES` | CIDRs de proxies confiáveis (CSV) para resolver o IP do cliente. O Matcher recusa `*`, `0.0.0.0/0` e `::/0`. | — | Produção |
| `PUBLIC_BASE_HOST` | `host[:port]` público que o Matcher coloca nas URLs de webhook e de callback que emite. Use o host puro, sem esquema nem caminho. Quando vazio, o Matcher usa `SERVER_ADDRESS`. | — | Não |
| `PUBLIC_BASE_SCHEMES` | Esquema dessas URLs públicas. | `https` | Não |
| `SWAGGER_ENABLED` | Serve a interface do Swagger. `ENV_NAME=production` a desabilita. | `false` | Não |

## Autenticação

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Habilita a autenticação do Access Manager. O Matcher também aceita o nome antigo `AUTH_ENABLED`. Quando os dois nomes têm valores diferentes, o Matcher se recusa a iniciar. | `false` | Não |
| `PLUGIN_AUTH_ADDRESS` | Endereço do Access Manager. O Matcher também aceita o nome antigo `AUTH_SERVICE_ADDRESS`, com a mesma regra de conflito. | — | Quando o provedor é `plugin-auth` |
| `AUTH_PROVIDER` | Provedor de autenticação: `plugin-auth` ou `disabled`. Quando não definido, `PLUGIN_AUTH_ENABLED` o seleciona. Um valor explícito prevalece. Qualquer outro valor interrompe a inicialização. | — | Não |
| `AUTH_REQUIRED` | Com `true` e a autenticação desabilitada, cada operação em `/v1` que precisa de uma permissão responde `503`. | `false` | Não |
| `AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED` | Com `true` e a autenticação desabilitada, cada operação em `/v1` que precisa de uma permissão ainda exige um bearer token e responde `401` sem ele. O Matcher não chama o Access Manager para essas requisições. Sem `AUTH_JWT_VERIFY_CERT` ou `AUTH_JWT_VERIFY_CERT_PATH`, o Matcher não verifica a assinatura do token. | `false` | Não |
| `AUTH_M2M_PRODUCT_FORWARD_ENABLED` | Com `true`, o Matcher também envia o nome do seu produto ao Access Manager quando verifica um token de aplicação. | `false` | Não |
| `AUTH_TIMEOUT` | Tempo limite da verificação no Access Manager de uma requisição, com as novas tentativas incluídas, como uma duração do tipo `5s`. | `30s` | Não |
| `AUTH_CACHE_TTL` | Tempo que o Matcher guarda cada decisão do Access Manager, como uma duração do tipo `60s`. Uma mudança de permissão pode levar esse tempo para valer. Quando não definida, o Matcher não guarda nenhuma decisão. | — | Não |
| `AUTH_BREAKER_ENABLED` | Habilita um circuit breaker nas chamadas ao Access Manager. Depois de 5 chamadas seguidas com falha, ele interrompe as chamadas por 30 segundos. Nesse intervalo, o Matcher recusa cada requisição que não tem uma aprovação em cache. | `false` | Não |
| `AUTH_RETRY_MAX` | Máximo de novas tentativas de uma chamada ao Access Manager que falha sem uma decisão. `0` desabilita as novas tentativas. | `0` | Não |
| `AUTH_JWT_VERIFY_CERT` | Uma ou mais chaves públicas RSA ou certificados X.509 em PEM, separados por quebras de linha. Com uma chave carregada, o Matcher verifica a assinatura RS256 e a expiração de cada bearer token, e responde `401` quando a verificação falha. Tem precedência sobre `AUTH_JWT_VERIFY_CERT_PATH`. | — | Não |
| `AUTH_JWT_VERIFY_CERT_PATH` | Caminho de um arquivo com o mesmo conteúdo. O Matcher o lê apenas quando `AUTH_JWT_VERIFY_CERT` está vazia. | — | Não |
| `AUTH_JWT_ISSUER` | Com uma chave carregada, o Matcher responde `401` a um token cuja claim `iss` difere deste valor. | — | Não |

## Tenancy

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `DEFAULT_TENANT_ID` | ID do tenant no modo single-tenant. Precisa ser um UUID. | `11111111-1111-1111-1111-111111111111` | Não |
| `DEFAULT_TENANT_SLUG` | Slug do tenant no modo single-tenant. | `default` | Não |
| `MULTI_TENANT_ENABLED` | Habilita o modo multi-tenant por meio do Tenant Manager. Exige o provedor `plugin-auth`, um ambiente `staging` ou `production`, `MULTI_TENANT_URL` e `MULTI_TENANT_SERVICE_API_KEY`. | `false` | Não |
| `ENVIRONMENT_NAME` | Nome do ambiente que o modo multi-tenant verifica. Quando não definido, o Matcher usa `ENV_NAME`. | — | Não |
| `MULTI_TENANT_URL` | Origem do Tenant Manager: `http` ou `https`, sem caminho e sem informação de usuário. | — | Modo multi-tenant. Produção: `https` |
| `MULTI_TENANT_SERVICE_API_KEY` | Chave de API que o Matcher envia ao Tenant Manager. Sensível. | — | Modo multi-tenant |
| `MULTI_TENANT_ENVIRONMENT` | Nome do ambiente multi-tenant. Quando não definido, o Matcher usa `ENV_NAME`. O modo multi-tenant precisa de um dos dois. | — | Não |
| `MULTI_TENANT_ALLOW_INSECURE_HTTP` | Permite uma origem `http` para o Tenant Manager. | `false` | Não |
| `MULTI_TENANT_REDIS_HOST` | Host do Redis que transporta os eventos de ciclo de vida dos tenants. | — | Não |
| `MULTI_TENANT_REDIS_PORT` | Porta desse Redis. | `6379` | Não |
| `MULTI_TENANT_REDIS_PASSWORD` | Senha desse Redis. Sensível. | — | Não |
| `MULTI_TENANT_REDIS_TLS` | Usa TLS nesse Redis. | `false` | Não |
| `MULTI_TENANT_MAX_TENANT_POOLS` | Número máximo de pools de conexão de tenants que o Matcher mantém abertos. | `100` | Não |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Segundos até o Matcher fechar um pool de tenant ocioso. | `300` | Não |
| `MULTI_TENANT_TIMEOUT` | Timeout, em segundos, de uma chamada ao Tenant Manager. | `30` | Não |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | Chamadas ao Tenant Manager com falha até o circuit breaker abrir. | `5` | Não |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | Segundos em que o circuit breaker fica aberto. | `30` | Não |
| `MULTI_TENANT_CACHE_TTL_SEC` | Segundos em que o Matcher mantém em cache a configuração de um tenant. | `120` | Não |
| `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | Segundos entre verificações das configurações de conexão dos tenants. | `30` | Não |
| `MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT` | Conexões abertas por banco de dados de tenant. O valor é ao mesmo tempo o padrão e o teto. `0` mantém os padrões da biblioteca. | `0` | Não |
| `MULTI_TENANT_MAX_IDLE_CONNS_PER_TENANT` | Conexões ociosas por banco de dados de tenant, com a mesma regra. | `0` | Não |

## PostgreSQL

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `POSTGRES_HOST` | Host do banco de dados primário. | `localhost` | Não |
| `POSTGRES_PORT` | Porta do banco de dados primário. | `5432` | Não |
| `POSTGRES_USER` | Usuário do banco de dados primário. | `matcher` | Não |
| `POSTGRES_PASSWORD` | Senha do banco de dados primário. Sensível. O padrão é um valor de desenvolvimento. | Valor de desenvolvimento | Produção: não vazia e diferente de um valor de desenvolvimento |
| `POSTGRES_DB` | Nome do banco de dados. | `matcher` | Não |
| `POSTGRES_SSLMODE` | `sslmode` do PostgreSQL. | `disable` | Não |
| `POSTGRES_TLS_REQUIRED` | Recusa a inicialização quando `POSTGRES_SSLMODE` é `disable`. | `false` | Não |
| `POSTGRES_REPLICA_HOST` | Host da réplica de leitura. Sem ele, o Matcher ignora as outras variáveis de réplica. | — | Não |
| `POSTGRES_REPLICA_PORT`, `POSTGRES_REPLICA_USER`, `POSTGRES_REPLICA_PASSWORD`, `POSTGRES_REPLICA_DB`, `POSTGRES_REPLICA_SSLMODE` | Conexão da réplica de leitura. Cada uma usa o valor do primário quando não definida. A senha é sensível. | Valor do primário | Não |
| `POSTGRES_REPLICA_TLS_REQUIRED` | Mesma regra de `POSTGRES_TLS_REQUIRED`, para a réplica. | `false` | Não |
| `POSTGRES_MAX_OPEN_CONNS` | Máximo de conexões abertas. | `25` | Não |
| `POSTGRES_MAX_IDLE_CONNS` | Máximo de conexões ociosas. | `5` | Não |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | Minutos até o Matcher substituir uma conexão. | `30` | Não |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | Minutos até o Matcher fechar uma conexão ociosa. | `5` | Não |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | Timeout de conexão, em segundos. | `10` | Não |
| `POSTGRES_QUERY_TIMEOUT_SEC` | Timeout de consulta, em segundos. `0` usa o padrão. | `30` | Não |
| `SYSTEMPLANE_POSTGRES_DSN` | String de conexão do armazenamento do Systemplane. Quando não definida, o Matcher a monta a partir da conexão primária. Sensível. | — | Não |

## Redis

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `REDIS_HOST` | Endereço do Redis. Um endereço seleciona o modo standalone. Uma lista CSV seleciona o modo Cluster. Com `REDIS_MASTER_NAME`, a lista indica nós Sentinel. | `localhost:6379` | Não |
| `REDIS_MASTER_NAME` | Nome do master no Sentinel. | — | Não |
| `REDIS_PASSWORD` | Senha do Redis. Sensível. | — | Produção |
| `REDIS_DB` | Número do banco de dados do Redis. | `0` | Não |
| `REDIS_TLS` | Usa TLS no Redis. | `false` | Não |
| `REDIS_TLS_REQUIRED` | Recusa a inicialização quando `REDIS_TLS` é `false`. | `false` | Não |
| `REDIS_CA_CERT` | Certificado da CA para o TLS do Redis. | — | Não |
| `REDIS_POOL_SIZE` | Tamanho do pool de conexões. | `10` | Não |
| `REDIS_MIN_IDLE_CONNS` | Mínimo de conexões ociosas. | `2` | Não |
| `REDIS_READ_TIMEOUT_MS` | Timeout de leitura, em milissegundos. | `3000` | Não |
| `REDIS_WRITE_TIMEOUT_MS` | Timeout de escrita, em milissegundos. | `3000` | Não |
| `REDIS_DIAL_TIMEOUT_MS` | Timeout de discagem, em milissegundos. | `5000` | Não |

## RabbitMQ

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `RABBITMQ_URI` | Esquema de conexão: `amqp` ou `amqps`. | `amqp` | Não |
| `RABBITMQ_HOST` | Host do broker. | `localhost` | Não |
| `RABBITMQ_PORT` | Porta do broker. | `5672` | Não |
| `RABBITMQ_USER` | Usuário do broker. | `matcher_admin` | Produção: diferente de `guest` |
| `RABBITMQ_PASSWORD` | Senha do broker. Sensível. O padrão é um valor de desenvolvimento. | Valor de desenvolvimento | Produção: diferente de `guest` e de um valor de desenvolvimento |
| `RABBITMQ_VHOST` | Virtual host. | `/` | Não |
| `RABBITMQ_HEALTH_URL` | URL da API de gerenciamento para o health check. | `http://localhost:15672` | Não |
| `RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK` | Permite uma URL `http` de health check. | `false` | Produção: `false` |
| `RABBITMQ_TLS_REQUIRED` | Recusa a inicialização quando `RABBITMQ_URI` não é `amqps`. | `false` | Não |

## Armazenamento de objetos

O Matcher grava os arquivos de exportação neste armazenamento compatível com S3.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `OBJECT_STORAGE_ENDPOINT` | URL do endpoint de armazenamento. | `http://localhost:8333` | Com o worker de exportação ou de limpeza habilitado. Produção: `https` |
| `OBJECT_STORAGE_REGION` | Região do armazenamento. | `us-east-1` | Não |
| `OBJECT_STORAGE_BUCKET` | Bucket dos arquivos de exportação. | `matcher-exports` | Com o worker de exportação ou de limpeza habilitado |
| `OBJECT_STORAGE_ACCESS_KEY_ID` | ID da chave de acesso estática. Sem as duas chaves estáticas, o Matcher usa a cadeia padrão de credenciais da AWS. | — | Não |
| `OBJECT_STORAGE_SECRET_ACCESS_KEY` | Chave secreta de acesso estática. Sensível. | — | Não |
| `OBJECT_STORAGE_USE_PATH_STYLE` | Usa endereços de bucket no estilo de caminho. | `true` | Não |
| `OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINT` | Permite um endpoint `http`. O Matcher aceita `true` apenas quando `ENV_NAME` é `development`, `dev`, `local` ou `test`. | `false` | Não |
| `OBJECT_STORAGE_TLS_REQUIRED` | Recusa a inicialização quando o endpoint não é `https`. | `false` | Não |

## Timeouts de infraestrutura

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `INFRA_CONNECT_TIMEOUT_SEC` | Total de segundos que o Matcher permite para as conexões com as dependências na inicialização. O valor precisa ser pelo menos `1`, e o Matcher o limita a `300`. | `30` | Não |
| `HEALTH_CHECK_TIMEOUT_MS` | Timeout, em milissegundos, de cada verificação de readiness. Prevalece sobre `HEALTH_CHECK_TIMEOUT_SEC`. | `800` | Não |
| `HEALTH_CHECK_TIMEOUT_SEC` | Timeout, em segundos, de cada verificação de readiness. O Matcher o usa apenas quando `HEALTH_CHECK_TIMEOUT_MS` é `0`. | `5` | Não |

## Telemetria

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Habilita a exportação do OpenTelemetry. | `false` | Não |
| `OTEL_RESOURCE_SERVICE_NAME` | Nome do serviço na telemetria. | `matcher` | Não |
| `OTEL_LIBRARY_NAME` | Nome da biblioteca de instrumentação. | `github.com/LerianStudio/matcher` | Não |
| `OTEL_RESOURCE_SERVICE_VERSION` | Versão do serviço na telemetria. | `1.1.0` | Não |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Ambiente de deploy na telemetria. Com a telemetria habilitada, precisa ser `development`, `staging` ou `production`. | `development` | Não |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do coletor OTLP. | `localhost:4317` | Não |
| `OTEL_TRACES_SAMPLER` | Sampler de traces, lido pelo SDK do OpenTelemetry. | `parentbased_always_on` | Não |
| `OTEL_TRACES_SAMPLER_ARG` | Argumento do sampler, como uma proporção. | — | Não |
| `ALLOW_INSECURE_OTEL` | Permite um endpoint de coletor sem criptografia quando o ambiente de deploy é `production`. Sem ela, o Matcher roda sem telemetria nesse caso. | — | Não |
| `DB_METRICS_INTERVAL_SEC` | Segundos entre amostras das métricas do pool do banco de dados. | `15` | Não |

## Rate limits

Cada limite é um número máximo de requisições por janela. Um máximo precisa estar entre `1` e `1000000`. Uma janela precisa estar entre `1` e `86400` segundos.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `RATE_LIMIT_ENABLED` | Habilita os limites desta seção. Quando ela não está definida ou é `false`, o Matcher não aplica nenhum deles, seja qual for o conteúdo do documento de runtime `rate_limit`. | `false` | Não |
| `ALLOW_RATELIMIT_FAIL_OPEN` | Comportamento quando o Matcher não consegue atualizar um contador de limite no Redis. Com `true`, a requisição continua sem limite. Com `false`, o Matcher responde `503`. | `false` | Não |
| `RATE_LIMIT_REDIS_TIMEOUT_MS` | Milissegundos que uma atualização de contador no Redis pode levar antes de a requisição parar de esperar por ela. | `500` | Não |
| `RATE_LIMIT_MAX` | Limite geral da API. | `100` | Não |
| `RATE_LIMIT_EXPIRY_SEC` | Janela geral da API, em segundos. | `60` | Não |
| `EXPORT_RATE_LIMIT_MAX` | Limite das requisições de exportação. | `10` | Não |
| `EXPORT_RATE_LIMIT_EXPIRY_SEC` | Janela de exportação, em segundos. | `60` | Não |
| `DISPATCH_RATE_LIMIT_MAX` | Limite das requisições de despacho de exceções. | `50` | Não |
| `DISPATCH_RATE_LIMIT_EXPIRY_SEC` | Janela de despacho, em segundos. | `60` | Não |
| `ADMIN_RATE_LIMIT_MAX` | Limite das rotas administrativas `/system`. | `30` | Não |
| `ADMIN_RATE_LIMIT_EXPIRY_SEC` | Janela administrativa, em segundos. | `60` | Não |

## Idempotência

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `IDEMPOTENCY_HMAC_SECRET` | Segredo usado como chave dos registros de idempotência. Precisa ter pelo menos 32 bytes em todos os modos. Um novo segredo torna indisponíveis os replays em cache anteriores. Sensível. | — | `saas`, `byoc` |
| `IDEMPOTENCY_RETIRED_HMAC_SECRET` | Segredo da versão anterior. Defina quando você trocar `IDEMPOTENCY_HMAC_SECRET` com a ponte de transição habilitada. Sensível. | — | Não |
| `IDEMPOTENCY_CUTOVER_BRIDGE` | Lê também os registros de idempotência da versão anterior, para que uma nova tentativa durante uma atualização não execute duas vezes. | `true` | Não |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | Segundos até uma requisição com falha poder executar de novo com a mesma chave. | `300` | Não |
| `IDEMPOTENCY_SUCCESS_TTL_HOURS` | Horas em que o Matcher guarda uma resposta de sucesso para replay. | `168` | Não |

## Outbox

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `OUTBOX_DISPATCH_INTERVAL_SEC` | Segundos entre execuções de despacho do outbox. | `2` | Não |
| `OUTBOX_RETRY_WINDOW_SEC` | Segundos até o Matcher tentar de novo um evento do outbox com falha. | `300` | Não |

## Ingestão

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `INGESTION_MAX_UPLOAD_BYTES` | Tamanho máximo de upload, em bytes. O limite vale para o corpo multipart inteiro. | `1073741824` | Não |
| `DEDUPE_TTL_SEC` | Segundos em que o Matcher mantém uma chave de detecção de duplicidade no Redis. | `3600` | Não |

## Correspondência

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `MATCH_RUN_WORKER_ENABLED` | Executa o worker que roda as execuções de correspondência. | `true` | Não |
| `MATCH_RUN_WORKER_POLL_INTERVAL_SEC` | Segundos entre consultas por novas execuções de correspondência. | `3` | Não |
| `MATCHING_CANDIDATE_BATCH_SIZE` | Candidatos por lote de correspondência. O Matcher o limita a `100000`. | `10000` | Não |
| `SCHEDULER_INTERVAL_SEC` | Segundos entre verificações de agendamentos vencidos. | `60` | Não |
| `BINDING_SCHEDULER_ENABLED` | Executa as coletas agendadas das fontes vinculadas. | `false` | Não |
| `BINDING_SCHEDULER_INTERVAL_SEC` | Segundos entre verificações de coletas vencidas. | `60` | Não |

## Exceções e webhooks

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `EXCEPTION_DISPUTE_LOCK_TIMEOUT_MS` | Milissegundos que o Matcher espera pelo lock de uma disputa. | `2000` | Não |
| `WEBHOOK_TIMEOUT_SEC` | Timeout padrão, em segundos, de uma chamada de webhook de saída. O Matcher o limita a `300`. | `30` | Não |
| `CALLBACK_RATE_LIMIT_PER_MIN` | Callbacks por minuto que o Matcher aceita de um sistema externo. | `60` | Não |

## Exportação e limpeza

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `EXPORT_WORKER_ENABLED` | Executa o worker que grava os arquivos de exportação. | `true` | Não |
| `EXPORT_WORKER_POLL_INTERVAL_SEC` | Segundos entre consultas por novos jobs de exportação. | `5` | Não |
| `EXPORT_WORKER_PAGE_SIZE` | Linhas por página de exportação. | `1000` | Não |
| `EXPORT_PRESIGN_EXPIRY_SEC` | Segundos em que um link de download de exportação fica válido. O Matcher o limita a `604800`. | `3600` | Não |
| `CLEANUP_WORKER_ENABLED` | Executa o worker que remove os arquivos de exportação expirados. | `true` | Não |
| `CLEANUP_WORKER_INTERVAL_SEC` | Segundos entre execuções de limpeza. | `3600` | Não |
| `CLEANUP_WORKER_BATCH_SIZE` | Arquivos por lote de limpeza. | `100` | Não |
| `CLEANUP_WORKER_GRACE_PERIOD_SEC` | Segundos após a expiração até a limpeza remover um arquivo. | `3600` | Não |

## Arquivamento

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ARCHIVAL_WORKER_ENABLED` | Executa o worker que arquiva as partições antigas do log de auditoria. | `false` | Não |
| `ARCHIVAL_WORKER_INTERVAL_HOURS` | Horas entre execuções de arquivamento. | `24` | Não |
| `ARCHIVAL_HOT_RETENTION_DAYS` | Retenção quente, em dias. | `90` | Não |
| `ARCHIVAL_WARM_RETENTION_MONTHS` | Meses até uma partição passar para o armazenamento frio de arquivos. Com o worker habilitado, precisa ser maior que a retenção quente dividida por 30. | `24` | Não |
| `ARCHIVAL_COLD_RETENTION_MONTHS` | Retenção fria, em meses. Com o worker habilitado, precisa ser pelo menos a retenção morna. | `84` | Não |
| `ARCHIVAL_BATCH_SIZE` | Linhas por lote de arquivamento. | `5000` | Não |
| `ARCHIVAL_STORAGE_BUCKET` | Bucket dos arquivos arquivados. | `matcher-archives` | Com o worker de arquivamento habilitado |
| `ARCHIVAL_STORAGE_CLASS` | Classe de armazenamento: `STANDARD`, `STANDARD_IA`, `ONEZONE_IA`, `INTELLIGENT_TIERING`, `GLACIER_IR`, `GLACIER` ou `DEEP_ARCHIVE`. | `GLACIER` | Não |
| `ARCHIVAL_PARTITION_LOOKAHEAD` | Partições mensais futuras que o Matcher cria com antecedência. | `3` | Não |
| `ARCHIVAL_PRESIGN_EXPIRY_SEC` | Segundos em que um link de download de um arquivo arquivado fica válido. | `3600` | Não |

Com o worker de arquivamento habilitado, a retenção quente, o tamanho do lote e a antecedência precisam ser cada um pelo menos `1`.

## Governança

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ACTOR_PII_ENCRYPTION_KEY` | Chave que criptografa os nomes e os endereços de e-mail dos atores. Base64 padrão de exatamente 32 bytes. Quando `ENV_NAME` não é `development`, `dev`, `local` nem `test`, os mapeamentos de atores precisam dela. Sensível. | — | Não |

## Motor de extração

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `APP_ENC_KEY` | Chave mestra que criptografa as credenciais de conexão armazenadas. Base64 padrão de pelo menos 32 bytes. Fora de produção, o Matcher usa uma chave temporária quando ela não está definida. Sensível. | — | Produção |
| `FETCHER_DISCOVERY_INTERVAL_SEC` | Segundos entre execuções de descoberta no motor de extração. | `60` | Não |
| `FETCHER_SCHEMA_CACHE_TTL_SEC` | Segundos em que o Matcher mantém em cache um schema descoberto. | `300` | Não |
| `FETCHER_EXTRACTION_TIMEOUT_SEC` | Segundos que o Matcher espera por uma extração. | `600` | Não |
| `FETCHER_MAX_EXTRACTION_BYTES` | Tamanho máximo, em bytes, do resultado de uma extração. | `2147483648` | Não |

## Conectores

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `PAGBANK_CONNECTOR_BASE_URL` | URL base da API do PagBank. | `https://api.pagseguro.com` | Não |
| `STRIPE_CONNECTOR_BASE_URL` | URL base da API do Stripe. | `https://api.stripe.com` | Não |
| `STRIPE_CONNECTOR_FILES_BASE_URL` | URL base da API de arquivos do Stripe. | `https://files.stripe.com` | Não |
| `PIX_CONNECTOR_BASE_URL` | URL base da API Pix. Sem ela, o conector Pix falha no primeiro uso. | — | Para o conector Pix |
| `PLUGGY_CONNECTOR_BASE_URL` | URL base da API do Pluggy. | `https://api.pluggy.ai` | Não |
| `PLUGGY_WEBHOOK_HMAC_SECRET` | Segredo que verifica os webhooks do Pluggy. Prevalece sobre a lista de IPs. Sensível. | — | Não |
| `PLUGGY_WEBHOOK_ALLOWED_IPS` | IPs de origem que o Matcher aceita para os webhooks do Pluggy (CSV). | — | Não |
| `BELVO_CONNECTOR_BASE_URL` | URL base da API do Belvo. | `https://api.belvo.com` | Não |
| `BELVO_WEBHOOK_HMAC_SECRET` | Segredo que verifica os webhooks do Belvo. Prevalece sobre a lista de IPs. Sensível. | — | Não |
| `BELVO_WEBHOOK_ALLOWED_IPS` | IPs de origem que o Matcher aceita para os webhooks do Belvo (CSV). | — | Não |

## Recursos de IA

Cada recurso tem um controle de habilitação, uma chave de API e um modelo. A extração de documentos e as sugestões de regras também precisam do consentimento no documento de runtime `ai_gates`. Por padrão, esse consentimento fica desabilitado.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ADVISOR_ENABLED` | Habilita o assistente de mapeamento. | `false` | Não |
| `ADVISOR_ANTHROPIC_API_KEY` | Chave de API do provedor de modelo de linguagem do assistente de mapeamento. Sensível. | — | Com o assistente habilitado |
| `ADVISOR_MODEL` | Modelo do assistente de mapeamento. | `claude-sonnet-4-6` | Não |
| `DOC_EXTRACTION_ENABLED` | Habilita a extração de documentos. | `false` | Não |
| `DOC_EXTRACTION_ANTHROPIC_API_KEY` | Chave de API da extração de documentos. Sensível. | — | Com a extração de documentos habilitada |
| `DOC_EXTRACTION_MODEL` | Modelo da extração de documentos. | `claude-sonnet-4-6` | Não |
| `RULE_ADVISOR_ENABLED` | Habilita as sugestões de regras. | `false` | Não |
| `RULE_ADVISOR_ANTHROPIC_API_KEY` | Chave de API das sugestões de regras. Sensível. | — | Com as sugestões de regras habilitadas |
| `RULE_ADVISOR_MODEL` | Modelo das sugestões de regras. | `claude-sonnet-4-6` | Não |

## Streaming de eventos

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_ENABLED` | Publica os eventos do Matcher no Kafka. | `false` | Não |
| `STREAMING_BROKERS` | Brokers do Kafka (CSV). | — | Com o streaming habilitado |
| `STREAMING_CLIENT_ID` | Client ID do Kafka. | `primary` | Não |
| `STREAMING_CLOUDEVENTS_SOURCE` | Nome da origem em cada evento. Também dá nome ao tópico `lerian.streaming.<source>`. Um único segmento em minúsculas que corresponda a `^[a-z0-9][a-z0-9_-]*$`. O Matcher verifica o formato mesmo com o streaming desabilitado. | — | Com o streaming habilitado |
| `STREAMING_TLS_ENABLED` | Usa TLS no Kafka. | `false` | Produção, com o streaming habilitado |
| `STREAMING_TLS_CA_CERT` | Certificado da CA para o TLS do Kafka. | — | Não |
| `STREAMING_SASL_MECHANISM` | Mecanismo SASL: `PLAIN`, `SCRAM-SHA-256` ou `SCRAM-SHA-512`. | — | Não |
| `STREAMING_SASL_USERNAME` | Usuário SASL. | — | Com um mecanismo SASL |
| `STREAMING_SASL_PASSWORD` | Senha SASL. Sensível. | — | Com um mecanismo SASL |
| `STREAMING_SASL_ALLOW_PLAINTEXT` | Permite SASL sem TLS. | `false` | Não |
| `STREAMING_CB_FAILURE_RATIO` | Proporção de falhas que abre o circuit breaker de publicação. | `0.5` | Não |
| `STREAMING_CB_MIN_REQUESTS` | Requisições de que o breaker precisa antes de poder abrir. | `10` | Não |
| `STREAMING_CB_TIMEOUT_S` | Segundos em que o breaker fica aberto. | `30` | Não |
| `STREAMING_CLOSE_TIMEOUT_S` | Segundos que o Matcher espera para enviar os eventos pendentes quando para. | `30` | Não |
| `STREAMING_TOPIC_AUTO_PROVISION` | Cria o tópico na inicialização quando ele não existe. | `true` | Não |
| `STREAMING_TOPIC_PARTITIONS` | Partições de um tópico criado. `-1` usa o padrão do broker. | `-1` | Não |
| `STREAMING_TOPIC_REPLICATION_FACTOR` | Fator de replicação de um tópico criado. `-1` usa o padrão do broker. | `-1` | Não |

## Documentos de runtime

O Matcher mantém onze documentos de runtime no namespace `matcher` do Systemplane, em `/system`. As variáveis abaixo definem o valor inicial de cada documento. Depois que a Lerian grava um documento por meio do Systemplane, o documento armazenado prevalece sobre as suas variáveis. O documento `rate_limit` não pode habilitar os limites enquanto `RATE_LIMIT_ENABLED` não está definida ou é `false`.

| Documento | Variáveis |
| - | - |
| `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` | Nenhuma variável. O documento guarda os consentimentos de IA, negados por padrão. |


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