Skip to main content
Um deploy novo deste trilho lança toda movimentação Pix em uma organização do Midaz e um ledger — o par que o vínculo dele nomeia. Desde a versão 2.0.2 esse é o padrão, não o teto: um deploy pode servir um grupo econômico — uma holding que opera, digamos, uma instituição de pagamento, uma fintech de crédito e um banco — com cada instituição regulada mantendo a própria organização e cada organização mantendo quantos ledgers precisar. A funcionalidade inteira é um toggle. Ela vive em uma única chave do systemplane, e enquanto essa chave está vazia o trilho se comporta byte a byte como se comportava antes de a chave existir. Nada nesta página é leitura obrigatória para um deploy que é uma instituição com um livro — pare em Configurar o trilho e pronto.

​
Um teto, vários armários, várias gavetas

Pense no deploy como um escritório de retaguarda com uma parede de armários de arquivo. Cada armário pertence a uma instituição regulada: os arquivos dela nunca se misturam com os de outra instituição, porque um regulador audita cada instituição por conta própria. Dentro de um armário, gavetas separam linhas de negócio — uma para o produto de carteira, uma para o produto de crédito. Na parede fica pendurada uma ficha dizendo quais armários e gavetas existem. Um funcionário arquiva movimentações de dinheiro apenas em uma gaveta que a ficha nomeia; uma movimentação endereçada a uma gaveta que não está na ficha é devolvida, nunca arquivada em algum lugar “perto o bastante”. O vocabulário do trilho mapeia um a um: Duas consequências caem direto do modelo:
  • Todo lançamento carrega o seu escopo. Cada transação é escrita na organização e no ledger em que ela resolveu, então os registros de cada instituição são completos por conta própria — relatórios regulatórios e contábeis saem por instituição sem desembaraçar um livro compartilhado.
  • O trilho nunca adivinha um escopo. Uma movimentação cuja organização e ledger não podem ser provados contra o catálogo é recusada antes de qualquer lançamento. Lançar dinheiro no ledger da instituição errada é o único erro que este desenho existe para tornar impossível.

​
O toggle: uma chave vazia significa desligado

A chave do catálogo começa vazia, e vazia é o valor sentinela de não provisionado: o tenant lança apenas na organização e no ledger que o vínculo dele nomeia, exatamente como antes de a chave existir. Escrever um catálogo liga a funcionalidade; o par que o vínculo nomeia continua sendo o padrão — o escopo em que todo fluxo lança, a menos que resolva outro.
A organização e o ledger padrão nunca ficam no catálogo. As rotas contábeis deles ficam nas chaves routing.* e o ativo e a conta de compensação deles ficam na própria configuração, exatamente como Configurar o trilho os provisiona. O catálogo declara apenas o que o vínculo não declara: repetir o ledger padrão lá daria a um livro duas fontes da verdade, então o trilho recusa um catálogo que o redeclara.
O modo de deploy decide até onde o toggle alcança. Um deploy single-tenant é um participante direto, então o catálogo dele pode acrescentar ledgers da própria organização — livros adicionais, mesma instituição. Uma entrada que carrega qualquer outro ISPB é recusada na leitura, porque um deploy single-tenant tem uma credencial da JD e não pode se autenticar como uma segunda instituição. Atuar como vários participantes — vários ISPBs sob um teto — é o formato multi-tenant, em que o tenant é o grupo e cada participante adicional é provisionado com uma credencial da JD própria.

​
Ative, passo a passo

1

Complete a configuração comum primeiro

O catálogo estende um deploy que funciona; ele não substitui a configuração. Rode Configurar o trilho de ponta a ponta: o vínculo que você escreve lá torna a sua instituição o participante padrão e o ledger dela o livro padrão. Se o seu deploy é uma instituição com um livro, pare lá — com a chave do catálogo vazia, nada nesta página muda coisa alguma.
2

Provisione o livro adicional no Midaz e no CRM

