> ## 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 4111

> Gere o relatório XML CADOC 4111 para o BACEN com o Reporter — saldos diários de contas agrupados por código COSIF no layout regulatório.

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 o relatório **CADOC 4111** em XML.

<Danger>
  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.
</Danger>

## O que é o CADOC 4111?

***

O **CADOC 4111** é um documento regulatório exigido pelo Banco Central do Brasil (BACEN) que reporta saldos diários de contas contábeis agrupados por código COSIF (Plano Contábil das Instituições do Sistema Financeiro Nacional).

### O que o BACEN espera receber

* Saldos consolidados por código COSIF
* Data-base do relatório
* CNPJ da instituição (primeiros 8 dígitos)
* Tipo de remessa (`I` = Inclusão, `S` = Substituição)

### Requisitos de envio

| Documento | Prazo                                                   | Código STA |
| --------- | ------------------------------------------------------- | ---------- |
| **4111**  | Dia seguinte à data de referência (ou próximo dia útil) | ACOS011    |

<Note>
  O código STA identifica o tipo de documento no sistema de transmissão do BACEN. Use `ACOS011` ao enviar o CADOC 4111.
</Note>

## Entendendo a estrutura de dados

***

Antes de construir o template, é essencial entender como os dados são organizados no ledger do Midaz.

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

Quando uma operação é registrada no Midaz, ela é associada a uma rota. Essa rota carrega o código COSIF correspondente.

<Tip>
  Pense nas rotas como "rótulos contábeis" vinculados a cada operação, indicando em qual categoria do plano de contas aquele movimento deve ser classificado.
</Tip>

### Operações

As operações representam movimentações financeiras no ledger. Cada operação contém:

* **Conta associada (`account_id`)**: Qual conta foi afetada
* **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

<Warning>
  O campo de saldo após a operação representa o saldo acumulado da conta naquele momento, não o valor da operação em si.
</Warning>

### Relacionamento entre rotas e operações

<Frame>
  <img src="https://mintcdn.com/lerian-49cb71fc/ZrZBZTM4DWnrahSd/images/pt/d2/cadoc-4111-structure.svg?fit=max&auto=format&n=ZrZBZTM4DWnrahSd&q=85&s=7fdb1581165fa0baf8090de905989441" alt="Relação entre as rotas contábeis e as operações usadas para montar o relatório CADOC 4111" width="958" height="466" data-path="images/pt/d2/cadoc-4111-structure.svg" />
</Frame>

Cada rota pode ter múltiplas operações vinculadas a ela ao longo do dia.

## Estrutura do CADOC

***

### Formato base

O relatório CADOC **deve** ser um arquivo XML e **deve** seguir a estrutura definida pelo **BACEN**:

<CodeGroup>
  ```xml XML theme={null}
  <?xml version="1.0" encoding="UTF-8"?>
  <documento codigoDocumento="4111" cnpj="99999999" dataBase="2025-11" tipoRemessa="I">
    <contas>
      <conta codigoConta="1000000009" saldoDia="99.99" />
      <conta codigoConta="1100000002" saldoDia="99.99" />
    </contas>
  </documento>
  ```
</CodeGroup>

### Campos obrigatórios

Estes campos são obrigatórios e devem ser incluídos:

