Pular para o conteúdo principal
Um deploy novo do Pix Direto via JD sobe, responde à health probe dele e recusa todo pagamento. Nada está quebrado. O trilho precisa de uma cadeia de objetos antes de poder mover dinheiro. Enquanto eles não existem, ele recusa o pagamento e não adivinha. Esta página mostra essa cadeia como um único roteiro, na ordem em que você age, para um serviço que já está instalado e rodando, com a falha que cada elo ausente causa. A Lerian executa essa configuração com você durante o onboarding. Use a página para saber o que deve existir, o que cada valor significa e como provar que ele foi aplicado.
Na Lerian Cloud, a Lerian roda o serviço. Você entrega à Lerian os valores de assinatura do passo 2, só se a JD os exigir. Todos os outros passos desta página são seus para executar, porque eles criam os seus próprios livros e as suas próprias configurações.
A ordem é uma cadeia de dependências. O Midaz recusa cada elo enquanto o anterior não existe. O passo de limites envia um pagamento, então ele vem depois das configurações. Onde um passo pode rodar em qualquer ordem, a página diz isso.

O roteiro

  1. Confira os pré-requisitos e garanta o acesso de quem vai fazer a configuração.
  2. Configure a assinatura das ordens de pagamento, apenas se a JD a exigir para a sua instituição.
  3. Provisione o ledger e os registros de titular no Midaz e no CRM.
  4. Crie as rotas contábeis no Midaz.
  5. Configure o trilho: as configurações do plugin.
  6. Envie o pagamento que cria as linhas de limite.
  7. Prove que a configuração está completa, até uma chave Pix registrada.
  8. 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. Você também precisa de:
  • 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 responde 404. 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ção get), para a rota de consulta de chave.
    • parked-credits (ação post), para as rotas de crédito em espera.
    • Com o JD Courier, courier-ownership (ação post), para a rota de propriedade do Courier.
    Sem a permissão dela, cada rota responde 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.
