> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Hospedar participantes indiretos > Os três passos de provisionamento que um deploy acrescenta quando liquida Pix em nome de outras instituições: a chave de criptografia do segredo de entrega, a postura de hospedagem, o cadastro de cada participante indireto e as chaves do systemplane do namespace indirects. 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](/pt/interfaces/pix-jd/pix-jd-setup) — 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. | # | Passo | Onde | | - | ------------------------------------------------------------- | -------------------------------------------------------------- | | 1 | o ISPB deste deploy (`tenancy/jd_integration_binding`) | [a página de configuração](/pt/interfaces/pix-jd/pix-jd-setup) | | 2 | organização, ledger, ativo, contas, titulares no CRM | [a página de configuração](/pt/interfaces/pix-jd/pix-jd-setup) | | 3 | as vinte pernas de rota contábil | [a página de configuração](/pt/interfaces/pix-jd/pix-jd-setup) | | 4 | o ativo de lançamento e a conta de compensação | [a página de configuração](/pt/interfaces/pix-jd/pix-jd-setup) | | 5 | a janela diária | [a página de configuração](/pt/interfaces/pix-jd/pix-jd-setup) | | 6 | as linhas de limite de transação, que não têm rota de criação | [a página de configuração](/pt/interfaces/pix-jd/pix-jd-setup) | | 7 | **a chave de criptografia do segredo de entrega** | abaixo | | 8 | **a postura de hospedagem, `indirects/enabled = true`** | abaixo | | 9 | **o cadastro de cada participante indireto** | abaixo | 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](/pt/reference/interfaces/pix-jd/indirect-participants). ### 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. ```text theme={null} 409 PIX-0107 "Indirect Delivery Encryption Not Provisioned" "No delivery-secret encryption key is provisioned for this tenant, so the indirect participant was not saved and no secret was stored. ..." ``` 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. **Onde ela vive, e por que não fica no systemplane.** Esse contraste explica onde cada tipo de valor pertence neste trilho. | | O ISPB (`tenancy/jd_integration_binding`) | A chave de criptografia | | ------------- | --------------------------------------------------------------------------- | --------------------------------------------------------- | | O que é | **identidade** — o número que identifica você no BACEN | **uma credencial** — material criptográfico | | É um segredo? | não. Um ISPB, um id de organização e um id de ledger não são credenciais | sim | | Onde vive | no **systemplane**, para poder ser lido e escrito pela API de administração | **fora** do systemplane | | De onde vem | da API de administração do systemplane | da variável de deploy `INDIRECTS_DELIVERY_ENCRYPTION_KEY` | 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. **O formato: exatamente 64 caracteres hexadecimais.** É uma chave AES-256 — 32 bytes — codificada em hexadecimal. Isso são **64 caracteres hexadecimais**, não 63 e não 65. ```bash theme={null} openssl rand -hex 32 ``` Gere uma por deploy. Não copie a chave de outro ambiente e não reutilize a de outro serviço. 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. Em single-tenant, defina a variável de deploy: ```bash theme={null} # in the process environment — never in a versioned file INDIRECTS_DELIVERY_ENCRYPTION_KEY="paste-the-64-hex-characters-here" ``` Esse placeholder deliberadamente não é uma chave válida: colado como está, ele falha fechado com a recusa acima em vez de criptografar os segredos dos seus clientes com um valor publicado em uma página de documentação. Ela é lida na inicialização, então mudá-la exige reiniciar o processo. Isso é diferente do vínculo do ISPB, que é lido a cada chamada e se recupera sem reinício. 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. **Como checar se ela funcionou.** Nenhuma rota lê a chave de volta, e é assim que deve ser — ela é um segredo. Há dois sinais. *O log de inicialização.* Com a chave resolvível, o aviso "key unavailable" não aparece. Se ele aparecer, nenhum cadastro que carrega um segredo vai passar. *O comportamento.* Cadastre um participante indireto: a resposta passa de `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`. ```bash theme={null} curl -s -o /dev/null -w '%{http_code}\n' -X PUT \ -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \ -d '{"value":true}' \ "$PIX_JD_BASE_URL/system/plugin-br-pix-jd.indirects/enabled" ``` `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](/pt/reference/interfaces/pix-jd/indirect-participants#before-you-register-anyone). 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. ```bash theme={null} # The signing secret must never appear in a process argument list: `ps` and # command logging expose arguments. Read it silently, export it, let jq pull it # from the environment, and have curl read the body from standard input. IFS= read -r -s -p 'delivery secret for this participant: ' INDIRECT_DELIVERY_SECRET; printf '\n' export INDIRECT_DELIVERY_SECRET jq -n '{ name: "Indirect PSP Ltda", ispb: "87654321", messagingMode: "raw", delivery: { endpointUrl: "https://indirect.example.com/pix", secret: env.INDIRECT_DELIVERY_SECRET } }' | curl -s -X POST "$PIX_JD_BASE_URL/v1/indirects" \ -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \ --data-binary @- unset INDIRECT_DELIVERY_SECRET ``` | Campo | Regra | Se estiver errado | | ---------------------- | -------------------------------------------------------------------- | ------------------------- | | `name` | de 1 a 120 caracteres | `422 PIX-0098` | | `ispb` | exatamente 8 dígitos — o ISPB **da instituição indireta**, não o seu | `422 PIX-0098` | | `delivery.endpointUrl` | uma URL `https` válida, para onde os avisos são entregues | `422 PIX-0098` | | `delivery.secret` | o segredo simétrico de assinatura, combinado com aquela instituição | `422 PIX-0098` se ausente | | `messagingMode` | `raw` é o único valor hoje | `422 PIX-0098` | 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 recusas, as ações de ciclo de vida e como ler o registro de volta estão em [Participantes indiretos](/pt/reference/interfaces/pix-jd/indirect-participants). ### 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`. | Chave | Tipo | Faixa | Padrão | O que é | | -------------------------- | -------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | booleano | — | `false` | a postura de hospedagem | | `delivery_concurrency` | inteiro | 1–256 | `8` | quantos `POST`s de entrega rodam em paralelo. O isolamento é por participante: um endpoint travado ocupa no máximo um slot e nunca bloqueia os outros | | `delivery_max_attempts` | inteiro | 1–64 | `8` | o orçamento de novas tentativas antes de uma linha de entrega acabar em `INVALID`. A recuperação a partir daí é manual | | `resolution_cache_ttl_sec` | inteiro | 0–86400 | `30` | por quanto tempo uma resolução fica em cache. `0` desabilita o cache, e é por isso que o mínimo é 0 | | `validate_ispb_on_jd` | booleano | — | `false` | com `true`, o cadastro consulta o diretório de participantes da JD e **falha de forma que permite nova tentativa** se a JD estiver fora do ar | ```bash theme={null} PUT() { curl -s -o /dev/null -w "$1 -> %{http_code}\n" -X PUT \ -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \ -d "$2" "$PIX_JD_BASE_URL/system/$1"; } PUT plugin-br-pix-jd.indirects/enabled '{"value":true}' PUT plugin-br-pix-jd.indirects/delivery_concurrency '{"value":8}' PUT plugin-br-pix-jd.indirects/delivery_max_attempts '{"value":8}' PUT plugin-br-pix-jd.indirects/resolution_cache_ttl_sec '{"value":30}' PUT plugin-br-pix-jd.indirects/validate_ispb_on_jd '{"value":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`.