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.

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):

{
  "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):

{
  "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:

{
  "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.

{
  "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:

{
  "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:

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:

Operation.route (UUID) → OperationRoute.id → OperationRoute.code (COSIF)

APIs de Midaz disponibles:

GET /v1/organizations/{org_id}/ledgers/{ledger_id}/accounts/{account_id}/operations

Los parámetros de consulta para filtrado incluyen cursor, limit y type. 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:

Seleccionar o crear una plantilla — las plantillas usan sintaxis Pongo2 (similar a Django) con tags de agregación personalizados
Configurar fuentes de datos — Reporter consulta las tablas de la base de datos de Midaz directamente
Aplicar filtros — especificar rangos de fechas, tipos de cuenta u otros criterios
Generar el informe — Reporter agrega los datos y renderiza la plantilla
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 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:

Organization

{
  "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"
  }
}

Assets

[
  {
    "name": "Brazilian Real",
    "type": "currency",
    "code": "BRL",
    "status": { "code": "ACTIVE" },
    "metadata": {
      "symbol": "R$",
      "centralBank": "BACEN"
    }
  }
]

Account Types

[
  {
    "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.

OperationRoutes con códigos COSIF

[
  {
    "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"]
    }
  }
]

TransactionRoute para PIX

{
  "title": "PIX Transfer PF to PJ",
  "description": "PIX transfer from personal to business account",
  "operationRoutes": [
    "uuid-pf-checking-debit",
    "uuid-pj-checking-credit"
  ]
}

Transacción de ejemplo

{
  "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:

Crear OperationRoutes con códigos COSIF en el campo code
Agrupar en TransactionRoutes para validación de transacciones
Procesar transacciones referenciando las rutas apropiadas
Unir operaciones con OperationRoutes usando el campo route (UUID) para acceder a los códigos COSIF
Agregar por OperationRoute.code para calcular saldos por cuenta COSIF
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

Introducción

Ejemplos de plantillas

Plantillas de BACEN

Usando Reporter con Midaz Console

Creación de un informe de balance de comprobación con Midaz y Reporter

Conceptos clave

OperationRoute y el campo code

TransactionRoute

Proceso paso a paso

1. Prepara tu plan de cuentas en Midaz

2. Crea OperationRoutes con códigos COSIF

3. Crea TransactionRoutes

4. Procesa transacciones con rutas

5. Entendiendo el flujo de datos

6. Genera tu informe con Reporter

7. Exportar e integrar

Ejemplo práctico — Configuración completa de Midaz

Ejemplo de salida del balance de comprobación

Resumen

Documentación relacionada

Introducción

Ejemplos de plantillas

Plantillas de BACEN

Usando Reporter con Midaz Console

​Conceptos clave

​OperationRoute y el campo code

​TransactionRoute

​Proceso paso a paso

​1. Prepara tu plan de cuentas en Midaz

​2. Crea OperationRoutes con códigos COSIF

​3. Crea TransactionRoutes

​4. Procesa transacciones con rutas

​5. Entendiendo el flujo de datos

​6. Genera tu informe con Reporter

​7. Exportar e integrar

​Ejemplo práctico — Configuración completa de Midaz

​Ejemplo de salida del balance de comprobación

​Resumen

​Documentación relacionada

Conceptos clave

OperationRoute y el campo code

TransactionRoute

Proceso paso a paso

1. Prepara tu plan de cuentas en Midaz

2. Crea OperationRoutes con códigos COSIF

3. Crea TransactionRoutes

4. Procesa transacciones con rutas

5. Entendiendo el flujo de datos

6. Genera tu informe con Reporter

7. Exportar e integrar

Ejemplo práctico — Configuración completa de Midaz

Ejemplo de salida del balance de comprobación

Resumen

Documentación relacionada