> ## 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. # Guía de contabilidad > Una guía práctica 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. 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](/es/midaz/accounting-in-midaz)**. ## 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 tiene un código de asset y un tipo de cuenta; también puede pertenecer a un portfolio y un segment. 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 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. Crea un Tipo de Cuenta por categoría conceptual — ej. `CASH`, `SETTLEMENT`, `FEE_REVENUE`, `FEE_EXPENSE`, `TREASURY`. Los segments separan dominios de negocio (`CUSTOMER_FUNDS`). Los portfolios gestionan la propiedad y la agrupación (`customer_12345_wallet`). 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 clasifican las cuentas por naturaleza y propósito. Con `validateAccountType` activado, el `type` de una Cuenta nueva 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 no definen por sí mismos 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 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](/es/midaz/account-types)**. ### Entender los compartimentos de saldo Antes de configurar flujos en dos fases, entiende que cada saldo rastrea los fondos en campos distintos: * **`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. * **`overdraftUsed`** — sobregiro consumido por el saldo, cuando el sobregiro está habilitado. Los tres 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](/es/midaz/amount) para conocer el modelo de valores decimales. Las acciones de dos fases mueven valor entre `available` y `onHold` en el saldo de origen: | Acción | `available` | `onHold` | | ---------- | ---------------------------------------------------- | ---------------------------------- | | **Direct** | Debitado (origen) / acreditado (destino) | sin cambios | | **Hold** | ↓ disminuye en el origen | ↑ aumenta en el origen | | **Commit** | acreditado en el destino | ↓ liberado del origen | | **Cancel** | ↑ devuelto al origen | ↓ liberado de vuelta a `available` | | **Revert** | restaurado en ambos lados vía una contra-transacción | sin cambios | Para el modelo completo de saldos — múltiples saldos por cuenta, banderas de permisos, sobregiro e historial — consulta **[Saldos](/es/midaz/balances)**. ## 4. Definir Asientos Contables (Rúbricas) *** Los **Asientos Contables** (Rúbricas) mapean una acción de transacción y la dirección de una 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 existe una rúbrica coincidente, 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 source requieren la rúbrica de **débito** y las rutas destination requieren la rúbrica de **crédito**. Las rúbricas dedicadas de `block` y `unblock` son opcionales; cuando no existen, Midaz resuelve la rúbrica `direct` para esas acciones. Las acciones `hold` y `cancel` en rutas source requieren **ambas** rúbricas, `overdraft` requiere **ambas** en cada tipo de ruta compatible, y las rutas bidirectional siempre requieren **ambas**. ### Las cinco acciones del ciclo de vida de la transacción | Acción | Código | Qué hace | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Direct** | `direct` | Registro inmediato de un solo paso con un débito y uno o más créditos, o con un crédito y uno o más débitos; sin etapas intermedias (ej. una comisión o un ajuste). | | **Hold** | `hold` | Reserva fondos creando un movimiento pendiente (`available` → `onHold` en el origen). | | **Commit** | `commit` | Confirma un monto previamente retenido, liberando `onHold` al destino. | | **Cancel** | `cancel` | Cancela una retención, devolviendo el valor `onHold` a `available` en el origen. | | **Revert** | `revert` | Revierte una transacción `APPROVED` mediante una contra-transacción cuando sus Rutas de Operación son bidireccionales. | Cada acción puede apuntar a diferentes clasificaciones contables de débito/crédito dentro de la misma rúbrica. Así, cada etapa de una operación recibe la anotación contable correcta. Registras estos mapeos a través de los endpoints de Ruta de Operación — consulta [Crear una Ruta de Operación](/es/reference/midaz/create-an-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 (Rúbricas)](/es/midaz/accounting-entries)**. ## 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](/es/midaz/transaction-routing-entities)**. ## 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. Crea la cuenta del cliente en tu ledger. Midaz crea `@external/BRL` automáticamente junto con el asset `BRL`; no la crees tú. * `customer_12345_brl` — Tipo de Cuenta `CASH`, asset `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 Source y solo el campo `credit` en la ruta Destination. 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`. 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](/es/midaz/ledgers#ledger-settings). El modo estricto valida entonces las rutas en cada transacción: ```json theme={null} { "accounting": { "validateRoutes": true } } ``` En el modo estricto, una acción solicitada sin rutas en la caché de rutas de transacción devuelve `0157 ErrNoRoutesForAction`. `0117 ErrAccountingRouteNotFound` se aplica cuando falta un ID de Ruta de Operación en esa caché. Cuando una ruta se resuelve, Midaz registra el `routeCode` y el `routeDescription` desde 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 configuras las rutas. ## Próximos pasos *** * Revisa la visión general de **[Contabilidad](/es/midaz/accounting-in-midaz)** 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](/es/reporter/what-is-reporter)** para transformar los eventos del ledger en archivos de conciliación, estados financieros y salidas regulatorias alineadas con COSIF.