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

> Variáveis de ambiente definidas no deploy do rail Pix Direto, via JD — integração com a JD, hospedagem de QR dinâmico, vínculo com o ledger Midaz, rotas de transação e notificações.

O Pix Direto, via JD conecta seu ledger diretamente ao arranjo Pix através do gateway DICT e SPI da JD. Seu comportamento é configurado através de variáveis de ambiente definidas no momento do deploy pela equipe de DevOps; alterar uma exige uma reinicialização do serviço. Esta página cobre as variáveis **distintivas deste rail** — para os parâmetros de datastore, multi-tenancy, streaming, telemetria e autenticação compartilhados entre todos os serviços Go da Lerian, consulte a [referência de configuração BYOC](/pt/reference/byoc-configuration).

<Note>
  Nas tabelas abaixo, a coluna **Padrão / Obrigatória** mostra o valor padrão; um qualificador em negrito (por exemplo **Obrigatória**) marca variáveis que você deve definir. `—` significa que não há padrão. `🔒` marca um **segredo** — injete-o no momento do deploy a partir do seu secret store, nunca faça commit dele. Esta página lista apenas nomes de variáveis e comportamento; ela não imprime nenhum valor de segredo.
</Note>

## Servidor e porta

O serviço escuta no endereço em `SERVER_ADDRESS` (padrão `:8080`). As probes de liveness, readiness e version se vinculam a essa mesma porta. Consulte [Servidor](/pt/reference/byoc-configuration#servidor) para os parâmetros de servidor compartilhados e [Portas de rede padrão](/pt/reference/default-network-ports).

## Integração com a JD

Credenciais e endpoints para a API da JD protegida por OAuth e sua superfície Pix (JDPI).

| Variável                   | Padrão / Obrigatória | Descrição                                                         |
| -------------------------- | -------------------- | ----------------------------------------------------------------- |
| `JD_BASE_URL`              | **Obrigatória**      | URL base da API da JD.                                            |
| `JD_CLIENT_ID`             | **Obrigatória**      | OAuth client ID para a API da JD.                                 |
| `JD_SECRET`                | 🔒 **Obrigatória**   | OAuth client secret para a API da JD.                             |
| `JD_GRANT_TYPE`            | `client_credentials` | Tipo de grant OAuth usado contra a JD.                            |
| `JD_BANK_ID`               | **Obrigatória**      | Seu identificador de instituição na JD.                           |
| `JD_USE_SERVICE_SEGMENTS`  | `false`              | Roteia chamadas através dos service segments da JD quando `true`. |
| `JD_PIX_URL`               | **Obrigatória**      | URL base da API Pix (JDPI) da JD.                                 |
| `JD_PIX_CLIENT_ID`         | **Obrigatória**      | OAuth client ID para a API Pix da JD.                             |
| `JD_PIX_CLIENT_SECRET`     | 🔒 **Obrigatória**   | OAuth client secret para a API Pix da JD.                         |
| `JDPI_MAX_RETRIES`         | `2`                  | Tentativas de retry em uma chamada JDPI falha.                    |
| `JDPI_RETRY_BASE_DELAY_MS` | `100`                | Atraso base de backoff em milissegundos entre retries JDPI.       |

## Hospedagem de QR code dinâmico

O rail hospeda payloads de QR dinâmico assinados (JWS) e o JWK set usado para verificá-los. `QRCODE_PUBLIC_BASE_URL` é a base acessível externamente sob a qual esses documentos são servidos.

| Variável                   | Padrão / Obrigatória       | Descrição                                                                  |
| -------------------------- | -------------------------- | -------------------------------------------------------------------------- |
| `QRCODE_PUBLIC_BASE_URL`   | **Obrigatória**            | URL base pública onde os payloads de QR dinâmico e o JWK set são servidos. |
| `QRCODE_PAYLOAD_PATH`      | **Obrigatória**            | Segmento de path onde os payloads de QR assinados são expostos.            |
| `QRCODE_JWK_PATH`          | **Obrigatória**            | Segmento de path onde o JWK set é exposto.                                 |
| `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 JWK set.                                   |

## Vínculo com o ledger Midaz

Qual organização, ledger, asset e conta externa do Midaz este rail usa para contabilizar movimentos Pix, além dos endpoints do serviço de ledger e das credenciais machine-to-machine.

| Variável                | Padrão / Obrigatória | Descrição                                               |
| ----------------------- | -------------------- | ------------------------------------------------------- |
| `MIDAZ_ORGANIZATION_ID` | **Obrigatória**      | UUID da organização Midaz que detém o ledger Pix.       |
| `MIDAZ_LEDGER_ID`       | **Obrigatória**      | UUID do ledger Midaz para contabilizações Pix.          |
| `MIDAZ_ASSET_ID`        | **Obrigatória**      | Asset (moeda) contabilizado para operações Pix.         |
| `MIDAZ_EXTERNAL_ID`     | **Obrigatória**      | Conta externa usada como contraparte de liquidação Pix. |
| `MIDAZ_URL_ONBOARDING`  | **Obrigatória**      | URL do serviço de onboarding do Midaz.                  |
| `MIDAZ_URL_TRANSACTION` | **Obrigatória**      | URL do serviço de transações do Midaz.                  |
| `MIDAZ_AUTH_ADDRESS`    | —                    | URL do Access Manager para tokens M2M do Midaz.         |
| `MIDAZ_CLIENT_ID`       | —                    | OAuth client ID para M2M do Midaz.                      |
| `MIDAZ_CLIENT_SECRET`   | 🔒 —                 | OAuth client secret para M2M do Midaz.                  |
| `MIDAZ_TIMEOUT`         | `30000`              | Timeout de requisição Midaz em milissegundos.           |

## Rotas de transação e operação

Os fluxos Pix de cash-in, cash-out, estorno e intra-PSP são mapeados em rotas nomeadas de transação e operação do Midaz. Defina um valor por fluxo para que o plugin contabilize cada evento Pix na rota correta.

| Variável                                                                                             | Padrão / Obrigatória | Descrição                                                                                                  |
| ---------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------- |
| `TRANSACTION_ROUTE_CASHIN` · `TRANSACTION_ROUTE_CASHIN_QRCODE` · `TRANSACTION_ROUTE_CASHIN_REVERSAL` | **Obrigatória**      | IDs de transaction-route para a família de cash-in (padrão, QR code, estorno).                             |
| `TRANSACTION_ROUTE_CASHOUT` · `TRANSACTION_ROUTE_CASHOUT_REVERSAL`                                   | **Obrigatória**      | IDs de transaction-route para a família de cash-out.                                                       |
| `TRANSACTION_ROUTE_INTRAPSP` · `TRANSACTION_ROUTE_INTRAPSP_REVERSAL`                                 | **Obrigatória**      | IDs de transaction-route para transferências intra-PSP e seus estornos.                                    |
| `OPERATION_ROUTE_CASHIN_*`                                                                           | **Obrigatória**      | IDs de operation-route para cada leg de cash-in (crédito, débito, QR code, externa, variantes de estorno). |
| `OPERATION_ROUTE_CASHOUT_*`                                                                          | **Obrigatória**      | IDs de operation-route para cada leg de cash-out (crédito, débito, externa, variantes de estorno).         |

<Note>
  `OPERATION_ROUTE_CASHIN_*` e `OPERATION_ROUTE_CASHOUT_*` representam exatamente doze variáveis concretas de mapeamento de rota por leg (oito de cash-in, quatro de cash-out). Cada uma mapeia um leg do pipeline para um ID de operation-route do Midaz; defina cada uma explicitamente:

  **Cash-in (8):** `OPERATION_ROUTE_CASHIN_CREDIT`, `OPERATION_ROUTE_CASHIN_CREDIT_QRCODE`, `OPERATION_ROUTE_CASHIN_CREDIT_REVERSAL`, `OPERATION_ROUTE_CASHIN_DEBIT`, `OPERATION_ROUTE_CASHIN_DEBIT_QRCODE_EXTERNAL`, `OPERATION_ROUTE_CASHIN_DEBIT_REVERSAL_EXTERNAL`, `OPERATION_ROUTE_CASHIN_REVERSAL_CREDIT`, `OPERATION_ROUTE_CASHIN_REVERSAL_DEBIT`

  **Cash-out (4):** `OPERATION_ROUTE_CASHOUT_CREDIT_EXTERNAL`, `OPERATION_ROUTE_CASHOUT_CREDIT_REVERSAL`, `OPERATION_ROUTE_CASHOUT_DEBIT`, `OPERATION_ROUTE_CASHOUT_DEBIT_REVERSAL_EXTERNAL`
</Note>

## Jobs e limites

| Variável                                                                     | Padrão / Obrigatória | Descrição                                                                                   |
| ---------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------- |
| `JOBS_CRON`                                                                  | `*/10 * * * * *`     | Expressão cron para o job de reconciliação/housekeeping.                                    |
| `JOBS_CRON_TRANSACTIONS`                                                     | —                    | Expressão cron para o job de processamento de transações.                                   |
| `JOBS_RECONCILE_STUCK_THRESHOLD_SEC`                                         | —                    | Idade em segundos após a qual uma transação pendente é tratada como travada e reconciliada. |
| `TRANSACTION_LIMIT_DAILY_PERIOD_INIT` · `TRANSACTION_LIMIT_DAILY_PERIOD_END` | —                    | Início e fim da janela diária usada para a contabilização de limite de transação.           |
| `MAX_PAGINATION_LIMIT` · `MAX_PAGINATION_MONTH_DATE_RANGE`                   | —                    | Limites superiores para o tamanho de página de listagem e o intervalo de datas.             |

## Notificações

Notificações opcionais ao cliente final para eventos Pix. Deixe os blocos de provider não definidos para desabilitar aquele canal.

| Variável                 | Padrão / Obrigatória | Descrição                                                  |
| ------------------------ | -------------------- | ---------------------------------------------------------- |
| `SENDGRID_API_KEY`       | 🔒 —                 | Chave de API do SendGrid para notificações por email.      |
| `SENDGRID_FROM_EMAIL`    | —                    | Endereço remetente para notificações por email.            |
| `SENDGRID_FROM_TEMPLATE` | —                    | ID do template do SendGrid usado para o corpo da mensagem. |
| `TWILIO_ACCOUNT_SID`     | 🔒 —                 | SID de conta do Twilio para notificações por SMS.          |
| `TWILIO_AUTH_TOKEN`      | 🔒 —                 | Auth token do Twilio para notificações por SMS.            |
| `TWILIO_PHONE_NUMBER`    | —                    | Número de telefone remetente para notificações por SMS.    |

## CRM

| Variável            | Padrão / Obrigatória | Descrição                                         |
| ------------------- | -------------------- | ------------------------------------------------- |
| `CRM_URL`           | —                    | URL do serviço CRM para consultas de contraparte. |
| `CRM_CLIENT_ID`     | —                    | OAuth client ID para M2M do CRM.                  |
| `CRM_CLIENT_SECRET` | 🔒 —                 | OAuth client secret para M2M do CRM.              |

## Configuração de runtime (systemplane)

Este rail monta a API de administração do systemplane em sua porta principal, controlada por `SYSTEMPLANE_ENABLED`.

| Variável              | Padrão / Obrigatória | Descrição                                                                  |
| --------------------- | -------------------- | -------------------------------------------------------------------------- |
| `SYSTEMPLANE_ENABLED` | `false`              | Habilita a API de administração de configuração de runtime do systemplane. |

Quando habilitado, o serviço expõe um plano autenticado para ler e gravar a configuração de runtime. Consulte [Systemplane](/pt/reference/systemplane/overview) para a API, os namespaces e as permissões necessárias.

## Saúde e prontidão

O rail expõe `GET /health` (liveness) e `GET /readyz` (readiness) na porta principal, além de `/metrics` e `/version`. Quando a multi-tenancy está habilitada (`MULTI_TENANT_ENABLED=true`), ele adiciona uma probe por tenant protegida por auth em `GET /readyz/tenant/{id}`. Consulte [Saúde e prontidão](/pt/reference/health-and-readiness) para o formato da resposta e o comportamento de startup/drain.