Skip to main content
Esta guía te muestra cómo implementar la contabilidad en Midaz de principio a fin. Asume que eres una persona desarrolladora. Quieres suficiente contexto contable para modelar un producto real, no un manual completo de contabilidad. Al terminar, entiendes cómo encajan las primitivas entre sí. También puedes configurar un pago Pix completo con los asientos de partida doble correctos. Para una visión conceptual general y enlaces a cada página de referencia, consulta Contabilidad.

​
1. Fundamentos de la contabilidad de partida doble

Midaz usa una contabilidad estricta de partida doble. Las reglas son simples pero innegociables:
  • Cada transacción debe tener al menos un débito y un crédito.
  • El total de débitos debe ser igual al total de créditos.
  • Cada movimiento impacta el ledger de manera balanceada.
Esto garantiza que no haya desviaciones en los saldos, pistas de auditoría precisas y estados financieros listos para regulación. En la práctica, rara vez haces partida doble a mano en Midaz. Modelas tus cuentas y enrutamiento una vez. El motor aplica el balance en cada transacción.
Piensa en términos de de dónde proviene el valor (el lado del débito / origen) y a dónde va (el lado del crédito / destino). Cada operación de Midaz cae en uno de los lados de esa ecuación.

​
2. El Plan de Cuentas en Midaz

En la contabilidad tradicional, el Plan de Cuentas (PdC) define las categorías de cuentas (Activos, Pasivos, Patrimonio, Ingresos, Gastos), su jerarquía y cómo clasificar los movimientos.
Midaz no tiene una API dedicada de Plan de Cuentas. El PdC no es un recurso que crees o recuperes. Es el resultado de cómo combinas assets, cuentas, segments, portfolios y tipos de cuenta. El campo code de los Asientos Contables (ej. 1.1.1.001) es donde la numeración tradicional de cuentas aparece en la práctica. Cada code anota un asiento con su clasificación.
Midaz te permite reflejar o adaptar un PdC digitalmente usando un pequeño conjunto de primitivas:
  • Assets definen qué se mueve — monedas (BRL, USD), puntos/millas, tokens criptográficos o unidades internas de valor — con precisión decimal y metadatos regulatorios.
  • Cuentas son contenedores de saldo. Cada una pertenece a un portfolio, un segment, un tipo de cuenta y un código de asset. Un alias (ej. @external/BRL) identifica cada cuenta y mantiene el enrutamiento intuitivo.
  • Segments categorizan y aíslan cuentas (fondos de clientes vs. internos, unidades de negocio, separación multi-tenant).
  • Portfolios agrupan cuentas que comparten un propósito o pertenecen a la misma entidad.
Para mapear un PdC en Midaz, decides qué saldos necesitas y los clasificas con Tipos de Cuenta. Luego los organizas con segments y portfolios en un ledger, y asignas valores de code en tus Asientos Contables para que coincidan con tu esquema de numeración.

​
Un proceso recomendado

1

Mapea tu modelo financiero

Lista los saldos que necesitas: saldos de clientes, cuentas internas, cuentas de reserva/liquidación, cuentas de comisiones e ingresos. Este es el plano de tu PdC.
2

Define los tipos de cuenta

Crea un Tipo de Cuenta por categoría conceptual — ej. CASH, SETTLEMENT, FEE_REVENUE, FEE_EXPENSE, TREASURY.
3

Crea segments y portfolios

Los segments separan dominios de negocio (CUSTOMER_FUNDS). Los portfolios gestionan la propiedad y la agrupación (customer_12345_wallet).
4

Crea las cuentas

Para cada saldo lógico, crea una cuenta en el ledger (cuenta BRL del cliente, cuenta de tesorería, cuenta de gastos por comisiones del proveedor, cuenta de liquidación del comerciante).

​
3. Configurar los Tipos de Cuenta

Los Tipos de Cuenta son plantillas para las cuentas de tu ledger. Definen cómo se comportan las cuentas: operaciones permitidas, clasificación interna vs. externa y reglas de conciliación. También te permiten clasificar las cuentas según tu estructura financiera. Una configuración típica para un producto de pagos:
  • CASH → fondos líquidos del cliente
  • SETTLEMENT → fondos pendientes de compensación
  • FEE_REVENUE → comisiones cobradas
  • FEE_EXPENSE → comisiones de proveedores
  • TREASURY → operaciones internas
Para habilitar la validación de Tipo de Cuenta, entender el campo type y gestionar los Tipos de Cuenta a través de la API, consulta Tipos de Cuenta.

​
Entender los compartimentos de saldo

Antes de configurar flujos en dos fases, entiende que cada saldo rastrea los fondos en compartimentos distintos. Un saldo expone dos campos de monto:
  • available — fondos que puedes gastar o enviar ahora mismo. Los débitos y créditos a un saldo mueven este número.
  • onHold — fondos que un hold pendiente reserva y aún no confirma. Midaz los saca de available, pero siguen perteneciendo a la cuenta hasta que confirmas o cancelas la retención.
