> ## 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
> Configure o trilho Pix Direto via JD: endpoints OAuth da JD e do JDPI, hospedagem de QR code dinâmico com JWS, vínculo com o ledger Midaz e configurações de notificação.
O Pix Direto via JD conecta o seu ledger direto ao arranjo Pix através do gateway DICT e SPI da JD. A equipe de DevOps define o comportamento dele por variáveis de ambiente no momento do deploy. Para mudar uma variável, reinicie o serviço. Esta página cobre as variáveis **específicas deste trilho**. Para os controles de datastore, multi-tenancy, streaming, telemetria e autenticação que todo serviço Go da Lerian compartilha, veja [Fundamentos de configuração BYOC](/pt/reference/byoc-configuration).
Estas variáveis descrevem um **deploy single-tenant**. Na oferta multi-tenant gerenciada (SaaS), os valores específicos de cliente daqui — credenciais da JD, o vínculo com o ledger Midaz, a conexão com o CRM, o host público de QR — são resolvidos automaticamente por tenant pela plataforma, nunca a partir do ambiente de um deploy.
Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor padrão. Um qualificador em negrito (por exemplo **Obrigatório**) marca as variáveis que você deve definir. `—` significa que não há padrão. `🔒` marca um **segredo**. Injete o valor no momento do deploy a partir do seu cofre de segredos e nunca faça commit dele. Esta página lista apenas nomes e comportamento de variáveis. Ela não imprime nenhum valor secreto.
## Servidor e porta
O serviço escuta no endereço em `SERVER_ADDRESS` (padrão `:8080`). As probes de liveness, readiness e versão usam essa mesma porta. Veja [Servidor](/pt/reference/byoc-configuration#server) para os controles de servidor compartilhados e [Portas de rede padrão](/pt/reference/default-network-ports).
## Integração com a JD
Credenciais e endpoints da API protegida por OAuth da JD e da superfície Pix (JDPI) dela.
| Variável | Padrão / Obrigatório | Descrição |
| -------------------------- | -------------------- | ----------------------------------------------------------------------- |
| `JD_BASE_URL` | **Obrigatório** | URL base da API da JD. |
| `JD_CLIENT_ID` | **Obrigatório** | Client ID OAuth da API da JD. |
| `JD_SECRET` | 🔒 **Obrigatório** | Client secret OAuth da API da JD. |
| `JD_GRANT_TYPE` | `client_credentials` | Tipo de grant OAuth usado com a JD. |
| `JD_USE_SERVICE_SEGMENTS` | `false` | Roteia as chamadas pelos service segments da JD quando `true`. |
| `JDPI_MAX_RETRIES` | `2` | Novas tentativas em uma chamada JDPI que falhou. |
| `JDPI_RETRY_BASE_DELAY_MS` | `100` | Atraso base de backoff em milissegundos entre as novas tentativas JDPI. |
**O seu próprio ISPB não é uma variável de ambiente.** Ele vem da chave de systemplane `tenancy/jd_integration_binding`, campo `ispb`, e não existe fallback por ambiente.
Enquanto essa chave estiver vazia, o trilho sobe, responde à health probe e recusa **todo** pagamento em **toda** rota de dinheiro com `409 PIX-0092`. Uma bateria de ponta a ponta juntou 86 recusas desse único valor não provisionado. Escrever a chave conserta um deploy em execução na requisição seguinte, sem reinício. O passo a passo está em [Configuração do trilho](/pt/interfaces/pix-jd/pix-jd-setup).
## Hospedagem de QR code dinâmico
O trilho hospeda payloads de QR dinâmico assinados (JWS) e o conjunto JWK usado para verificá-los, e serve esses documentos sob o host em `QRCODE_PUBLIC_BASE_URL`. Os formatos das rotas públicas, a forma do host sem esquema e o orçamento de 77 caracteres da URL de payload do BACEN que esses caminhos consomem são o contrato da [seção de referência de QR codes](/pt/reference/interfaces/pix-jd/create-dynamic-qr-code); as variáveis abaixo definem as partes que este deploy controla.
| Variável | Padrão / Obrigatório | Descrição |
| -------------------------- | -------------------------- | ------------------------------------------------------------------------------------------ |
| `QRCODE_PUBLIC_BASE_URL` | **Obrigatório** | Host sem esquema (FQDN) em que o plugin serve os payloads de QR dinâmico e o conjunto JWK. |
| `QRCODE_PAYLOAD_PATH` | `v1/qrcodes/payload` | Segmento de caminho em que o plugin expõe os payloads de QR assinados. |
| `QRCODE_JWK_PATH` | `v1/qrcodes/jwks` | Segmento de caminho em que o plugin expõe o conjunto JWK. |
| `QRCODE_JWS_CONTENT_TYPE` | `application/jose` | `Content-Type` retornado para o payload assinado. |
| `QRCODE_JWKS_CONTENT_TYPE` | `application/jwk-set+json` | `Content-Type` retornado para o conjunto JWK. |
## Vínculo com o ledger Midaz
Contra qual organização, ledger, ativo e conta externa do Midaz este trilho lança as movimentações de Pix, mais os endpoints dos serviços do ledger e as credenciais máquina a máquina.
| Variável | Padrão / Obrigatório | Descrição |
| ----------------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
| `MIDAZ_ORGANIZATION_ID` | **Obrigatório** | UUID da organização Midaz dona do ledger de Pix. |
| `MIDAZ_LEDGER_ID` | **Obrigatório** | UUID do ledger Midaz para os lançamentos de Pix. |
| `MIDAZ_ASSET_ID` | **Obrigatório** (single-tenant) | **Código** do ativo lançado nas operações de Pix, por exemplo `BRL`. Sem padrão. |
| `MIDAZ_EXTERNAL_ID` | **Obrigatório** (single-tenant) | **Alias** da conta externa de compensação, por exemplo `@external/BRL`. Sem padrão. |
| `MIDAZ_URL_ONBOARDING` | **Obrigatório** | URL do serviço de onboarding do Midaz. |
| `MIDAZ_URL_TRANSACTION` | **Obrigatório** | URL do serviço de transação do Midaz. |
| `MIDAZ_CLIENT_ID` | — | Client ID OAuth para o M2M do Midaz. |
| `MIDAZ_CLIENT_SECRET` | 🔒 — | Client secret OAuth para o M2M do Midaz. |
| `MIDAZ_TIMEOUT` | `30000` | Timeout das requisições ao Midaz em milissegundos. |
Não existe um endereço separado de Access Manager para o Midaz. O trilho emite o token de saída do Midaz contra o mesmo Access Manager com que valida os bearers de entrada, `PLUGIN_AUTH_HOST`. Veja [Fundamentos de configuração BYOC](/pt/reference/byoc-configuration).
`MIDAZ_ASSET_ID` e `MIDAZ_EXTERNAL_ID` não têm **nenhum padrão**, e os dois nomes mentem sobre o formato: o primeiro quer um código de ativo (`BRL`) e o segundo um alias de conta (`@external/BRL`), apesar do `_ID`. Um UUID em qualquer um dos dois responde `PIX-4011` sem nomear uma conta, e deixar qualquer um deles sem valor recusa todo lançamento com `409 PIX-0106`, nomeando as duas metades.
As chaves de systemplane `tenant_policy/midaz.asset_id` e `tenant_policy/midaz.external_id` aceitam uma escrita e respondem `204`, mas nada as lê — as duas variáveis acima são a única fonte. Veja [Configuração do trilho](/pt/interfaces/pix-jd/pix-jd-setup).
## Rotas contábeis
O trilho lança cada fluxo de Pix em um par de rotas de operação do Midaz — uma perna de crédito, uma perna de débito, em dez perfis. **Esses vinte identificadores de rota não são variáveis de ambiente.** Eles ficam nas chaves de systemplane `tenant_policy/routing..operation_credit_route` e `tenant_policy/routing..operation_debit_route`, sem fallback por ambiente.
As variáveis `TRANSACTION_ROUTE_*` e `OPERATION_ROUTE_*` foram removidas. Um valor remanescente gera um aviso na inicialização e nunca é carregado. Uma perna de rota ausente recusa o próprio caminho de dinheiro com `409 PIX-0105` enquanto todos os outros fluxos continuam funcionando, então um único fluxo que "não funciona" aponta primeiro para cá.
Os perfis, os nomes exatos das chaves e como escrevê-las estão em [Configuração do trilho](/pt/interfaces/pix-jd/pix-jd-setup).
## Jobs e limites
| Variável | Padrão / Obrigatório | Descrição |
| ---------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------- |
| `JOBS_CRON` | `*/10 * * * * *` | Expressão cron do job de conciliação e manutenção. |
| `JOBS_CRON_TRANSACTIONS` | `*/10 * * * * *` | Expressão cron do job de processamento de transações. |
| `JOBS_RECONCILE_STUCK_THRESHOLD_SEC` | `80` | Idade em segundos a partir da qual um cash-out pendente é marcado como travado. |
| `MAX_PAGINATION_LIMIT` · `MAX_PAGINATION_MONTH_DATE_RANGE` | `100` · `3` | Limites máximos do tamanho de página das listagens e do intervalo de datas. |
A janela diária em que os limites de transação são contabilizados **não** é uma variável de ambiente. Ela fica nas chaves de systemplane `tenant_policy/transaction_limits.daily_period_init` e `tenant_policy/transaction_limits.daily_period_end`, nos dois modos de deploy; as duas recebem uma hora do relógio de 0 a 23. As variáveis aposentadas `TRANSACTION_LIMIT_DAILY_PERIOD_INIT` e `TRANSACTION_LIMIT_DAILY_PERIOD_END` são ignoradas.
## Notificações
Notificações opcionais ao cliente final para eventos de Pix. Deixe os blocos de provedor sem valor para desabilitar aquele canal.
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------ | -------------------- | ---------------------------------------------------------- |
| `SENDGRID_API_KEY` | 🔒 — | Chave de API do SendGrid para notificações por e-mail. |
| `SENDGRID_FROM_EMAIL` | — | Endereço remetente das notificações por e-mail. |
| `SENDGRID_FROM_TEMPLATE` | — | ID do template do SendGrid usado no corpo da mensagem. |
| `TWILIO_ACCOUNT_SID` | 🔒 — | SID da conta Twilio para notificações por SMS. |
| `TWILIO_AUTH_TOKEN` | 🔒 — | Token de autenticação da Twilio para notificações por SMS. |
| `TWILIO_PHONE_NUMBER` | — | Número de telefone remetente das notificações por SMS. |
## CRM
| Variável | Padrão / Obrigatório | Descrição |
| ------------------- | -------------------- | ---------------------------------------------------- |
| `CRM_URL` | — | URL do serviço de CRM para consultas de contraparte. |
| `CRM_CLIENT_ID` | — | Client ID OAuth para o M2M do CRM. |
| `CRM_CLIENT_SECRET` | 🔒 — | Client secret OAuth para o M2M do CRM. |
## Participantes indiretos
Relevante apenas se este deploy liquida Pix em nome de outras instituições.
| Variável | Padrão / Obrigatório | Descrição |
| ----------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INDIRECTS_DELIVERY_ENCRYPTION_KEY` | 🔒 **Obrigatório** para hospedar participantes indiretos | Chave AES-256 que criptografa em repouso o segredo de entrega de cada participante indireto. Exatamente 64 caracteres hexadecimais (32 bytes), de `openssl rand -hex 32`. Sem padrão. |
Sem essa chave, **todo** registro de participante indireto é recusado com `409 PIX-0107` — e recusado antes de qualquer escrita, então nenhum segredo em texto puro chega a ser armazenado. Um valor ausente, em branco ou malformado produz a mesma recusa: não há padrão nem degradação para guardar o segredo aberto. O `409` significa "provisione o valor", não "tente de novo": o irmão dele que aceita nova tentativa é `503 PIX-0123`, que é o que responde uma chave que não pôde ser **lida**.
O trilho sobe sem ela. A inicialização registra um aviso e o processo fica saudável, então o sintoma aparece no primeiro registro, não no deploy. Ela é lida na inicialização, então uma mudança exige um reinício.
Veja [Hospedagem de participantes indiretos](/pt/interfaces/pix-jd/hosting-indirect-participants) para o onboarding que essa chave destrava.
## Configuração em tempo de execução (systemplane)
Este trilho monta a API de administração do systemplane na porta principal dele, controlada por `SYSTEMPLANE_ENABLED`.
| Variável | Padrão / Obrigatório | Descrição |
| --------------------- | -------------------- | ------------------------------------------------------------------------------------ |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita a API de administração de configuração em tempo de execução do systemplane. |
Quando habilitada, o serviço expõe um plano autenticado para ler e escrever configuração em tempo de execução. Veja [Systemplane](/pt/reference/platform/systemplane/overview) para a API, os namespaces e as permissões necessárias.
Vários valores de que este trilho precisa são alcançáveis **apenas** por esse plano, nos dois modos de deploy, e um deploy que os deixa sem valor sobe saudável e recusa dinheiro:
| Chave de systemplane | O que ela carrega | Sem valor |
| ---------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------- |
| `tenancy/jd_integration_binding` | o seu próprio ISPB, no campo `ispb` de uma **string** JSON | `409 PIX-0092` em toda rota de dinheiro |
| `tenant_policy/routing..operation_{credit,debit}_route` | as vinte pernas de rota contábil | `409 PIX-0105` nos fluxos que usam o perfil ausente |
| `tenant_policy/transaction_limits.daily_period_{init,end}` | a janela do limite diário | a contabilização do limite fica sem janela |
| `plugin-br-pix-jd.indirects/enabled` | se este tenant hospeda participantes indiretos | a resolução de indiretos fica desligada |
Com `SYSTEMPLANE_ENABLED=false` o grupo de rotas `/system` sequer é montado, então toda escrita de configuração responde `404`, e um caminho de dinheiro que não consegue ler a configuração responde o `503 PIX-0051`, que aceita nova tentativa, em vez de uma recusa de provisionamento. A permissão do lado de escrita é `systemplane:write`; sem ela as escritas respondem `403`.
[Configuração do trilho](/pt/interfaces/pix-jd/pix-jd-setup) percorre cada uma dessas chaves, com o corpo exato que cada escrita recebe e como confirmar que ela foi aplicada.
## Health e readiness
O trilho expõe `GET /health` (liveness) e `GET /readyz` (readiness) na porta principal, mais `/metrics` e `/version`. Veja [Health e readiness](/pt/reference/health-and-readiness) para o formato da resposta e o comportamento de inicialização e drenagem.