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

> Variáveis de ambiente que o JD Courier lê no início: papéis, servidor, PostgreSQL, Access Manager, canal SPB da JD, interface SOAP, trânsito Pix, drenagem do SPB, licença, multi-tenancy e telemetria.

O JD Courier lê estas variáveis quando o processo inicia. Uma mudança vale depois que você reinicia o processo. Cada processo lê as variáveis dos papéis em `COURIER_ROLES`.

Nas tabelas, a coluna **Obrigatória** marca uma variável que você deve definir, sempre ou na condição indicada. `—` significa sem padrão. 🔒 marca um segredo: guarde-o no seu cofre de segredos.

> [!NOTE]
>
> Com `ENVIRONMENT_NAME=production`, o Courier não inicia a menos que tudo isto seja verdade: `PLUGIN_AUTH_ENABLED` é `true`, `POSTGRES_PASSWORD` está definida, `POSTGRES_SSLMODE` não é `disable` e `ALLOW_CORS_WILDCARD` não é `true`. Cada papel acrescenta as próprias verificações, indicadas nas tabelas abaixo.

## Serviço e servidor

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `COURIER_ROLES` | Os papéis do processo, separados por vírgulas: `spb-consumer`, `spb-sender`, `pix-ingress`, `admin`. Um papel desconhecido ou repetido para o boot. `spb-consumer` roda sozinho no processo dele. | — | Sim |
| `ENVIRONMENT_NAME` | O ambiente. `production` liga as verificações de produção. `ENV_NAME` é lida quando `ENVIRONMENT_NAME` não está definida. | `development` | Não |
| `DEPLOYMENT_MODE` | `byoc`, `saas` ou `local`. Outro valor para o boot. | `local` | Não |
| `LOG_LEVEL` | O nível de log. | `info` | Não |
| `SERVER_ADDRESS` | A porta HTTP: os probes, a API do operador, a API dos motores e o endereço Pix. | `:8080` | Não |
| `SERVER_TLS_CERT_FILE`, `SERVER_TLS_KEY_FILE` | O certificado e a chave para TLS na porta HTTP. Defina as duas ou nenhuma. Um processo com `spb-sender` ou com o trânsito Pix as recusa, a menos que `TLS_TERMINATED_UPSTREAM` seja `true`. | — | Não |
| `TLS_TERMINATED_UPSTREAM` | `true` quando o TLS termina antes da porta HTTP. | `false` | Não |
| `HTTP_BODY_LIMIT_BYTES` | O maior corpo de requisição na porta HTTP, em bytes. | `1048576` | Não |
| `SWAGGER_ENABLED` | Serve o documento OpenAPI na raiz da porta HTTP. O Courier a ignora em produção. | `false` | Não |
| `SYSTEMPLANE_ENABLED` | Liga as configurações de runtime e a API delas em `/system`. | `false` | Não |
| `INFRA_CONNECT_TIMEOUT_SEC` | O limite de tempo para conectar aos datastores no boot, em segundos. | `30` | Não |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | Por quanto tempo o Courier guarda a resposta a uma chave `X-Idempotency`, em segundos. | `300` | Não |
| `ALLOW_CORS_WILDCARD` | A produção recusa `true`. | — | Não |

