Recorrido de contabilidad

Esta guía te muestra cómo implementar la contabilidad en Midaz de principio a fin. Supone que eres desarrollador. Necesitas suficiente contexto contable para modelar un producto real, no un manual completo de contabilidad. Al final, entiendes cómo encajan las primitivas entre sí. También puedes configurar un pago Pix completo con apuntes de doble entrada correctos. Para la visión general conceptual y los enlaces a cada página de referencia, consulta Contabilidad.

1. Fundamentos de la contabilidad de doble entrada

Midaz admite la contabilidad de doble entrada mediante sus rutas de transacción. Configura una ruta con Rutas de operación de origen y de destino, o una Ruta de operación bidireccional que cubra ambos lados. Con la Validación de rutas habilitada, Midaz valida las reglas de ruta configuradas para las transacciones directas. La validación de rutas está deshabilitada de forma predeterminada. Habilítala solo después de configurar las rutas que necesita tu Ledger. No todas las acciones de ciclo de vida usan ambos lados: la cancelación opera solo del lado del origen y libera los fondos retenidos en la cuenta de origen.

Piensa en de dónde viene 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 un lado de esa ecuación.

2. Plan de cuentas en Midaz

En la contabilidad tradicional, el Plan de cuentas define las categorías de cuenta (Activos, Pasivos, Patrimonio, Ingresos, Gastos), su jerarquía y cómo clasificar los movimientos.

Midaz no tiene una API dedicada para el Plan de cuentas. El Plan de cuentas es el resultado de cómo combinas activos, cuentas, segmentos, portafolios y tipos de cuenta. El campo code de los Asientos contables (por ejemplo, 1.1.1.001) es donde aparece en la práctica la numeración de cuentas tradicional. Cada code anota un apunte con su clasificación.

Midaz permite reflejar o adaptar un Plan de cuentas de forma digital con un pequeño conjunto de primitivas:

Activos definen qué se mueve: monedas (BRL, USD), puntos/millas, tokens cripto o unidades internas de valor. Cada activo tiene precisión decimal y metadatos regulatorios.
Cuentas son contenedores de saldo. Cada una tiene un código de activo y un tipo. También puede pertenecer a un portafolio y a un segmento. Un alias (por ejemplo, @external/BRL) identifica cada cuenta y mantiene el enrutamiento intuitivo.
Segmentos categorizan y aíslan cuentas (fondos de clientes frente a fondos internos, unidades de negocio, separación multi-tenant).
Portafolios agrupan cuentas que comparten un propósito o pertenecen a la misma entidad.

Para mapear un Plan de cuentas en Midaz, decides qué saldos necesitas y los clasificas con Tipos de cuenta. Luego los organizas con segmentos y portafolios en un ledger, y asignas valores code en tus Asientos contables para que coincidan con tu esquema de numeración.

Un proceso recomendado

Mapea tu modelo financiero

Enumera 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 Plan de cuentas.

Define los tipos de cuenta

Crea un Tipo de cuenta por cada categoría conceptual, por ejemplo CASH, SETTLEMENT, FEE_REVENUE, FEE_EXPENSE, TREASURY.

Crea segmentos y portafolios

Los segmentos separan dominios de negocio (CUSTOMER_FUNDS). Los portafolios administran la propiedad y la agrupación (customer_12345_wallet).

Crea las cuentas

Para cada saldo lógico, crea una cuenta de ledger (cuenta BRL del cliente, cuenta de tesorería, cuenta de gasto de comisión del proveedor, cuenta de liquidación del comercio).

3. Configurar los Tipos de cuenta

Los Tipos de cuenta clasifican las cuentas por naturaleza y propósito. Con validateAccountType habilitado, el type de una nueva cuenta no externa debe coincidir con un keyValue registrado. Una Ruta de operación puede usar por separado ruleType: account_type para validar una cuenta durante el procesamiento de la ruta. Los Tipos de cuenta en sí no definen las operaciones permitidas, el estado interno o externo, ni las reglas de conciliación. Una configuración típica para un producto de pagos:

CASH → fondos líquidos del cliente
SETTLEMENT → fondos a la espera de compensación
FEE_REVENUE → comisiones cobradas
FEE_EXPENSE → comisiones de proveedor
TREASURY → operaciones internas

Para habilitar la validación de Tipo de cuenta, entender el campo type y administrar los Tipos de cuenta mediante la API, consulta Tipos de cuenta.

Entender las categorías de saldo

Antes de configurar flujos de dos fases, entiende que cada saldo rastrea los fondos en campos distintos:

