> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Recorrido de contabilidad > Una guía práctica y de principio a fin para diseñar e implementar la contabilidad en Midaz, desde el plan de cuentas hasta un ejemplo funcional de pago Pix. 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](/es/products/midaz/accounting-in-midaz)**. ## 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 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. Crea un Tipo de cuenta por cada categoría conceptual, por ejemplo `CASH`, `SETTLEMENT`, `FEE_REVENUE`, `FEE_EXPENSE`, `TREASURY`. Los segmentos separan dominios de negocio (`CUSTOMER_FUNDS`). Los portafolios administran la propiedad y la agrupación (`customer_12345_wallet`). 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](/es/products/midaz/account-types)**. ### 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](/es/products/midaz/amount) 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](/es/products/midaz/balances)**. ## 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](/es/reference/products/midaz/v2/create-operation-route). ```json theme={null} { "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)](/es/products/midaz/accounting-entries)**. ## 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](/es/products/midaz/transaction-routing-entities)**. ## 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. 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 `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`: ```json theme={null} { "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. 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`. 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](/es/products/midaz/ledgers#ledger-settings). El modo estricto valida entonces las rutas en cada transacción: ```json theme={null} { "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](/es/products/midaz/accounting-in-midaz)** 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](/es/products/reporter/what-is-reporter)** para transformar los eventos del ledger en archivos de conciliación, estados financieros y salidas regulatorias alineadas con COSIF.