## PostgreSQL

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `POSTGRES_HOST` | O host primário. | `localhost` | Não |
| `POSTGRES_PORT` | A porta primária. | `5432` | Não |
| `POSTGRES_USER` | O usuário do banco de dados. | `jd-courier` | Não |
| `POSTGRES_PASSWORD` | 🔒 A senha do banco de dados. | — | Em produção |
| `POSTGRES_NAME` | O nome do banco de dados. | `jd-courier` | Não |
| `POSTGRES_SSLMODE` | O modo TLS da libpq. Com `disable`, o Courier não inicia, a menos que `ALLOW_INSECURE_TLS` seja `true`. A produção recusa `disable`. Use `verify-full` em produção. | `require` | Não |
| `POSTGRES_REPLICA_HOST`, `POSTGRES_REPLICA_PORT`, `POSTGRES_REPLICA_USER`, `POSTGRES_REPLICA_PASSWORD`, `POSTGRES_REPLICA_NAME`, `POSTGRES_REPLICA_SSLMODE` | Uma réplica de leitura opcional. Um valor que você não define recebe o valor do primário. Quando você define qualquer uma delas, `POSTGRES_REPLICA_HOST` é obrigatória. A produção recusa `POSTGRES_REPLICA_SSLMODE=disable`. | — | Não |
| `POSTGRES_MAX_OPEN_CONNS` | O maior número de conexões abertas. | `25` | Não |
| `POSTGRES_MAX_IDLE_CONNS` | O maior número de conexões ociosas. | `5` | Não |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | A maior duração de uma conexão, em minutos. | `30` | Não |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | O maior tempo ocioso de uma conexão, em minutos. | `5` | Não |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | O limite de tempo para abrir uma conexão, em segundos. | `10` | Não |
| `ALLOW_INSECURE_TLS` | `true` permite que as conexões aos datastores funcionem sem TLS. | `false` | Não |

## Access Manager

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Verifica o token e a permissão do Access Manager em cada chamada. `false` precisa de `ALLOW_AUTH_DISABLED_LOCAL_ONLY=true`. A produção e o modo multi-tenant recusam `false`. | `true` | Não |
| `PLUGIN_AUTH_HOST` | O endereço do seu Access Manager. | — | Quando `PLUGIN_AUTH_ENABLED` é `true` |
| `ALLOW_AUTH_DISABLED_LOCAL_ONLY` | Permite que `PLUGIN_AUTH_ENABLED=false` inicie, apenas na máquina de um desenvolvedor. | `false` | Não |
| `AUTH_M2M_INVERSION_ENABLED` | Vincula cada chamada de motor à identidade que o Access Manager verificou. Com `false`, o Courier recusa cada credencial de motor com `401`, e um processo de produção com o papel `admin` não inicia. | `true` | Não |
| `AUTH_M2M_PRODUCT_FORWARD_ENABLED` | Envia o nome de produto do Courier ao Access Manager quando ele autoriza uma chamada de motor. | `true` | Não |
| `AUTH_TIMEOUT`, `AUTH_CACHE_TTL`, `AUTH_RETRY_MAX`, `AUTH_BREAKER_ENABLED`, `AUTH_REQUIRED`, `AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED`, `AUTH_JWT_VERIFY_CERT`, `AUTH_JWT_VERIFY_CERT_PATH`, `AUTH_JWT_ISSUER` | As configurações do cliente do Access Manager. Um valor que não é válido para o boot. | Os padrões do cliente | Não |
| `IDP_DECLARATION_ENABLED` | No modo single-tenant, `true` publica no seu Access Manager as permissões do Courier e a adesão dele a parceiros. Sem valor ou `false`, publica apenas a adesão a parceiros. | — | Não |
| `IDP_HOST` | O endereço do serviço de identidade do Access Manager, onde o Courier as publica. | — | Para a publicação |
| `IDP_M2M_CLIENT_ID` | O client ID da aplicação que as publica. | — | Para a publicação |
| `IDP_M2M_CLIENT_SECRET` | 🔒 O secret dessa aplicação. | — | Para a publicação |

