> ## 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. Esse par é o padrão. Um deploy também pode servir um **grupo econômico**. Por exemplo, uma holding pode operar uma instituição de pagamento, uma fintech de crédito e um banco. Cada instituição regulada mantém a própria organização, e cada organização mantém quantos ledgers precisar.

A funcionalidade inteira é um toggle em uma única chave do systemplane. Enquanto essa chave está vazia, o trilho se comporta exatamente como se comportava antes de a chave existir. Um deploy que é uma instituição com um livro não precisa desta página. Para esse deploy, [Configurar o trilho](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md) basta.

## 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 dele nunca se misturam com os arquivos de outra instituição, porque um regulador audita cada instituição separadamente.

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** que lista os armários e as gavetas. Um funcionário arquiva movimentações de dinheiro apenas em uma gaveta que está na ficha. O funcionário devolve uma movimentação para uma gaveta que não está na ficha, e nunca a arquiva em uma gaveta "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 caracteres do Banco Central. 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 |

Dois resultados vêm do modelo:

* **Todo lançamento carrega o seu escopo.** O trilho escreve cada transação na organização e no ledger em que ela resolveu. Os registros de cada instituição são, portanto, completos por conta própria. Relatórios regulatórios e contábeis saem por instituição, sem livro compartilhado para separar.
* **O trilho nunca adivinha um escopo.** Ele confere a organização e o ledger de uma movimentação contra o catálogo. Se não consegue prová-los, ele recusa a movimentação antes de qualquer lançamento. O desenho existe para tornar impossível que o dinheiro caia no ledger da instituição errada.

## O toggle: uma chave vazia significa desligado

***

A chave do catálogo começa vazia, e vazia significa **não provisionado**. O tenant então lança apenas na organização e no ledger que o vínculo dele nomeia, como antes de a chave existir. Uma escrita de catálogo liga a funcionalidade. O par que o vínculo nomeia continua sendo o **padrão**: o escopo de todo fluxo que não resolve outro.

> [!NOTE]
>
> O ledger padrão **nunca** fica no catálogo. As rotas contábeis dele ficam nas chaves `routing.*`, e o ativo e a conta de compensação dele ficam nas chaves `midaz.*`. [Configurar o trilho](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md) mostra como provisioná-los. O catálogo declara apenas o que o vínculo não declara. Uma cópia do ledger padrão no catálogo daria a um livro duas fontes da verdade, então o trilho recusa esse catálogo.

**O deploy define até onde o toggle alcança.** Um deploy self-hosted é um participante direto. O catálogo dele pode acrescentar **ledgers** da própria organização: mais livros da mesma instituição. Uma entrada que carrega qualquer outro ISPB é recusada na leitura, porque um deploy self-hosted tem uma credencial da JD e não pode se autenticar como uma segunda instituição. Para atuar como **vários participantes**, com vários ISPBs sob um teto, fale com a Lerian sobre a Lerian Cloud, em que cada participante adicional tem 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](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md) do início ao fim. 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á. Enquanto a chave do catálogo estiver vazia, nada nesta página muda coisa alguma.

**2. Provisione o livro adicional no Midaz e no CRM**

Provisione cada ledger adicional com os mesmos passos da página de configuração, no livro novo:

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 ganha uma organização própria, porque cada organização do Midaz contém exatamente uma instituição regulada.
2. **O ativo e as contas** no ledger novo, com 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 para cada perfil de dinheiro do livro. Esses UUIDs não vão nas chaves `routing.*`. Eles vão dentro do documento do catálogo no próximo passo.
4. **Os titulares e os instrumentos no CRM**, na organização dona do livro. O `ledgerId` do instrumento diz ao trilho em qual livro uma conta é mantida.

**3. Escreva o catálogo**

Escreva o catálogo com uma chamada a `PUT /system/tenant_policy/organizations`. O embrulho é o mesmo do vínculo. O corpo é `{"value": ...}`, e `value` é uma **string** cujo conteúdo é um documento JSON. O documento é uma lista com uma entrada por **organização** do catálogo. Cada entrada nomeia 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 fica no catálogo apenas quando tem ledgers adicionais, e nunca com o ledger padrão. A organização de um participante adicional sempre fica nele.

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 **self-hosted**, a entrada tem o seu próprio ISPB e o seu próprio id de organização, e os ledgers são os livros adicionais.

Cada perfil é um par de UUIDs de rota de operação do Midaz.

Apenas `in` e `inQrCode` são obrigatórios, porque todo ledger do catálogo existe para receber. Um livro que não pode servir nenhuma das duas pernas de entrada mostra um erro de provisionamento. Sem `refundSent`, uma devolução que você envia é lançada em `out`. Qualquer outro fluxo que precisa de um perfil ausente recusa com `409 PIX-0105`, e a resposta nomeia o perfil, a organização e o ledger. Uma chave `routing.*` não definida no livro padrão se comporta da mesma forma.

Três campos são opcionais:

