Saltar al contenido principal
Esta guía te lleva por la implementación de la contabilidad en Midaz de principio a fin. Asume que eres una persona desarrolladora que quiere suficiente contexto contable para modelar un producto real correctamente — no un manual completo de contabilidad. Al terminar entenderás cómo encajan las primitivas entre sí y cómo configurar un pago Pix completo con los asientos de partida doble adecuados. 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 está construido sobre 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, y 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 se clasifican 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, anotando cada 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 — junto con la precisión decimal y los 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, y se identifica por un alias (ej. @external/BRL) para hacer 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.
Mapear un PdC en Midaz significa decidir qué saldos necesitas, clasificarlos con Tipos de Cuenta, organizarlos con segments y portfolios en un ledger, y asignar valores de code en tus Asientos Contables para reflejar tu esquema de numeración de cuentas.

​
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 — y 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 saber cómo habilitar la validación de Tipo de Cuenta, el comportamiento del campo type y cómo 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, conviene saber que cada saldo rastrea los fondos en compartimentos distintos. Un saldo se expone a través de tres campos:
  • available — fondos libres para gastar o enviar ahora mismo. Los débitos y créditos a un saldo mueven este número.
  • onHold — fondos reservados por un hold pendiente y aún no confirmados. Se retiran de available pero siguen perteneciendo a la cuenta hasta que la retención se confirma o se cancela.
  • scale — la cantidad de decimales usados para interpretar los montos enteros (ej. scale: 2 significa que available: 100 es 1.00). Define la precisión, no un grupo de fondos separado.
Las acciones de dos fases mueven valor entre available y onHold en el saldo de origen:
AcciónavailableonHold
DirectDebitado (origen) / acreditado (destino)sin cambios
Hold↓ disminuye en el origen↑ aumenta en el origen
Commitacreditado en el destino↓ liberado del origen
Cancel↑ devuelto al origen↓ liberado de vuelta a available
Revertrestaurado en ambos lados vía una contra-transacciónsin cambios
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. En lugar de calcular las clasificaciones contables a mano para cada movimiento, registras las rúbricas una vez y dejas que Midaz las resuelva automáticamente — registrando el routeCode y el routeDescription resultantes en cada operación. Las rúbricas se configuran 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.

​
Los cinco tipos de acción

AcciónCódigoQué hace
DirectdirectDébito/crédito inmediato, de un solo paso, entre dos cuentas, sin etapas intermedias (ej. una comisión o un ajuste).
HoldholdReserva fondos creando un movimiento pendiente (available → on_hold en el origen).
CommitcommitConfirma un monto previamente retenido, liberando on_hold al destino.
CancelcancelCancela una retención, devolviendo el valor on_hold a available en el origen.
RevertrevertRevierte una transacción direct completada vía una contra-transacción.
Cada acción puede apuntar a diferentes mapeos de débito/crédito dentro de la misma rúbrica, de modo que cada etapa de una operación llegue al asiento correcto del ledger. Las registras a través de los endpoints de Ruta de Operación — consulta Crear una Ruta de Operación. 
{
  "accountingEntries": {
    "direct": {
      "debit":  { "code": "1.1.1.001", "description": "Customer cash-out" },
      "credit": { "code": "2.1.1.001", "description": "External settlement" }
    },
    "hold": {
      "debit": { "code": "1.1.2.001", "description": "Pending settlement — hold" }
    }
  }
}
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 se debitan/acreditan, las claves de saldo, las reglas de validación — y 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 se envía 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 que se realiza. Valida que los saldos existan, que los débitos no excedan el saldo disponible, que los assets coincidan y que el ledger permanezca balanceado — antes de registrar nada. 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:
{
  "accountingEntries": {
    "direct": {
      "debit":  { "code": "1.1.1.001", "description": "Pix cash-out — customer" },
      "credit": { "code": "2.1.1.001", "description": "Pix cash-out — external settlement" }
    }
  }
}
3

Transacción

Envía una transacción contra la Ruta de Transacción PIX_CASH_OUT, moviendo, 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 y envía las acciones correspondientes; cada etapa resuelve su propia rúbrica.

​
7. Modos de validación

Por defecto, si no hay una rúbrica registrada para una acción, la transacción procede normalmente y los campos routeCode/routeDescription simplemente se dejan vacíos para esa operación — no se genera ningún error. Este modo tolerante es conveniente mientras aún estás configurando las rutas. En producción, establece accounting.validateRoutes en true en la Configuración del Ledger para exigir que cada acción tenga una rúbrica registrada: 
{
  "accounting": {
    "validateRoutes": true
  }
}
Con el modo estricto habilitado, cualquier operación cuya acción y dirección no tenga un mapeo registrado se rechaza con 0117 ErrAccountingRouteNotFound. Esto previene que los movimientos caigan silenciosamente sin una clasificación contable.
Usa el modo estricto (validateRoutes: true) en ledgers de producción donde cada tipo de transacción debe estar contabilizado. 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.