Skip to main content
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 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: 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. 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

1

Completa primero la configuración ordinaria

El catálogo extiende un despliegue que funciona; no reemplaza la configuración. Ejecuta Configurar el riel 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.
2

Aprovisiona el libro adicional en Midaz y el CRM

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.
3

Escribe el catálogo

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:
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:
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:
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.
4

Conoce qué rechazan los validadores, y cuándo

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:
5

Entiende cómo se enruta el dinero una vez activo

  • 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

Configurar el riel

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.

El modelo directo e indirecto

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.

Variables de entorno

La configuración del momento del despliegue, y qué valores viven en claves del systemplane en su lugar.

Lista de errores de Pix JD

Todos los códigos PIX-NNNN que esta página nombra, con su estado y el texto detail que lleva la respuesta.