available: los fondos que puedes gastar o enviar de inmediato. Los débitos y créditos a un saldo mueven este número.
onHold: los fondos que una retención (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.
overdraftUsed: el sobregiro consumido por el saldo, cuando el sobregiro está habilitado.

Los tres campos llevan cadenas decimales con precisión exacta (por ejemplo, "12.50"). No existe un campo scale independiente que interpretar. Consulta Monto de la transacción para conocer el modelo de valor decimal. Las acciones de dos fases mueven valor entre available y onHold en el saldo de origen:

Acción	`available`	`onHold`
Directa	Debitado (origen) / acreditado (destino)	sin cambios
Retención	↓ disminuye en el origen	↑ aumenta en el origen
Confirmación	acreditado en el destino	↓ liberado del origen
Cancelación	↑ devuelto al origen	↓ liberado de vuelta a `available`
Reversión	restaurado en ambos lados mediante una contratransacción	sin cambios

Para el modelo de saldo completo (varios saldos por cuenta, indicadores de permiso, sobregiro e historial), consulta Saldos.

4. Definir los Asientos contables (Rubricas)

Los Asientos contables (Rubricas) mapean una acción de transacción y una dirección de ruta a un code y una description contables. Registras las rúbricas una vez, en lugar de calcular las clasificaciones contables a mano para cada movimiento. Cuando accounting.validateRoutes está habilitado en el ledger y hay una rúbrica coincidente configurada, Midaz anota cada operación con el routeCode y el routeDescription resultantes. Las reglas de la Ruta de operación y los tramos de la transacción determinan las cuentas participantes. Configuras las rúbricas por acción en cada Ruta de operación, dentro del bloque accountingEntries. Para las acciones direct y commit, las rutas de origen requieren la rúbrica de débito y las rutas de destino requieren la rúbrica de crédito. Las rúbricas dedicadas block y unblock son opcionales. Cuando no las configuras, Midaz resuelve la rúbrica direct para esas acciones. Las acciones hold y cancel del lado del origen requieren ambas rúbricas, overdraft requiere ambas en cada tipo de ruta admitido, y las rutas bidireccionales siempre requieren ambas.

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

Acción	Código	Qué hace
Directa	`direct`	Apunte inmediato de un solo paso con un débito y uno o más créditos, o un crédito y uno o más débitos; sin etapas intermedias (por ejemplo, una comisión o un ajuste).
Retención	`hold`	Reserva fondos al crear un movimiento pendiente (`available` → `onHold` en el origen).
Confirmación	`commit`	Confirma un monto retenido antes, y libera `onHold` hacia el destino.
Cancelación	`cancel`	Cancela una retención, y devuelve el valor `onHold` a `available` en el origen.
Reversión	`revert`	Revierte una transacción `APPROVED` mediante una contratransacción cuando sus Rutas de operación son bidireccionales.

Cada acción puede apuntar a distintas clasificaciones contables de débito y crédito dentro de la misma rúbrica. Así, cada etapa de una operación recibe la anotación contable correcta. Registras estos mapeos mediante 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" }
    }
  }
}

Para el modelo completo, consulta Asientos contables (Rubricas).

5. Enrutamiento de transacciones

El enrutamiento es un sistema de dos capas que se resuelve en tiempo de ejecución:

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 (rubricas) descritos antes.
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 verificaciones. Confirma que los saldos existan, que los débitos no superen el saldo disponible, que los activos coincidan y que el ledger se mantenga balanceado. Para la estructura de rutas, los campos, la matriz de validación por tipo de operación y el comportamiento de la API, consulta Enrutamiento de transacciones.

6. Ejemplo de principio a fin: un pago Pix

Vamos a unir todo con un cash-out Pix simple: un cliente envía BRL desde su billetera hacia una cuenta externa.

Configuración de cuentas

Crea la cuenta del cliente en tu ledger. Midaz crea @external/BRL automáticamente junto con el Activo BRL. No la crees tú mismo.

customer_12345_brl: Tipo de cuenta CASH, activo BRL
@external/BRL: la cuenta de liquidación externa creada automáticamente para los fondos que salen del ledger

Habilita la validación de rutas y registra las rúbricas

Habilita accounting.validateRoutes en el ledger. Luego, 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" }
    }
  }
}

Este bloque es una ilustración combinada de ambas rúbricas. Registra solo el campo debit en la ruta de origen y solo el campo credit en la ruta de destino.

Transacción

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

Operaciones resultantes

Midaz registra dos operaciones balanceadas:

Débito customer_12345_brl 100.00 BRL, routeCode: 1.1.1.001
Crédito @external/BRL 100.00 BRL, routeCode: 2.1.1.001

Ambas comparten el mismo transactionId, lo que te da un registro completo desde la transacción hasta la operación y la rúbrica.

Para un flujo de dos fases (retención → confirmación/cancelación), 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 de cada ledger. El valor predeterminado es false. En este modo tolerante, Midaz omite la validación de rutas. Deja los campos routeCode y routeDescription vacíos en cada operación y no genera ningún error. El modo tolerante es cómodo mientras incorporas rutas. En producción, define accounting.validateRoutes en true en la configuración del Ledger. El modo estricto valida entonces las rutas en cada transacción:

{
  "accounting": {
    "validateRoutes": true
  }
}

En modo estricto, una acción solicitada sin rutas en la caché de rutas de transacción devuelve 0157 ErrNoRoutesForAction. 0117 ErrAccountingRouteNotFound aplica cuando un ID de ruta de operación está ausente de esa caché. Cuando una ruta se resuelve, Midaz estampa routeCode y routeDescription a partir de su rúbrica.

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 incorporas rutas.

Próximos pasos

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

Midaz Core

CRM

Fees

Recorrido de contabilidad

1. Fundamentos de la contabilidad de doble entrada

2. Plan de cuentas en Midaz

Un proceso recomendado

3. Configurar los Tipos de cuenta

Entender las categorías de saldo

4. Definir los Asientos contables (Rubricas)

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

5. Enrutamiento de transacciones

6. Ejemplo de principio a fin: un pago Pix

7. Modos de validación

Próximos pasos

​1. Fundamentos de la contabilidad de doble entrada

​2. Plan de cuentas en Midaz

​Un proceso recomendado

​3. Configurar los Tipos de cuenta

​Entender las categorías de saldo

​4. Definir los Asientos contables (Rubricas)

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

​5. Enrutamiento de transacciones

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

​7. Modos de validación

​Próximos pasos

1. Fundamentos de la contabilidad de doble entrada

2. Plan de cuentas en Midaz

Un proceso recomendado

3. Configurar los Tipos de cuenta

Entender las categorías de saldo

4. Definir los Asientos contables (Rubricas)

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

5. Enrutamiento de transacciones

6. Ejemplo de principio a fin: un pago Pix

7. Modos de validación

Próximos pasos