Workflow recomendado

Un workflow estructurado mantiene cada transacción clara, trazable y auditable desde el inicio. Sigue los pasos a continuación en orden. Configuran tu Organización, Ledgers, Activos, Tipos de cuenta y Cuentas.

​

Configuración y gestión de Ledgers

---

Cuando te incorporas a Midaz, sigue estos pasos:

​

Paso 1: Configurar la Organización

Tu organización en Midaz representa tu banco o entidad de negocio. Si aún no la has creado, configúrala en la Console o en la API. Confirma que los datos principales sean correctos, como la razón social y los identificadores.

​

Paso 2: Crear los Ledgers

Crea un Ledger dentro de tu organización para contener los registros financieros. La mayoría de las configuraciones empiezan con un ledger principal para todas las operaciones de cara al cliente (por ejemplo, “Main Banking Ledger”). Al principio no contiene cuentas. Sirve como la capa base para toda la actividad financiera.

​

Paso 3: Definir tipos de Activo

Registra los activos que admite tu ledger. Estos pueden incluir monedas (por ejemplo, BRL, USD), puntos o tokens cripto. Usas estos activos en toda la configuración de cuentas y transacciones. Puedes agregar más activos a medida que crece tu portafolio de productos.

​

Paso 4: Crear Tipos de cuenta

Para aplicar reglas de clasificación de cuentas, define tus Tipos de cuenta. Son categorías, por ejemplo user_wallet, treasury o revenue. Las referencias más adelante durante la creación de cuentas o la validación de transacciones. Cada Tipo de cuenta tiene un keyValue. El keyValue debe ser único y alfanumérico, y permite guiones y guiones bajos. Usas estos identificadores en los flujos de validación y en las rutas de transacción.

​

Paso 5: Configurar Rutas contables

Usa las Rutas de operación y la Ruta de transacción (el recurso transactionRoute en la API) para definir y aplicar la validación de tus transacciones.

• Primero, crea las Rutas de operación. Cada Ruta de operación valida un lado de la transacción. Por ejemplo, el débito debe provenir de una cuenta de tipo user_wallet, y el crédito debe ir al alias @external/BRL.
• Luego, crea la Ruta de transacción. Combina las rutas de operación individuales en un flujo completo. Un ejemplo es una transacción de cashout con validaciones específicas de débito y crédito.

​

Paso 6: Gestionar tus Ledgers

Mantén tus ledgers limpios y escalables con las siguientes buenas prácticas:

• Usa el sistema RBAC de Midaz para asignar permisos y controlar el acceso por ledger.
• Planifica ledgers separados cuando sea necesario, por ejemplo “Testing”, “Internal” o “Multi-entity”. Documenta su propiedad.
• Revisa y concilia los datos del ledger con regularidad, especialmente cuando te integras con sistemas de liquidación externos.
• Midaz aplica la lógica de partida doble, por lo que cada movimiento es completamente trazable. No cambies los saldos manualmente.

​

Configuración de Cuentas, Portafolios y Segmentos

---

Esta sección muestra cómo estructurar los datos de clientes y los derechos de producto en Midaz.

​

Paso 1: Crear un Portafolio de cliente

Crea un Portafolio para cada cliente nuevo. Los Portafolios actúan como los contenedores lógicos de las cuentas. Vincula cada portafolio con tu CRM o sistema interno mediante metadatos (por ejemplo, un Entity ID).

​

Paso 2: Configurar Cuentas de cliente

Cada producto financiero o activo que posee el cliente se convierte en una Cuenta separada dentro de su portafolio.

• Una cuenta corriente en BRL y una cuenta de ahorro en USD son cuentas separadas.
• Si habilitas los Tipos de cuenta, el campo type debe coincidir con uno de los valores prerregistrados.
• Usa alias de cuenta para simplificar las operaciones posteriores.

​

Paso 3: Aplicar segmentación

Usa Segmentos para categorizar portafolios o cuentas (por ejemplo, standard, vip, enterprise). Estas etiquetas impulsan la lógica dinámica basada en la segmentación de clientes, como exenciones de tarifas o intereses escalonados.

​

Paso 4: Establecer subcuentas (opcional)

Para organizaciones o casos especiales, puedes configurar subcuentas. Usa convenciones de nombres claras para mantener la trazabilidad (por ejemplo, “Acme USD - Payroll”).

​

Paso 5: Establecer el saldo inicial

Usa la API de Transacciones para agregar el saldo de apertura. Esto mantiene la trazabilidad y el cumplimiento de la partida doble:

• Debita la fuente de fondeo.
• Acredita la cuenta nueva.
• No actualices los saldos manualmente. Midaz rastrea cada valor mediante transacciones.

​

Paso 6: Verificar y revisar

Antes de ejecutar operaciones, revisa lo siguiente:

• Confirma que cada cuenta tenga los activos y tipos correctos.
• Valida los saldos de las cuentas.
• Verifica que hayas aplicado la segmentación.
• Confirma la configuración en la API o en la Console.

​

Paso 7: Gestión continua de Cuentas

Gestiona las operaciones del ciclo de vida mediante la API o la Console para mantener la integridad del sistema:

• Actualiza los datos de la cuenta según sea necesario.
• Cierra las cuentas solo cuando el saldo llegue a cero.
• Reclasifica portafolios/cuentas si cambia la segmentación.

​

Implementación de la gestión de transacciones de partida doble

---

Midaz garantiza la integridad del ledger mediante la aplicación estricta de la lógica de partida doble. Cada transacción debe contener al menos una operación de débito y una de crédito.

​

Paso 1: Estructurar la transacción

Estructura tu objeto de Transacción:

• Después de configurar tu Ruta de transacción, inserta su ID en el campo route del payload de tu transacción.
• Define las cuentas de origen y destino, con sus datos de activo y valor.
• Agrega metadatos descriptivos para mantener la trazabilidad y la claridad.

​

Paso 2: Elegir tu método de integración

Usa la API de Transacciones para la creación programática de transacciones.

​

Paso 3: Aplicar la validación de partida doble

Midaz verifica que la suma de los créditos coincida con la suma de los débitos. Midaz rechaza una transacción que tenga un desajuste o una violación estructural.

​

Paso 4: Implementar la idempotencia

Usa claves de idempotencia para evitar duplicados por reintentos de red. Midaz reconoce una clave repetida y repite la respuesta original en lugar de procesar la solicitud dos veces.

​

Paso 5: Rastrear y conciliar transacciones

Usa las herramientas integradas para:

• Rastrear las transacciones enviadas y contabilizadas.
• Auditar metadatos y marcas de tiempo.
• Conciliar lotes de transacciones para el cumplimiento normativo.

​

Paso 6: Enviar correcciones mediante reversiones

No edites ni elimines transacciones. En su lugar, envía una reversión. Midaz vincula cada reversión con su transacción original para lograr una trazabilidad completa.

​

Paso 7: Optimizar workflows complejos

Usa transacciones multioperación para:

• Procesar la acumulación de intereses.
• Ejecutar pagos por lotes.
• Manejar flujos condicionales con lógica de enrutamiento.

Midaz mantiene la atomicidad en todos los lados. O se contabiliza la transacción completa, o no se contabiliza nada.