Ambos campos llevan strings decimales con precisión exacta (por ejemplo, "12.50"). No existe un campo scale separado para interpretarlos. Consulta Monto de la transacción para conocer el modelo de valores decimales. Las acciones de dos fases mueven valor entre available y onHold en el saldo de origen: Para el modelo completo de saldos — múltiples saldos por cuenta, banderas de permisos, sobregiro e historial — consulta Saldos.

​
4. Definir Asientos Contables (Rúbricas)

Los Asientos Contables (Rúbricas) mapean una acción de transacción a las cuentas del ledger que debita y acredita. Registras las rúbricas una vez en lugar de calcular las clasificaciones contables a mano para cada movimiento. Luego Midaz las resuelve automáticamente y registra el routeCode y el routeDescription resultantes en cada operación. Configuras las rúbricas por acción en cada Ruta de Operación, dentro del bloque accountingEntries. Las rutas source requieren la rúbrica de débito, las rutas destination requieren la rúbrica de crédito, y las rutas bidirectional requieren ambas.

​
Las cinco acciones del ciclo de vida de la transacción

Cada acción puede apuntar a diferentes mapeos de débito/crédito dentro de la misma rúbrica. Así, cada etapa de una operación llega al asiento correcto del ledger. Registras estos mapeos a través de los endpoints de Ruta de Operación — consulta Crear una Ruta de Operación.
Para el modelo completo, consulta Asientos Contables (Rúbricas).

​
5. Enrutamiento de transacciones

El enrutamiento es un sistema de dos capas que se resuelve en tiempo de ejecución:
  • Las Rutas de Operación definen la lógica contable de cada tramo de una transacción: qué cuentas debitar o acreditar, las claves de saldo y las reglas de validación. Llevan los Asientos Contables (rúbricas) descritos arriba.
  • Las Rutas de Transacción definen el evento de negocio que dispara la contabilidad (PIX_CASH_OUT, WALLET_TRANSFER, BANK_SLIP_SETTLEMENT, …) y combinan Rutas de Operación en un evento financiero balanceado.
Cuando envías una transacción, Midaz resuelve la Ruta de Transacción coincidente. Luego resuelve cada Ruta de Operación y su rúbrica para la acción actual. Antes de registrar nada, Midaz ejecuta cuatro comprobaciones. Confirma que los saldos existen, que los débitos no exceden el saldo disponible, que los assets coinciden y que el ledger permanece balanceado. Para la estructura de las rutas, los campos, la matriz de validación de tipos de operación y el comportamiento de la API, consulta Enrutamiento de Transacciones.

​
6. Ejemplo de principio a fin — un pago Pix

Atémoslo todo con un simple Pix de retiro (cash-out): un cliente envía BRL desde su billetera a una cuenta externa.
1

Configuración de cuentas

Crea las cuentas en tu ledger:
  • customer_12345_brl — Tipo de Cuenta CASH, asset BRL
  • @external/BRL — la cuenta de liquidación externa para los fondos que salen del ledger
2

Registro de la rúbrica

En la Ruta de Operación del tramo del cliente (origen), registra la rúbrica de débito direct. En el tramo externo (destino), registra la rúbrica de crédito direct:
3

Transacción

Envía una transacción contra la Ruta de Transacción PIX_CASH_OUT. Mueve, digamos, 100.00 BRL de customer_12345_brl a @external/BRL.
4

Operaciones resultantes

Midaz registra dos operaciones balanceadas:
  • Débito a customer_12345_brl 100.00 BRL, routeCode: 1.1.1.001
  • Crédito a @external/BRL 100.00 BRL, routeCode: 2.1.1.001
Ambas comparten el mismo transactionId, dándote una pista completa desde la transacción → operación → rúbrica.
Para un flujo en dos fases (hold → commit/cancel), registra las rúbricas hold, commit y cancel en la ruta. Envía las acciones correspondientes. Cada etapa resuelve su propia rúbrica.

​
7. Modos de validación

Midaz controla la validación de rutas con la configuración accounting.validateRoutes en cada ledger. El valor predeterminado es false. En este modo tolerante, Midaz omite la validación de rutas. Deja vacíos los campos routeCode y routeDescription en cada operación y no genera ningún error. El modo tolerante es conveniente mientras configuras las rutas. En producción, establece accounting.validateRoutes en true en la Configuración del Ledger. El modo estricto valida entonces las rutas en cada transacción:
En el modo estricto, cada operación debe referenciar una ruta de operación válida para su acción y dirección. Si una operación no tiene ruta, o referencia una ruta que no existe para la acción, Midaz rechaza la transacción con 0117 ErrAccountingRouteNotFound. Cuando la ruta se resuelve, Midaz estampa el routeCode y el routeDescription desde su rúbrica. Esto evita que los movimientos caigan sin una clasificación contable.
Usa el modo estricto (validateRoutes: true) en ledgers de producción donde cada tipo de transacción necesita una clasificación contable. Mantén el valor predeterminado tolerante solo mientras configuras las rutas.

​
Próximos pasos

  • Revisa la visión general de Contabilidad y las páginas de referencia para el detalle completo a nivel de campo.
  • Una vez que tu ledger produzca asientos estructurados, consulta Lerian Reporter para transformar los eventos del ledger en archivos de conciliación, estados financieros y salidas regulatorias alineadas con COSIF.