> ## 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. # CADOC 4010 e 4016 > Gere os relatórios XML CADOC 4010 e 4016 para o BACEN com o Reporter, seguindo o padrão COSIF e o layout regulatório exigido. 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 XML theme={null} ``` ### Campos obrigatórios **``** 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 ``** 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 ``** Agrupa todas as entradas de contas do período de reporte. **Tag ``** * `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: 1. **Primeiro nível**: Iterar por todas as rotas de operação disponíveis 2. **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: 1. **Verificar se possui código COSIF**: Apenas rotas com código preenchido geram linhas 2. **Filtrar operações**: Selecionar as operações que pertencem àquela rota 3. **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 tpl theme={null} {%- for op_route in midaz_transaction.operation_route %} {%- if op_route.code %} {%- endif %} {%- endfor %} ``` ### Explicação linha a linha **Linha 1 - Declaração XML** Cabeçalho XML padrão com codificação UTF-8. **Linha 2 - Elemento raiz ``** * `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 ``** * `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 tpl theme={null} {%- 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" %} {%- endif %} {%- endfor %} ``` ### 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: ```json JSON theme={null} { "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: ```json JSON theme={null} { "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: 1. Agrupar operações por conta 2. Ordenar registros por data e hora 3. Selecionar o último registro de cada conta para obter o saldo final 4. 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 ```xml tpl theme={null} 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.