Veja [Access Manager](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-deployment.md#access-manager) para o que a publicação faz.

## Canal SPB da JD

Os papéis `spb-consumer` e `spb-sender` leem estas variáveis.

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `JD_BASE_URL` | O endereço do serviço SPB da JD. Use https em produção. | — | Em produção, no modo single-tenant |
| `JD_SOAP_PATH` | O caminho do serviço SOAP da JD. | `/soap` | Não |
| `JD_LEGACY_CODE` | A credencial JD que você já tem. No máximo 10 bytes. | — | Em produção, no modo single-tenant |
| `JD_USER_CODE` | A credencial JD que você já tem. No máximo 10 bytes. | — | Em produção, no modo single-tenant |
| `JD_PASSWORD` | 🔒 A credencial JD que você já tem. No máximo 20 bytes. | — | Em produção, no modo single-tenant |
| `SPB_VENDOR_TIMEOUT` | Quanto tempo o Courier espera pela JD. Deve ser maior que zero e menor que `8s`. | `7s` | Não |
| `JD_ALLOW_PRIVATE_NETWORK` | `true` permite que o Courier se conecte à JD em um endereço de rede privada, para o canal SPB e a cabine SPI. A produção a aceita. | `false` | Não |
| `JD_PRIVATE_KEY_PEM` | Não deve estar presente em produção. O Courier não assina nada. | — | Não |

## Interface SOAP

O papel `spb-sender` lê estas variáveis.

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `SOAP_SERVER_ADDRESS` | A porta SOAP. | `:8081` | Não |
| `SOAP_MAX_BODY_BYTES` | O maior corpo de requisição SOAP, em bytes. | `10485760` | Não |
| `SOAP_TLS_CERT_FILE`, `SOAP_TLS_KEY_FILE` | O certificado e a chave para TLS na porta SOAP. Defina as duas ou nenhuma. A versão mínima do TLS é 1.2. | — | Em produção, a menos que `SOAP_TLS_TERMINATED_UPSTREAM` seja `true` |
| `SOAP_TLS_TERMINATED_UPSTREAM` | `true` quando o TLS termina antes da porta SOAP. | `false` | Não |
| `SPB_CHANNEL_CREDENTIAL_ROTATION_OVERLAP` | Por quanto tempo as credenciais SOAP e do trânsito Pix anteriores de um motor continuam funcionando depois que o operador emite uma nova. O papel `admin` a lê quando emite uma credencial. `spb-sender` recusa um valor que não é positivo. | `24h` | Não |

## Trânsito Pix

O papel `admin` lê estas variáveis.

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `PIX_TRANSIT_SERVER_ADDRESS` | O endereço do trânsito Pix. Quando está vazio, o Courier não serve trânsito. | — | Para o trânsito |
| `PIX_TRANSIT_TLS_CERT_FILE`, `PIX_TRANSIT_TLS_KEY_FILE` | O certificado e a chave para TLS no trânsito. Defina as duas ou nenhuma. A versão mínima do TLS é 1.2. | — | Em produção, a menos que `PIX_TRANSIT_TLS_TERMINATED_UPSTREAM` seja `true` |
| `PIX_TRANSIT_TLS_TERMINATED_UPSTREAM` | `true` quando o TLS termina antes do trânsito. | `false` | Não |
| `JD_SPI_BASE_URL` | No modo single-tenant, o endereço da cabine SPI da JD. Use https em produção. | — | Para o trânsito |
| `JD_SPI_CLIENT_ID` | No modo single-tenant, o client ID da credencial da cabine SPI da sua instituição. | — | Para o trânsito |
| `JD_SPI_CLIENT_SECRET` | 🔒 No modo single-tenant, o secret dessa credencial. | — | Para o trânsito |
| `JD_SPI_USE_SERVICE_SEGMENTS` | `true` quando a JD serve a cabine SPI pelos caminhos do gateway dela: o Courier então pede o token em `/auth` e envia os resultados das validações de conta em `/spi-api`. | `false` | Não |

## Drenagem do SPB

O papel `spb-consumer` lê estas variáveis. `SPB_TAKE_BUDGET_SEC` mais o maior entre `SPB_IDLE_INTERVAL_SEC` e `SPB_EMPTY_BACKOFF_CAP_SEC` deve ficar abaixo de `SPB_LEASE_TTL_SEC`.

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `POD_NAME` | O nome do detentor do lease de leitura. Quando está vazio, o Courier usa o nome do host. | — | Não |
| `SPB_LEASE_TTL_SEC` | Quanto tempo o lease de leitura dura sem uma renovação, em segundos. | `30` | Não |
| `SPB_TAKE_BUDGET_SEC` | O maior tempo para tirar uma mensagem da JD, em segundos. Deve ser pelo menos `SPB_VENDOR_TIMEOUT`. | `15` | Não |
| `SPB_IDLE_INTERVAL_SEC` | A espera enquanto a drenagem não lê, em segundos. | `5` | Não |
| `SPB_EMPTY_BACKOFF_CAP_SEC` | A maior espera depois que a JD informa uma fila vazia, em segundos. | `10` | Não |
| `SPB_PERSIST_TIMEOUT_SEC` | O limite de tempo de uma tentativa de guardar uma mensagem, em segundos. | `60` | Não |
| `SPB_TENANT_REFRESH_SEC` | Com que frequência a drenagem lê de novo a lista de tenants, em segundos. | `30` | Não |
| `SPB_MESSAGE_SIZE_ALERT_BYTES` | Uma mensagem maior que isto grava um aviso. O Courier a guarda. | `1048576` | Não |

## Pix e credenciais dos motores

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `AWS_REGION` | A região AWS do AWS Secrets Manager, onde o Courier lê as credenciais que usa nos motores. | `us-east-1` | Não |

Veja [Credenciais dos motores](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-deployment.md#engine-credentials).

## Licença

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `LICENSE_KEY` | 🔒 A sua chave de licença da Lerian. | — | Sim |
| `ORGANIZATION_IDS` | O ID da sua organização. | — | Não |
| `APPLICATION_NAME` | O nome de produto que a verificação da licença usa. Deixe-a sem valor: então, o Courier usa o próprio nome de produto. | — | Não |

## Multi-tenancy

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `MULTI_TENANT_ENABLED` | Liga o modo multi-tenant. | `false` | Não |
| `MULTI_TENANT_URL` | O endereço do Tenant Manager. | — | No modo multi-tenant |
| `MULTI_TENANT_SERVICE_API_KEY` | 🔒 A chave do Courier no Tenant Manager. | — | No modo multi-tenant |
| `MULTI_TENANT_REDIS_HOST` | O host Redis do cache de tenants. | — | No modo multi-tenant |
| `MULTI_TENANT_REDIS_PORT` | A porta Redis. | `6379` | Não |
| `MULTI_TENANT_REDIS_PASSWORD` | 🔒 A senha do Redis. | — | Não |
| `MULTI_TENANT_REDIS_TLS` | Conecta ao Redis com TLS. | `false` | Não |
| `MULTI_TENANT_MAX_TENANT_POOLS` | O maior número de pools de conexão de tenant. | `100` | Não |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Por quanto tempo um pool de tenant ocioso fica aberto, em segundos. | `300` | Não |
| `MULTI_TENANT_TIMEOUT` | O limite de tempo de uma chamada ao Tenant Manager, em segundos. | `30` | Não |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | As falhas que abrem o circuit breaker do Tenant Manager. | `5` | Não |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | Por quanto tempo o circuit breaker fica aberto, em segundos. | `30` | Não |
| `MULTI_TENANT_CACHE_TTL_SEC` | Por quanto tempo o Courier guarda a configuração de um tenant, em segundos. | `120` | Não |
| `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | Com que frequência o Courier verifica as conexões de tenant, em segundos. | `30` | Não |

## Telemetria

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Liga o OpenTelemetry. | `true` | Não |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | O endereço do coletor OTLP. | `localhost:4317` | Não |
| `OTEL_RESOURCE_SERVICE_NAME` | O nome do serviço na telemetria. | `jd-courier` | Não |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | O nome do ambiente na telemetria. | `development` | Não |
| `OTEL_LIBRARY_NAME` | O nome da biblioteca de instrumentação na telemetria. | O nome do módulo do Courier | Não |
| `OTEL_TRUST_INBOUND_TRACE_CONTEXT` | Continua o trace que um chamador envia. Defina `true` apenas atrás de um gateway em que você confia. | `false` | Não |


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