Saltar al contenido principal
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. Ese par es el valor predeterminado. Un despliegue también puede servir a un grupo económico. Por ejemplo, un holding puede operar una institución de pago, una fintech de crédito y un banco. Cada institución regulada conserva su propia organización, y cada organización tiene tantos ledgers como necesite. Toda la función es un toggle en una sola clave del systemplane. Mientras esa clave está vacía, el riel se comporta exactamente como antes de que la clave existiera. Un despliegue que es una institución con un libro no necesita esta página. Para ese despliegue, Configurar el riel es suficiente.

​
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 lista los archivadores y los cajones. Un empleado archiva los movimientos de dinero solo en un cajón que está en el índice. El empleado devuelve un movimiento para un cajón que no está en el índice, y nunca lo archiva en un cajón “suficientemente parecido”. El vocabulario del riel corresponde uno a uno: Del modelo salen dos resultados:
  • Cada asiento lleva su alcance. El riel escribe cada transacción en la organización y el ledger a los que resolvió. Por eso, los registros de cada institución están completos por sí solos. Los informes regulatorios y contables salen por institución, sin un libro compartido que separar.
  • El riel nunca adivina un alcance. Comprueba la organización y el ledger de un movimiento contra el catálogo. Si no puede probarlos, rechaza el movimiento antes de cualquier asiento. El diseño existe para hacer imposible que el dinero caiga en el ledger de la institución equivocada.

​
El toggle: una clave vacía significa apagado

La clave del catálogo empieza vacía, y vacía significa no aprovisionada. El tenant registra entonces solo en la organización y el ledger que nombra su vínculo, como antes de que la clave existiera. Una escritura del catálogo activa la función. El par que nombra el vínculo sigue siendo el predeterminado: el alcance de cada flujo que no resuelve otro.
El ledger predeterminado nunca está en el catálogo. Sus rutas contables se quedan en las claves routing.*, y su activo y su cuenta de compensación se quedan en las claves midaz.*. Configurar el riel muestra cómo aprovisionarlos. El catálogo declara solo lo que el vínculo no declara. Una copia del ledger predeterminado en el catálogo le daría a un libro dos fuentes de verdad, así que el riel rechaza ese catálogo.
El despliegue define hasta dónde llega el toggle. Un despliegue self-hosted es un participante directo. Su catálogo puede agregar ledgers de su propia organización: más libros de la misma institución. Una entrada que lleve cualquier otro ISPB se rechaza en el momento de la lectura, porque un despliegue self-hosted tiene una sola credencial de JD y no puede autenticarse como una segunda institución. Para actuar como varios participantes, con varios ISPB bajo un mismo techo, habla con Lerian sobre Lerian Cloud, donde cada participante adicional tiene 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 principio a fin. 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í. Mientras la clave del catálogo está vacía, nada en esta página cambia nada.
2

Aprovisiona el libro adicional en Midaz y el CRM

Aprovisiona cada ledger adicional con los mismos pasos de la página de configuración, en el libro nuevo:
  1. La organización y el ledger. Un ledger adicional de tu propia institución va bajo tu organización existente. Un participante adicional recibe su propia organización, porque cada organización de Midaz contiene exactamente una institución regulada.
  2. El activo y las cuentas en el ledger nuevo, con 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 del libro. Estos UUID no van en las claves routing.*. Van dentro del documento del catálogo en el paso siguiente.
  4. Los titulares y los instrumentos en el CRM, en la organización dueña del libro. El ledgerId del instrumento le dice al riel en qué libro opera una cuenta.
3

Escribe el catálogo

