> ## 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 do TED Lerian

> Variáveis de ambiente que o TED Lerian lê na inicialização: servidor, autenticação, armazenamentos, Midaz, Lerian SPB, política, idempotência, eventos e telemetria.

O TED Lerian lê estas variáveis quando o serviço inicia. Uma mudança passa a valer depois que você reinicia o serviço. As configurações de runtime, como o endereço do Lerian SPB e o pacote da estimativa de tarifa, não são variáveis de ambiente.

Nas tabelas, **Obrigatória** marca uma variável que você deve definir, sempre ou na condição indicada. `—` significa sem padrão.

> [!NOTE]
>
> Com `ENVIRONMENT_NAME=production`, o serviço não inicia a menos que todas estas condições sejam verdadeiras: `POSTGRES_PASSWORD` está definida, `POSTGRES_SSLMODE` não é `disable`, `PLUGIN_AUTH_ENABLED` é `true`, `TRUSTED_PROXIES` está definida, `REDIS_TLS` é `true`, `AUDIT_MONGO_URI` pede TLS, e nem `ALLOW_CORS_WILDCARD` nem `ALLOW_RATELIMIT_FAIL_OPEN` é `true`.

## Runtime e servidor

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `ENVIRONMENT_NAME` | Nome do ambiente. `production` liga as verificações de inicialização da nota acima. `ENV_NAME` é lida quando `ENVIRONMENT_NAME` não está definida. | `development` | Não |
| `DEPLOYMENT_MODE` | `local`, `byoc` ou `saas`. | `local` | Não |
| `LOG_LEVEL` | Nível de log. | `info` | Não |
| `SERVER_ADDRESS` | Endereço em que o HTTP escuta. | `:8080` | Não |
| `HTTP_BODY_LIMIT_BYTES` | Maior body que o servidor HTTP aceita, em bytes. Um body maior recebe `413` `TED-9003`. | `104857600` | Não |
| `SERVER_TLS_CERT_FILE`, `SERVER_TLS_KEY_FILE` | Certificado e chave para TLS no próprio serviço. Defina as duas ou nenhuma. | — | Não |
| `TLS_TERMINATED_UPSTREAM` | `true` quando um proxy na frente do serviço encerra o TLS. O serviço então escuta em HTTP simples. | `false` | Não |
| `TRUSTED_PROXIES` | IPs ou CIDRs, separados por vírgula, dos proxies na frente do serviço. O serviço os usa para encontrar o IP do cliente. | — | Em produção |
| `CORS_ALLOWED_ORIGINS` | Origens CORS permitidas. | `http://localhost:3000` | Não |
| `CORS_ALLOWED_METHODS` | Métodos CORS permitidos. | `GET,POST,PUT,PATCH,DELETE,OPTIONS` | Não |
| `CORS_ALLOWED_HEADERS` | Headers CORS permitidos. | `Origin,Content-Type,Accept,Authorization,X-Request-ID` | Não |
| `CORS_EXPOSE_HEADERS` | Headers expostos ao navegador. | — | Não |
| `CORS_ALLOW_CREDENTIALS` | Permite credenciais em requisições CORS. | `false` | Não |
| `SWAGGER_ENABLED` | Serve o documento OpenAPI do serviço. | `false` | Não |
| `SYSTEMPLANE_ENABLED` | Liga as configurações de runtime e a API delas. | `false` | Para enviar TEDs |
| `INFRA_CONNECT_TIMEOUT_SEC` | Limite de tempo para conectar aos armazenamentos na inicialização, em segundos. | `30` | Não |

## Autenticação e licença

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Confere o token e a permissão do Access Manager em cada chamada. | `true` | Não |
| `PLUGIN_AUTH_HOST` | Endereço base do Access Manager, uma URL `http` ou `https` absoluta. O TED Lerian também obtém dele o token das suas chamadas ao CRM e ao Lerian SPB. | — | Sim |
| `CRM_CLIENT_ID`, `CRM_CLIENT_SECRET` | Aplicação do Access Manager que o TED Lerian usa nas suas chamadas ao CRM e ao Lerian SPB. O secret é sensível. | — | Sim |
| `LICENSE_ENABLED` | Confere a licença do produto para cada organização. | `false` | Não |
| `LICENSE_APPLICATION_ID` | Nome da aplicação enviado à verificação de licença. | `plugin-br-ted-lerian` | Não |
| `LICENSE_KEY` | Chave de licença que a verificação de licença usa. Sensível. | — | Não |
| `ORGANIZATION_IDS` | Organizações, separadas por vírgula, que a licença cobre. | — | Não |

