Variáveis de ambiente

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.

​

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.

​

Conexões sem TLS

​

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

​

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

​

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

​

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.<profile>.operation_credit_route e tenant_policy/routing.<profile>.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.<profile>.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. Para os perfis, os nomes exatos das chaves e como escrevê-las, veja Configuração do trilho.

​

Jobs

​

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

​

Notificações

Notificações opcionais ao cliente final para eventos de Pix. Deixe os blocos de provedor sem valor para desabilitar aquele canal.

​

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

​

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: 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 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. 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 (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.

​

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. 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 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: Configuração do trilho mostra cada uma dessas chaves, o corpo exato de cada escrita e como confirmá-la.

​

Chamadas da JD sem o JD Courier

Para os passos, veja Dê à JD a credencial dela.

​

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

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

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, 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. 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. 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 para o formato da resposta.