Os exemplos abaixo usam estas variáveis de shell. Onde o trilho já tem um nome para um valor, a variável tem esse mesmo nome. Todo UUID, documento e ISPB é um placeholder. Use os valores do seu próprio ambiente.
O Midaz tem uma superfície de onboarding e uma superfície de transação. Quando um endereço serve as duas, dê o mesmo valor às duas variáveis. As chamadas abaixo seguem o objeto que cada uma cria.

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 responde 403 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: Depois da configuração, reduza o acesso. Para a operação do dia a dia (pagamentos, limites, participantes indiretos), Plugin PIX JD Contributor (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/-/catalog deve responder 200.
  • A primeira escrita em /system, a do vínculo de integração no passo 5, deve responder 204 No Content. Um 403 ali 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 origem jd-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:
  1. Defina AUTH_M2M_INVERSION_ENABLED=true e AUTH_M2M_PRODUCT_FORWARD_ENABLED=true no plugin. Defina as duas juntas. Só com a primeira, o plugin recusa o JD Courier com 403. Na Lerian Cloud, a Lerian as define.
  2. No Access Manager, crie uma aplicação com o destino plugin-br-pix-jd e sem origem.
  3. 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 recebe 403. Um PUT substitui a lista inteira, então leia a chave primeiro e envie todo client ID que precisa continuar, separados por vírgulas.
  4. Entregue à JD o client ID e o secret.
Uma aplicação listada recebe 403 PIX-0005 em toda rota que a JD não chama.
Para cortar a JD, exclua a aplicação dela no Access Manager. Remover o client ID da lista não revoga a aplicação. Ela passa a ter o acesso das suas próprias aplicações, Pix enviado incluído.

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.
Faça este passo antes do passo 6. O passo 6 envia um pagamento. Se a JD exige ordens assinadas e a ordem não está assinada, a JD a recusa. Depois de recusas repetidas, a JD bloqueia todos os débitos da sua instituição.

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

Crie a organização e o ledger

A organização é a sua instituição nos livros. O ledger é o livro em que ela lança. Uma instituição pode ter mais de um ledger. Este trilho lança no ledger padrão: o par que você cria aqui e nomeia no vínculo do passo 5. Todo fluxo usa esse par até você declarar mais livros no catálogo de organizações. Para o catálogo, veja Multiorganização e ledgers.
Um 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.
2

Crie o ativo BRL e espere ele aparecer

O ativo é a moeda dos registros. Para Pix ele é BRL.
Tanto 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:
  1. O ledger começa a aceitar contas naquele ativo. Antes disso, ele recusa toda conta com 0034 Asset Code Not Found.
  2. O Midaz cria a conta @external/BRL junto 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.
O 201 chega antes de o ativo aparecer na listagem. Um script que cria o ativo e depois cria uma conta na linha seguinte falha de vez em quando. Faça polling da listagem até o código aparecer, com um prazo:
3

Crie uma conta por papel

Crie uma conta para cada papel que o seu ambiente usa: pagador, recebedor e os outros papéis do seu produto.
Você usa o id da conta duas vezes mais adiante: no vínculo do CRM abaixo e como o 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.
4

Crie o titular no CRM

O titular é o dono da conta. O plugin lê quem é uma contraparte no CRM, não no ledger.
Quatro campos exigem cuidado:
  • document deve ser um CPF ou CNPJ válido, com os dígitos verificadores corretos.
  • type segue o tamanho do documento. Use NATURAL_PERSON para um CPF (11 dígitos) e LEGAL_PERSON para 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.
  • externalId guarda 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 sem externalId responde 422 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 responde 422 PIX-0033 para payee.city. Nenhum caminho de pagamento lê o campo, então a ausência dele aparece apenas quando alguém gera um QR.
5

Vincule o titular à conta

O titular e a conta no ledger existem, mas nada os une ainda. Este passo é a união, que o CRM chama de instrumento. O plugin a usa para descobrir onde creditar um Pix recebido e qual conta um pagamento debita.
Nunca envie bankId como string vazia. Uma string vazia é um valor. Ela registra “esta conta pertence à instituição cujo ISPB é vazio”, o que é pior do que nenhum valor. Se você ainda não tem o ISPB, omita o campo.
Confira o que o CRM registrou, e sempre filtre. Uma consulta sem filtro retorna o primeiro vínculo da organização. É assim que uma verificação pode aprovar a conta de outra pessoa:
6

Coloque saldo nas contas

Uma conta nova tem zero, e você não pode pagar a partir de uma conta vazia. O crédito inicial vem de @external/BRL, que o Midaz criou junto com o ativo, dois passos acima.
Em produção, você não coloca saldo assim na conta de cliente de um participante direto. O dinheiro entra como um Pix real recebido, ou como um aporte que o cliente faz. A carga via @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 é.
Dois corpos idênticos enviados em até 300 segundos fazem um lançamento só. O Midaz colapsa a repetição: o segundo POST responde 201 com o id do primeiro lançamento, e nada se move. Use essa propriedade quando fizer uma nova tentativa.A nova tentativa de uma recarga cuja resposta você perdeu deve enviar o corpo exatamente igual, description incluído, em até 300 segundos. Assim a conta não pode receber dois créditos. Depois dessa janela, leia o saldo da conta antes de enviar a recarga de novo. Mude o description apenas para uma recarga nova. Uma nova description em uma nova tentativa real adiciona um segundo crédito por engano.
Você pode nomear @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: Então o mínimo são seis pares, doze rotas. Um perfil pode reutilizar o par de outro perfil apenas quando o dinheiro se move na mesma direção. Uma devolução de MED e um estorno do Pix Automático trazem dinheiro, como in. Um débito de MED e um débito do Pix Automático tiram dinheiro, como out. Crie cada perna com uma chamada:
Cada chamada retorna {"id": "..."}. Guarde cada id com o perfil e a perna dele. O passo 5 os escreve.
Você pode inverter a direção, e nada avisa você. Um débito sai do pagador, então é a perna source. Um crédito chega, então é a perna destination. Se você trocá-las, todo lançamento continua respondendo sucesso, na direção errada. Nenhum código de status relata isso.
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 é um PUT 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.
Pergunte ao plugin o que ele espera. Não confie em uma cópia. 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.
1

Escreva o vínculo de integração com a JD

O que é. O vínculo é um documento com três campos. O ISPB é o código de 8 caracteres, letras maiúsculas ou dígitos, que identifica a sua instituição no Banco Central. Ele vai em toda mensagem de Pix, e o plugin não consegue assinar como a sua instituição sem ele. Os outros dois campos nomeiam a sua organização e o seu ledger padrão do Midaz, do passo 3.Onde fica. Nenhum dos três é uma variável de deploy. Eles vêm da chave de systemplane 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.
Reiniciar não ajuda. O plugin lê a chave em cada chamada, não no boot. Um deploy sem ISPB continua sem ISPB depois de um reinício. Escreva a chave com a aplicação rodando, e a requisição seguinte passa, sem um novo deploy.
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:
Deixe o jq fazer o escaping:
O vínculo nomeia a sua organização e o seu ledger padrão. Todo fluxo lança nesse par, a menos que resolva outro pelo catálogo de organizações. Se 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.
O decodificador é estrito. Ele recusa um campo desconhecido, e essa recusa interrompe a escrita inteira. Isso inclui o campo antigo routeProfiles, porque as rotas contábeis foram para as chaves routing.* abaixo. Por isso, um documento de uma configuração antiga falha. O decodificador também recusa qualquer coisa depois do primeiro documento JSON.
Como conferir. Leia a chave de volta. Ela não guarda segredo, então o valor volta aberto:
Se 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.
Por isso, você não vê 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.
Um 400 aqui não é um problema de permissão. Uma permissão ausente responde 403. Este 400 significa que o valor está errado. A resposta não diz qual campo, então confira o ISPB primeiro. Esse é o erro mais comum.
O plugin aceita a string vazia, que significa “não provisionado”. Se você a escrever, o deploy volta a 409 PIX-0092. Não faça isso em um ambiente que paga.
2

Confira a conexão com a JD

Por que este passo existe. O vínculo é a última peça de que o plugin precisa para falar com a JD como a sua instituição. Antes de mover qualquer dinheiro, prove que a conversa funciona: peça à JD a lista de participantes do Pix.Acesso: qualquer grupo do Pix JD, inclusive Plugin PIX JD Viewer.
O plugin consulta a JD a cada chamada, sem cache, então a resposta é atual. List Pix participant bank IDs descreve a resposta.Uma resposta 200 com a lista de participantes, como esta (resumida), prova que o plugin chegou à JD e recebeu o catálogo de participantes:
Se a resposta for diferente, refaça os passos anteriores, começando pelo acesso e pelo vínculo de integração. Se a resposta continuar diferente, entre em contato com o nosso time de suporte.
3

Escreva as chaves de roteamento

O que é. Para cada perfil, o par de UUIDs das rotas de operação do Midaz do passo 4. Todas as chaves ficam no namespace tenant_policy. Cada uma guarda uma string: o UUID de uma rota que existe no Midaz.
O que quebra sem elas. O trilho lê os seis perfis de pagamento juntos em cada pagamento. Uma perna ausente de qualquer um dos seis recusa todo fluxo de pagamento com 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.
Como conferir. Cada escrita responde 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.
A string vazia significa “ainda não provisionado”, e o plugin a aceita. O plugin recusa o UUID só de zeros. Esse UUID tem um formato válido, mas nunca é um identificador real do Midaz. Não preencha as rotas não usadas com zeros como um “vazio seguro”. Use a string vazia.
4

Defina o ativo de lançamento e a conta de compensação

O que é. O ativo de todo lançamento e a conta externa que representa o mundo fora da sua instituição. Duas chaves de systemplane no namespace tenant_policy guardam esses valores, nos dois modos de deploy:Os dois valores são strings simples:
Escreva o código e o alias, não os UUIDs do Midaz do ativo e da conta. Os nomes das chaves terminam em _id, mas o plugin coloca o valor no lançamento como ele está.
O que quebra sem isso. As duas chaves começam vazias. Até você escrever as duas, o plugin recusa todo lançamento, devolução e crédito de entrada com 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.
5

Defina a janela diária

Estas são as duas pontas da janela dos limites de transação. As duas são inteiros de 0 a 23. São horas do relógio, não timestamps. As duas são chaves de systemplane nos dois modos de deploy.
Por que este passo existe. Cada instituição escolhe a hora em que a janela diária de limites de transação abre e fecha. O plugin não tem como adivinhar.Os valores acima são um exemplo. Use os seus. O tipo JSON continua o mesmo: um inteiro, sem aspas. Um valor fora da faixa responde 400. O plugin não o ajusta ao limite.
6

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.
Esta é uma escrita de configuração, então exige Plugin PIX JD Editor. O valor é um booleano JSON, sem aspas. {"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.
Se a JD exige ordens de pagamento assinadas para a sua instituição, termine o passo 2 primeiro. Caso contrário, a JD recusa este pagamento. Depois de recusas repetidas, a JD bloqueia todos os débitos da sua instituição.
Acesso: o pagamento exige Plugin PIX JD Contributor ou Plugin PIX JD Editor. Alterar um limite depois com PATCH /v1/limits exige o mesmo.
Uma conta sem linhas de limite não é uma conta sem limite. Se o plugin não consegue criar os limites, ele recusa o pagamento.Não tente forçar as linhas com um valor acima do teto. A verificação de saldo roda antes da verificação de limite. Um valor alto falha por falta de fundos antes da verificação de limite, e nenhuma linha aparece. Envie um pagamento comum que cabe no saldo.
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.
  1. 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.
  2. 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.
  3. GET /v1/banks responde 200 com a lista de participantes do Pix, como na verificação de conexão do passo 5.
  4. As duas chaves tenant_policy/midaz.* voltam na leitura com o código do ativo e o alias da conta de compensação.
  5. A consulta de instrumentos retorna a sua conta, filtrada por documento, agência e número da conta.
  6. Uma rota de dinheiro para de responder 409 PIX-0092 e 409 PIX-0106. Use a chamada que você já faz. Você não precisa de nenhum aparato de teste.
  7. GET /v1/limits retorna uma lista para a conta que enviou o pagamento do passo 6.
  8. Uma chave Pix é registrada e aparece na lista da conta. Esta verificação passa pelo CRM, pelo vínculo e pelo DICT na JD.
Para a última verificação, registre uma chave aleatória para a conta. Envie 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:
Depois liste as chaves da conta:
A chave está na lista. Uma chave de CPF ou CNPJ também vai para o DICT na primeira chamada. Uma chave de e-mail ou de telefone também precisa do código de 6 dígitos que o plugin envia pelo provedor de notificação de Variáveis de ambiente. Register a Pix key entry descreve cada resposta. Quando terminar, remova uma chave de teste com 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 é um 409, menos a de limites. Nenhuma delas se resolve se você esperar. Cada uma se resolve quando você provisiona o valor ausente.
Quando o 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.
As rotas contábeis são a exceção. PIX-0105 não tem irmão 503. Uma perna de rota ausente, vazia, malformada, o UUID só de zeros ou ilegível dá o mesmo 409. Então um PIX-0105 sozinho não separa “esta perna não tem valor” de “o plano de configuração não respondeu”. Leia as pernas de volta antes de decidir que é uma indisponibilidade.
Os dois códigos de cada par recusam a operação. Nenhum deles lança nem armazena nada. A diferença é apenas a sua próxima ação, por isso eles são códigos separados.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.
Mais dois códigos nomeiam um serviço de que o trilho depende. Eles não se referem à sua configuração. Repita-os: A lista de erros do Pix JD tem todos os códigos, com o detail exato de cada um.

Para onde ir agora

Variáveis de ambiente

A configuração deste trilho no momento do deploy: conectividade com a JD, os endpoints do ledger e do CRM, a hospedagem de QR e os provedores de notificação.

Multiorganização e ledgers

Estenda esta configuração para vários livros, ou vários participantes diretos, no mesmo deploy: o catálogo de organizações, como um toggle de funcionalidade.

Participantes indiretos

O que é uma participação hospedada, como um crédito de entrada chega a ela, o ciclo de vida dela e toda recusa que ela pode responder.

Pix Direto via JD

Como as movimentações de Pix liquidadas chegam ao Midaz, e como os dois sistemas se correlacionam.

Lista de erros do Pix JD

Todo código PIX-NNNN, o status dele e o texto detail da resposta.