## PostgreSQL

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `POSTGRES_HOST` | Host primário. | `localhost` | Não |
| `POSTGRES_PORT` | Porta primária. | `5432` | Não |
| `POSTGRES_USER` | Usuário do banco. | `plugin-br-ted-lerian` | Não |
| `POSTGRES_PASSWORD` | Senha do banco. Sensível. | — | Em produção |
| `POSTGRES_NAME` | Nome do banco. | `plugin-br-ted-lerian` | Não |
| `POSTGRES_SSLMODE` | Modo TLS da libpq. | `disable` | Não |
| `POSTGRES_REPLICA_HOST`, `POSTGRES_REPLICA_PORT`, `POSTGRES_REPLICA_USER`, `POSTGRES_REPLICA_PASSWORD`, `POSTGRES_REPLICA_NAME`, `POSTGRES_REPLICA_SSLMODE` | Réplica de leitura opcional, com o mesmo significado dos valores do primário. | — | Não |
| `POSTGRES_MAX_OPEN_CONNS` | Maior número de conexões abertas. | `25` | Não |
| `POSTGRES_MAX_IDLE_CONNS` | Maior número de conexões ociosas. | `5` | Não |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | Tempo de vida de uma conexão, em minutos. | `30` | Não |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | Tempo ocioso antes de uma conexão fechar, em minutos. | `5` | Não |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | Limite de tempo da conexão, em segundos. | `10` | Não |

## Valkey

O Valkey guarda os registros de idempotência, os contadores de rate limit e os contadores dos limites de uso.

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `REDIS_HOST` | Endereço, `host:port`. | `localhost:6379` | Não |
| `REDIS_MASTER_NAME` | Nome do master do Sentinel, quando você usa Sentinel. | — | Não |
| `REDIS_PASSWORD` | Senha. Sensível. | — | Não |
| `REDIS_DB` | Número do banco. | `0` | Não |
| `REDIS_PROTOCOL` | Versão do protocolo. | `3` | Não |
| `REDIS_TLS` | Conecta com TLS. | `false` | Em produção |
| `REDIS_CA_CERT` | Bundle de CA, em base64, para um certificado de servidor emitido por uma CA privada. | — | Não |
| `REDIS_POOL_SIZE` | Tamanho do pool de conexões. | `10` | Não |
| `REDIS_MIN_IDLE_CONNS` | Menor número de conexões ociosas. | `2` | Não |
| `REDIS_READ_TIMEOUT`, `REDIS_WRITE_TIMEOUT` | Limites de tempo de leitura e escrita, em segundos. | `3` | Não |
| `REDIS_DIAL_TIMEOUT` | Limite de tempo da conexão, em segundos. | `5` | Não |
| `REDIS_POOL_TIMEOUT` | Espera por uma conexão livre, em segundos. | `2` | Não |
| `REDIS_MAX_RETRIES` | Novas tentativas de um comando que falhou. | `3` | Não |
| `REDIS_MIN_RETRY_BACKOFF` | Menor espera entre tentativas, em milissegundos. | `8` | Não |
| `REDIS_MAX_RETRY_BACKOFF` | Maior espera entre tentativas, em segundos. | `1` | Não |

## Trilha de auditoria

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `AUDIT_MONGO_URI` | String de conexão do MongoDB da trilha de auditoria. Em produção, ela deve pedir TLS (`tls=true`, ou uma URI `mongodb+srv://`). | — | Sim |

## Midaz

