> ## 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.
# Multiorganização e ledgers
> Rode vários participantes diretos e vários livros em um deploy do Pix Direto via JD: o que é o catálogo de organizações, por que um grupo econômico precisa dele, como ativá-lo como um toggle de funcionalidade e como o dinheiro roteia depois que ele está ligado.
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](/pt/interfaces/pix-jd/pix-jd-setup) 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:
| Na analogia | No trilho | O que é |
| -------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| o escritório de retaguarda | o tenant | um deploy, um grupo econômico. Ele guarda o banco de dados e a conexão com o Midaz de todos sob o teto |
| um armário | uma **organização** do Midaz | exatamente um participante direto — um ISPB, a identidade de 8 dígitos que o Banco Central credencia. Uma organização é uma instituição regulada, nunca duas |
| uma gaveta | um **ledger** | um livro daquela instituição. Uma organização tem um ou muitos — por exemplo um por produto, ou um por família de carteiras |
| a ficha | o **catálogo de organizações** | a chave do systemplane `tenant_policy/organizations`. Ela declara cada participante e livro *adicional* em que este tenant lança |
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](/pt/interfaces/pix-jd/pix-jd-setup) 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
***
O catálogo estende um deploy que funciona; ele não substitui a configuração. Rode [Configurar o trilho](/pt/interfaces/pix-jd/pix-jd-setup) 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.
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.
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:
```json theme={null}
[
{
"ispb": "12345678",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ledgers": [
{
"ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
"externalAlias": "@external/BRL",
"asset": "BRL",
"routes": {
"in": { "operationDebitRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a01", "operationCreditRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a02" },
"inQrCode": { "operationDebitRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a03", "operationCreditRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a04" },
"out": { "operationDebitRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a05", "operationCreditRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a06" }
}
}
]
}
]
```
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:
```bash theme={null}
# CATALOG_DOCUMENT holds the JSON document above, with your own identifiers.
CATALOG_DOCUMENT='[{"ispb":"12345678","organizationId":"...","ledgers":[...]}]'
curl -s -o /dev/null -w '%{http_code}\n' -X PUT \
-H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
-d "$(jq -nc --arg document "$CATALOG_DOCUMENT" '{value:$document}')" \
"$PIX_JD_BASE_URL/system/tenant_policy/organizations"
```
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:
```bash theme={null}
curl -s -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
"$PIX_JD_BASE_URL/system/tenant_policy/organizations" | jq
```
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.
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:
| O trilho responde | Quando |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `500 PIX-0125` | o catálogo contradiz o vínculo — ele redeclara o ledger padrão, coloca o seu próprio ISPB sob outra organização, dá a outro participante a sua organização, ou nomeia um ISPB de terceiro em um deploy single-tenant — ou o documento armazenado não faz mais parse. Apenas um operador pode resolver isso, então o pagamento é recusado em vez de arquivado errado |
| `503 PIX-0122` | o catálogo não pôde ser **lido**. Não se sabe de nada errado com ele, então a recusa permite nova tentativa e se resolve sozinha |
| `500 PIX-0120` | o catálogo está bem e esta movimentação resolveu para um escopo que ele não declara — incluindo um registro de conta que não nomeia nenhum ledger utilizável em uma organização que tem vários |
* **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
***
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.
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.
A configuração no momento do deploy, e quais valores vivem em chaves do systemplane em vez disso.
Todo código `PIX-NNNN` que esta página nomeia, com o status dele e o texto `detail` que a resposta carrega.