Configuración y gestión de Libros Contables
Al incorporarse a Midaz, siga estos pasos clave para establecer una base sólida para su infraestructura financiera:
Figura 1. Flujo de trabajo para configurar y gestionar libros contables.
Paso 1: Configurar la Organización
Su organización en Midaz representa su banco o entidad comercial. Si aún no se ha creado, configúrela a través de la Consola o API. Asegúrese 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
Cree un Libro Contable bajo su 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
Registre los activos que su libro contable admitirá—esto puede incluir monedas (por ejemplo, BRL, USD), puntos o incluso tokens cripto. Estos activos se utilizarán en toda su configuración de cuentas y transacciones. Los activos pueden extenderse a medida que evoluciona su cartera de productos.Paso 4: Crear Tipos de Cuenta
Si planea aplicar reglas de clasificación de cuentas, defina sus 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.
Los Tipos de Cuenta son opcionales por defecto, pero cuando están habilitados, se vuelven obligatorios durante la creación de cuentas para garantizar la consistencia de clasificación en todo su libro contable.
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 Enrutamiento de Transacciones
Use Rutas de Operación y Rutas de Transacción para definir y aplicar validación estructurada para sus transacciones.- Comience 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, cree 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).
Una vez que el enrutamiento esté configurado y la validación esté habilitada en el libro contable, todas las transacciones enviadas deben cumplir con la estructura de enrutamiento definida—de lo contrario, serán rechazadas.El campo
route en el payload de la transacción debe incluir el ID de la Ruta de Transacción que creó.Paso 6: Gestionar sus Libros Contables
Mantenga sus libros contables limpios y escalables con las siguientes mejores prácticas:- Use el sistema RBAC de Midaz para asignar permisos y controlar el acceso por libro contable.
- Planifique libros contables separados cuando sea necesario (por ejemplo, “Pruebas”, “Interno”, “Multi-entidad”), y documente la propiedad.
- Revise y concilie 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 le ayuda a estructurar los datos del cliente y los derechos de productos en Midaz.
Figura 2. Flujo de trabajo para configurar Cuentas, Portafolios y Segmentos.
Paso 1: Crear un Portafolio de cliente
Comience creando un Portafolio para cada nuevo cliente. Los Portafolios actúan como los contenedores lógicos para las cuentas. Vincule cada portafolio a su 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
typese vuelve obligatorio y debe coincidir con uno de los valores pre-registrados. - Use alias de cuenta para simplificar las operaciones posteriores.
Los Tipos de Cuenta ayudan a estandarizar la categorización de cuentas en todo su ecosistema—mejorando el enrutamiento, los informes y las integraciones.
Paso 3: Aplicar segmentación
Use 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, puede configurar subcuentas. Use convenciones de nomenclatura claras para mantener la trazabilidad (por ejemplo, “Acme USD - Nómina”).Paso 5: Establecer el saldo inicial
Use la API de Transacciones para inyectar el saldo de apertura. Esto asegura trazabilidad y cumplimiento de doble entrada:- Debite la fuente de financiamiento.
- Acredite la nueva cuenta.
- No actualice manualmente los saldos—Midaz rastrea cada valor a través de transacciones.
Paso 6: Verificar y revisar
Antes de proceder con las operaciones:- Confirme que las cuentas se crearon con los activos y tipos correctos.
- Valide los saldos de las cuentas.
- Verifique si se ha aplicado la segmentación.
- Confirme la configuración a través de la API o la Consola.
Paso 7: Gestión continua de Cuentas
Mantenga la integridad del sistema gestionando operaciones de ciclo de vida a través de API o Consola:- Actualice los detalles de la cuenta según sea necesario.
- Cierre cuentas solo una vez que el saldo llegue a cero.
- Reclasifique 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.
Figura 3. Flujo de trabajo para implementar gestión de transacciones de doble entrada
Paso 1: Estructurar la transacción
Comience estructurando su objeto Transacción:- Una vez que su Ruta de Transacción esté configurada, inserte su ID en el campo
routede su payload de transacción. - Defina las cuentas de origen y destino, incluyendo detalles de activo y valor.
- Agregue metadatos descriptivos para garantizar trazabilidad y claridad.
Paso 2: Elegir su método de integración
Puede 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.
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
Use 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
Use 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íe 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
Use transacciones de múltiples operaciones para:- Procesar acumulaciones de intereses.
- Ejecutar pagos por lotes.
- Manejar flujos condicionales con lógica de enrutamiento.