O TED Lerian reserva, liquida e credita o dinheiro no ledger do Midaz, e encontra contas e titulares no CRM.

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `MIDAZ_LEDGER_ENABLED` | Conecta ao ledger do Midaz. Sem ela, o TED Lerian não consegue movimentar dinheiro no Midaz. | `false` | Não |
| `MIDAZ_LEDGER_BASE_URL` | Endereço base do ledger do Midaz. | — | Não |
| `MIDAZ_ORGANIZATION_ID`, `MIDAZ_LEDGER_ID` | Organização e ledger desta instalação. O TED Lerian credita ali as TEDs recebidas, e um vínculo de ISPB deve apontar para esse par. | — | Se o ledger estiver ligado |
| `MIDAZ_ACCESS_MANAGER_ADDRESS` | Endereço do Access Manager para as chamadas ao ledger do Midaz. | — | Se o ledger estiver ligado, a menos que `MIDAZ_ANONYMOUS` seja `true` |
| `MIDAZ_CLIENT_ID`, `MIDAZ_CLIENT_SECRET` | Aplicação do Access Manager para as chamadas ao ledger do Midaz. O secret é sensível. | — | Se o ledger estiver ligado, a menos que `MIDAZ_ANONYMOUS` seja `true` |
| `MIDAZ_ANONYMOUS` | Chama um Midaz local que não tem autenticação. Apenas para desenvolvimento local. | `false` | Não |
| `MIDAZ_IDEMPOTENCY_TTL_SECONDS` | Por quanto tempo o Midaz guarda a chave de idempotência de cada chamada ao ledger, em segundos, de `3600` a `604800`. Um valor fora desse intervalo interrompe a inicialização. | `86400` | Não |
| `MIDAZ_CRM_ENABLED` | Conecta ao CRM, onde o TED Lerian encontra contas e titulares. | `false` | Não |
| `MIDAZ_CRM_BASE_URL` | Endereço base do CRM, uma URL `http` ou `https` absoluta. Ela deve ser `https` quando `ENVIRONMENT_NAME` não é `development`, `local`, `test` ou `ci`. | — | Se o CRM estiver ligado |

## Lerian SPB

O endereço do Lerian SPB é uma configuração de runtime de cada instituição. `RAIL_ALLOWED_HOSTS` limita os hosts que o TED Lerian aceita ali.

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `RAIL_ALLOWED_HOSTS` | Valores `host:port` do Lerian SPB, separados por vírgula. O TED Lerian não chama um endereço do Lerian SPB em nenhum outro host. | — | Sim |
| `CIRCUIT_BREAKER_ENABLED` | Protege as chamadas ao Lerian SPB com um circuit breaker. | `false` | Não |

## Política e operações

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `POLICY_USAGE_LIMITS_MODE` | `enforced` aplica os limites de uso. `disabled` recusa todo envio com `TED-0080`. `noop` não confere nenhum limite. Qualquer outro valor interrompe a inicialização. | `enforced` | Não |
| `RECONCILIATION_QUEUE_CURSOR_KEY` | Chave que assina os cursores da fila de conciliação: o base64 de exatamente 32 bytes. Sensível. Uma chave nova invalida os cursores em uso. | — | Sim |

## Idempotência e rate limits

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `IDEMPOTENCY_MIN_TTL_SEC`, `IDEMPOTENCY_MAX_TTL_SEC` | Menor e maior `X-TTL` que o serviço aceita, em segundos. Um valor fora deles é ajustado a eles. | `30`, `604800` | Não |
| `RATE_LIMIT_ENABLED` | Liga os rate limits. | `true` | Não |
| `RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_SEC` | Requisições permitidas em cada janela, e a janela em segundos, para as rotas padrão. | `500`, `60` | Não |
| `AGGRESSIVE_RATE_LIMIT_MAX`, `AGGRESSIVE_RATE_LIMIT_WINDOW_SEC` | O mesmo, para as rotas estritas. | `100`, `60` | Não |
| `RELAXED_RATE_LIMIT_MAX`, `RELAXED_RATE_LIMIT_WINDOW_SEC` | O mesmo, para as rotas relaxadas. | `1000`, `60` | Não |

## Eventos

