CADOC 4010 e 4016

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)

O 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.

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

Relação entre as entidades do ledger e as operações usadas para montar os relatórios CADOC 4010 e 4016

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

Formato base

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.

Tag <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

Cuidado com a nomenclatura de variáveis

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ítico
cnpj: Extrai os primeiros 8 dígitos do documento legal da organização
dataBase: 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ção
midaz_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 atual
saldo: 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.

Tags e filtros utilizados

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

Gerando o relatório com filtro de data

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

Formato de data: ISO 8601 com fuso horário 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"]
        }
      }
    }
  }
}

Para o segundo semestre, ajuste as datas para julho até dezembro.

Evolução do template e extração de saldos

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.

Template de extração

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.

Exemplo de template de extração

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 %}

Saída da extração

O template exporta todas as operações em formato CSV, contendo:

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.

Comparação com o CADOC 4111

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

Template idêntico: A lógica para iterar sobre as rotas e agregar saldos é a mesma.

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.

Formato de data

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.

​O que são os CADOC 4010 e 4016?

​O que o BACEN espera receber

​Diferença entre CADOC 4010 e 4016

​Requisitos de envio

​Entendendo a estrutura de dados

​Rotas de operação

​Operações

​Relacionamento entre entidades

​Estrutura do CADOC

​Formato base

​Campos obrigatórios

​Lógica de construção do template

​Estrutura geral

​Iterando sobre as rotas

​Cuidado com a nomenclatura de variáveis

​Template do CADOC 4010

​Explicação linha a linha

​Tags e filtros utilizados

​Template do CADOC 4016

​Por que excluir os grupos 7 e 8?

​Exemplo de template

​Diferença em relação ao 4010

​Como funciona a exclusão

​Gerando o relatório com filtro de data

​Exemplo de requisição para o 4010

​Explicação dos campos

​Exemplo de requisição para o 4016

​Evolução do template e extração de saldos

​Template de extração

​Exemplo de template de extração

​Saída da extração

​Comparação com o CADOC 4111

​Boas práticas para construção de templates

​Nomenclatura de variáveis

​Validação de campos

​Formato de data

​Tratamento do CNPJ

​Código de conta COSIF

​Resumo dos componentes

O que são os CADOC 4010 e 4016?

O que o BACEN espera receber

Diferença entre CADOC 4010 e 4016

Requisitos de envio

Entendendo a estrutura de dados

Rotas de operação

Operações

Relacionamento entre entidades

Estrutura do CADOC

Formato base

Campos obrigatórios

Lógica de construção do template

Estrutura geral

Iterando sobre as rotas

Cuidado com a nomenclatura de variáveis

Template do CADOC 4010

Explicação linha a linha

Tags e filtros utilizados

Template do CADOC 4016

Por que excluir os grupos 7 e 8?

Exemplo de template

Diferença em relação ao 4010

Como funciona a exclusão

Gerando o relatório com filtro de data

Exemplo de requisição para o 4010

Explicação dos campos

Exemplo de requisição para o 4016

Evolução do template e extração de saldos

Template de extração

Exemplo de template de extração

Saída da extração

Comparação com o CADOC 4111

Boas práticas para construção de templates

Nomenclatura de variáveis

Validação de campos

Formato de data

Tratamento do CNPJ

Código de conta COSIF

Resumo dos componentes