> ## 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, timeouts do JDPI, hospedagem de QR code dinâmico com JWS, as conexões com o Midaz e o CRM, o mapa de propriedade do Courier e as reivindicações, a declaração de permissões e os valores que ficam no systemplane em vez disso. 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, streaming, telemetria e autenticação que todo serviço Go da Lerian compartilha, veja [Fundamentos de configuração BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md). > [!NOTE] > > Estas variáveis descrevem um **deploy BYOC**. Na Lerian Cloud, você não as define. > [!NOTE] > > 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](https://docs.lerian.studio/pt/reference/byoc-configuration.md#server) para os controles de servidor compartilhados e [Portas de rede padrão](https://docs.lerian.studio/pt/reference/default-network-ports.md). ## Conexões sem TLS | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `ALLOW_INSECURE_TLS` | `false` | Defina `true` para que o trilho use endereços `http://`, em todo ambiente. Ela cobre `MIDAZ_URL_TRANSACTION`, `MIDAZ_URL_TRACER`, `PLUGIN_AUTH_HOST` para os tokens de saída, `COURIER_URL` e o `delivery.endpointUrl` de cada participante indireto. No modo multi-tenant, ela também cobre o Tenant Manager e os endereços da JD e do JD Courier de cada tenant. Para o efeito dela nos datastores, veja [Fundamentos de configuração BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md). | > [!WARNING] > > Com `true`, o Pix JD aceita endereços `http://` para essas conexões em todo ambiente, inclusive em produção. O tráfego em uma conexão `http://` não é criptografado, e ele carrega credenciais ou dados Pix. O Pix JD registra um aviso na inicialização quando o valor é `true`. Mantenha o valor `false` quando toda conexão usa https. ## Integração com a JD Credenciais, endpoints, novas tentativas e limites de tempo 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. No modo single-tenant com `ENV_NAME=production`, ela deve ser um endereço `https`. Caso contrário, o serviço não inicia. | | `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` | Como o trilho monta os endereços da JD. Defina `true` quando a JD der a você um endereço de gateway, em que cada serviço da JD tem o próprio segmento de caminho depois de `JD_BASE_URL`. Mantenha `false` quando a JD der a você o endereço direto, em que todo caminho começa com `/jdpi/`. Pergunte à JD qual tipo de endereço você tem. | | `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. | | `JDPI_CALL_TIMEOUT_MS` | `30000` | Limite de tempo de uma tentativa HTTP JDPI, em milissegundos. | | `JDPI_TOTAL_TIMEOUT_MS` | `50000` | Limite de tempo de uma chamada JDPI inteira feita pela API, em milissegundos: o token, cada tentativa e cada espera entre tentativas. | Os dois timeouts valem nos dois modos de deploy. Um valor de `0` ou menor dá o padrão. Mantenha `JDPI_TOTAL_TIMEOUT_MS` abaixo do timeout do seu ingress. Assim, em uma requisição de cliente, quando a JD não responde, a requisição recebe `504 PIX-1051` do trilho, e não um timeout do proxy. > [!WARNING] > > **O seu próprio ISPB não é uma variável de ambiente.** Ele vem da chave de systemplane `tenancy/jd_integration_binding`, campo `ispb`. Não existe fallback por ambiente. > > Enquanto essa chave estiver vazia, o trilho sobe e responde à health probe. Ele recusa **todo** pagamento em **toda** rota de dinheiro com `409 PIX-0092`. Escreva a chave e a próxima requisição passa, sem reinício. Para os passos, veja [Configuração do trilho](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md). ## Assinatura da ordem de pagamento A chave que assina cada ordem de pagamento de saída. Elas são opcionais: você precisa delas apenas quando o seu ambiente JD exige ordens assinadas. A API lê estas variáveis. O worker não lê. | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `JD_PAYMENT_SIGNING_PRIVATE_KEY` | 🔒 — | PEM da chave privada que assina a ordem de pagamento. | | `JD_PAYMENT_SIGNING_CERTIFICATE` | — | PEM do certificado cadastrado no JDPI Cabine para essa chave. | | `JD_PAYMENT_SIGNING_ALGORITHM` | `ECDSA_P256_SHA256` | `ECDSA_P256_SHA256`, `ECDSA_P384_SHA384` ou `RSA_PKCS1_SHA256`. | Deixe as três vazias e o trilho envia ordens sem assinatura. Defina só algumas, ou um valor que não serve, e o trilho recusa cada pagamento para outra instituição com `409 PIX-0136` antes de chamar a JD. Para a chave, o certificado e o JDPI Cabine, veja [Assinatura da ordem de pagamento](https://docs.lerian.studio/pt/interfaces/pix-jd/payment-order-signing.md). ## Hospedagem de QR code dinâmico O trilho hospeda payloads de QR dinâmico assinados (JWS) e o conjunto JWK que os verifica. A [seção de referência de QR codes](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/create-dynamic-qr-code.md) dá os formatos das rotas públicas, a forma do host sem esquema e o limite de 77 caracteres do BACEN para a URL de payload. 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 (FQDN) sem esquema, em que o plugin serve os payloads de QR dinâmico e o conjunto JWK de um participante direto que não tem host próprio. | | `QRCODE_PAYLOAD_PATH` | `qr` | Segmento de caminho em que o plugin serve os payloads de QR assinados. Cada caractere extra usa o mesmo limite de 77 caracteres que o host. | | `QRCODE_JWK_PATH` | `v1/qrcodes/jwks` | Segmento de caminho em que o plugin serve o conjunto JWK. | | `QRCODE_JWS_CONTENT_TYPE` | `application/jose` | `Content-Type` do payload assinado. | | `QRCODE_JWKS_CONTENT_TYPE` | `application/jwk-set+json` | `Content-Type` do conjunto JWK. | > [!WARNING] > > Não mude `QRCODE_PAYLOAD_PATH` depois da entrada em produção. Um QR code impresso ou exibido carrega a URL antiga, e nada a redireciona. Um participante direto pode publicar os QR codes dinâmicos dele em um host próprio. O trilho pega o host dos QR codes dinâmicos de um participante direto da primeira destas fontes que tem valor: 1. O campo `qrPublicBaseUrl` da entrada do participante no [catálogo de organizações](https://docs.lerian.studio/pt/interfaces/pix-jd/multi-organization-and-ledgers.md). Uma entrada com o ISPB de `tenancy/jd_integration_binding` define o host desse participante. 2. Para o participante que `tenancy/jd_integration_binding` nomeia, a chave do systemplane `tenant_policy/qrcodes.public_base_url`. O padrão dela é vazio. 3. `QRCODE_PUBLIC_BASE_URL`. O campo e a chave recebem um host, com um caminho opcional, e sem esquema. Uma escrita recusa um esquema, uma porta, uma query, um fragmento, informações de usuário, um host que não é público e um valor com mais de 37 caracteres. Quando um valor gravado viola essas regras, o trilho recusa criar ou atualizar os QR codes dinâmicos desse participante com `500 PIX-0053`. Quando o trilho não consegue ler a chave, ele os recusa com `503 PIX-0122`. Antes de definir ou mudar o host de um participante: 1. Roteie o caminho de payload e o caminho JWK do novo host (por padrão `/qr/*` e `/v1/qrcodes/jwks/*`) para este serviço, sem nenhum autorizador na frente deles. O PSP do pagador chama essas rotas sem credencial. 2. Mantenha o host antigo em serviço até que os QR codes emitidos nele expirem. Um QR code mantém o host em que foi emitido. Uma atualização de um QR code dinâmico o publica no host atual do participante dele. ## Conexão com o ledger Midaz Os endpoints dos serviços do ledger e as credenciais máquina a máquina. | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `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. | | `MIDAZ_FEE_MODE` | `auto` | A API de transações do Midaz em que o trilho lança. `auto` lê a versão do ledger e usa a API que aplica tarifas do Midaz quando o ledger a tem (Midaz 4.1 ou posterior). `legacy` usa sempre a API anterior. `native` usa sempre a API que aplica tarifas. Qualquer outro valor impede a inicialização. | | `MIDAZ_FEE_MODE_REFRESH` | `5m` | A frequência com que `auto` lê de novo a versão do ledger, como duração Go. Uma leitura que falha mantém o último modo. | | `MIDAZ_URL_TRACER` | — | Endereço do seu Tracer, para a [triagem de créditos de entrada](#inbound-credit-screening). Quando ela está vazia, o trilho não faz a triagem de nenhum crédito. Um endereço malformado impede a inicialização. | > [!NOTE] > > 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](https://docs.lerian.studio/pt/reference/byoc-configuration.md). **A identidade do ledger não é uma variável de ambiente.** Quatro valores dizem ao trilho onde ele lança. Os quatro vêm do systemplane, nos dois modos de deploy: | Valor | Origem no systemplane | | - | - | | a organização do Midaz | `tenancy/jd_integration_binding`, campo `organizationId` | | o ledger do Midaz | `tenancy/jd_integration_binding`, campo `ledgerId` | | o ativo de lançamento, pelo código dele (por exemplo `BRL`) | `tenant_policy/midaz.asset_id` | | a conta externa de compensação, pelo alias dela (por exemplo `@external/BRL`) | `tenant_policy/midaz.external_id` | As duas chaves `tenant_policy` começam vazias. Até você escrever as duas, o trilho recusa todo lançamento, devolução e crédito de entrada com `409 PIX-0106`. Para os passos, veja [Configuração do trilho](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md). > [!WARNING] > > O trilho não lê mais `MIDAZ_ORGANIZATION_ID`, `MIDAZ_LEDGER_ID`, `MIDAZ_ASSET_ID` e `MIDAZ_EXTERNAL_ID`. Um valor deixado em uma delas gera um aviso na inicialização e não tem efeito. ## 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 e uma perna de débito. Os 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`. Não existe fallback por ambiente. Cada perfil também tem uma chave opcional de rota de transação, `tenant_policy/routing..transaction_route`. O trilho envia o valor dela como a rota de todo lançamento daquele perfil. Um ledger Midaz que valida rotas recusa um lançamento sem rota. O trilho então responde `PIX-4011`. Quando a chave está vazia, o lançamento não carrega rota de transação. > [!WARNING] > > As variáveis `TRANSACTION_ROUTE_*` e `OPERATION_ROUTE_*` não existem mais. Um valor remanescente gera um aviso na inicialização e não tem efeito. Uma perna ausente de um dos seis perfis de pagamento recusa todo fluxo de pagamento com `409 PIX-0105`. Uma perna ausente de MED ou do Pix Automático recusa apenas aquele fluxo. Quando um fluxo falha e os outros funcionam, olhe aqui primeiro. Para os perfis, os nomes exatos das chaves e como escrevê-las, veja [Configuração do trilho](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md). ## Jobs | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `JOBS_CRON` | `*/10 * * * * *` | Expressão cron que define com que frequência o worker roda os jobs periódicos dele. | | `JOBS_RECONCILE_STUCK_THRESHOLD_SEC` | `80` | Idade em segundos a partir da qual o trilho reporta um cash-out pendente como travado. | | `JOBS_CLAIM_RECEIVED_POLL_ENABLED` | `false` | Defina `true` para emitir o evento `key.claim-received`. O worker passa então a ler as reivindicações pendentes da JD uma vez por minuto para cada participante. Ele precisa de `OUTBOX_ENABLED=true` e `STREAMING_ENABLED=true`, ou o worker não inicia. | > [!NOTE] > > A janela diária dos limites de transação **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. Cada chave recebe uma hora do relógio de 0 a 23. O trilho ignora as variáveis antigas `TRANSACTION_LIMIT_DAILY_PERIOD_INIT` e `TRANSACTION_LIMIT_DAILY_PERIOD_END`. ## Pix Automático O Pix Automático da JD tem dois passos opcionais que ficam desligados até a sua instituição ligá-los. O débito em si sempre roda. | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `PIX_AUTOMATICO_BLOQUEAR_ENABLED` | `false` | Defina `true` para aceitar o bloqueio que a JD coloca no saldo do pagador antes de um débito do Pix Automático. | | `PIX_AUTOMATICO_ESTORNO_ENABLED` | `false` | Defina `true` para aceitar o estorno de um débito do Pix Automático. | Ligue cada um apenas depois que a sua instituição combinar com a JD o uso daquele passo. O trilho lê os dois na inicialização, então uma mudança exige um reinício. ## Triagem de créditos de entrada O seu Tracer pode julgar os créditos Pix de entrada na validação de conta, síncrona e assíncrona, antes que o trilho os aceite. A chave do systemplane `tenant_policy/tracer.inbound_credit_enabled` liga a triagem para um tenant. O padrão dela é `false`. Quando ela é `true`: * O Tracer julga os créditos que passaram pelas verificações do próprio trilho, apenas com as regras dele. Ele não verifica nem conta limites. * O Tracer não vê estes créditos, e cada um mantém o veredito do próprio trilho: * um crédito cujo pagador é o Bacen * um crédito em que você atende apenas o lado do pagador * um crédito cujos dados de conta não correspondem a nenhuma conta do CRM, ou correspondem a mais de uma * um crédito sem valor * um crédito para um cliente de um [participante indireto](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/indirect-participants.md) * `DENY` e `REVIEW` recusam o crédito com o motivo `DS04`. * Quando o Tracer não consegue responder, o trilho aceita o crédito sem triagem. Isso inclui uma `MIDAZ_URL_TRACER` vazia, um Tracer de uma release do Midaz anterior à 4.3.0 e nenhuma resposta em 1 segundo. * O Tracer recebe o CPF ou o CNPJ e o ISPB do pagador, o valor, a conta do ledger creditada e o `endToEndId`. Ele não recebe nomes. A credencial do Midaz usada pelo trilho também precisa da permissão do Tracer `validations` (ação `post`). Essa triagem não é a verificação do Tracer no ledger. Quando essa verificação recusa o crédito de um Pix recebido, o Pix espera um operador. Veja [Pix recebido que espera um operador](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-pix-via-jd.md#received-pix-that-waits-for-an-operator). ## 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 para o 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` | — | Endereço do Midaz que mantém o CRM, para consultas de contraparte. O trilho lê `GET /version` para escolher a API do CRM. Até a primeira resposta dessa chamada, toda leitura do CRM falha. | | `CRM_CLIENT_ID` | — | Client ID OAuth para o M2M do CRM. | | `CRM_CLIENT_SECRET` | 🔒 — | Client secret OAuth para o M2M do CRM. | ## Mapa de propriedade do Courier Algumas instituições compartilham um ISPB entre dois sistemas core. O JD Courier mantém um mapa de propriedade que diz qual core guarda cada conta. O trilho consulta esse mapa em um único caso. O recebedor de um Pix de saída nomeia o próprio ISPB do participante pagador, e você declara esse ISPB como compartilhado. | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `COURIER_URL` | — | URL base do processo do Courier que roda o papel `admin`. Só esse papel responde à consulta de propriedade. | | `COURIER_CLIENT_ID` | — | O client ID do Courier. | | `COURIER_CLIENT_SECRET` | 🔒 — | O client secret do Courier. | O Pix JD troca `COURIER_CLIENT_ID` e `COURIER_CLIENT_SECRET` com o Access Manager por um token, e envia esse token em cada chamada ao JD Courier. Você declara um ISPB compartilhado no systemplane. A chave `tenant_policy/onus.shared_ispb_gate_enabled` cobre a sua organização padrão, e o padrão dela é `false`. Uma organização no [catálogo de organizações](https://docs.lerian.studio/pt/interfaces/pix-jd/multi-organization-and-ledgers.md) usa o campo `sharedIspbGate` dela. Enquanto a declaração for `false`, o trilho não consulta o mapa. Quando a declaração é `true`, estas recusas se aplicam a um Pix de saída para uma conta no seu próprio ISPB: | Condição | Resposta | | - | - | | `COURIER_URL` está vazia, ou o Courier não dá uma resposta | `503 PIX-0130`. Você pode tentar de novo | | O Courier responde, mas o trilho não consegue usar a resposta. Um processo do Courier em um papel diferente de `admin` dá esse resultado | `502 PIX-0131` | | A agência ou a conta do recebedor no cadastro não consegue formar uma consulta | `422 PIX-0132` | | O mapa não atribui a conta a nenhum core | `422 PIX-0129` | O trilho recusa antes de reservar um saldo, então uma recusa não move dinheiro. Três chaves de systemplane definem os limites de tempo da consulta. Elas valem nos dois modos de deploy: | Chave de systemplane | Padrão | Faixa | O que ela limita | | - | - | - | - | | `tenant_policy/courier.lookup.timeout_ms` | `2000` | 100–30000 | uma tentativa, em milissegundos | | `tenant_policy/courier.lookup.max_retries` | `1` | 0–3 | as novas tentativas depois da primeira tentativa | | `tenant_policy/courier.lookup.total_budget_ms` | `4500` | 100–60000 | todas as tentativas e as esperas entre elas, em milissegundos | ### Pix entre cores Quando o mapa atribui a conta ao outro core, o trilho não envia o Pix ao SPI. Ele retém o valor na conta do pagador contra a conta `@intercore`. Depois, envia o Pix ao outro core pelo [relay do JD Courier](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-engine-integration.md#cross-core-relay): | Resposta do outro core | Resultado | | - | - | | `2xx` | O trilho confirma a retenção. O Pix fica `EXECUTED`. | | Uma recusa: `400`, `404`, `409` ou `422` | O trilho libera a retenção e responde `422 PIX-0145`. | | Nada chegou ao outro core | O trilho libera a retenção e responde `503 PIX-0146`. | | Outra resposta, ou nenhuma resposta | O resultado é desconhecido. O Pix fica `PENDING`, e o trilho envia o mesmo Pix de novo. | Pelo relay, o trilho também recebe os Pix que o outro core envia e as devoluções dos Pix que o trilho enviou. Ele credita o recebedor contra a `@intercore`. Uma devolução de um Pix que o trilho recebeu do outro core volta pelo relay. Antes do primeiro Pix entre cores, crie a conta `@intercore` no ledger. Um Pix ou uma devolução do outro core a debita, então [permita saldo negativo](https://docs.lerian.studio/pt/products/midaz/balance-overdraft.md) no saldo dela. Defina também as rotas dos perfis `cross_core_out`, `cross_core_in`, `cross_core_return_out` e `cross_core_return_in`. Sem as rotas de um perfil, o trilho recusa o fluxo dele com `409 PIX-0105`. ### Reivindicações no Courier Veja [Conectar um motor](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-engine-integration.md). Quando o Courier está configurado, o worker reivindica no Courier as recorrências do Pix Automático que o trilho aceitou como a instituição do pagador. Ele envia até 100 reivindicações em cada passada. Quando uma reivindicação falha, o worker a envia de novo em uma passada posterior. O worker não envia de novo uma reivindicação que o Courier recusa com um conflito. O worker lê as configurações do Courier do mesmo lugar que a API. O worker e a rota abaixo reivindicam cada participante no Courier dele, e pulam um participante que não tem Courier. Antes de o Courier começar a receber o seu Pix, chame [a rota de propriedade do Courier](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/tell-the-jd-courier-which-pix-automatico-traffic-is-this-engine-s.md) (`POST /v1/pix-automatico/courier-ownership`). Ela reivindica as recorrências que já existem e declara os bloqueios do débito e os agendamentos dos pagamentos em andamento. Chame-a de novo depois que o Courier começar a receber o seu Pix, para declarar as etapas abertas entre as duas chamadas. A rota também reivindica de novo as recorrências que o Courier recusou antes. `heldElsewhere` na resposta lista as chaves que o Courier recusou com um conflito. Um operador resolve cada uma. ## 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. | > [!WARNING] > > Sem essa chave, **todo** registro de participante indireto é recusado com `409 PIX-0107`. A recusa vem 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](https://docs.lerian.studio/pt/interfaces/pix-jd/hosting-indirect-participants.md) para o onboarding que exige essa chave. ## Configuração em tempo de execução (systemplane) Este trilho monta a API de administração do systemplane na porta principal dele. `SYSTEMPLANE_ENABLED` a liga. | 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 você a habilita, o serviço expõe um plano autenticado para ler e escrever configuração em tempo de execução. Veja [Systemplane](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md) para a API, os namespaces e as permissões necessárias. O trilho lê vários valores **apenas** desse plano, nos dois modos de deploy. 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 e a sua organização e o seu ledger Midaz padrão, como uma **string** JSON | `409 PIX-0092` em toda rota de dinheiro | | `tenant_policy/midaz.asset_id`, `tenant_policy/midaz.external_id` | o ativo de lançamento e a conta externa de compensação | `409 PIX-0106` em todo lançamento | | `tenant_policy/routing..operation_{credit,debit}_route` | as pernas de rota contábil | `409 PIX-0105` em todo fluxo de pagamento quando falta uma perna dos seis perfis de pagamento, e apenas naquele fluxo para MED e Pix Automático. Uma devolução que você envia é lançada em `out` enquanto `refund_sent` estiver vazio | | `tenant_policy/routing..transaction_route` | a rota de transação opcional de cada perfil | `PIX-4011` apenas quando o ledger valida rotas | | `tenant_policy/transaction_limits.daily_period_{init,end}` | a janela do limite diário | a janela vai das 6 às 20 | | `plugin-br-pix-jd.indirects/enabled` | se este tenant hospeda participantes indiretos | a resolução de indiretos fica desligada | | `tenant_policy/organizations` | o catálogo de organizações e ledgers **adicionais** em que este tenant lança, como uma **string** JSON | o trilho lança apenas na organização e no ledger padrão. Veja [Multiorganização e ledgers](https://docs.lerian.studio/pt/interfaces/pix-jd/multi-organization-and-ledgers.md) | > [!NOTE] > > Com `SYSTEMPLANE_ENABLED=false`, o serviço não monta o grupo de rotas `/system`. Toda escrita de configuração então responde `404`. Um caminho de dinheiro que não consegue ler a configuração responde o `503 PIX-0051`, que aceita nova tentativa, e não uma recusa de provisionamento. A permissão de escrita é `systemplane:write`. Sem ela, as escritas respondem `403`. [Configuração do trilho](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md) mostra cada uma dessas chaves, o corpo exato de cada escrita e como confirmá-la. ## Chamadas da JD sem o JD Courier | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `AUTH_M2M_INVERSION_ENABLED` | `false` | Defina `true` para admitir as aplicações que você lista para a JD em `tenant_policy/jd.direct_client_ids`. Todo token de aplicação passa então a ser autorizado com as próprias permissões. Veja [Controle de acesso no nível do produto](https://docs.lerian.studio/pt/platform/access-manager/product-level-enforcement.md). | | `AUTH_M2M_PRODUCT_FORWARD_ENABLED` | `false` | Defina `true` junto com `AUTH_M2M_INVERSION_ENABLED`. Só com a inversão, o plugin recusa o JD Courier com `403`. | Para os passos, veja [Dê à JD a credencial dela](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md#give-jd-its-credential). ## Declaração de permissões Na inicialização, o serviço pode publicar a declaração de permissões dele no Access Manager. No modo multi-tenant, o Tenant Manager a publica. | Variável | Padrão / Obrigatório | Descrição | | - | - | - | | `IDP_DECLARATION_ENABLED` | `false` | Defina `true` para publicar a declaração de permissões na inicialização. A declaração também publica o catálogo de escopo do Pix JD com a adesão a parceiros. Até o Pix JD publicar um catálogo de escopo, você não pode dar permissões no Pix JD a um [parceiro](https://docs.lerian.studio/pt/platform/access-manager/features/partners/overview). | | `IDP_HOST` | — | URL absoluta `http` ou `https` do serviço Identity do Access Manager. | | `IDP_M2M_CLIENT_ID` | — | O client ID com que o serviço publica. Emita-o com [Emitir uma credencial de serviço](https://docs.lerian.studio/pt/reference/platform/access-manager/issue-a-service-credential.md), com a origem `plugin-br-pix-jd` e o destino `plugin-identity`. | | `IDP_M2M_CLIENT_SECRET` | 🔒 — | O client secret com que o serviço publica. | Com `IDP_DECLARATION_ENABLED=true`, o serviço não inicia quando uma das outras três variáveis está vazia, quando `IDP_HOST` não é válida, ou quando `PLUGIN_AUTH_ENABLED` não é `true`. Quando o Access Manager recusa a publicação ou não responde, o serviço inicia mesmo assim. ## Atualização a partir de uma versão anterior Siga os passos de cada versão por que você passa até a versão que você instala. **Para a 1.4.0.** 1. Em um deploy self-hosted em que a declaração de permissões do Pix JD não está publicada, dê aos papéis do Pix a permissão `parked-credits` (ação `post`). Sem ela, as duas [rotas de crédito em espera](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-pix-via-jd.md#received-pix-that-waits-for-an-operator) respondem `403`. 2. Atualize fora do intervalo 00:00–08:00, horário de Brasília. Os bloqueios e os débitos do Pix Automático rodam nesse intervalo. 3. Uma aplicação existente da JD com a origem `jd-consultores` continua funcionando, e uma instalação atrás do JD Courier não precisa de nenhum passo. Para uma nova integração direta com a JD, veja [Dê à JD a credencial dela](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md#give-jd-its-credential). **Para a 1.3.0.** 1. Se a aplicação da JD não tem a origem `jd-consultores`, liste o client ID dela como [Dê à JD a credencial dela](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md#give-jd-its-credential) descreve, assim que o trilho rodar a 1.4.0. Até você listá-lo, o trilho recusa toda chamada que a JD faz, Pix recebidos incluídos, com `403 PIX-0005`. Com o JD Courier, a credencial do Courier deve ter a origem `jd-courier`. 2. No modo single-tenant com `ENV_NAME=production`, confirme que `JD_BASE_URL` é um endereço `https`. Caso contrário, o serviço não inicia. 3. Confirme que os seus clientes enviam o header `X-Idempotency` quando registram uma chave aleatória (`keyType` `4`). Sem ele, o trilho responde `400 PIX-0061`. 4. Confirme que os seus clientes usam apenas os nomes de campo em inglês. Veja [Nomes de campo em inglês](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-pix-via-jd.md#english-field-names). **Para a 1.2.1.** O trilho não lê mais `MULTI_TENANT_ALLOW_INSECURE_HTTP`. No modo multi-tenant com um Tenant Manager em `http://`, defina `ALLOW_INSECURE_TLS=true` na API e no worker antes da atualização. Caso contrário, o serviço não inicia. Se o seu deploy já define `ALLOW_INSECURE_TLS=true`, o Pix JD 1.2.1 e posteriores também aceitam endereços `http://` para as conexões de [Conexões sem TLS](#connections-without-tls), em todo ambiente. **Para a 1.2.0.** Em um deploy self-hosted, antes da atualização, dê à aplicação que `COURIER_CLIENT_ID` nomeia a permissão `ownership:write` no JD Courier. Onde a declaração de permissões do Pix JD não está publicada, confirme também que os papéis do Pix no Access Manager têm a permissão `courier-ownership` (ação `post`). A rota de propriedade do Courier desta versão precisa de `courier-ownership`, e responde `403` sem ela. Em um deploy single-tenant, defina também as variáveis `CRM_*`, e com o JD Courier as variáveis `COURIER_*`, no worker. Veja [Reivindicações no Courier](#claims-on-the-courier). **Para a 1.1.1.** Nenhum passo é obrigatório. As três variáveis de assinatura da ordem de pagamento são novas e opcionais. Defina-as apenas se a JD exige ordens de pagamento assinadas para a sua instituição. Veja [Assinatura da ordem de pagamento](https://docs.lerian.studio/pt/interfaces/pix-jd/payment-order-signing.md). **Para a 1.1.0.** Em um deploy self-hosted em que a declaração de permissões do Pix JD não está publicada, antes da atualização, confirme que os papéis do Pix no Access Manager têm a permissão `entries-lookup` (ação `get`). A rota de consulta de chave desta versão precisa dela, e responde `403` sem ela. **Para a 1.0.0, a partir do plugin Pix anterior.** 1. Antes da atualização, escreva `tenant_policy/midaz.asset_id` e `tenant_policy/midaz.external_id`. Use os valores de `MIDAZ_ASSET_ID` e `MIDAZ_EXTERNAL_ID`. Sem essas chaves, o trilho atualizado recusa todo lançamento com `409 PIX-0106`. 2. Leia `tenancy/jd_integration_binding` de volta. Confirme que `organizationId` e `ledgerId` nomeiam a organização e o ledger em que este deploy lança. O trilho os lê em toda chamada. 3. Antes de atualizar, defina `MIDAZ_FEE_MODE=legacy` na API e no worker. O padrão é `auto`. Mude o valor para `auto` só depois que as duas condições abaixo forem verdadeiras: * Nenhum pod da versão anterior atende algum tenant. * Você revisou os seus pacotes de tarifas. Um pacote de tarifas sem rota de transação pode cobrar uma tarifa em todo fluxo Pix. Adicione uma entrada `refundSent` ao catálogo de organizações só depois que nenhum pod da versão anterior atender o tenant. 4. Com o streaming de eventos ligado, o serviço não sobe enquanto o outbox dele guardar eventos não entregues em um formato de evento anterior. Entregue esses eventos com o build que os escreveu antes de atualizar. 5. Depois da atualização, remova do seu ambiente as quatro variáveis de identidade `MIDAZ_*`. ## 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](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o formato da resposta. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.