Pular para o conteúdo principal
Segurança, conformidade e clareza nos relatórios financeiros começam com o seu livro-razão. O Midaz é essencialmente um livro-razão financeiro — o que significa que ele já armazena todos os dados necessários para produzir um balancete de verificação, desde estruturas de contas até históricos de transações. Enquanto o Midaz fornece os dados brutos, o produto Reporter transforma esses dados em saídas prontas para compartilhamento. Com o Reporter, você pode gerar balancetes de verificação e exportá-los diretamente em formatos como XML, TXT, HTML e PDF — sem precisar de ferramentas adicionais de conversão.

​
Conceitos-chave

Antes de mergulhar no processo passo a passo, é importante entender como o Midaz estrutura os dados para relatórios regulatórios:

​
OperationRoute e o campo code

A entidade OperationRoute é central para o mapeamento COSIF. Cada OperationRoute possui um campo code (máximo de 100 caracteres) projetado especificamente para armazenar códigos de referência externos, como códigos de contas COSIF. Quando as transações são processadas, cada operação é associada a uma OperationRoute. Ao agregar operações agrupadas por OperationRoute.code, você pode calcular saldos por conta COSIF — que é exatamente o que um balancete de verificação requer. 
OperationRoute
├── code: "1.1.1.10-8"        ← Código COSIF para agregação
├── title: "Débito em Conta Corrente"
├── operationType: "source" | "destination"
└── account: AccountRule      ← Regras de validação

​
TransactionRoute

Uma TransactionRoute agrupa múltiplas OperationRoutes (origens e destinos) em um template reutilizável. Ao criar transações, você referencia uma TransactionRoute, e o Midaz valida que as operações seguem as regras definidas.

​
Processo passo a passo

​
1. Prepare seu Plano de Contas no Midaz

Configure suas Organizations, Ledgers, Assets, Account Types e Accounts de acordo com as necessidades do seu negócio. As entidades-chave para a geração do balancete de verificação são:
  • Account Types — definem a natureza de cada conta (ativo, passivo, patrimônio líquido, receita, despesa) usando o campo keyValue.
  • OperationRoutes — mapeiam cada tipo de operação para um código COSIF através do campo code.
  • TransactionRoutes — agrupam OperationRoutes em templates de transação com regras de validação.

​
2. Crie OperationRoutes com códigos COSIF

Para cada conta COSIF no seu plano de contas, crie as OperationRoutes correspondentes com o código COSIF no campo code. Exemplos de OperationRoutes para uma instituição financeira brasileira: OperationRoute para débitos em conta corrente (origem): 
{
  "title": "Saque em Conta Corrente",
  "description": "Operações de débito de contas correntes pessoais",
  "code": "1.1.1.10-8",
  "operationType": "source",
  "account": {
    "ruleType": "account_type",
    "validIf": ["checking_account_pf", "checking_account_pj"]
  }
}
OperationRoute para créditos em conta corrente (destino): 
{
  "title": "Depósito em Conta Corrente",
  "description": "Operações de crédito para contas correntes pessoais",
  "code": "1.1.1.10-8",
  "operationType": "destination",
  "account": {
    "ruleType": "account_type",
    "validIf": ["checking_account_pf", "checking_account_pj"]
  }
}
OperationRoute para conta de investimento: 
{
  "title": "Movimentação de Conta de Investimento",
  "description": "Operações envolvendo contas de investimento",
  "code": "1.2.3.00-0",
  "operationType": "source",
  "account": {
    "ruleType": "account_type",
    "validIf": ["investment_account"]
  }
}
Mapeamentos COSIF comuns:
Código COSIFDescriçãoTipos de Conta
1.1.1.10-8Contas Correntes - Pessoas Físicaschecking_account_pf
1.1.1.20-5Contas Correntes - Pessoas Jurídicaschecking_account_pj
1.2.3.00-0Contas de Investimentoinvestment_account
7.1.1.00-0Receita de Serviçosrevenue_services
8.1.1.00-0Despesas Administrativasexpense_admin