O TED Lerian grava cada evento no seu outbox, na mesma transação da mudança de status. O relay do outbox então o publica. A conexão com o broker vem das configurações compartilhadas `STREAMING_*` em [Streaming e outbox](https://docs.lerian.studio/pt/reference/byoc-configuration.md#streaming-and-outbox).

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `STREAMING_ENABLED` | Publica eventos. Exige `OUTBOX_ENABLED=true`. | `false` | Não |
| `STREAMING_CLOUDEVENTS_SOURCE` | Source do CloudEvents. Deve ser `br-ted` quando o streaming está ligado. | — | Se o streaming estiver ligado |
| `STREAMING_HEALTH_CHECK_TIMEOUT` | Limite de tempo da verificação de prontidão do broker (duração Go). | `2s` | Não |
| `OUTBOX_ENABLED` | Liga o relay do outbox. | `false` | Se o streaming estiver ligado |
| `OUTBOX_DISPATCH_INTERVAL_SEC` | Tempo entre ciclos do relay enquanto há eventos esperando, em segundos. | `2` | Não |
| `OUTBOX_COLD_DISPATCH_INTERVAL_SEC` | Tempo entre ciclos do relay enquanto o outbox não tem atividade recente, em segundos. O primeiro evento depois de um período ocioso pode esperar esse tempo. | `60` | Não |
| `OUTBOX_BATCH_SIZE` | Maior número de eventos em um ciclo. | `50` | Não |
| `OUTBOX_PUBLISH_MAX_ATTEMPTS` | Tentativas de publicação de cada evento. | `3` | Não |
| `OUTBOX_PUBLISH_BACKOFF_MS` | Espera base entre tentativas de publicação, em milissegundos. | `200` | Não |
| `OUTBOX_RETRY_WINDOW_SEC` | Espera antes de um evento que falhou ser tentado de novo, em segundos. | `300` | Não |
| `OUTBOX_MAX_DISPATCH_ATTEMPTS` | Tentativas de despacho antes de um evento ser marcado como inválido. | `10` | Não |
| `OUTBOX_PROCESSING_TIMEOUT_SEC` | Tempo depois do qual o relay retoma um evento preso em processamento, em segundos. | `600` | Não |
| `OUTBOX_MAX_FAILED_PER_BATCH` | Eventos com falha que cada ciclo retoma para uma nova tentativa. | `25` | Não |
| `OUTBOX_PRIORITY_EVENT_TYPES` | Tipos de evento, separados por vírgula, que cada ciclo pega primeiro. | — | Não |
| `OUTBOX_TABLE_NAME` | Nome da tabela do outbox. | `outbox_events` | Não |
| `RABBITMQ_ENABLED` | Abre uma conexão RabbitMQ que só a verificação de prontidão usa. O TED Lerian não publica nenhum evento por ela. | `false` | Não |
| `RABBITMQ_URL`, `RABBITMQ_HOST`, `RABBITMQ_PORT_AMQP`, `RABBITMQ_PORT_HOST`, `RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS`, `RABBITMQ_VHOST`, `RABBITMQ_QUEUE` | Conexão RabbitMQ. `RABBITMQ_URL` ou `RABBITMQ_HOST` é obrigatória quando o RabbitMQ está ligado. | `RABBITMQ_HOST`: `localhost` | Se o RabbitMQ estiver ligado |
| `RABBITMQ_HEALTH_CHECK_URL`, `RABBITMQ_HEALTH_CHECK_ALLOWED_HOSTS`, `RABBITMQ_REQUIRE_HEALTH_ALLOWED_HOSTS`, `RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK`, `RABBITMQ_ALLOW_INSECURE_TLS` | Configurações de health check e TLS do RabbitMQ. | — | Não |

## Telemetria

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Exporta traces e métricas OpenTelemetry. | `false` | Não |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endereço do coletor OTLP. | `localhost:4317` | Não |
| `OTEL_RESOURCE_SERVICE_NAME` | Nome do serviço na telemetria. | `plugin-br-ted-lerian` | Não |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Nome do ambiente na telemetria. | `development` | Não |
| `OTEL_LIBRARY_NAME` | Nome da biblioteca de instrumentação. | Padrão do serviço | Não |
| `OTEL_TRUST_INBOUND_TRACE_CONTEXT` | Continua o trace que um chamador envia nos headers da requisição. | `false` | Não |


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