> ## 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.
# Multiorganización y ledgers
> Opera varios participantes directos y varios libros en un solo despliegue de Pix Directo vía JD: qué es el catálogo de organizaciones, por qué un grupo económico lo necesita, cómo activarlo como un toggle y cómo se enruta el dinero una vez que está activo.
Un despliegue nuevo de este riel registra cada movimiento Pix en **una** organización de Midaz y **un** ledger — el par que nombra su vínculo. Desde la versión 2.0.2 ese es el valor predeterminado, no el techo: un despliegue puede servir a un **grupo económico** — un holding que opera, digamos, una institución de pago, una fintech de crédito y un banco — con cada institución regulada conservando su propia organización y cada organización con tantos ledgers como necesite.
Toda la función es un toggle. Vive en una sola clave del systemplane, y mientras esa clave está vacía el riel se comporta byte por byte como antes de que la clave existiera. Nada en esta página es lectura obligatoria para un despliegue que es una institución con un libro — detente en [Configurar el riel](/es/interfaces/pix-jd/pix-jd-setup) y ya está.
## Un techo, varios archivadores, varios cajones
***
Piensa en el despliegue como una oficina administrativa con una pared de archivadores. Cada **archivador** pertenece a una institución regulada: sus expedientes nunca se mezclan con los de otra institución, porque un regulador audita a cada institución por separado. Dentro de un archivador, los **cajones** separan líneas de negocio — uno para el producto de billetera, otro para el producto de crédito. En la pared cuelga una **ficha índice** que dice qué archivadores y cajones existen. Un empleado archiva los movimientos de dinero solo en un cajón que el índice nombra; un movimiento dirigido a un cajón que no está en el índice se devuelve, nunca se archiva en algún lugar "suficientemente parecido".
El vocabulario del riel corresponde uno a uno:
| En la analogía | En el riel | Qué es |
| ------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| la oficina administrativa | el tenant | un despliegue, un grupo económico. Mantiene la base de datos y la conexión con Midaz de todos los que están bajo el techo |
| un archivador | una **organización** de Midaz | exactamente un participante directo — un ISPB, la identidad de 8 dígitos que el Banco Central acredita. Una organización es una institución regulada, nunca dos |
| un cajón | un **ledger** | un libro de esa institución. Una organización tiene uno o muchos — por ejemplo uno por producto, o uno por familia de billeteras |
| la ficha índice | el **catálogo de organizaciones** | la clave del systemplane `tenant_policy/organizations`. Declara cada participante y libro *adicional* para el que este tenant registra |
Dos consecuencias salen directo del modelo:
* **Cada asiento lleva su alcance.** Cada transacción se escribe en la organización y el ledger a los que resolvió, así que los registros de cada institución están completos por sí solos — los informes regulatorios y contables salen por institución sin desenredar un libro compartido.
* **El riel nunca adivina un alcance.** Un movimiento cuya organización y ledger no pueden probarse contra el catálogo se rechaza antes de cualquier asiento. Registrar dinero en el ledger de la institución equivocada es el único error que este diseño existe para hacer imposible.
## El toggle: una clave vacía significa apagado
***
La clave del catálogo empieza vacía, y vacío es el centinela de **no aprovisionado**: el tenant registra solo en la organización y el ledger que nombra su vínculo, exactamente como antes de que la clave existiera. Escribir un catálogo activa la función; el par que nombra el vínculo sigue siendo el **predeterminado** — el alcance en el que registra cada flujo a menos que resuelva otro.
La organización y el ledger predeterminados **nunca** están en el catálogo. Sus rutas contables se quedan en las claves `routing.*` y su activo y cuenta de compensación en su propia configuración, exactamente como los aprovisiona [Configurar el riel](/es/interfaces/pix-jd/pix-jd-setup). El catálogo declara solo lo que el vínculo no declara: repetir ahí el ledger predeterminado le daría a un libro dos fuentes de verdad, así que el riel rechaza un catálogo que lo vuelve a declarar.
**El modo de despliegue decide hasta dónde llega el toggle.** Un despliegue single-tenant es un participante directo, así que su catálogo puede agregar **ledgers** de su propia organización — libros adicionales, la misma institución. Una entrada que lleve cualquier otro ISPB se rechaza en el momento de la lectura, porque un despliegue single-tenant tiene una sola credencial de JD y no puede autenticarse como una segunda institución. Actuar como **varios participantes** — varios ISPB bajo un mismo techo — es la forma multi-tenant, donde el tenant es el grupo y cada participante adicional se aprovisiona con una credencial de JD propia.
## Actívalo, paso a paso
***
El catálogo extiende un despliegue que funciona; no reemplaza la configuración. Ejecuta [Configurar el riel](/es/interfaces/pix-jd/pix-jd-setup) de punta a punta: el vínculo que escribes ahí convierte a tu institución en el participante **predeterminado** y a su ledger en el libro predeterminado. Si tu despliegue es una institución con un libro, detente ahí — con la clave del catálogo vacía, nada en esta página cambia nada.
Cada ledger adicional se aprovisiona con la misma receta que recorre la página de configuración, apuntada al libro nuevo en lugar del predeterminado:
1. **La organización y el ledger.** Un ledger adicional de tu propia institución va bajo tu organización existente. Un *participante* adicional (multi-tenant) recibe una organización propia, porque una organización de Midaz es exactamente una institución regulada.
2. **El activo y las cuentas** en el ledger nuevo, incluida su propia cuenta externa de compensación — un alias como `@external/BRL` es único dentro de un ledger, así que cada libro necesita el suyo.
3. **Las rutas de operación** en el ledger nuevo, un par de crédito y débito por cada perfil de dinero que el libro atiende. A diferencia del ledger predeterminado, estos UUID no van en las claves `routing.*` — van dentro del documento del catálogo en el paso siguiente.
4. **Los registros de titulares y los alias en el CRM**, dirigidos con el `X-Organization-Id` de la organización dueña del libro. El `ledgerId` del alias es lo que le dice al riel en qué libro opera una cuenta, así que en una organización con más de un ledger cada alias debe nombrar su ledger.
El catálogo se escribe una sola vez, en `PUT /system/tenant_policy/organizations`, con la misma envoltura que usa el vínculo: el cuerpo es `{"value": ...}` y `value` es una **cadena** cuyo contenido es un documento JSON — una lista con una entrada por **organización** catalogada, cada una nombrando el ISPB de su participante, su organización de Midaz y los ledgers de esa organización con sus rutas. Tu propia organización aparece aquí cuando lleva ledgers adicionales — sin redeclarar nunca el ledger por defecto — y la organización de un participante adicional siempre aparece.
Este es el documento, sin envolver, con identificadores de ejemplo:
```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" }
}
}
]
}
]
```
En un despliegue **single-tenant** la entrada lleva tu propio ISPB y tu propio id de organización, y los ledgers son los libros adicionales; los identificadores difieren por participante solo en multi-tenant.
`routes` acepta hasta diez perfiles — `in`, `inQrCode`, `out`, `outReversal`, `intraPsp`, `intraPspReversal`, `medDebit`, `medCredit`, `pixautomaticoDebit`, `pixautomaticoReversal` — cada uno un par de UUID de rutas de operación de Midaz. Solo `in` e `inQrCode` son obligatorios: cada ledger del catálogo existe para recibir, así que un libro que no puede atender ninguna de las dos patas entrantes es un error de aprovisionamiento, no un libro más acotado. Los otros ocho son opcionales; un flujo que necesita uno ausente rechaza con `409 PIX-0105`, nombrando el perfil, la organización y el ledger — el mismo comportamiento que una clave `routing.*` sin definir produce en el libro predeterminado.
Deja que `jq` haga el escapado de la cadena, como con el 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"
```
Una escritura exitosa responde `204`. Vuelve a leer la clave como vuelves a leer el vínculo — el valor regresa como una cadena entre comillas que lleva tu documento:
```bash theme={null}
curl -s -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
"$PIX_JD_BASE_URL/system/tenant_policy/organizations" | jq
```
La clave es de hot reload: escríbela con la aplicación en marcha y tiene efecto en el deployment en ejecución, sin reinicio y sin redeploy.
El catálogo se valida dos veces, y la división importa: el validador de escritura atrapa todo lo que puede juzgarse solo con el documento, así que un catálogo mal formado se rechaza en la superficie de administración en lugar de descubrirse en un pago.
**Rechazado al escribir**, con `400 validation_error`:
* un `value` que no es una cadena, o cualquier cosa después del primer documento JSON;
* un campo desconocido en cualquier profundidad — incluido un nombre de perfil de ruta mal escrito, para que un error de tipeo no pueda pasar como un perfil ausente en silencio;
* un `ispb` que no es exactamente de 8 dígitos; un `organizationId`, `ledgerId` o pata de ruta que no es un UUID distinto de cero;
* un `externalAlias` o `asset` vacíos; un par de rutas al que le falta cualquiera de las dos patas; una organización que no declara ningún ledger;
* un perfil `in` o `inQrCode` ausente en cualquier ledger;
* un `ispb`, `organizationId` o `ledgerId` duplicados en cualquier parte del documento. Un `403` es un permiso ausente, nunca un valor rechazado.
**Rechazado al leer**, porque solo el riel en ejecución conoce tu vínculo y tu modo. Estos aparecen en la ruta del dinero, antes de cualquier asiento:
| El riel responde | Cuándo |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `500 PIX-0125` | el catálogo contradice el vínculo — vuelve a declarar el ledger predeterminado, pone tu propio ISPB bajo otra organización, le da a otro participante tu organización, o nombra un ISPB ajeno en un despliegue single-tenant — o el documento almacenado ya no se puede parsear. Solo un operador puede despejarlo, así que el pago se rechaza en lugar de archivarse mal |
| `503 PIX-0122` | el catálogo no se pudo **leer**. No se sabe que tenga nada malo, así que el rechazo es reintentable y se despeja solo |
| `500 PIX-0120` | el catálogo está bien y este movimiento resolvió a un alcance que no declara — incluido un registro de cuenta que no nombra ningún ledger usable en una organización que tiene varios |
* **Cada transacción se registra en su alcance.** El asiento lleva la organización y el ledger a los que resolvió, así que el libro de cada institución se mantiene completo y auditable por sí solo.
* **Un crédito entrante encuentra su propio libro.** El ISPB receptor elige la organización; el registro de la cuenta en el CRM elige el ledger. Una organización con un solo ledger tolera un registro que no nombra ninguno — no hay nada entre qué elegir; una con varios no, y rechaza con `500 PIX-0120` en lugar de adivinar.
* **Una orden saliente nombra al participante que paga cuando el tenant es varios.** `POST /v1/transactions` acepta un `payerIspb` opcional. Un tenant que actúa como un participante lo omite y se comporta exactamente como antes; un tenant que actúa como varios debe suministrarlo — omitido es `422 PIX-0127`, y un ISPB que el tenant no opera es `422 PIX-0128` — porque elegir un pagador arbitrariamente debitaría al cliente de otra institución.
* **Entre dos ledgers de la misma organización, la transferencia es interna.** Un alias es único dentro de un ledger, así que no puede ser un solo asiento: el riel reserva el monto en el ledger del pagador contra su cuenta de compensación, registra el crédito final en el ledger del receptor contra *su* cuenta de compensación, y luego confirma la reserva. Las dos patas se asientan en el par de rutas `intraPsp` propio de cada ledger, y cada libro se mantiene internamente de partida doble.
* **Entre dos organizaciones del mismo tenant, el pago es Pix ordinario.** Dos organizaciones son dos participantes regulados, así que el dinero viaja por el riel de liquidación (SPI) exactamente como viajaría un pago a cualquier otra institución — mismo tenant nunca es "mismo libro".
* **Cada participante adicional se autentica como sí mismo.** Las órdenes que salen de una organización adicional se envían a JD con la credencial propia de ese participante, aprovisionada por ISPB. Un participante cuya credencial no está aprovisionada rechaza su primera orden con `409 PIX-0092` y libera la retención, y la sonda de readiness lo reporta caído nombrando ese ISPB antes de que el tráfico le llegue.
## Apagarlo
***
Escribir una cadena vacía de vuelta en `tenant_policy/organizations` se acepta y devuelve al tenant al comportamiento de solo predeterminado — el mismo estado que antes de la activación. No deshace nada ya asentado: el dinero registrado en un alcance adicional se queda en ese ledger, y ya no es alcanzable a través de este riel — cualquier flujo que resuelva a un alcance que el catálogo ya no declara rechaza con `500 PIX-0120` antes de tocar el ledger. Así que vacía la clave solo cuando ya nada se enruta a los libros adicionales: sin cuentas cuyos registros apunten a ellos, sin pagos en vuelo y sin participante hospedado montado sobre una organización adicional. Para retirar un libro conservando la función, elimina la entrada de ese ledger y deja el resto del catálogo en su lugar — la misma prueba de lectura aplica, alcance por alcance.
## A dónde ir después
***
La cadena de aprovisionamiento que esta página extiende: los objetos del ledger, los registros del CRM, las claves de enrutamiento y el vínculo que nombra el par predeterminado.
En qué difiere este eje de hospedar participantes indirectos: un indirecto es una posición dentro de tu libro; una organización adicional es un participante directo con libros propios.
La configuración del momento del despliegue, y qué valores viven en claves del systemplane en su lugar.
Todos los códigos `PIX-NNNN` que esta página nombra, con su estado y el texto `detail` que lleva la respuesta.