O roteiro
- Confira os pré-requisitos e garanta o acesso de quem vai fazer a configuração.
- Configure a assinatura das ordens de pagamento, apenas se a JD a exigir para a sua instituição.
- Provisione o ledger e os registros de titular no Midaz e no CRM.
- Crie as rotas contábeis no Midaz.
- Configure o trilho: as configurações do plugin.
- Envie o pagamento que cria as linhas de limite.
- Prove que a configuração está completa, até uma chave Pix registrada.
- Adicione as capacidades opcionais de que a sua instituição precisa.
Passo 1: Confira os pré-requisitos
Você usa três endereços. Não os confunda.-
O plugin Pix rodando. A API de configurações do plugin precisa estar habilitada (
SYSTEMPLANE_ENABLED=true). Sem ela, toda chamada de configuração do passo 5 responde404. No SaaS, a Lerian a habilita. -
Em um deploy self-hosted em que a declaração de permissões do Pix JD não está publicada, estas permissões nos papéis do Pix no Access Manager:
entries-lookup(açãoget), para a rota de consulta de chave.parked-credits(açãopost), para as rotas de crédito em espera.- Com o JD Courier,
courier-ownership(açãopost), para a rota de propriedade do Courier.
403. Depois que a declaração é publicada, os papéis que ela declara têm essas permissões. - Um bearer token para o Midaz e um para o plugin, emitidos pelo Access Manager. Eles podem vir de audiences diferentes.
- A credencial da JD, quando a JD chama o plugin sem o JD Courier. Veja Dê à JD a credencial dela.
-
O acesso certo para quem vai fazer a configuração. O passo de acesso abaixo lista os grupos. Sem ele, as chamadas respondem
403. - O ISPB da sua instituição: o identificador do seu credenciamento no BACEN, 8 letras maiúsculas ou dígitos.
Garanta o acesso de quem vai fazer a configuração
Por que este passo existe. Configurar o Pix mexe em dois produtos: o Midaz, com o cadastro de titulares (CRM), e o próprio plugin Pix JD. Cada um confere a sua própria permissão. Sem ela, a chamada responde403 e nada é gravado.
Se você é administrador, já tem tudo. O grupo Administrator (admin-group) tem acesso completo aos dois produtos. Siga para o próximo passo.
Para que outra pessoa faça a configuração sem ser administradora, coloque essa pessoa nos grupos abaixo pelo Access Manager, no console ou por Update a User. É o acesso mínimo que cobre todos os passos desta página:
plugin-br-pix-jd-contributor-group) basta. Ele não altera a configuração do Pix, então um erro de operação não muda o roteamento do seu dinheiro. Para quem só consulta, use Plugin PIX JD Viewer (plugin-br-pix-jd-viewer-group).
Prove que o acesso está certo antes de seguir. Com o token da pessoa:
GET /system/-/catalogdeve responder200.- A primeira escrita em
/system, a do vínculo de integração no passo 5, deve responder204 No Content. Um403ali significa que a pessoa não está no grupo Plugin PIX JD Editor.
Dê à JD a credencial dela
Por que este passo existe. A JD chama o plugin para o Pix recebido e para os fluxos do Pix Automático. Essas rotas aceitam quatro credenciais: a credencial do JD Courier, a aplicação existente da JD com a origemjd-consultores, uma aplicação que você lista para a JD, e um parceiro que tem as permissões de canal da JD. Qualquer outro chamador recebe 403 PIX-0005.
Atrás do JD Courier, a JD não precisa de credencial sua. O Courier chama o plugin com a credencial dele. No modo multi-tenant, o Tenant Manager a emite. No modo single-tenant, um administrador a emite com Emitir uma credencial de serviço, com a origem jd-courier e o destino plugin-br-pix-jd. Essa chamada responde 422 enquanto a declaração de permissões do Pix JD não está publicada.
Uma aplicação existente com a origem jd-consultores continua funcionando. Você não precisa de mais nada para ela.
A JD também pode chamar como parceiro do seu tenant. Veja A JD como parceiro.
Para listar uma aplicação para a JD, sem o JD Courier:
- Defina
AUTH_M2M_INVERSION_ENABLED=trueeAUTH_M2M_PRODUCT_FORWARD_ENABLED=trueno plugin. Defina as duas juntas. Só com a primeira, o plugin recusa o JD Courier com403. Na Lerian Cloud, a Lerian as define. - No Access Manager, crie uma aplicação com o destino
plugin-br-pix-jde sem origem. - Escreva o client ID dela na chave do plugin
tenant_policy/jd.direct_client_ids. Uma pessoa do Plugin PIX JD Editor, ou um administrador, precisa fazer a escrita. Um token de aplicação recebe403. UmPUTsubstitui a lista inteira, então leia a chave primeiro e envie todo client ID que precisa continuar, separados por vírgulas. - Entregue à JD o client ID e o secret.
403 PIX-0005 em toda rota que a JD não chama.
Passo 2: Configure a assinatura das ordens de pagamento, se a JD a exigir
A JD pode exigir uma assinatura em cada ordem de pagamento da sua instituição. Confirme isso com a JD. Se a JD a exigir, siga Assinatura da ordem de pagamento agora, antes de qualquer pagamento. Se a JD não a exigir, pule este passo.Passo 3: Provisione o ledger e os registros de titular
Estes passos rodam contra o Midaz e o CRM dele. Eles criam as contas em que o trilho lança e os registros de titular de onde ele lê as contrapartes. Acesso: Midaz Editor.Crie a organização e o ledger
201 sem id no corpo não é sucesso. Nada consegue endereçar o novo objeto, nem você nem uma limpeza posterior. Pare aí. Não leve um id vazio para o passo seguinte.Crie o ativo BRL e espere ele aparecer
BRL.201 quanto 409 são boas respostas. Um ledger endereça um ativo pelo código dele, então “já existe” significa o mesmo que sucesso.Duas coisas acontecem aqui:- O ledger começa a aceitar contas naquele ativo. Antes disso, ele recusa toda conta com
0034 Asset Code Not Found. - O Midaz cria a conta
@external/BRLjunto com o ativo. Ela é a única conta em um livro que você pode debitar antes de qualquer crédito. O saldo inicial vem dela. Ela também é a contraparte de toda liquidação com o mundo externo.
Crie uma conta por papel
accountId das chamadas de negócio que você faz ao plugin. O alias (@payer) é o nome curto pelo qual o livro lê e lança. Ele volta no passo seguinte.Crie o titular no CRM
documentdeve ser um CPF ou CNPJ válido, com os dígitos verificadores corretos.typesegue o tamanho do documento. UseNATURAL_PERSONpara um CPF (11 dígitos) eLEGAL_PERSONpara um CNPJ (14). O plugin converte esse tipo no número que vai para a JD. Um tipo errado registra a parte como o tipo errado de pessoa.externalIdguarda o alias da conta no ledger (@payer). O CRM o chama de identificador externo de correlação, então ele parece opcional. Para este trilho não é. Um registro de chave Pix para um titular semexternalIdresponde422 PIX-0108.addresses.primary.cityé obrigatório para QR codes e Pix Automático. É a cidade do recebedor no código. Sem ela, o plugin se recusa a gerar um QR e responde422 PIX-0033parapayee.city. Nenhum caminho de pagamento lê o campo, então a ausência dele aparece apenas quando alguém gera um QR.
Vincule o titular à conta
Coloque saldo nas contas
@external/BRL, que o Midaz criou junto com o ativo, dois passos acima.@external/BRL tem dois usos. Um é a posição de liquidação @pi de um participante indireto hospedado. O outro é um ambiente de teste ou homologação, onde nenhum Pix real chega. Veja O modelo direto e indireto para saber o que cada posição é.@external/BRL em um corpo, mas não em um caminho. O alias contém uma barra, e a rota do ledger não a decodifica. Uma leitura de saldo por caminho responde 404 ou um 200 vazio. Lançar a partir dela é normal. Lê-la desse jeito não é.Passo 4: Crie as rotas contábeis
Cada caminho de dinheiro neste trilho tem o próprio par de rotas de operação do Midaz: uma perna de crédito e uma perna de débito. O passo 5 guarda os UUIDs das rotas no plugin. Acesso: Midaz Editor. Quais pares você precisa. Você não cria um par para cada perfil. Crie um par para cada um dos seis perfis de pagamento. Os outros perfis reutilizam um par, ou ficam vazios:in. Um débito de MED e um débito do Pix Automático tiram dinheiro, como out.
Crie cada perna com uma chamada:
{"id": "..."}. Guarde cada id com o perfil e a perna dele. O passo 5 os escreve.
Procure uma rota pelo título antes de criá-la. Com duas rotas do mesmo título, a busca seguinte pode escolher qualquer uma das duas. Se você provisiona o mesmo livro mais de uma vez, liste primeiro.
Se o seu ledger valida rotas, crie também uma rota de transação do Midaz por perfil que você usa. Um ledger que valida rotas recusa um lançamento que não nomeia nenhuma rota de transação. Veja Entidades de roteamento de transações para saber como criar uma.
Passo 5: Configure o trilho
O plugin guarda a configuração viva dele no systemplane dele. Você escreve esses valores pela API de administração, e eles passam a valer sem um novo deploy e sem um reinício. Toda escrita é umPUT para /system/<namespace>/<key> com um corpo {"value": ...}. Um sucesso responde 204 No Content, sem corpo.
O tenant vem do bearer validado, nunca da URL nem do corpo.
Acesso: toda escrita abaixo exige Plugin PIX JD Editor. Esses valores decidem com qual instituição o plugin se apresenta à JD e em quais contas ele lança, então apenas esse grupo e os administradores podem alterá-los. Qualquer grupo do Pix JD pode lê-los.
GET /system/-/catalog lista cada chave com o tipo e a descrição dela, e GET /system/-/catalog/<namespace>/<key> descreve uma chave. O catálogo é a fonte da verdade. Esta página é uma cópia dele, e cópias envelhecem.Escreva o vínculo de integração com a JD
tenancy/jd_integration_binding, sem fallback por ambiente. Enquanto a chave está vazia, o plugin sobe e responde à health probe dele. Ele recusa todo pagamento em toda rota de dinheiro.O que quebra sem ele. 409 PIX-0092, “Tenant Pix integration not provisioned”. O texto da resposta pede que você contate o suporte e não nomeia a chave. Procure pelo código.O valor é um documento JSON dentro de uma string. O corpo é sempre {"value": ...}. Aqui value não é um objeto. É uma string, e o conteúdo dela é um documento JSON. O plugin o armazena com as aspas internas escapadas:jq fazer o escaping:organizationId ou ledgerId está ausente ou inutilizável, o plugin recusa todo lançamento, devolução e crédito de entrada com 409 PIX-0106.value volta como um objeto e não como uma string entre aspas, você escreveu a forma errada. Se volta "", a escrita não aconteceu. Confira o código de status do PUT. A prova real é que as rotas de dinheiro param de responder 409 PIX-0092.Você não consegue armazenar um ISPB malformado por esta rota. O validador de escrita usa o mesmo decodificador que a leitura. Ele recusa na hora um ISPB de 7 dígitos ou um UUID quebrado, com 400 validation_error. Você não descobre o erro no primeiro pagamento.409 PIX-0121, “Tenant Pix integration ISPB invalid”, quando segue esta página. Esse código significa que o vínculo existe e o ispb dele não tem 8 letras maiúsculas ou dígitos, e esta rota não consegue criar esse estado. Ele aparece apenas quando um valor chegou à chave por outro caminho. Exemplos são uma escrita direta no banco de dados do plugin, ou uma escrita de antes do validador. A mensagem dele nomeia tanto a chave quanto o campo a corrigir.409 PIX-0092. Não faça isso em um ambiente que paga.Confira a conexão com a JD
200 com a lista de participantes, como esta (resumida), prova que o plugin chegou à JD e recebeu o catálogo de participantes:Escreva as chaves de roteamento
tenant_policy. Cada uma guarda uma string: o UUID de uma rota que existe no Midaz.409 PIX-0105: enviado, recebido, QR code e entre as suas próprias contas. Uma perna ausente de MED ou do Pix Automático recusa apenas aquele fluxo. A exceção é refund_sent. Enquanto as duas pernas dele estiverem vazias, o trilho lança uma devolução que você envia nas rotas de out.204. Se você não usa MED ou Pix Automático, deixe os perfis deles vazios. Esse fluxo então recusa, o que é melhor do que um lançamento em uma rota indefinida.A rota de transação de cada perfil. Cada perfil também tem uma chave opcional, tenant_policy/routing.<profile>.transaction_route. Preencha-a quando o seu ledger valida rotas. O plugin então nomeia essa rota de transação em cada lançamento do perfil. Sem ela, esse ledger recusa o lançamento, e o plugin responde PIX-4011. Quando o seu ledger não valida rotas, deixe essas chaves vazias.Defina o ativo de lançamento e a conta de compensação
tenant_policy guardam esses valores, nos dois modos de deploy:409 PIX-0106, “Tenant ledger configuration missing”. A resposta nomeia os campos do vínculo e as duas chaves. Esse código não é PIX-0105. Um tenant pode ter todas as pernas de rota e ainda recusar todo lançamento, porque o ativo ou a conta de compensação está vazio.As variáveis de deploy MIDAZ_ASSET_ID e MIDAZ_EXTERNAL_ID não existem mais. O plugin as ignora.Defina a janela diária
400. O plugin não o ajusta ao limite.Declare se este deploy hospeda participantes indiretos
plugin-br-pix-jd.indirects/enabled declara o que o tenant é. Um participante direto simples define o valor como false.{"value":"true"} responde 400. Se este deploy liquida Pix para outras instituições, o passo 8 define o valor como true.Passo 6: Crie as linhas de limite de transação com um pagamento pequeno
O produto não tem rota para criar o que este passo precisa. O que você espera. Você provisiona uma conta e lê o limite disponível dela. O que acontece.GET /v1/limits/available responde 404 PIX-0063, “The specified transaction limit was not found in the system. Please verify the identifier and try again.” GET /v1/limits responde {"data":[]}. A conta parece quebrada, mas não está. Este é o estado inicial normal de uma conta que nunca enviou um pagamento.
PIX-0063 nomeia o que o plugin consultou. A lista de erros mostra a forma genérica dele, “The specified entity was not found in the system”. Esta rota coloca transaction limit nela. O código e o 404 continuam os mesmos.
Por que você não pode criar as linhas. Não existe rota de criação. PATCH /v1/limits atualiza linhas que já existem. Apenas a verificação de limite de um pagamento de saída cria as linhas. Quando uma conta envia o primeiro pagamento, o plugin não encontra linhas. Ele cria os padrões, lê de novo e continua.
Então envie um pagamento pequeno de saída. Um centavo basta.
Acesso: o pagamento exige Plugin PIX JD Contributor ou Plugin PIX JD Editor. Alterar um limite depois com PATCH /v1/limits exige o mesmo.
Como conferir. GET /v1/limits muda de {"data":[]} para uma lista. /v1/limits/available muda de 404 para 200.
Faça este passo depois de todos os passos acima. O pagamento deve ser lançado, então ele precisa de todos os valores dos passos 3 a 5. Sem uma rota, por exemplo, ele falha com PIX-0105.
Passo 7: Prove que a configuração está completa
Rode estas verificações em ordem. Cada uma falha por um motivo diferente. Isso torna a sequência mais útil do que um único teste de fumaça.- O ledger aceita uma conta. Crie uma conta descartável e apague-a. Se o livro recusar, a recusa nomeia o elo ausente. Sem esta verificação, o mesmo problema volta depois como “conta não encontrada” dentro de um fluxo de pagamento, a três camadas da causa. Não coloque saldo na conta de teste: o Midaz se recusa a apagar uma conta com saldo. Apagar exige Midaz Editor.
- O vínculo volta na leitura como uma string entre aspas com o seu ISPB, a sua organização e o seu ledger, como mostrado no passo 5.
GET /v1/banksresponde200com a lista de participantes do Pix, como na verificação de conexão do passo 5.- As duas chaves
tenant_policy/midaz.*voltam na leitura com o código do ativo e o alias da conta de compensação. - A consulta de instrumentos retorna a sua conta, filtrada por documento, agência e número da conta.
- Uma rota de dinheiro para de responder
409 PIX-0092e409 PIX-0106. Use a chamada que você já faz. Você não precisa de nenhum aparato de teste. GET /v1/limitsretorna uma lista para a conta que enviou o pagamento do passo 6.- Uma chave Pix é registrada e aparece na lista da conta. Esta verificação passa pelo CRM, pelo vínculo e pelo DICT na JD.
keyType 4 e nenhuma key: o DICT cria o valor da chave. Uma chave aleatória não precisa de código de confirmação, então ela vai para o DICT na primeira chamada. Ela precisa do header X-Idempotency, um texto de no máximo 255 bytes. Um reenvio com o mesmo valor retorna a chave que o DICT já criou:
DELETE /v1/entries/{entryId}.
Passo 8: Adicione as capacidades opcionais
A sua configuração termina no passo 7 se a sua instituição é um participante direto com um livro, e liquida apenas o Pix dos próprios clientes. Caso contrário, continue na página que se aplica:- Vários livros, ou vários participantes diretos em um deploy. Siga Multiorganização e ledgers.
- Liquidar Pix para outras instituições. Siga Hospedagem de participantes indiretos. Ela adiciona a chave de criptografia, a postura de hospedagem, o registro de cada participante indireto, o certificado de QR próprio dele se ele tiver um, e o saldo da posição de liquidação dele.
Como é cada passo pulado
Toda recusa abaixo é um409, menos a de limites. Nenhuma delas se resolve se você esperar. Cada uma se resolve quando você provisiona o valor ausente.
PIX-0092 para, os pagamentos nem sempre passam. Ele é apenas a primeira barreira. Com o vínculo no lugar, uma rota contábil vazia ainda responde PIX-0105. Um ativo ou uma conta de compensação ausente ainda responde PIX-0106. Três códigos têm três causas e três correções diferentes.Não repita um 409. Repita o irmão 503 dele
O status diz se o problema é a sua configuração ou uma indisponibilidade.
Um 409 acima é conhecimento positivo de ausência. O trilho leu a sua configuração e não encontrou nada ali. Apenas um operador pode fornecer o valor, então repetir a requisição traz a mesma resposta. Um cliente que faz novas tentativas com este código entra em loop para sempre. Cada uma dessas respostas nomeia o que definir.
A maior parte dessas condições tem um irmão 503. Ele vale quando o trilho não conseguiu ler a configuração de forma alguma. O trilho não sabe nada sobre o que você provisionou. A resposta nomeia a dependência que falhou, e uma nova tentativa é a ação certa.
PIX-0121 é um caso especial. Você não consegue provocá-lo pela API de administração, porque o validador de escrita recusa um ispb malformado antes de ele ser armazenado. Ele aparece apenas quando um valor chegou à chave por outro caminho. Veja o vínculo no passo 5.detail exato de cada um.
Para onde ir agora
Variáveis de ambiente
Multiorganização e ledgers
Participantes indiretos
Pix Direto via JD
Lista de erros do Pix JD
PIX-NNNN, o status dele e o texto detail da resposta.