​
3. Crie TransactionRoutes

Agrupe suas OperationRoutes em TransactionRoutes que representem padrões comuns de transação.
Ao criar uma TransactionRoute, você passa um array de UUIDs de OperationRoute. Ao consultar uma TransactionRoute via API, ela retorna os objetos completos de OperationRoute com todos os seus detalhes.
{
  "title": "Transferência PIX Entre Contas",
  "description": "Transferência PIX interna de uma conta corrente para outra",
  "operationRoutes": [
    "uuid-of-checking-account-source-route",
    "uuid-of-checking-account-destination-route"
  ]
}

​
4. Processe transações com rotas

Ao criar transações, referencie a TransactionRoute. Cada operação será associada à sua OperationRoute correspondente e ao código COSIF: 
{
  "code": "PIX_TRANSFER_001",
  "description": "Pagamento de almoço via PIX",
  "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": "Almoço"
  }
}
O asset e o value são definidos no nível do send. Operações individuais em from e to usam accountAlias (não account). O valor é expresso na menor unidade do ativo (por exemplo, centavos para BRL, então 4550 = R$ 45,50).
O mapeamento COSIF acontece automaticamente através da rota: 
Transação usa rota → TransactionRoute
                              ↓
                       OperationRoutes[]
                              ↓
            origem: code = "1.1.1.10-8" (COSIF)
            destino: code = "1.1.1.20-5" (COSIF)

​
5. Entendendo o fluxo de dados

O Midaz armazena todos os dados financeiros necessários para a geração do balancete de verificação:
  • Operations — cada operação inclui um campo route contendo o UUID da OperationRoute
  • OperationRoutes — contêm o campo code com códigos COSIF para agregação
  • Account Balances — posições atuais por conta
Como a agregação funciona: Cada Operation armazena um campo route que referencia o UUID da OperationRoute (não o código COSIF diretamente). Para agregar por código COSIF, o Reporter faz a junção das operações com suas OperationRoutes correspondentes para acessar o campo code: 
Operation.route (UUID) → OperationRoute.id → OperationRoute.code (COSIF)
APIs disponíveis do Midaz: 
GET /v1/organizations/{org_id}/ledgers/{ledger_id}/accounts/{account_id}/operations
Os parâmetros de consulta para filtragem incluem cursor, limit e type. As operações são recuperadas por conta.
O Reporter se conecta diretamente ao banco de dados do Midaz para geração de relatórios, permitindo consultas em lote e agregações eficientes. As APIs acima estão disponíveis para integrações personalizadas e consultas ad-hoc.

​
6. Gere seu relatório com o Reporter

O Reporter utiliza uma arquitetura orientada a templates para gerar relatórios. O processo envolve:
  1. Selecione ou crie um template — os templates usam sintaxe Pongo2 (similar ao Django) com tags de agregação personalizadas
  2. Configure as fontes de dados — o Reporter consulta as tabelas do banco de dados do Midaz diretamente
  3. Aplique filtros — especifique intervalos de datas, tipos de conta ou outros critérios
  4. Gere o relatório — o Reporter agrega os dados e renderiza o template
  5. Exporte no formato desejado (XML, TXT, HTML, PDF, CSV, JSON)
Como o Reporter agrega dados: Os templates do Reporter suportam tags de agregação integradas para calcular saldos:
  • {% sum_by collection by "field" %} — soma valores por campo
  • {% count_by collection if condition %} — conta registros que correspondem à condição
  • {% calc expression %} — cálculos aritméticos
Exemplo de trecho de template para agregação 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 %}
O Reporter inclui templates prontos para uso para diferentes necessidades de relatórios. Use o template CADOC 4010 ao gerar relatórios para envio regulatório ao BACEN, pois ele segue a estrutura oficial exigida.

​
7. Exporte e integre

