> ## 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.
# Balancete de verificação com Midaz e Reporter
> Gere um balancete a partir do seu Ledger do Midaz com o Reporter e exporte em XML, TXT, HTML ou PDF — sem ferramentas adicionais.
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.
```text theme={null}
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):
```json theme={null}
{
"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):
```json theme={null}
{
"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:
```json theme={null}
{
"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 COSIF | Descrição | Tipos de Conta |
| ------------ | ------------------------------------ | --------------------- |
| 1.1.1.10-8 | Contas Correntes - Pessoas Físicas | `checking_account_pf` |
| 1.1.1.20-5 | Contas Correntes - Pessoas Jurídicas | `checking_account_pj` |
| 1.2.3.00-0 | Contas de Investimento | `investment_account` |
| 7.1.1.00-0 | Receita de Serviços | `revenue_services` |
| 8.1.1.00-0 | Despesas Administrativas | `expense_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.
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```text theme={null}
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`:
```text theme={null}
Operation.route (UUID) → OperationRoute.id → OperationRoute.code (COSIF)
```
**APIs disponíveis do Midaz:**
```text theme={null}
GET /v1/organizations/{org_id}/ledgers/{ledger_id}/accounts/{account_id}/operations
```
Os parâmetros de consulta para filtragem incluem `cursor`, `limit`, `type` e `direction`. Para restringir os resultados a uma OperationRoute específica, use `route_id` (UUID) ou `route_code` (como o código COSIF). 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**](/pt/reporter/cadoc-4010-and-4016) 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:
```json theme={null}
{
"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"
}
}
```
```json theme={null}
[
{
"name": "Real Brasileiro",
"type": "currency",
"code": "BRL",
"status": { "code": "ACTIVE" },
"metadata": {
"symbol": "R$",
"centralBank": "BACEN"
}
}
]
```
```json theme={null}
[
{
"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.
```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": "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"
]
}
```
```json theme={null}
{
"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 COSIF | Descrição | Débitos (R\$) | Créditos (R\$) | Saldo (R\$) |
| ------------ | ------------------- | -------------- | -------------- | ------------ |
| 1.1.1.10-8 | Conta Corrente - PF | 150.000,00 | 145.000,00 | 5.000,00 |
| 1.1.1.20-5 | Conta Corrente - PJ | 89.000,00 | 92.500,00 | -3.500,00 |
| 1.2.3.00-0 | Investimentos | 50.000,00 | 48.000,00 | 2.000,00 |
| **Total** | | **289.000,00** | **285.500,00** | **3.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
***
* [Referência da API de OperationRoutes](/pt/reference/midaz/create-an-operation-route)
* [Referência da API de TransactionRoutes](/pt/reference/midaz/create-transaction-route)
* [Referência da API de Account Types](/pt/reference/midaz/create-an-account-type)
* [Referência da API de Operations](/pt/reference/midaz/list-operations-by-account)
* [Visão geral do Reporter](/pt/reporter/what-is-reporter)
* [CADOC 4010 e 4016](/pt/reporter/cadoc-4010-and-4016)