CADOC 4111

Genera el reporte XML CADOC 4111 para BACEN con Reporter — saldos diarios de cuentas agrupados por código COSIF en el layout regulatorio.

Reporter te 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 te muestra la estructura y la lógica utilizada para generar el informe CADOC 4111 en XML.

Estos informes siguen el estándar COSIF y deben coincidir con la estructura XML definida por BACEN. Puedes adaptar la lógica a tu propio modelo de datos, pero el formato XML debe respetarse.

​

¿Qué es CADOC 4111?

---

El CADOC 4111 es un documento regulatorio requerido por el Banco Central de Brasil (BACEN) que reporta saldos diarios de cuentas contables agrupados por código COSIF (Plan de Cuentas para Instituciones del Sistema Financiero Nacional).

​

Lo que BACEN espera recibir

• Saldos consolidados por código COSIF
• Fecha base del informe
• CNPJ de la institución (primeros 8 dígitos)
• Tipo de envío (I = Inclusión, S = Sustitución)

​

Requisitos de envío

Documento	Plazo	Código STA
4111	Día siguiente a la fecha de referencia (o siguiente día hábil)	ACOS011

El código STA identifica el tipo de documento en el sistema de transmisión de BACEN. Usa ACOS011 al enviar CADOC 4111.

​

Entendiendo la estructura de datos

---

Antes de construir la plantilla, es esencial entender cómo se organizan los datos en el libro mayor de Midaz.

​

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

Cuando se registra una operación en Midaz, se asocia con una ruta. Esta ruta contiene el código COSIF correspondiente.

Piensa en las rutas como “etiquetas contables” adjuntas a cada operación, indicando bajo qué categoría 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 afectada
• 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

El campo de saldo después de la operación representa el saldo acumulado de la cuenta en ese momento, no el valor de la operación en sí.

​

Relación entre rutas y operaciones

Cada ruta puede tener múltiples operaciones vinculadas a lo largo del día.

​

Estructura de CADOC

---

​

Formato base

El informe CADOC debe ser un archivo XML y debe seguir la estructura definida por BACEN:

XML

<?xml version="1.0" encoding="UTF-8"?>
<documento codigoDocumento="4111" cnpj="99999999" dataBase="2025/11/30" tipoRemessa="I">
  <registros>
    <registro>
      <conta>1000000009</conta>
      <saldoDia>99.99</saldoDia>
    </registro>
    <registro>
      <conta>1100000002</conta>
      <saldoDia>99.99</saldoDia>
    </registro>
  </registros>
</documento>

​

Campos obligatorios

Estos campos son requeridos y deben incluirse:

<?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	"4111"
cnpj	Primeros 8 dígitos del CNPJ	Numérico, 8 posiciones
dataBase	Fecha de referencia	YYYY/MM/dd
tipoRemessa	Tipo de envío	"I" o "S"

Si tu primer envío fue rechazado debido a errores, aún necesitas usar "I" en tu próximo intento. Solo usa "S" para reemplazar datos previamente aprobados.

Etiqueta <registros>

Agrupa los registros del período del informe.

Etiqueta <registro>

Agrupa un registro de cuenta. Cada registro contiene:

• conta: Código COSIF de la ruta de operación (10 dígitos numéricos)
• saldoDia: Saldo consolidado en formato decimal (dos decimales)

​

Lógica de construcción de la plantilla

---

​

Estructura general

La plantilla primero conserva la última operación de cada par de cuenta y ruta. Luego recorre las rutas de operación disponibles y suma esos últimos saldos para cada ruta.

​

Encabezado del documento

El encabezado XML debe contener:

• Código del documento: Identificador fijo 4111
• CNPJ: Extraído de los datos de la organización, limitado a los primeros 8 dígitos
• Fecha base: Fecha de generación del informe en formato YYYY/MM/dd
• Tipo de envío: I para inclusión

Los datos de la organización se obtienen de la fuente de datos de onboarding de Midaz, específicamente de la entidad organización.

​

Iterando sobre rutas

La plantilla debe iterar a través de todas las rutas de operación registradas. Para cada ruta:

1. Verificar código COSIF: Solo las rutas con un código COSIF válido deben generar líneas en el informe
2. Filtrar operaciones: A partir del resultado de last_item_by_group, seleccionar solo las últimas operaciones que pertenecen a esa ruta específica
3. Calcular saldo: Sumar los saldos de esas últimas operaciones

No todas las rutas tienen un código COSIF completo. Las rutas sin código se usan para controles internos y no deben aparecer en el informe regulatorio.

​

Filtrando operaciones por ruta

La asociación entre operaciones y rutas se realiza a través del identificador de ruta. La plantilla usa este identificador para:

1. Acceder a una ruta específica
2. Encontrar todas las operaciones que referencian esta ruta
3. Procesar solo estas operaciones en la agregación

Al construir la plantilla, evita usar el mismo nombre para la variable de iteración y el campo de filtro, ya que esto puede causar conflictos en la interpretación de la plantilla.

​

Sumando saldos

Para cada ruta, la plantilla suma available_balance_after solo de la última operación seleccionada para cada par de cuenta y ruta. No suma todas las operaciones históricas, lo que sobrestimaría el saldo.

​

Usando Reporter

---

Aquí está la plantilla completa para generar CADOC 4111 en Reporter:

Plantilla

