O Reporter permite gerar relatórios baseados em XML que seguem a estrutura oficial do CADOC, exatamente como exigido pelo Banco Central do Brasil (BACEN).
Este guia apresenta a estrutura e a lógica utilizadas para gerar os relatórios CADOC 4010 e CADOC 4016 em XML.
Estes relatórios seguem o padrão COSIF e devem corresponder à estrutura XML definida pelo BACEN. Você pode adaptar a lógica ao seu próprio modelo de dados, mas o formato XML deve ser respeitado.
O que são os CADOC 4010 e 4016?
O 4010 e o 4016 são relatórios de Balancete Analítico utilizados para enviar relatórios financeiros ao BACEN (Banco Central do Brasil).
O que o BACEN espera receber
- Saldos de fechamento por código COSIF
- Data-base do relatório (mês de referência)
- CNPJ da instituição (primeiros 8 dígitos)
- Tipo de remessa (
I = Inclusão, S = Substituição)
Diferença entre CADOC 4010 e 4016
| Documento | Periodicidade | Data-base | Contas esperadas |
|---|
| 4010 | Mensal | YYYY-MM | Todas as contas |
| 4016 | Semestral (Jun/Dez) | YYYY-MM | Sem os grupos 7 e 8 (Receitas/Despesas) |
Requisitos de envio
| Documento | Prazo | Código STA |
|---|
| 4010 | Dia 18 do mês seguinte (ou próximo dia útil) | ACOS010 |
| 4016 | Último dia útil do mês seguinte | ACOS016 |
O código STA identifica o tipo de documento no sistema de transmissão do BACEN. Use ACOS010 ao enviar o CADOC 4010 e ACOS016 ao enviar o CADOC 4016.
Entendendo a estrutura de dados
Rotas de operação
As rotas de operação funcionam como classificadores contábeis. Cada rota possui:
- Identificador único (
id): Usado internamente para relacionar operações
- Código COSIF (
code): O código contábil de 10 dígitos que será reportado ao BACEN
Pense nas rotas como “rótulos contábeis” vinculados a cada operação, indicando em qual item do plano de contas aquele movimento deve ser classificado.
Operações
As operações representam movimentações financeiras no ledger. Cada operação contém:
- Conta associada (
account_id): Qual conta foi movimentada
- Rota (
route): ID da rota/classificação contábil aplicada
- Saldo após a operação (
available_balance_after): O saldo da conta imediatamente após esta operação
- Data e hora (
created_at): Quando a operação ocorreu
Relacionamento entre entidades
A entidade balance representa o saldo atual da conta, não o histórico. Para relatórios regulatórios que precisam de saldos de um período específico, use a entidade operation com filtros de data.
Estrutura do CADOC
O relatório CADOC deve ser um arquivo XML e deve seguir a estrutura definida pelo BACEN:
<?xml version="1.0" encoding="UTF-8"?>
<documento codigoDocumento="4010" cnpj="99999999" dataBase="2025-11" tipoRemessa="I">
<contas>
<conta codigoConta="1000000009" saldo="99.99" />
<conta codigoConta="1100000002" saldo="99.99" />
</contas>
</documento>
Campos obrigatórios
<?xml version="1.0" encoding="UTF-8"?>
Sempre inicia o arquivo. Define a versão do XML e a codificação para que o sistema saiba como ler o conteúdo.
Tag <documento>
Envolve toda a estrutura do CADOC e inclui:
| Campo | Descrição | Formato |
|---|
codigoDocumento | Identificador fixo | "4010" ou "4016" |
cnpj | Primeiros 8 dígitos do CNPJ | Numérico, 8 posições |
dataBase | Mês de referência | YYYY-MM |
tipoRemessa | Tipo de remessa | "I" ou "S" |
Se o seu primeiro envio foi rejeitado por erros, você ainda precisa usar "I" na próxima tentativa. Use "S" apenas para substituir dados previamente aprovados.
<contas>
Agrupa todas as entradas de contas do período de reporte.
Tag <conta>
codigoConta: Código da conta, seguindo o formato COSIF (10 dígitos numéricos).saldo: Saldo da conta em formato decimal (duas casas decimais).
Lógica de construção do template
Estrutura geral
O template segue uma lógica de agregação em dois níveis:
- Primeiro nível: Iterar por todas as rotas de operação disponíveis
- Segundo nível: Para cada rota, agregar os saldos das operações vinculadas
Iterando sobre as rotas
O template deve iterar por todas as rotas de operação registradas. Para cada rota:
- Verificar se possui código COSIF: Apenas rotas com código preenchido geram linhas
- Filtrar operações: Selecionar as operações que pertencem àquela rota
- Calcular o saldo: Agregar os saldos das operações filtradas
Ao construir o template, evite usar o mesmo nome para a variável de iteração e o campo de filtro:
| Abordagem | Exemplo | Resultado |
|---|
| Incorreta | for route in ... if route == route.id | Conflito de nomes |
| Correta | for op_route in ... if route == op_route.id | Funciona corretamente |
Template do CADOC 4010
Aqui está o template completo para gerar o CADOC 4010 no Reporter:
<?xml version="1.0" encoding="UTF-8"?>
<documento codigoDocumento="4010" cnpj="{{ midaz_onboarding.organization.0.legal_document|slice:':8' }}" dataBase="{% date_time 'YYYY-MM' %}" tipoRemessa="I">
<contas>
{%- for op_route in midaz_transaction.operation_route %}
{%- if op_route.code %}
<conta codigoConta="{{ op_route.code }}" saldo="{% sum_by midaz_transaction.operation by "available_balance_after" if route == op_route.id %}" />
{%- endif %}
{%- endfor %}
</contas>
</documento>
Explicação linha a linha
Linha 1 - Declaração XML
Cabeçalho XML padrão com codificação UTF-8.
Linha 2 - Elemento raiz <documento>
codigoDocumento="4010": Identificador fixo do Balancete Analíticocnpj: Extrai os primeiros 8 dígitos do documento legal da organizaçãodataBase: Gera a data no formato YYYY-MM (mês de referência)tipoRemessa="I": Indica inclusão de dados
Linha 4 - Início do loop for
op_route: Variável que recebe cada rota durante a iteraçãomidaz_transaction.operation_route: Coleção de todas as rotas de operação
Linha 5 - Condição if
Verifica se a rota possui um código COSIF preenchido.
Linha 6 - Elemento <conta>
codigoConta: Exibe o código COSIF da rota atualsaldo: Usa a tag sum_by para agregar saldos, filtrando as operações cuja rota corresponde ao identificador da rota atual (op_route.id)
Linhas 7-8 - Fechamento dos blocos
Fecham a condição e o loop respectivamente.
| Elemento | Tipo | Função |
|---|
{{ variable }} | Expressão | Exibe o valor de uma variável |
{% tag %} | Tag | Executa lógica (loop, condição, agregação) |
|slice:':8' | Filtro | Extrai os primeiros 8 caracteres |
for ... in | Tag | Itera por uma coleção |
if | Tag | Condição de execução |
sum_by ... by ... if | Tag | Soma valores com filtro condicional |
date_time | Tag | Gera data formatada |
Template do CADOC 4016
O CADOC 4016 é o Balancete Analítico, similar ao 4010, mas com periodicidade semestral e uma restrição importante: não deve conter contas dos grupos 7 (Receitas) e 8 (Despesas).
Por que excluir os grupos 7 e 8?
O documento 4016 representa a posição contábil da entidade após o encerramento da demonstração de resultados. Nesse momento, as contas de Receita (grupo 7) e as contas de Despesa (grupo 8) já foram encerradas e seus saldos transferidos para o Patrimônio Líquido.
Exemplo de template
<?xml version="1.0" encoding="UTF-8"?>
<documento codigoDocumento="4016" cnpj="{{ midaz_onboarding.organization.0.legal_document|slice:':8' }}" dataBase="{% date_time 'YYYY-MM' %}" tipoRemessa="I">
<contas>
{%- for op_route in midaz_transaction.operation_route %}
{%- if op_route.code and op_route.code|slice:":1" != "7" and op_route.code|slice:":1" != "8" %}
<conta codigoConta="{{ op_route.code }}" saldo="{% sum_by midaz_transaction.operation by "available_balance_after" if route == op_route.id %}" />
{%- endif %}
{%- endfor %}
</contas>
</documento>
Diferença em relação ao 4010
A única diferença no template é a condição adicional no if:
| Template | Condição | | |
|---|
| 4010 | if op_route.code | | |
| 4016 | `if op_route.code and op_route.code | slice:“:1” != “7” and op_route.code | slice:“:1” != “8”` |
Como funciona a exclusão
O filtro slice:":1" extrai o primeiro caractere do código COSIF:
| Código COSIF | Primeiro dígito | Grupo | Incluído no 4016? |
|---|
| 1000000009 | 1 | Ativo | Sim |
| 2100000003 | 2 | Passivo | Sim |
| 7100000001 | 7 | Receitas | Não |
| 8200000005 | 8 | Despesas | Não |
Exemplo de requisição para o 4010
Para gerar o CADOC 4010 para um mês específico, envie uma requisição POST /v1/reports com o header X-Organization-Id e o seguinte corpo:
{
"templateId": "CADOC_4010_TEMPLATE_ID",
"filters": {
"midaz_transaction": {
"operation": {
"created_at": {
"between": ["2025-11-01T00:00:00Z", "2025-11-30T23:59:59Z"]
}
}
}
}
}
Explicação dos campos
| Campo | Descrição |
|---|
templateId | Identificador do template CADOC 4010 registrado no Reporter |
filters.midaz_transaction.operation | Indica que o filtro será aplicado à coleção de operações |
created_at.between | Filtra operações criadas dentro do intervalo especificado |
between[0] | Primeiro dia do mês às 00:00:00 UTC |
between[1] | Último dia do mês às 23:59:59 UTC |
Z).
Ajuste o último dia de acordo com o mês (28, 29, 30 ou 31 dias).
Exemplo de requisição para o 4016
Para gerar o CADOC 4016 para o primeiro semestre:
{
"templateId": "CADOC_4016_TEMPLATE_ID",
"filters": {
"midaz_transaction": {
"operation": {
"created_at": {
"between": ["2025-01-01T00:00:00Z", "2025-06-30T23:59:59Z"]
}
}
}
}
}
Estamos trabalhando na evolução do nosso template principal para suportar agregação de saldos em conformidade com o BACEN CADOC 4010/4016, que exige o saldo final do último dia útil do mês.
Enquanto essa funcionalidade está sendo desenvolvida, fornecemos uma versão alternativa para extrair esses saldos usando o template a seguir.
Este template auxiliar foi projetado para calcular saldos corretamente, garantindo a conformidade dos seus relatórios por meio dos seguintes passos:
- Agrupar operações por conta
- Ordenar registros por data e hora
- Selecionar o último registro de cada conta para obter o saldo final
- Somar os saldos finais por código COSIF
Com essa opção, você pode extrair as informações necessárias para o CADOC 4010/4016 e transferi-las para o formato de layout exigido pelo BACEN. Este template pode ajudar se você já possui um provedor que constrói arquivos CADOC.
account_id;account_alias;codigo_cosif;created_at;saldo_disponivel
{%- for op_route in midaz_transaction.operation_route %}
{%- if op_route.code %}
{%- for op in filter(midaz_transaction.operation, "route", op_route.id) %}
{{ op.account_id }};{{ op.account_alias }};{{ op_route.code }};{{ op.created_at }};{{ op.available_balance_after }}
{%- endfor %}
{%- endif %}
{%- endfor %}
- Identificador da conta
- Alias da conta
- Código COSIF
- Data e hora da operação
- Saldo disponível
Você pode importar este CSV em uma planilha ou no seu sistema de conciliação existente para processar os saldos finais.
O CADOC 4010 e o CADOC 4111 compartilham a mesma estrutura de template, com diferenças apenas nos parâmetros:
| Aspecto | CADOC 4111 | CADOC 4010 |
|---|
| Documento | Saldos diários | Balancete mensal |
| Periodicidade | Diária | Mensal |
codigoDocumento | "4111" | "4010" |
dataBase | YYYY-MM | YYYY-MM |
| Filtro de data | 1 dia | 1 mês |
| Saldo esperado | Último do dia | Último do mês |
Boas práticas para construção de templates
Nomenclatura de variáveis
Use nomes descritivos e únicos para variáveis de iteração, evitando conflitos com nomes de campos das entidades.
Validação de campos
Sempre verifique se campos opcionais possuem valores antes de utilizá-los. Campos vazios podem gerar linhas indesejadas no relatório.
O BACEN exige datas no formato YYYY-MM para o 4010. Certifique-se de configurar o formato corretamente no template.
Tratamento do CNPJ
O CNPJ deve ser apresentado apenas com os primeiros 8 dígitos, sem formatação (pontos, barras ou hifens).
Código de conta COSIF
O plano de contas COSIF é estruturado com 6 níveis hierárquicos e um dígito verificador. O campo codigoConta deve ter 10 dígitos numéricos, sem pontos ou hifens.
Resumo dos componentes
| Componente | Fonte de dados | Uso no template |
|---|
| CNPJ | Organização (Onboarding) | Cabeçalho do documento |
| Código COSIF | Rota de operação (Transaction) | Identificador da conta |
| Saldo | Operação (Transaction) | Valor a ser agregado |
| Data-base | Função de data atual | Cabeçalho do documento |
Sempre valide o XML renderizado contra o schema do BACEN antes de enviar. A estrutura por si só não é suficiente — os dados devem refletir o ledger real da sua instituição.