Cada ledger adicional é provisionado com a mesma receita que a página de configuração percorre, apontada para o livro novo em vez do padrão:
  1. A organização e o ledger. Um ledger adicional da sua própria instituição vai sob a sua organização existente. Um participante adicional (multi-tenant) ganha uma organização própria, porque uma organização do Midaz é exatamente uma instituição regulada.
  2. O ativo e as contas no ledger novo, incluindo a própria conta externa de compensação — um alias como @external/BRL é único dentro de um ledger, então cada livro precisa da sua.
  3. As rotas de operação no ledger novo, um par de crédito e débito por perfil de dinheiro que o livro serve. Diferente do ledger padrão, esses UUIDs não vão nas chaves routing.* — eles vão dentro do documento do catálogo no próximo passo.
  4. Os registros de titular e os vínculos no CRM, endereçados com o X-Organization-Id da organização dona do livro. O ledgerId do vínculo é o que diz ao trilho em qual livro uma conta é mantida, então em uma organização com mais de um ledger todo vínculo deve nomear o seu ledger.
3

Escreva o catálogo

O catálogo é escrito uma vez, em PUT /system/tenant_policy/organizations, com o mesmo embrulho que o vínculo usa: o corpo é {"value": ...} e value é uma string cujo conteúdo é um documento JSON — uma lista com uma entrada por organização catalogada, cada uma nomeando o ISPB do seu participante, a sua organização do Midaz e os ledgers dessa organização com as suas rotas. A sua própria organização aparece aqui quando carrega ledgers adicionais — nunca redeclarando o ledger padrão — e a organização de um participante adicional sempre aparece.Este é o documento, desembrulhado, com identificadores de exemplo:
Em um deploy single-tenant a entrada carrega o seu próprio ISPB e o seu próprio id de organização, e os ledgers são os livros adicionais; os identificadores diferem por participante apenas no multi-tenant.routes aceita até dez perfis — in, inQrCode, out, outReversal, intraPsp, intraPspReversal, medDebit, medCredit, pixautomaticoDebit, pixautomaticoReversal — cada um um par de UUIDs de rota de operação do Midaz. Apenas in e inQrCode são obrigatórios: todo ledger do catálogo existe para receber, então um livro que não pode servir nenhuma das duas pernas de entrada é um erro de provisionamento, não um livro mais estreito. Os outros oito são opcionais; um fluxo que precisa de um ausente recusa com 409 PIX-0105, nomeando o perfil, a organização e o ledger — o mesmo comportamento que uma chave routing.* não definida produz no livro padrão.Deixe o jq fazer o escape da string, como com o vínculo:
Uma escrita bem-sucedida responde 204. Leia a chave de volta do jeito que você lê o vínculo de volta — o valor retorna como uma string entre aspas carregando o seu documento:
A chave tem hot reload: escreva-a com a aplicação de pé e ela passa a valer no deployment em execução, sem reinício e sem redeploy.
4

Saiba o que os validadores recusam, e quando

O catálogo é validado duas vezes, e a divisão importa: o validador de escrita pega tudo o que pode ser julgado só pelo documento, então um catálogo malformado é recusado na superfície de administração em vez de descoberto em um pagamento.Recusado na escrita, com 400 validation_error:
  • um value que não é uma string, ou qualquer coisa depois do primeiro documento JSON;
  • um campo desconhecido em qualquer profundidade — um nome de perfil de rota digitado errado incluído, então um erro de digitação não pode passar como um perfil silenciosamente ausente;
  • um ispb que não tem exatamente 8 dígitos; um organizationId, ledgerId ou perna de rota que não é um UUID diferente de zero;
  • um externalAlias ou asset vazio; um par de rotas sem uma das pernas; uma organização que não declara nenhum ledger;
  • um perfil in ou inQrCode ausente em qualquer ledger;
  • um ispb, organizationId ou ledgerId duplicado em qualquer lugar do documento. Um 403 é uma permissão ausente, nunca um valor rejeitado.