<?xml version="1.0" encoding="UTF-8"?>
<documento codigoDocumento="4111" cnpj="{{ midaz_onboarding.organization.0.legal_document|slice:":8" }}" dataBase="{% date_time "YYYY/MM/dd" %}" tipoRemessa="I">
  <registros>
{% last_item_by_group midaz_transaction.operation group_by "account_id,route" order_by "created_at" if route as listaOperations %}
{%- for oproute in midaz_transaction.operation_route %}
{%- if oproute.code %}
    <registro>
      <conta>{{ oproute.code }}</conta>
      <saldoDia>{% sum_by listaOperations by "available_balance_after" if oproute.id == route %}</saldoDia>
    </registro>
{%- endif %}
{%- endfor %}
  </registros>
</documento>

​

Desglose del código

---

​

Línea 1 - Declaración XML

<?xml version="1.0" encoding="UTF-8"?>

Encabezado XML estándar con codificación UTF-8.

​

Línea 2 - Elemento raíz <documento>

<documento codigoDocumento="4111" cnpj="{{ midaz_onboarding.organization.0.legal_document|slice:":8" }}" dataBase="{% date_time "YYYY/MM/dd" %}" tipoRemessa="I">

• codigoDocumento="4111": Identificador fijo del tipo de documento
• cnpj: Accede al documento legal de la organización y extrae los primeros 8 caracteres usando el filtro slice
• dataBase: Genera la fecha actual en el formato YYYY/MM/dd usando la etiqueta date_time
• tipoRemessa="I": Indica inclusión de datos

​

Línea 4 - Seleccionar las últimas operaciones

{% last_item_by_group midaz_transaction.operation group_by "account_id,route" order_by "created_at" if route as listaOperations %}

• last_item_by_group: Conserva la última operación de cada par account_id y route, ordenada por created_at
• listaOperations: Colección de esas últimas operaciones utilizada para calcular el saldo

​

Línea 5 - Iniciar el bucle de rutas y verificar su código

{%- for oproute in midaz_transaction.operation_route %}
{%- if oproute.code %}

oproute recibe cada ruta de operación. La condición omite las rutas sin código COSIF.

​

Línea 6 - Elemento <registro>

<registro>
  <conta>{{ oproute.code }}</conta>
  <saldoDia>{% sum_by listaOperations by "available_balance_after" if oproute.id == route %}</saldoDia>
</registro>

• conta: Muestra el código COSIF de la ruta actual
• saldoDia: Usa sum_by para sumar los últimos saldos seleccionados cuya ruta coincide con el identificador de la ruta actual (oproute.id)

​

Líneas 7-8 - Cierre de bloques

{%- endif %}
{%- endfor %}

Cierran la condición y el bucle respectivamente.

​

Referencia de etiquetas y filtros

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	Extrae los primeros 8 caracteres
last_item_by_group	Etiqueta	Conserva el último elemento de cada grupo
for ... in	Etiqueta	Itera a través de una colección
if	Etiqueta	Condición de ejecución
sum_by ... by ... if	Etiqueta	Suma valores con filtro condicional
date_time	Etiqueta	Genera fecha formateada

​

Consideraciones del filtro de fecha

---

​

Ejemplo de solicitud con filtro de fecha

Para generar CADOC 4111 para un día específico, envía una solicitud POST /v1/reports con el siguiente cuerpo:

Solicitud

{
  "templateId": "CADOC_4111_TEMPLATE_ID",
  "filters": {
    "midaz_transaction": {
      "operation": {
        "created_at": {
          "between": ["2025-11-11T00:00:00Z", "2025-11-11T23:59:59Z"]
        }
      }
    }
  }
}

​

Explicación de campos

Campo	Descripción
templateId	Identificador de la plantilla CADOC 4111 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]	Fecha y hora de inicio (medianoche del día deseado)
between[1]	Fecha y hora de fin (último segundo del día deseado)

Las fechas deben estar en formato ISO 8601 con zona horaria UTC (Z).

​

Evolución de la plantilla y extracción de saldos

---

Estamos trabajando en la evolución de nuestra plantilla principal para soportar la agregación de saldos en cumplimiento con BACEN CADOC 4111, que requiere el saldo final del último día hábil.

Mientras esta funcionalidad está siendo desarrollada, proporcionamos una versión alternativa para extraer estos saldos usando la siguiente plantilla.

​

Plantilla de extracción

Esta plantilla auxiliar está diseñada para calcular correctamente los saldos, asegurando el cumplimiento de tus informes a través de los siguientes pasos:

1. Agrupar operaciones por cuenta
2. Ordenar entradas por fecha y hora
3. Seleccionar el último registro de cada cuenta para obtener el saldo final
4. Sumar saldos finales por código COSIF

Con esta opción, puedes extraer la información requerida para CADOC 4111 y transferirla al formato de diseño requerido por BACEN. Esta plantilla puede ayudar si ya tienes un proveedor que construye archivos CADOC.

​

Ejemplo de plantilla de extracción

Extracción CSV

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

​

Salida de extracción

La plantilla exporta todas las operaciones en formato CSV, conteniendo:

• Identificador de cuenta
• Alias de cuenta
• Código COSIF
• Fecha y hora de la operación
• Saldo disponible

Puedes importar este CSV en una hoja de cálculo o tu sistema de conciliación existente para procesar los saldos finales.

​

Mejores prácticas para construcción de plantillas

---

​

Nomenclatura de variables

Usa nombres descriptivos y únicos para las variables de iteración, evitando conflictos con los nombres de campos de entidades.

​

Validación de campos

Siempre verifica si los campos opcionales tienen valores antes de usarlos. Los campos vacíos pueden generar líneas no deseadas en el informe.

​

Formato de fecha

BACEN requiere fechas en formato AAAA-MM. Asegúrate 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).

​

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 valida 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 tu institución.