Você pode:
  • Exportar um PDF pronto para compartilhamento para auditores e reguladores
  • Gerar arquivos XML formatados para envio ao BACEN
  • Integrar com seus fluxos de trabalho de relatórios ou sistemas contábeis existentes

​
Exemplo prático — Configuração completa do Midaz

Abaixo está uma instituição fictícia, DigitalBank, mostrando como as entidades do Midaz se conectam para suportar um balancete de verificação: 
{
  "legalName": "DigitalBank S.A.",
  "legalDocument": "12.345.678/0001-90",
  "address": {
    "line1": "Av. Faria Lima, 3064",
    "line2": "12º andar",
    "zipCode": "01451-000",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil"
  },
  "metadata": {
    "cnae": "6422-1",
    "licenseNumber": "BCB-2024-001",
    "foundedAt": "2024-01-15"
  }
}

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

[
  {
    "name": "Conta Corrente Pessoa Física",
    "keyValue": "checking_account_pf",
    "description": "Contas correntes para clientes pessoa física"
  },
  {
    "name": "Conta Corrente Pessoa Jurídica",
    "keyValue": "checking_account_pj",
    "description": "Contas correntes para clientes pessoa jurídica"
  },
  {
    "name": "Conta de Investimento",
    "keyValue": "investment_account",
    "description": "Contas de investimento e poupança"
  }
]
Os códigos COSIF são definidos nas OperationRoutes através do campo code, não nos Account Types. Os Account Types definem a natureza das contas e são usados pelas OperationRoutes para regras de validação.
[
  {
    "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"]
    }
  }
]

{
  "title": "Transferência PIX PF para PJ",
  "description": "Transferência PIX de conta pessoal para conta empresarial",
  "operationRoutes": [
    "uuid-pf-checking-debit",
    "uuid-pj-checking-credit"
  ]
}

{
  "code": "PIX_TRANSFER_001",
  "description": "Pagamento de almoço via PIX",
  "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": "Pagamento de almoço"
  }
}

​
Exemplo de saída do balancete de verificação

Após fazer a junção das operações com suas OperationRoutes e agregar pelo campo code, seu balancete de verificação ficaria assim:
Código COSIFDescriçãoDébitos (R$)Créditos (R$)Saldo (R$)
1.1.1.10-8Conta Corrente - PF150.000,00145.000,005.000,00
1.1.1.20-5Conta Corrente - PJ89.000,0092.500,00-3.500,00
1.2.3.00-0Investimentos50.000,0048.000,002.000,00
Total289.000,00285.500,003.500,00
Usando o Reporter, esses dados podem ser formatados em:
  • XML — estruturado para envio regulatório ao BACEN
  • PDF — relatório profissional para auditores e stakeholders
  • TXT — arquivo plano para integração com sistemas legados
O relatório consolida os dados do livro-razão por código COSIF, apresentando saldos agrupados por seções contábeis (Ativo, Passivo, Patrimônio Líquido, Receitas e Despesas), junto com subtotais e um total geral. Esta saída reflete o resultado da agregação e validação automatizadas realizadas sobre os dados do Midaz, pronta para auditoria, conformidade e uso regulatório.

​
Resumo

A chave para gerar balancetes de verificação precisos com o Midaz é o uso adequado do campo code nas OperationRoutes:
  1. Crie OperationRoutes com códigos COSIF no campo code
  2. Agrupe em TransactionRoutes para validação de transações
  3. Processe transações referenciando as rotas apropriadas
  4. Faça a junção de operações com OperationRoutes usando o campo route (UUID) para acessar os códigos COSIF
  5. Agregue por OperationRoute.code para calcular saldos por conta COSIF
  6. Gere relatórios com o Reporter usando templates que realizam a agregação automaticamente
Essa abordagem garante:
  • Conformidade regulatória com os padrões COSIF
  • Agregação automática de saldos por código de conta
  • Validação das operações de transação
  • Relatórios flexíveis em múltiplos formatos

​
Documentação relacionada