> ## 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.
# Informe de balance de comprobación con Midaz y Reporter
> Genera un balance de comprobación desde tu Ledger de Midaz con Reporter y exporta en XML, TXT, HTML o PDF — sin herramientas adicionales.
La seguridad, el cumplimiento y la claridad en los informes financieros comienzan con tu libro mayor. **Midaz** es, en esencia, un libro mayor financiero, lo que significa que ya almacena todos los datos necesarios para producir un balance de comprobación, desde estructuras de cuentas hasta historiales de transacciones.
Mientras Midaz proporciona los datos sin procesar, el producto **Reporter** transforma estos datos en salidas listas para compartir. Con Reporter, puedes generar balances de comprobación y exportarlos directamente en formatos como **XML, TXT, HTML y PDF**, sin necesidad de herramientas de conversión adicionales.
# Conceptos clave
***
Antes de profundizar en el proceso paso a paso, es importante entender cómo Midaz estructura los datos para informes regulatorios:
## OperationRoute y el campo code
***
La entidad **OperationRoute** es central para el mapeo COSIF. Cada OperationRoute tiene un campo code (máximo 100 caracteres) diseñado específicamente para almacenar códigos de referencia externos como códigos de cuentas COSIF.
Cuando se procesan las transacciones, cada operación se asocia con un OperationRoute. Al agregar operaciones agrupadas por OperationRoute.code, puedes calcular saldos por cuenta COSIF, que es exactamente lo que requiere un balance de comprobación.
```text theme={null}
OperationRoute
├── code: "1.1.1.10-8" ← Código COSIF para agregación
├── title: "Checking Account Debit"
├── operationType: "source" | "destination"
└── account: AccountRule ← Reglas de validación
```
## TransactionRoute
***
Un **TransactionRoute** agrupa múltiples OperationRoutes (orígenes y destinos) en una plantilla reutilizable. Al crear transacciones, haces referencia a un TransactionRoute, y Midaz valida que las operaciones sigan las reglas definidas.
# Proceso paso a paso
***
## 1. Prepara tu plan de cuentas en Midaz
***
Configura tus **Organizations, Ledgers, Assets, Account Types y Accounts** según las necesidades de tu negocio.
Las entidades clave para la generación del balance de comprobación son:
* **Account Types** — definen la naturaleza de cada cuenta (activo, pasivo, patrimonio, ingresos, gastos) usando el campo keyValue.
* **OperationRoutes** — mapean cada tipo de operación a un código COSIF a través del campo code.
* **TransactionRoutes** — agrupan OperationRoutes en plantillas de transacción con reglas de validación.
## 2. Crea OperationRoutes con códigos COSIF
***
Para cada cuenta COSIF en tu plan de cuentas, crea los OperationRoutes correspondientes con el código COSIF en el campo code.
Ejemplo de OperationRoutes para una institución financiera brasileña:
OperationRoute para débitos de cuenta corriente (origen):
```json theme={null}
{
"title": "Checking Account Withdrawal",
"description": "Debit operations from personal checking accounts",
"code": "1.1.1.10-8",
"operationType": "source",
"account": {
"ruleType": "account_type",
"validIf": ["checking_account_pf", "checking_account_pj"]
}
}
```
OperationRoute para créditos de cuenta corriente (destino):
```json theme={null}
{
"title": "Checking Account Deposit",
"description": "Credit operations to personal checking accounts",
"code": "1.1.1.10-8",
"operationType": "destination",
"account": {
"ruleType": "account_type",
"validIf": ["checking_account_pf", "checking_account_pj"]
}
}
```
OperationRoute para cuenta de inversiones:
```json theme={null}
{
"title": "Investment Account Movement",
"description": "Operations involving investment accounts",
"code": "1.2.3.00-0",
"operationType": "source",
"account": {
"ruleType": "account_type",
"validIf": ["investment_account"]
}
}
```
Mapeos COSIF comunes:
| Código COSIF | Descripción | Account Types |
| ------------ | ------------------------------------- | --------------------- |
| 1.1.1.10-8 | Cuentas Corrientes - Personas Físicas | checking\_account\_pf |
| 1.1.1.20-5 | Cuentas Corrientes - Empresas | checking\_account\_pj |
| 1.2.3.00-0 | Cuentas de Inversión | investment\_account |
| 7.1.1.00-0 | Ingresos por Servicios | revenue\_services |
| 8.1.1.00-0 | Gastos Administrativos | expense\_admin |
## 3. Crea TransactionRoutes
***
Agrupa tus OperationRoutes en TransactionRoutes que representen patrones de transacción comunes.
Al crear un TransactionRoute, pasas un array de UUIDs de OperationRoute. Al recuperar un TransactionRoute a través de la API, devuelve los objetos OperationRoute completos con todos sus detalles.
```json theme={null}
{
"title": "PIX Transfer Between Accounts",
"description": "Internal PIX transfer from one checking account to another",
"operationRoutes": [
"uuid-of-checking-account-source-route",
"uuid-of-checking-account-destination-route"
]
}
```
## 4. Procesa transacciones con rutas
***
Al crear transacciones, haz referencia al TransactionRoute. Cada operación se asociará con su OperationRoute y código COSIF correspondiente:
```json theme={null}
{
"code": "PIX_TRANSFER_001",
"description": "PIX lunch payment",
"route": "uuid-of-pix-transfer-route",
"send": {
"asset": "BRL",
"value": 4550,
"source": {
"from": [{
"accountAlias": "@joao_silva_cc"
}]
},
"distribute": {
"to": [{
"accountAlias": "@restaurante_abc"
}]
}
},
"metadata": {
"pixKey": "12345678901",
"description": "Lunch"
}
}
```
El `asset` y `value` se definen a nivel de `send`. Las operaciones individuales en `from` y `to` usan `accountAlias` (no `account`). El valor se expresa en la unidad más pequeña del activo (por ejemplo, centavos para BRL, entonces 4550 = R\$ 45.50).
El mapeo COSIF ocurre automáticamente a través de la ruta:
```text theme={null}
Transaction uses route → TransactionRoute
↓
OperationRoutes[]
↓
source: code = "1.1.1.10-8" (COSIF)
destination: code = "1.1.1.20-5" (COSIF)
```
## 5. Entendiendo el flujo de datos
***
Midaz almacena todos los datos financieros necesarios para la generación del balance de comprobación:
* **Operations** — cada operación incluye un campo `route` que contiene el UUID del OperationRoute
* **OperationRoutes** — contienen el campo `code` con códigos COSIF para agregación
* **Account Balances** — posiciones actuales por cuenta
**Cómo funciona la agregación:**
Cada Operation almacena un campo `route` que referencia el UUID del OperationRoute (no el código COSIF directamente). Para agregar por código COSIF, Reporter une las operaciones con sus OperationRoutes correspondientes para acceder al campo `code`:
```text theme={null}
Operation.route (UUID) → OperationRoute.id → OperationRoute.code (COSIF)
```
**APIs de Midaz disponibles:**
```text theme={null}
GET /v1/organizations/{org_id}/ledgers/{ledger_id}/accounts/{account_id}/operations
```
Los parámetros de consulta para filtrado incluyen `cursor`, `limit`, `type` y `direction`. Para restringir los resultados a una OperationRoute específica, utilice `route_id` (UUID) o `route_code` (como el código COSIF). Las operaciones se recuperan por cuenta.
Reporter se conecta directamente a la base de datos de Midaz para la generación de informes, permitiendo consultas y agregaciones por lotes eficientes. Las APIs anteriores están disponibles para integraciones personalizadas y consultas ad-hoc.
## 6. Genera tu informe con Reporter
***
Reporter utiliza una arquitectura basada en plantillas para generar informes. El proceso implica:
1. **Seleccionar o crear una plantilla** — las plantillas usan sintaxis Pongo2 (similar a Django) con tags de agregación personalizados
2. **Configurar fuentes de datos** — Reporter consulta las tablas de la base de datos de Midaz directamente
3. **Aplicar filtros** — especificar rangos de fechas, tipos de cuenta u otros criterios
4. **Generar el informe** — Reporter agrega los datos y renderiza la plantilla
5. **Exportar** en el formato elegido (XML, TXT, HTML, PDF, CSV, JSON)
**Cómo Reporter agrega datos:**
Las plantillas de Reporter soportan tags de agregación incorporados para calcular saldos:
* `{% sum_by collection by "field" %}` — suma valores por campo
* `{% count_by collection if condition %}` — cuenta registros que coinciden con la condición
* `{% calc expression %}` — cálculos aritméticos
**Ejemplo de fragmento de plantilla para agregación COSIF:**
```
{% for route in operation_routes %}
{{ route.code }} |
Débitos: {% sum_by operations by "amount" if operation.route == route.id and operation.type == "DEBIT" %} |
Créditos: {% sum_by operations by "amount" if operation.route == route.id and operation.type == "CREDIT" %}
{% endfor %}
```
Reporter incluye plantillas listas para usar para diferentes necesidades de informes. Usa la plantilla [**CADOC 4010**](/es/reporter/cadoc-4010-and-4016) al generar informes para **envío regulatorio a BACEN**, ya que sigue la estructura oficial requerida.
## 7. Exportar e integrar
***
Puedes:
* Exportar un **PDF listo para compartir** para auditores y reguladores
* Generar archivos **XML** formateados para envío a BACEN
* Integrar con tus flujos de trabajo de informes o sistemas contables existentes
# Ejemplo práctico — Configuración completa de Midaz
***
A continuación se muestra una institución ficticia, **DigitalBank**, mostrando cómo las entidades de Midaz se conectan para soportar un balance de comprobación:
```json theme={null}
{
"legalName": "DigitalBank S.A.",
"legalDocument": "12.345.678/0001-90",
"address": {
"line1": "Av. Faria Lima, 3064",
"line2": "12th floor",
"zipCode": "01451-000",
"city": "Sao Paulo",
"state": "SP",
"country": "Brazil"
},
"metadata": {
"cnae": "6422-1",
"licenseNumber": "BCB-2024-001",
"foundedAt": "2024-01-15"
}
}
```
```json theme={null}
[
{
"name": "Brazilian Real",
"type": "currency",
"code": "BRL",
"status": { "code": "ACTIVE" },
"metadata": {
"symbol": "R$",
"centralBank": "BACEN"
}
}
]
```
```json theme={null}
[
{
"name": "Personal Checking Account",
"keyValue": "checking_account_pf",
"description": "Checking accounts for individual customers"
},
{
"name": "Business Checking Account",
"keyValue": "checking_account_pj",
"description": "Checking accounts for business customers"
},
{
"name": "Investment Account",
"keyValue": "investment_account",
"description": "Investment and savings accounts"
}
]
```
Los códigos COSIF se definen en OperationRoutes a través del campo `code`, **no** en Account Types. Los Account Types definen la naturaleza de las cuentas y son usados por OperationRoutes para reglas de validación.
```json theme={null}
[
{
"title": "PF Checking - Debit",
"code": "1.1.1.10-8",
"operationType": "source",
"account": {
"ruleType": "account_type",
"validIf": ["checking_account_pf"]
}
},
{
"title": "PF Checking - Credit",
"code": "1.1.1.10-8",
"operationType": "destination",
"account": {
"ruleType": "account_type",
"validIf": ["checking_account_pf"]
}
},
{
"title": "PJ Checking - Debit",
"code": "1.1.1.20-5",
"operationType": "source",
"account": {
"ruleType": "account_type",
"validIf": ["checking_account_pj"]
}
},
{
"title": "PJ Checking - Credit",
"code": "1.1.1.20-5",
"operationType": "destination",
"account": {
"ruleType": "account_type",
"validIf": ["checking_account_pj"]
}
}
]
```
```json theme={null}
{
"title": "PIX Transfer PF to PJ",
"description": "PIX transfer from personal to business account",
"operationRoutes": [
"uuid-pf-checking-debit",
"uuid-pj-checking-credit"
]
}
```
```json theme={null}
{
"code": "PIX_TRANSFER_001",
"description": "PIX lunch payment",
"route": "uuid-pix-transfer-pf-to-pj",
"send": {
"asset": "BRL",
"value": 4550,
"source": {
"from": [{
"accountAlias": "@joao_silva_cc"
}]
},
"distribute": {
"to": [{
"accountAlias": "@restaurante_abc"
}]
}
},
"metadata": {
"pixKey": "12345678901",
"purpose": "Lunch payment"
}
}
```
# Ejemplo de salida del balance de comprobación
***
Después de unir las operaciones con sus OperationRoutes y agregar por el campo `code`, tu balance de comprobación se vería así:
| Código COSIF | Descripción | Débitos (R\$) | Créditos (R\$) | Saldo (R\$) |
| ------------ | --------------------- | -------------- | -------------- | ------------ |
| 1.1.1.10-8 | Cuenta Corriente - PF | 150,000.00 | 145,000.00 | 5,000.00 |
| 1.1.1.20-5 | Cuenta Corriente - PJ | 89,000.00 | 92,500.00 | -3,500.00 |
| 1.2.3.00-0 | Inversiones | 50,000.00 | 48,000.00 | 2,000.00 |
| **Total** | | **289,000.00** | **285,500.00** | **3,500.00** |
Usando Reporter, estos datos pueden formatearse en:
* **XML** — estructurado para envío regulatorio a BACEN
* **PDF** — informe profesional para auditores y partes interesadas
* **TXT** — archivo plano para integración con sistemas legacy
El informe consolida datos del libro mayor por código COSIF, presentando saldos agrupados por secciones contables (Activos, Pasivos, Patrimonio, Ingresos y Gastos), junto con subtotales y un total global. Esta salida refleja el resultado de la agregación y validación automatizada realizada sobre los datos de Midaz, lista para auditoría, cumplimiento y uso regulatorio.
# Resumen
***
La clave para generar balances de comprobación precisos con Midaz es el uso adecuado del campo `code` en OperationRoutes:
1. **Crear OperationRoutes** con códigos COSIF en el campo `code`
2. **Agrupar en TransactionRoutes** para validación de transacciones
3. **Procesar transacciones** referenciando las rutas apropiadas
4. **Unir operaciones con OperationRoutes** usando el campo `route` (UUID) para acceder a los códigos COSIF
5. **Agregar por OperationRoute.code** para calcular saldos por cuenta COSIF
6. **Generar informes** con Reporter usando plantillas que realizan la agregación automáticamente
Este enfoque asegura:
* Cumplimiento regulatorio con estándares COSIF
* Agregación automática de saldos por código de cuenta
* Validación de operaciones de transacción
* Informes flexibles en múltiples formatos
# Documentación relacionada
***
* [Referencia API de OperationRoutes](/es/reference/midaz/create-an-operation-route)
* [Referencia API de TransactionRoutes](/es/reference/midaz/create-transaction-route)
* [Referencia API de Account Types](/es/reference/midaz/create-an-account-type)
* [Referencia API de Operations](/es/reference/midaz/list-operations-by-account)
* [Visión general de Reporter](/es/reporter/what-is-reporter)
* [CADOC 4010 y 4016](/es/reporter/cadoc-4010-and-4016)