Skip to main content
Has explorado cómo funciona Midaz, desde sus entidades centrales hasta su arquitectura y seguridad. Esta página convierte ese conocimiento en una configuración funcional. Un flujo de trabajo estructurado mantiene cada transacción clara, trazable y auditable desde el principio. 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 Libros Contables

Cuando te incorporas a Midaz, sigue estos pasos para construir una base sólida para tu infraestructura financiera:
Flujo de trabajo para configurar y gestionar ledgers durante la incorporación a Midaz

Figura 1. Flujo de trabajo para configurar y gestionar libros contables.

​
Paso 1: Configurar la Organización

Tu organización en Midaz representa tu banco o entidad comercial. Si aún no la has creado, configúrala en la Consola o API. Asegúrate de que los detalles principales sean precisos, como el nombre legal y los identificadores. Este contexto sustenta todas las operaciones del libro contable.

​
Paso 2: Crear los Libros Contables

Crea un Libro Contable bajo tu organización para mantener registros financieros. La mayoría de las configuraciones comienzan con un libro contable principal para todas las operaciones orientadas al cliente (por ejemplo, “Libro Contable Bancario Principal”). Al inicio no contiene cuentas. Sirve como la capa base para toda la actividad financiera.

​
Paso 3: Definir tipos de Activos

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

​
Paso 4: Crear Tipos de Cuenta

Para aplicar reglas de clasificación de cuentas, define tus Tipos de Cuenta. Estas son categorías estructuradas, por ejemplo user_wallet, treasury o revenue. Las referencias más tarde durante la creación de cuentas o la validación de transacciones.
Cuando habilitas la validación de Tipos de Cuenta, cada cuenta nueva debe usar un Tipo de Cuenta registrado. Por defecto, los Tipos de Cuenta son opcionales. Esto mantiene la clasificación consistente en todo tu libro contable.
Cada Tipo de Cuenta tiene un keyValue. El keyValue debe ser único y alfanumérico, con guiones y guiones bajos permitidos. Usas estos identificadores en flujos de validación y rutas de transacción.

​
Paso 5: Configurar Rutas Contables

Usa 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 tramo 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 retiro de efectivo con validaciones específicas de débito y crédito.
Después de que configuras el enrutamiento y habilitas la validación en el libro contable, todas las transacciones deben coincidir con la estructura de enrutamiento definida. Midaz rechaza cualquier transacción que no coincida.El campo route en el payload de la transacción debe incluir el ID de la Ruta de Transacción que creaste.

​
Paso 6: Gestionar tus Libros Contables

Mantén tus libros contables limpios y escalables con las siguientes mejores prácticas:
  • Usa el sistema RBAC de Midaz para asignar permisos y controlar el acceso por libro contable.
  • Planifica libros contables separados cuando sea necesario, por ejemplo “Pruebas”, “Interno” o “Multi-entidad”. Documenta su propiedad.
  • Revisa y concilia los datos del libro contable con regularidad, especialmente cuando integras con sistemas de liquidación externos.
  • Midaz aplica lógica de doble entrada, por lo que cada movimiento es completamente rastreable. No cambies los saldos manualmente.

​
Configuración de Cuentas, Portafolios y Segmentos

Esta sección muestra cómo estructurar los datos del cliente y los derechos de productos en Midaz.
Flujo de trabajo para configurar cuentas, portafolios y segmentos con el fin de estructurar los datos de clientes y los derechos de producto en Midaz

Figura 2. Flujo de trabajo para configurar Cuentas, Portafolios y Segmentos.

​
Paso 1: Crear un Portafolio de cliente

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

​
Paso 2: Configurar Cuentas de cliente

Cada producto financiero o activo que posee el cliente se convierte en una Cuenta separada bajo su portafolio.
  • Una cuenta corriente en BRL y una cuenta de ahorros en USD son cuentas separadas.
  • Si habilitas los Tipos de Cuenta, el campo type debe coincidir con uno de los valores pre-registrados.
  • Usa alias de cuenta para simplificar las operaciones posteriores.
Los Tipos de Cuenta estandarizan la categorización de cuentas en todo tu ecosistema. Mejoran el enrutamiento, los informes y las integraciones.

​
Paso 3: Aplicar segmentación

Usa Segmentos para categorizar portafolios o cuentas (por ejemplo, standard, vip, enterprise). Estas etiquetas impulsan lógica dinámica basada en la segmentación del cliente, como exenciones de comisiones o interés escalonado.

​
Paso 4: Establecer subcuentas (opcional)

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

​
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 doble entrada:
  • Debita la fuente de financiamiento.
  • Acredita la nueva cuenta.
  • No actualices los saldos manualmente. Midaz rastrea cada valor a través de transacciones.

​
Paso 6: Verificar y revisar

Antes de ejecutar operaciones, verifica lo siguiente:
  • Confirma que cada cuenta tiene los activos y tipos correctos.
  • Valida los saldos de las cuentas.
  • Verifica que aplicaste la segmentación.
  • Confirma la configuración en la API o la Consola.

​
Paso 7: Gestión continua de Cuentas

Gestiona las operaciones de ciclo de vida a través de la API o la Consola para mantener la integridad del sistema:
  • Actualiza los detalles de la cuenta según sea necesario.
  • Cierra cuentas solo una vez que el saldo llegue a cero.
  • Reclasifica portafolios/cuentas si cambia la segmentación.

​
Implementación de gestión de transacciones de doble entrada

Midaz garantiza la integridad del libro contable mediante la aplicación estricta de la lógica de doble entrada. Cada transacción debe contener al menos una operación de débito y una de crédito.
Flujo de trabajo para implementar la gestión de transacciones por partida doble, donde cada transacción lleva al menos una operación de débito y una de crédito

Figura 3. Flujo de trabajo para implementar gestión de transacciones de doble entrada

​
Paso 1: Estructurar la transacción

Estructura tu objeto Transacción:
  • Después de que configuras tu Ruta de Transacción, inserta su ID en el campo route de tu payload de transacción.
  • Define las cuentas de origen y destino, con sus detalles 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 crear transacciones de forma programática.

​
Paso 3: Aplicar validación de doble entrada

Midaz verifica que la suma de créditos coincida con la suma de débitos. Midaz rechaza una transacción que tiene una discrepancia o una violación estructural.

​
Paso 4: Implementar idempotencia

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

​
Paso 5: Rastrear y conciliar transacciones

Usa las herramientas integradas para:
  • Rastrear transacciones enviadas y publicadas.
  • Auditar metadatos y marcas de tiempo.
  • Conciliar lotes de transacciones para cumplimiento.

​
Paso 6: Enviar correcciones a través de reversiones

No edites ni elimines transacciones. Envía una reversión en su lugar. Midaz vincula cada reversión a su transacción original para trazabilidad completa.

​
Paso 7: Optimizar flujos de trabajo complejos

Usa transacciones de múltiples operaciones para:
  • Procesar acumulaciones de intereses.
  • Ejecutar pagos por lotes.
  • Manejar flujos condicionales con lógica de enrutamiento.
Midaz mantiene la atomicidad en todos los tramos. O la transacción completa se publica, o nada lo hace.