**`<?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          | `"4111"`             |
| `cnpj`            | Primeiros 8 dígitos do CNPJ | Numérico, 8 posições |
| `dataBase`        | Data de referência          | YYYY-MM              |
| `tipoRemessa`     | Tipo de remessa             | `"I"` ou `"S"`       |

<Danger>
  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.
</Danger>

**Tag `<contas>`**

Agrupa todas as entradas de contas do período de reporte.

**Tag `<conta>`**

* `codigoConta`: Código COSIF da rota de operação (10 dígitos numéricos)
* `saldoDia`: Saldo consolidado 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, somar os saldos das operações vinculadas

### Cabeçalho do documento

O cabeçalho do XML deve conter:

* **Código do documento**: Identificador fixo `4111`
* **CNPJ**: Extraído dos dados da organização, limitado aos primeiros 8 dígitos
* **Data-base**: Data de geração do relatório no formato `YYYY-MM`
* **Tipo de remessa**: `I` para inclusão

Os dados da organização são obtidos da fonte de dados de onboarding do Midaz, especificamente da entidade de organização.

### Iterando sobre as rotas

O template deve iterar por todas as rotas de operação registradas. Para cada rota:

1. **Verificar o código COSIF**: Apenas rotas com um código COSIF válido devem gerar linhas no relatório
2. **Filtrar operações**: Selecionar apenas as operações pertencentes àquela rota específica
3. **Calcular o saldo**: Somar os saldos das operações filtradas

<Info>
  Nem todas as rotas possuem um código COSIF preenchido. Rotas sem código são usadas para controles internos e não devem aparecer no relatório regulatório.
</Info>

### Filtrando operações por rota

A associação entre operações e rotas é feita por meio do identificador da rota. O template usa esse identificador para:

1. Acessar uma rota específica
2. Encontrar todas as operações que referenciam essa rota
3. Processar apenas essas operações na agregação

<Warning>
  Ao construir o template, evite usar o mesmo nome para a variável de iteração e o campo de filtro, pois isso pode causar conflitos na interpretação do template.
</Warning>

### Somando saldos

Para cada conjunto de operações de uma rota, o template soma os saldos disponíveis. O campo utilizado é o saldo disponível após cada operação.

A função de agregação itera por todas as operações que atendem aos critérios de filtro (mesma rota) e acumula os valores do campo de saldo.

## Usando o Reporter

***

Aqui está o template completo para gerar o CADOC 4111 no Reporter:

<CodeGroup>
  ```tpl Template theme={null}
  <?xml version="1.0" encoding="UTF-8"?>
  <documento codigoDocumento="4111" 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 }}" saldoDia="{% sum_by midaz_transaction.operation by "available_balance_after" if route == op_route.id %}" />
  {%- endif %}
  {%- endfor %}
    </contas>
  </documento>
  ```
</CodeGroup>

## Detalhamento do código

***

### Linha 1 - Declaração XML

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
```

Cabeçalho XML padrão com codificação UTF-8.

### Linha 2 - Elemento raiz `<documento>`

```tpl theme={null}
<documento codigoDocumento="4111" cnpj="{{ midaz_onboarding.organization.0.legal_document|slice:":8" }}" dataBase="{% date_time "YYYY-MM" %}" tipoRemessa="I">
```

* `codigoDocumento="4111"`: Identificador fixo do tipo de documento
* `cnpj`: Acessa o documento legal da organização e extrai os primeiros 8 caracteres usando o filtro `slice`
* `dataBase`: Gera a data atual no formato exigido pelo BACEN usando a tag `date_time`
* `tipoRemessa="I"`: Indica inclusão de dados

### Linha 4 - Início do loop `for`

```tpl theme={null}
{%- for op_route in midaz_transaction.operation_route %}
```

* `op_route`: Variável que recebe cada rota durante a iteração (nome escolhido para evitar conflito com o campo `route` nas operações)
* `midaz_transaction.operation_route`: Coleção de todas as rotas de operação

### Linha 5 - Condição `if`

```tpl theme={null}
{%- if op_route.code %}
```

Verifica se a rota possui um código COSIF preenchido. Rotas sem código são ignoradas.

### Linha 6 - Elemento `<conta>`

```tpl theme={null}
<conta codigoConta="{{ op_route.code }}" saldoDia="{% sum_by midaz_transaction.operation by "available_balance_after" if route == op_route.id %}" />
```

* `codigoConta`: Exibe o código COSIF da rota atual
* `saldoDia`: Usa a tag `sum_by` para somar saldos, filtrando apenas as operações cuja rota corresponde ao identificador da rota atual (`op_route.id`)

### Linhas 7-8 - Fechamento dos blocos

```tpl theme={null}
{%- endif %}
{%- endfor %}
```

Fecham a condição e o loop respectivamente.

### Referência de tags e filtros

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

## Considerações sobre filtro de data

***

### Exemplo de requisição com filtro de data

Para gerar o CADOC 4111 para um dia específico, envie uma requisição `POST /v1/reports` com o header `X-Organization-Id` e o seguinte corpo:

<CodeGroup>
  ```json Request theme={null}
  {
    "templateId": "CADOC_4111_TEMPLATE_ID",
    "filters": {
      "midaz_transaction": {
        "operation": {
          "created_at": {
            "between": ["2025-11-11T00:00:00Z", "2025-11-11T23:59:59Z"]
          }
        }
      }
    }
  }
  ```
</CodeGroup>

### Explicação dos campos

| Campo                                 | Descrição                                                   |
| ------------------------------------- | ----------------------------------------------------------- |
| `templateId`                          | Identificador do template CADOC 4111 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]`                          | Data e hora de início (meia-noite do dia desejado)          |
| `between[1]`                          | Data e hora de fim (último segundo do dia desejado)         |

<Info>
  As datas devem estar no formato ISO 8601 com fuso horário UTC (`Z`).
</Info>

## 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 4111, que exige o saldo final do último dia útil.

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

<CodeGroup>
  ```tpl CSV Extraction 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 %}
  ```
</CodeGroup>

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

## 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`. 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).

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

<Warning>
  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.
</Warning>