Recusado na leitura, porque só o trilho em execução conhece o seu vínculo e o seu modo. Estes aparecem no caminho do dinheiro, antes de qualquer lançamento:
5

Entenda como o dinheiro roteia depois que está ligado

  • Toda transação é registrada no seu escopo. O lançamento carrega a organização e o ledger em que ele resolveu, então o livro de cada instituição fica completo e auditável por conta própria.
  • Um crédito de entrada encontra o próprio livro. O ISPB do recebedor escolhe a organização; o registro da conta no CRM escolhe o ledger. Uma organização com um único ledger tolera um registro que não nomeia nenhum — não há entre o que escolher; uma com vários não tolera, e recusa com 500 PIX-0120 em vez de adivinhar.
  • Uma ordem de saída nomeia o participante pagador quando o tenant é vários. POST /v1/transactions aceita um payerIspb opcional. Um tenant que atua como um participante o omite e se comporta exatamente como antes; um tenant que atua como vários deve enviá-lo — omitido é 422 PIX-0127, e um ISPB como o qual o tenant não atua é 422 PIX-0128 — porque escolher um pagador arbitrariamente debitaria o cliente de outra instituição.
  • Entre dois ledgers da mesma organização, a transferência é interna. Um alias é único dentro de um ledger, então ela não pode ser um lançamento só: o trilho reserva o valor no ledger do pagador contra a conta de compensação dele, lança o crédito final no ledger do recebedor contra a conta de compensação dele, e então confirma a reserva. As duas pernas são lançadas no par de rotas intraPsp de cada ledger, e cada livro fica internamente em partidas dobradas.
  • Entre duas organizações do mesmo tenant, o pagamento é Pix comum. Duas organizações são dois participantes regulados, então o dinheiro viaja o trilho de liquidação (SPI) exatamente como um pagamento para qualquer outra instituição viajaria — mesmo tenant nunca é “mesmo livro”.
  • Cada participante adicional se autentica como ele mesmo. Ordens que saem de uma organização adicional são enviadas à JD sob a credencial própria daquele participante, provisionada por ISPB. Um participante cuja credencial não está provisionada recusa a primeira ordem dele com 409 PIX-0092 e libera a reserva, e a probe de readiness o reporta fora do ar nomeando aquele ISPB antes de o tráfego alcançá-lo.

​
Desligando

Escrever uma string vazia de volta em tenant_policy/organizations é aceito e retorna o tenant ao comportamento só-padrão — o mesmo estado de antes da ativação. Isso não desfaz nada já lançado: dinheiro lançado em um escopo adicional fica naquele ledger, e ele deixa de ser alcançável por este trilho — qualquer fluxo que resolve para um escopo que o catálogo não declara mais recusa com 500 PIX-0120 antes de tocar o ledger. Então esvazie a chave apenas quando nada mais roteia para os livros adicionais: nenhuma conta cujos registros apontam para eles, nenhum pagamento em andamento e nenhum participante hospedado montado em uma organização adicional. Para aposentar um livro mantendo a funcionalidade, remova a entrada daquele ledger e deixe o resto do catálogo no lugar — a mesma prova de leitura se aplica, escopo por escopo.

​
Para onde ir agora

Configurar o trilho

A cadeia de provisionamento que esta página estende: os objetos do ledger, os registros do CRM, as chaves de roteamento e o vínculo que nomeia o par padrão.

O modelo direto e indireto

Como este eixo difere de hospedar participantes indiretos: um indireto é uma posição dentro do seu livro; uma organização adicional é um participante direto com livros próprios.

Variáveis de ambiente

A configuração no momento do deploy, e quais valores vivem em chaves do systemplane em vez disso.

Lista de erros do Pix JD

Todo código PIX-NNNN que esta página nomeia, com o status dele e o texto detail que a resposta carrega.