Skip to main content
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.
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 para os controles de servidor compartilhados e Portas de rede padrão.

​
Integração com a JD

Credenciais e endpoints da API protegida por OAuth da JD e da superfície Pix (JDPI) dela.
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.

​
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; as variáveis abaixo definem as partes que este deploy controla.

​
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.
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.
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.

​
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.<profile>.operation_credit_route e tenant_policy/routing.<profile>.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.

​
Jobs e limites

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.

​
CRM

​
Participantes indiretos

Relevante apenas se este deploy liquida Pix em nome de outras instituições.
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 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. Quando habilitada, o serviço expõe um plano autenticado para ler e escrever configuração em tempo de execução. Veja Systemplane 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:
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 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 para o formato da resposta e o comportamento de inicialização e drenagem.