Para liquidar um Pix no Banco Central, uma instituição precisa estar conectada à infraestrutura do Sistema Financeiro Nacional. Isso é caro e lento, e nem toda instituição faz isso. A instituição que não faz usa a conexão de outra: ela vira um participante indireto, e um participante direto liquida por ela e a hospeda.
Um tenant que hospeda participantes indiretos é antes de tudo um participante direto. Tudo em Configurar o trilho — o vínculo do ISPB, a organização, o ledger, o ativo, as contas, os registros do CRM, as vinte rotas contábeis — é provisionado exatamente como está escrito lá. Chame isso de cadeia do participante direto, passos 1 a 6. Esta página é o que você acrescenta em cima, e a sua numeração continua dali. Se o seu deploy liquida apenas o Pix dos seus próprios clientes, pule esta página.
O passo 7 vem antes do passo 9, não depois: sem a chave de criptografia, todo cadastro do passo 9 falha. Os passos 7 e 8 são independentes entre si — a postura não valida a chave, e a chave não é lida pela postura.
Esta página é o provisionamento. O que uma participação hospedada é, como um crédito de entrada chega até ela, como o seu ciclo de vida se comporta e cada recusa que ela pode responder estão em Participantes indiretos. Passo 7: a chave de criptografia do segredo de entrega
Por que este passo existe. Quando você cadastra um participante indireto, você informa um segredo de entrega. O plugin assina com ele cada aviso que envia ao endpoint daquela instituição, e é assim que a instituição sabe que o aviso veio mesmo de você. Esse segredo é guardado criptografado, e a chave que o criptografa não vem do banco de dados. Ela vem de fora.
Se a chave não estiver configurada, todo cadastro que carrega um segredo falha. Isso não é um caso de borda — é toda a superfície de escrita do fluxo de indiretos.
Leia a garantia no meio dessa frase: nenhum segredo foi armazenado. A criptografia falha antes de qualquer escrita, então não existe uma linha meio criada com um segredo em texto claro para você ir limpar. Corrigir a chave e repetir o POST é toda a recuperação.
Aqui 409 significa “provisione a chave”, não “tente de novo mais tarde”. O trilho procurou a chave e constatou que ela não está lá, e apenas um operador pode colocá-la lá — então repetir a chamada sem essa mudança falha de forma idêntica. É por isso que o código é um 409 e não diz nada sobre nova tentativa.O irmão dele é 503 PIX-0123, “Indirect delivery key source unavailable”, que é o que você recebe quando a chave não pôde ser lida: o backend de custódia recusou ou não respondeu. Ali, não se sabe que a chave está ausente — a própria leitura não terminou — então a resposta nomeia a dependência que falhou, e tentar de novo é o movimento certo. Os dois recusam o cadastro e não armazenam nada; o par existe para você poder distinguir uma configuração incompleta de uma indisponibilidade.
O plugin inicia sem a chave. Não há recusa na inicialização: o processo grava um aviso no log ao iniciar e sobe saudável, porque nada na inicialização distingue um deploy que vai hospedar participantes indiretos de um que nunca cadastra nenhum — a chave é lida a cada requisição, não uma vez no boot. Então o sintoma chega no primeiro cadastro, não no deploy. Se você não leu o log de inicialização, a recusa é o seu primeiro aviso.
Não coloque a chave de criptografia no systemplane. O systemplane é o plano de configuração ao vivo, legível pela API de administração, e é a casa certa para tudo o que não é segredo. Material de credencial não vai para lá, e o trilho separa os dois de propósito.Também não faça commit dela — nem em um .env versionado, nem em um values.yaml, nem em um arquivo de compose.
Um valor ausente, em branco ou malformado produz o mesmo 409 PIX-0107. Não há padrão e não há degradação para guardar o segredo em texto claro. Isso é deliberado: um padrão silencioso aqui guardaria segredos de clientes criptografados com uma chave que todo mundo conhece.
Não digite o valor em uma linha de comando. Ele acaba no histórico do seu shell e nos logs de CI. Leia de um cofre, ou digite com read -rs, que não ecoa.
409 PIX-0107 para 201.
Pense antes de usar a checagem por comportamento. Um cadastro é permanente — não há rota de exclusão, e a única saída é close, que mantém a linha e segura o ISPB. Não gaste um cadastro descartável para testar a chave em um ambiente de produção; use um ISPB que você realmente pretende operar. O log de inicialização poupa esse custo.
Passo 8: declare que este tenant hospeda participantes indiretos
plugin-br-pix-jd.indirects/enabled precisa ser true.
204 quando aceito. É um booleano JSON, sem aspas: {"value":"true"} responde 400.
A API de gestão funciona com a postura desligada, então você pode cadastrar participantes antes de habilitar — o que a postura controla são os caminhos do dinheiro. O detalhamento completo do que cada metade faz está em Antes de cadastrar alguém.
A leitura falha fechada. Se o systemplane não responder, se a chave não resolver, ou se o valor voltar com o tipo errado, o plugin a lê como desligada — nunca ligada por acidente. Um caminho do dinheiro que “voltou a se comportar como um direto” sem ninguém ter tocado na chave é esse mecanismo. Olhe o systemplane.
Passo 9: cadastre um participante indireto
Uma chamada executa toda a montagem: ela checa o ISPB, cria a conta de liquidação @pi_{ispb} no Midaz e marca a participação como ativa.
Um 201 significa que a participação está pronta para uso: o cadastro é atômico, status é sempre ACTIVE, e não há nada para ficar consultando.
Não escreva o ISPB de um participante indireto em tenancy/jd_integration_binding. Essa chave é a identidade que o plugin apresenta à JD, então o ISPB de um terceiro ali faz o plugin se apresentar como outra instituição — e nada avisa você, porque 8 dígitos válidos são aceitos e a escrita responde 204. A chave é uma por participante direto, não uma por participante indireto: cada participante indireto que você hospeda alcança o SPI pelo seu ISPB.
O cadastro é permanente. Não existe DELETE em /v1/indirects, e CLOSED é terminal. Um participante indireto cadastrado por engano em um tenant ativo não sai mais, e o ISPB dele continua retido pela regra de unicidade até alguém encerrá-lo. Confira o nome, o ISPB e o endpoint antes de chamar. Ensaie em um ambiente descartável.
As chaves do systemplane do namespace indirects
Cinco chaves, todas em plugin-br-pix-jd.indirects, e todas elas sempre existem. As três chaves de entrega e de resolução apenas produzem efeito quando enabled é true, porque elas ajustam os caminhos do dinheiro. validate_ispb_on_jd é a exceção: ela controla um passo do cadastro, que funciona enquanto enabled ainda é false.
204 quando aceito, 400 quando o validador recusa. Booleanos e inteiros vão sem aspas, e um valor fora da faixa responde 400 em vez de ser limitado em silêncio.
Nenhum dos dois passos que quebram o fluxo de indiretos por conta própria vive neste namespace. A identidade é a chave do systemplane tenancy/jd_integration_binding, e sem ela todo pagamento recusa com 409 PIX-0092. A chave de criptografia vive em uma variável de deploy ou em um cofre de segredos, e sem ela todo cadastro recusa com 409 PIX-0107.
