> ## 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 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
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 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](/es/midaz/account-types)**.
### 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](/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 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
| Acción | Código | Qué hace |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| **Direct** | `direct` | Débito/crédito inmediato, de un solo paso, entre dos cuentas, 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 `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. 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](/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" }
},
"hold": {
"debit": { "code": "1.1.2.001", "description": "Pending settlement — hold" }
}
}
}
```
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 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
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" }
}
}
}
```
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, 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](/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.