* **`transactionRoute`**, dentro de um perfil: o UUID da rota de transação do Midaz que os lançamentos deste ledger naquele perfil nomeiam. Defina-o quando o ledger valida rotas. Sem ele, um ledger assim recusa o lançamento. Sem o campo, o lançamento não carrega rota de transação.
* **`sharedIspbGate`**, em uma entrada: `true` declara que este participante compartilha o ISPB dele com outro core. As transferências on-us dele então consultam primeiro o mapa de propriedade do Courier. A organização padrão declara o mesmo fato com a chave `tenant_policy/onus.shared_ispb_gate_enabled`. Veja [Mapa de propriedade do Courier](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md#courier-ownership-map).
* **`qrPublicBaseUrl`**, em uma entrada: o host em que este participante publica os QR codes dinâmicos dele. Veja [Hospedagem de QR code dinâmico](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md#dynamic-qr-code-hosting).

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 como você lê o vínculo de volta. O valor volta como uma string entre aspas com 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 recarrega sem reinício. Escreva-a com a aplicação em execução, e o deploy em execução passa a usá-la, sem reinício e sem redeploy.

**4. Saiba o que os validadores recusam, e quando**

O trilho confere o catálogo duas vezes. O validador de escrita pega todo erro que só o documento mostra. A superfície de administração, portanto, recusa um catálogo malformado antes que algum pagamento o encontre.

**A escrita recusa estes valores**, com `400 validation_error`:

* um `value` diferente de string, ou qualquer coisa depois do primeiro documento JSON.
* um campo desconhecido em qualquer profundidade. Um nome de perfil de rota digitado errado também é um campo desconhecido, então um erro de digitação não pode passar como um perfil ausente.
* um `ispb` que não tem exatamente 8 letras maiúsculas ou dígitos.
* um `organizationId`, `ledgerId`, perna de rota ou `transactionRoute` que não é um UUID diferente de zero.
* um `externalAlias` ou `asset` vazio, um par de rotas sem uma das pernas, ou uma organização sem ledger.
* um ledger sem o perfil `in` ou o perfil `inQrCode`.
* o mesmo `ispb`, `organizationId` ou `ledgerId` duas vezes em qualquer lugar do documento.
* um `qrPublicBaseUrl` com esquema, porta, query, fragmento, informações de usuário, um host que não é público, ou mais de 37 caracteres.

Um `403` significa uma permissão ausente, nunca um valor recusado.

**A leitura recusa outros casos**, porque só o trilho em execução conhece o seu vínculo e o seu modo. As recusas aparecem no caminho do dinheiro, antes de qualquer lançamento:

| O trilho responde | Quando |
| - | - |
| `500 PIX-0125` | o catálogo contradiz o vínculo, ou o documento armazenado não faz mais parse. Exemplos: ele repete o ledger padrão, coloca o seu próprio ISPB sob outra organização, dá a sua organização a outro participante, ou nomeia um ISPB de terceiro em um deploy self-hosted. Apenas um operador pode corrigir isso, então o trilho recusa o pagamento e não o arquiva errado |
| `503 PIX-0122` | o trilho não conseguiu **ler** o catálogo. 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 é válido, mas esta movimentação resolveu para um escopo que ele não declara. Um exemplo é um registro de conta sem ledger utilizável em uma organização que tem vários |

**5. Entenda como o dinheiro roteia depois que está ligado**

* **Toda transação vai para o seu escopo.** O lançamento carrega a organização e o ledger em que ele resolveu. O livro de cada instituição, portanto, 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 aceita um registro que não nomeia nenhum ledger, porque ela não tem escolha a fazer. Uma organização com vários ledgers recusa esse registro com `500 PIX-0120` e não adivinha.
* **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. Um tenant que atua como vários deve enviá-lo. Sem ele, a ordem responde `422 PIX-0127`. Um ISPB como o qual o tenant não atua responde `422 PIX-0128`. Um pagador arbitrário poderia debitar 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 um lançamento não consegue conter as duas pernas. O trilho reserva o valor no ledger do pagador contra a conta de compensação dele. Depois, lança o crédito no ledger do recebedor contra a conta de compensação *daquele* ledger. Por último, confirma a reserva. As duas pernas usam o par de rotas `intraPsp` próprio de cada ledger, e cada livro continua em partidas dobradas por conta própria.
* **Entre duas organizações do mesmo tenant, o pagamento é Pix comum.** Duas organizações significam dois participantes regulados. O dinheiro, portanto, passa pelo trilho de liquidação (SPI), como faz um pagamento para qualquer outra instituição. O mesmo tenant nunca é "o 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

***

Você pode escrever uma string vazia de volta em `tenant_policy/organizations`. O tenant então volta ao comportamento só-padrão, como antes da ativação. Isso não desfaz nada já lançado. Dinheiro lançado em um escopo adicional fica naquele ledger, e este trilho não consegue mais alcançá-lo. Um 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 roteia para os livros adicionais. Isso significa nenhuma conta cujos registros apontam para eles, nenhum pagamento em andamento e nenhum participante hospedado em uma organização adicional. Para aposentar um livro e manter a funcionalidade, remova a entrada daquele ledger e mantenha o resto do catálogo. A mesma prova de leitura se aplica, escopo por escopo.

## Para onde ir agora

***

> [card] [Configurar o trilho](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md)
>
> 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.

> [card] [O modelo direto e indireto](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-and-indirect-model.md)
>
> 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.

> [card] [Variáveis de ambiente](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md)
>
> A configuração no momento do deploy, e os valores que ficam em chaves do systemplane em vez disso.

> [card] [Lista de erros do Pix JD](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/pix-jd-error-list.md)
>
> Todo código `PIX-NNNN` que esta página nomeia, com o status dele e o texto `detail` da resposta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.