Flujo de trabajo recomendado

Has explorado cómo funciona Midaz—desde sus entidades centrales hasta su arquitectura, lógica y seguridad. Ahora es el momento de poner ese conocimiento en acción. Ya sea que estés lanzando un producto fintech o modernizando sistemas internos, los flujos de trabajo estructurados son clave para traducir los conceptos de Midaz en operaciones financieras del mundo real. Los gerentes de producto e ingenieros juegan un papel central en este proceso—especialmente en el Modelo Comunitario, donde las características principales se alojan por cuenta propia y sin plugins. Piensa en cada transacción como un evento de libro contable. Con esa mentalidad, los flujos de trabajo descritos aquí te ayudarán a aplicar todo lo que has aprendido—asegurando claridad, trazabilidad y auditabilidad desde el principio.

​

Configuración y gestión de Libros Contables

---

Al incorporarte a Midaz, sigue estos pasos clave para establecer una base sólida para tu infraestructura financiera:

​

Paso 1: Configurar la Organización

Tu organización en Midaz representa tu banco o entidad comercial. Si aún no se ha creado, configúrala a través de la Consola o API. Asegúrate de que todos los detalles principales, como el nombre legal y los identificadores, sean precisos, ya que este contexto sustentará todas las operaciones del libro contable.

​

Paso 2: Crear los Libros Contables

Crea un Libro Contable bajo tu organización para mantener registros financieros. Es común comenzar con un libro contable principal para todas las operaciones orientadas al cliente (por ejemplo, “Libro Contable Bancario Principal”). Inicialmente, no contendrá cuentas, pero sirve como la capa base para toda la actividad financiera.

​

Paso 3: Definir tipos de Activos

Registra los activos que tu libro contable admitirá—esto puede incluir monedas (por ejemplo, BRL, USD), puntos o incluso tokens cripto. Estos activos se utilizarán en toda tu configuración de cuentas y transacciones. Los activos pueden extenderse a medida que evoluciona tu cartera de productos.

​

Paso 4: Crear Tipos de Cuenta

Si planeas aplicar reglas de clasificación de cuentas, define tus Tipos de Cuenta. Estos representan categorías estructuradas (por ejemplo, user_wallet, treasury, revenue) que luego pueden referenciarse durante la creación de cuentas o la validación de transacciones. Cada Tipo de Cuenta tiene un keyValue, que debe ser único y alfanumérico (se permiten guiones y guiones bajos). Estos identificadores se utilizarán en flujos de validación y rutas de transacción.

​

Paso 5: Configurar Rutas Contables

Usa Rutas de Operación y Rutas Contables (el recurso transactionRoute en la API) para definir y aplicar validación estructurada para tus transacciones.

• Comienza creando las Rutas de Operación, que validan cada tramo de la transacción individualmente (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, combinando las rutas de operación individuales en un flujo completo (por ejemplo, una transacción de retiro de efectivo con validaciones específicas de débito y crédito).

​

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”, “Multi-entidad”), y documenta la propiedad.
• Revisa y concilia periódicamente los datos del libro contable, especialmente al integrar con sistemas de liquidación externos.
• Midaz aplica lógica de doble entrada, por lo que cada movimiento es completamente rastreable—sin cambios manuales de saldo.

​

Configuración de Cuentas, Portafolios y Segmentos

---

Esta sección te ayuda a estructurar los datos del cliente y los derechos de productos en Midaz.

​

Paso 1: Crear un Portafolio de cliente

Comienza creando 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, 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 los Tipos de Cuenta están habilitados, el campo type se vuelve obligatorio y debe coincidir con uno de los valores pre-registrados.
• 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 permiten lógica dinámica (por ejemplo, exenciones de comisiones, interés escalonado) basada en la segmentación del cliente.

​

Paso 4: Establecer subcuentas (opcional)

Para organizaciones o casos especializados, 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 inyectar el saldo de apertura. Esto asegura trazabilidad y cumplimiento de doble entrada:

• Debita la fuente de financiamiento.
• Acredita la nueva cuenta.
• No actualices manualmente los saldos—Midaz rastrea cada valor a través de transacciones.

​

Paso 6: Verificar y revisar

Antes de proceder con las operaciones:

• Confirma que las cuentas se crearon con los activos y tipos correctos.
• Valida los saldos de las cuentas.
• Verifica si se ha aplicado la segmentación.
• Confirma la configuración a través de la API o la Consola.

​

Paso 7: Gestión continua de Cuentas

Mantén la integridad del sistema gestionando operaciones de ciclo de vida a través de API o Consola:

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

​

Paso 1: Estructurar la transacción

Comienza estructurando tu objeto Transacción:

• Una vez que tu Ruta de Transacción esté configurada, inserta su ID en el campo route de tu payload de transacción.
• Define las cuentas de origen y destino, incluyendo detalles de activo y valor.
• Agrega metadatos descriptivos para garantizar trazabilidad y claridad.

​

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

Puedes definir transacciones a través de:

• DSL de Transacciones (Lenguaje Gold) – una sintaxis legible por humanos para prototipado rápido.
• API de Transacciones – para control completo y ejecución programática.

Ambos enfoques son totalmente compatibles y producen entradas de libro contable idénticas.

​

Paso 3: Aplicar validación de doble entrada

Midaz verifica automáticamente que la suma de créditos coincida con la suma de débitos. Las discrepancias o violaciones estructurales rechazarán la transacción al enviarla.

​

Paso 4: Implementar idempotencia

Usa claves de idempotencia para prevenir duplicados de reintentos de red. Midaz reconocerá claves repetidas y evitará el procesamiento duplicado.

​

Paso 5: Rastrear y conciliar transacciones

Usa 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

En lugar de editar o eliminar transacciones, envía entradas correctivas. Cada reversión está vinculada a su original a través de los metadatos de la transacción 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 garantiza atomicidad en todos los tramos—o la transacción completa se publica, o nada lo hace.