Escribe el catálogo con una sola llamada a PUT /system/tenant_policy/organizations. La envoltura es la misma que la del vínculo. El cuerpo es {"value": ...}, y value es una cadena cuyo contenido es un documento JSON. El documento es una lista con una entrada por organización del catálogo. Cada entrada nombra el ISPB de su participante, su organización de Midaz y los ledgers de esa organización con sus rutas.Tu propia organización está en el catálogo solo cuando tiene ledgers adicionales, y nunca con el ledger predeterminado. La organización de un participante adicional siempre está en él.Este es el documento, sin envolver, con identificadores de ejemplo:
En un despliegue self-hosted, la entrada tiene tu propio ISPB y tu propio id de organización, y los ledgers son los libros adicionales.Cada perfil es un par de UUID de rutas de operación de Midaz.Solo in e inQrCode son obligatorios, porque cada ledger del catálogo existe para recibir. Un libro que no puede atender ninguna de las dos patas entrantes muestra un error de aprovisionamiento. Sin refundSent, una devolución que envías se registra en out. Cualquier otro flujo que necesita un perfil ausente rechaza con 409 PIX-0105, y la respuesta nombra el perfil, la organización y el ledger. Una clave routing.* sin definir en el libro predeterminado se comporta de la misma forma.Tres campos son opcionales:
  • transactionRoute, dentro de un perfil: el UUID de la ruta de transacción de Midaz que nombran los asientos de ese perfil en este ledger. Defínelo cuando el ledger valida rutas. Sin él, un ledger así rechaza el asiento. Sin el campo, el asiento no lleva ruta de transacción.
  • sharedIspbGate, en una entrada: true declara que este participante comparte su ISPB con otro core. Sus transferencias on-us consultan entonces primero el mapa de propiedad de Courier. La organización predeterminada declara el mismo hecho con la clave tenant_policy/onus.shared_ispb_gate_enabled. Consulta Mapa de propiedad de Courier.
  • qrPublicBaseUrl, en una entrada: el host donde este participante publica sus QR codes dinámicos. Consulta Alojamiento de QR codes dinámicos.
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 con tu documento:
La clave se recarga sin reinicio. Escríbela con la aplicación en marcha, y el despliegue en ejecución la usa, sin reinicio y sin redeploy.
4

Conoce qué rechazan los validadores, y cuándo

El riel valida el catálogo dos veces. El validador de escritura atrapa cada error que muestra el documento por sí solo. Por eso, la superficie de administración rechaza un catálogo mal formado antes de que lo encuentre un pago.La escritura rechaza estos valores, 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. Un nombre de perfil de ruta mal escrito también es un campo desconocido, así que un error de tipeo no puede pasar como un perfil ausente.
  • un ispb que no tiene exactamente 8 letras mayúsculas o dígitos.
  • un organizationId, ledgerId, pata de ruta o transactionRoute que no es un UUID distinto de cero.
  • un externalAlias o asset vacíos, un par de rutas sin una de sus patas, o una organización sin ledger.
  • un ledger sin el perfil in o sin el perfil inQrCode.
  • el mismo ispb, organizationId o ledgerId dos veces en cualquier parte del documento.
  • un qrPublicBaseUrl con esquema, puerto, query, fragmento, información de usuario, un host que no es público, o más de 37 caracteres.
Un 403 significa un permiso ausente, nunca un valor rechazado.La lectura rechaza otros casos, porque solo el riel en ejecución conoce tu vínculo y tu modo. Los rechazos aparecen en la ruta del dinero, antes de cualquier asiento:
5

Entiende cómo se enruta el dinero una vez activo

  • Cada transacción va a su alcance. El asiento lleva la organización y el ledger a los que resolvió. Por eso, 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 acepta un registro que no nombra ningún ledger, porque no tiene nada que elegir. Una organización con varios ledgers rechaza ese registro con 500 PIX-0120 y no adivina.
  • 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. Un tenant que actúa como varios debe enviarlo. Sin él, la orden responde 422 PIX-0127. Un ISPB que el tenant no opera responde 422 PIX-0128. Un pagador arbitrario podría debitar 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 un solo asiento no puede contener las dos patas. El riel reserva el monto en el ledger del pagador contra su cuenta de compensación. Luego registra el crédito en el ledger del receptor contra la cuenta de compensación de ese ledger. Por último, confirma la reserva. Las dos patas usan el par de rutas intraPsp propio de cada ledger, y cada libro se mantiene de partida doble por sí solo.
  • Entre dos organizaciones del mismo tenant, el pago es Pix ordinario. Dos organizaciones son dos participantes regulados. Por eso, el dinero va por el riel de liquidación (SPI), como un pago a cualquier otra institución. El mismo tenant nunca es “el 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

Puedes escribir una cadena vacía de vuelta en tenant_policy/organizations. El tenant vuelve entonces al comportamiento de solo predeterminado, como antes de la activación. Esto no deshace nada ya asentado. El dinero registrado en un alcance adicional se queda en ese ledger, y este riel ya no puede alcanzarlo. Un flujo que resuelve 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 nada se enruta a los libros adicionales. Eso significa ninguna cuenta cuyos registros apunten a ellos, ningún pago en vuelo y ningún participante hospedado en una organización adicional. Para retirar un libro y conservar la función, elimina la entrada de ese ledger y conserva el resto del catálogo. 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 los valores que 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 de la respuesta.