Reporter le permite generar informes basados en XML que siguen la estructura oficial de CADOC, exactamente como lo requiere el Banco Central de Brasil (BACEN).
Esta guía le muestra la estructura y la lógica utilizada para generar los informes CADOC 4010 y CADOC 4016 en XML.
Estos informes siguen el estándar COSIF y deben coincidir con la estructura XML definida por BACEN. Puede adaptar la lógica a su propio modelo de datos, pero el formato XML debe respetarse.
¿Qué son CADOC 4010 y 4016?
El 4010 y el 4016 son informes de Balance Analítico utilizados para enviar informes financieros al BACEN (Banco Central de Brasil).
Lo que BACEN espera recibir
- Saldos de cierre por código COSIF
- Fecha base del informe (mes de referencia)
- CNPJ de la institución (primeros 8 dígitos)
- Tipo de envío (
I = Inclusión, S = Sustitución)
Diferencia entre CADOC 4010 y 4016
| Documento | Periodicidad | Fecha Base | Cuentas Esperadas |
|---|
| 4010 | Mensual | AAAA-MM | Todas las cuentas |
| 4016 | Semestral (Jun/Dic) | AAAA-MM | Sin grupos 7 y 8 (Ingresos/Gastos) |
Requisitos de envío
| Documento | Plazo | Código STA |
|---|
| 4010 | Día 18 del mes siguiente (o el siguiente día hábil) | ACOS010 |
| 4016 | Último día hábil del mes siguiente | ACOS016 |
El código STA identifica el tipo de documento en el sistema de transmisión de BACEN. Use ACOS010 al enviar CADOC 4010 y ACOS016 al enviar CADOC 4016.
Entendiendo la estructura de datos
Rutas de operación
Las rutas de operación funcionan como clasificadores contables. Cada ruta tiene:
- Identificador único (
id): Usado internamente para relacionar operaciones
- Código COSIF (
code): El código contable de 10 dígitos que será reportado a BACEN
Piense en las rutas como “etiquetas contables” adjuntas a cada operación, indicando bajo qué elemento del plan de cuentas debe clasificarse ese movimiento.
Operaciones
Las operaciones representan movimientos financieros en el libro mayor. Cada operación contiene:
- Cuenta asociada (
account_id): Qué cuenta fue movida
- Ruta (
route): ID de la ruta/clasificación contable aplicada
- Saldo después de la operación (
available_balance_after): El saldo de la cuenta inmediatamente después de esta operación
- Fecha y hora (
created_at): Cuándo ocurrió la operación
Relación entre entidades
La entidad balance representa el saldo actual de la cuenta, no el historial. Para informes regulatorios que necesitan saldos de un período específico, use la entidad operation con filtros de fecha.
Estructura de CADOC
El informe CADOC debe ser un archivo XML y debe seguir la estructura definida por 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 obligatorios
<?xml version="1.0" encoding="UTF-8"?>
Siempre inicia el archivo. Define la versión de XML y la codificación para que el sistema sepa cómo leer el contenido.
Etiqueta <documento>
Envuelve toda la estructura CADOC e incluye:
| Campo | Descripción | Formato |
|---|
codigoDocumento | Identificador fijo | "4010" o "4016" |
cnpj | Primeros 8 dígitos del CNPJ | Numérico, 8 posiciones |
dataBase | Mes de referencia | AAAA-MM |
tipoRemessa | Tipo de envío | "I" o "S" |
Si su primer envío fue rechazado debido a errores, aún necesita usar "I" en su próximo intento. Solo use "S" para reemplazar datos previamente aprobados.
<contas>
Agrupa todas las entradas de cuentas para el período del informe.
Etiqueta <conta>
codigoConta: Código de cuenta, siguiendo el formato COSIF (10 dígitos numéricos).saldo: Saldo de la cuenta en formato decimal (dos decimales).
Lógica de construcción de la plantilla
Estructura general
La plantilla sigue una lógica de agregación en dos niveles:
- Primer nivel: Iterar a través de todas las rutas de operación disponibles
- Segundo nivel: Para cada ruta, agregar los saldos de las operaciones vinculadas
Iterando sobre rutas
La plantilla debe iterar a través de todas las rutas de operación registradas. Para cada ruta:
- Verificar si tiene código COSIF: Solo las rutas con código completo generan líneas
- Filtrar operaciones: Seleccionar operaciones que pertenecen a esa ruta
- Calcular el saldo: Agregar los saldos de las operaciones filtradas
Precaución con nomenclatura de variables
Al construir la plantilla, evite usar el mismo nombre para la variable de iteración y el campo de filtro:
| Enfoque | Ejemplo | Resultado |
|---|
| Incorrecto | for route in ... if route == route.id | Conflicto de nombres |
| Correcto | for op_route in ... if route == op_route.id | Funciona correctamente |
Plantilla CADOC 4010
Aquí está la plantilla completa para generar CADOC 4010 en 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>
Explicación línea por línea
Línea 1 - Declaración XML
Encabezado XML estándar con codificación UTF-8.
Línea 2 - Elemento raíz <documento>
codigoDocumento="4010": Identificador fijo para el Balance Analíticocnpj: Extrae los primeros 8 dígitos del documento legal de la organizacióndataBase: Genera la fecha en formato AAAA-MM (mes de referencia)tipoRemessa="I": Indica inclusión de datos
Línea 4 - Inicio del bucle for
op_route: Variable que recibe cada ruta durante la iteraciónmidaz_transaction.operation_route: Colección de todas las rutas de operación
Línea 5 - Condición if
Verifica si la ruta tiene un código COSIF completo.
Línea 6 - Elemento <conta>
codigoConta: Muestra el código COSIF de la ruta actualsaldo: Usa la etiqueta sum_by para agregar saldos, filtrando operaciones cuya ruta coincide con el identificador de la ruta actual (op_route.id)
Líneas 7-8 - Cierre de bloques
Cierran la condición y el bucle respectivamente.
Etiquetas y filtros utilizados
| Elemento | Tipo | Función |
|---|
{{ variable }} | Expresión | Muestra el valor de una variable |
{% tag %} | Etiqueta | Ejecuta lógica (bucle, condición, agregación) |
|slice:':8' | Filtro | Corta los primeros 8 caracteres |
for ... in | Etiqueta | Itera a través de una colección |
if | Etiqueta | Condición para ejecución |
sum_by ... by ... if | Etiqueta | Suma valores con filtro condicional |
date_time | Etiqueta | Genera fecha formateada |
Plantilla CADOC 4016
El CADOC 4016 es el Balance Analítico, similar al 4010, pero con periodicidad semestral y una restricción importante: no debe contener cuentas de los grupos 7 (Ingresos) y 8 (Gastos).
¿Por qué excluir los grupos 7 y 8?
El documento 4016 representa la posición contable de la entidad después del cierre del estado de resultados. En este punto, las cuentas de Ingresos (grupo 7) y las cuentas de Gastos (grupo 8) ya han sido cerradas y sus saldos transferidos al Patrimonio.
Ejemplo de plantilla
<?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>
Diferencia con 4010
La única diferencia en la plantilla es la condición adicional en el if:
| Plantilla | Condición |
|---|
| 4010 | if op_route.code |
| 4016 | if op_route.code and op_route.code|slice:":1" != "7" and op_route.code|slice:":1" != "8" |
Cómo funciona la exclusión
El filtro slice:":1" extrae el primer carácter del código COSIF:
| Código COSIF | Primer Dígito | Grupo | ¿Incluido en 4016? |
|---|
| 1000000009 | 1 | Activos | Sí |
| 2100000003 | 2 | Pasivos | Sí |
| 7100000001 | 7 | Ingresos | No |
| 8200000005 | 8 | Gastos | No |
Ejemplo de solicitud para 4010
Para generar el CADOC 4010 para un mes específico, envíe una solicitud POST /v1/reports con el encabezado X-Organization-Id y el siguiente cuerpo:
{
"templateId": "CADOC_4010_TEMPLATE_ID",
"filters": {
"midaz_transaction": {
"operation": {
"created_at": {
"between": ["2025-11-01T00:00:00Z", "2025-11-30T23:59:59Z"]
}
}
}
}
}
Explicación de campos
| Campo | Descripción |
|---|
templateId | Identificador de la plantilla CADOC 4010 registrada en Reporter |
filters.midaz_transaction.operation | Indica que el filtro se aplicará a la colección de operaciones |
created_at.between | Filtra operaciones creadas dentro del intervalo especificado |
between[0] | Primer día del mes a las 00:00:00 UTC |
between[1] | Último día del mes a las 23:59:59 UTC |
Z).
Ajuste el último día según el mes (28, 29, 30 o 31 días).
Ejemplo de solicitud para 4016
Para generar el CADOC 4016 para el primer semestre:
{
"templateId": "CADOC_4016_TEMPLATE_ID",
"filters": {
"midaz_transaction": {
"operation": {
"created_at": {
"between": ["2025-01-01T00:00:00Z", "2025-06-30T23:59:59Z"]
}
}
}
}
}
Estamos trabajando en la evolución de nuestra plantilla principal para soportar la agregación de saldos en cumplimiento con BACEN CADOC 4010/4016, que requiere el saldo final del último día hábil del mes.
Mientras esta funcionalidad está siendo desarrollada, proporcionamos una versión alternativa para extraer estos saldos usando la siguiente plantilla.
Esta plantilla auxiliar está diseñada para calcular correctamente los saldos, asegurando el cumplimiento de sus informes a través de los siguientes pasos:
- Agrupar operaciones por cuenta
- Ordenar entradas por fecha y hora
- Seleccionar el último registro de cada cuenta para obtener el saldo final
- Sumar saldos finales por código COSIF
Con esta opción, puede extraer la información requerida para CADOC 4010/4016 y transferirla al formato de diseño requerido por BACEN. Esta plantilla puede ayudar si ya tiene un proveedor que construye archivos 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 de cuenta
- Alias de cuenta
- Código COSIF
- Fecha y hora de la operación
- Saldo disponible
Puede importar este CSV en una hoja de cálculo o su sistema de conciliación existente para procesar los saldos finales.
Comparación con CADOC 4111
CADOC 4010 y CADOC 4111 comparten la misma estructura de plantilla, con diferencias solo en los parámetros:
| Aspecto | CADOC 4111 | CADOC 4010 |
|---|
| Documento | Saldos Diarios | Balance Mensual |
| Periodicidad | Diaria | Mensual |
codigoDocumento | "4111" | "4010" |
dataBase | AAAA-MM | AAAA-MM |
| Filtro de fecha | 1 día | 1 mes |
| Saldo esperado | Último del día | Último del mes |
Mejores prácticas para construcción de plantillas
Nomenclatura de variables
Use nombres descriptivos y únicos para las variables de iteración, evitando conflictos con los nombres de campos de entidades.
Validación de campos
Siempre verifique si los campos opcionales tienen valores antes de usarlos. Los campos vacíos pueden generar líneas no deseadas en el informe.
BACEN requiere fechas en formato AAAA-MM para 4010. Asegúrese de configurar el formato correctamente en la plantilla.
Manejo de CNPJ
El CNPJ debe presentarse con solo los primeros 8 dígitos, sin formato (puntos, barras o guiones).
Código de cuenta COSIF
El plan de cuentas COSIF está estructurado con 6 niveles jerárquicos y un dígito verificador. El campo codigoConta debe tener 10 dígitos numéricos, sin puntos ni guiones.
Resumen de componentes
| Componente | Fuente de Datos | Uso en Plantilla |
|---|
| CNPJ | Organización (Onboarding) | Encabezado del documento |
| Código COSIF | Ruta de Operación (Transacción) | Identificador de cuenta |
| Saldo | Operación (Transacción) | Valor a agregar |
| Fecha Base | Función de fecha actual | Encabezado del documento |
Siempre valide el XML renderizado contra el esquema de BACEN antes de enviar. La estructura por sí sola no es suficiente — los datos deben reflejar el libro mayor real de su institución.
