Saltar al contenido principal
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 el informe CADOC 4111 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é 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

DocumentoPlazoCódigo STA
4111Dí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. Use 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.
Piense 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 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>

​
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:
CampoDescripciónFormato
codigoDocumentoIdentificador fijo"4111"
cnpjPrimeros 8 dígitos del CNPJNumérico, 8 posiciones
dataBaseFecha de referenciaAAAA-MM
tipoRemessaTipo 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.
Etiqueta <contas> Agrupa todas las entradas de cuentas para el período del informe. Etiqueta <conta>
  • codigoConta: 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 sigue una lógica de agregación en dos niveles:
  1. Primer nivel: Iterar a través de todas las rutas de operación disponibles
  2. Segundo nivel: Para cada ruta, sumar los saldos de las operaciones vinculadas

​
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 AAAA-MM
  • 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: Seleccionar solo las operaciones que pertenecen a esa ruta específica
  3. Calcular saldo: Sumar los saldos de las operaciones filtradas
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, evite 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 conjunto de operaciones de una ruta, la plantilla suma los saldos disponibles. El campo utilizado es el saldo disponible después de cada operación. La función de agregación itera a través de todas las operaciones que cumplen los criterios de filtro (misma ruta) y acumula los valores del campo de saldo.

​
Usando Reporter

Aquí está la plantilla completa para generar CADOC 4111 en Reporter: 
<?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>

​
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" %}" 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 requerido por BACEN usando la etiqueta date_time
  • tipoRemessa="I": Indica inclusión de datos

​
Línea 4 - Inicio del bucle for

{%- for op_route in midaz_transaction.operation_route %}
  • op_route: Variable que recibe cada ruta durante la iteración (nombre elegido para evitar conflicto con el campo route en operaciones)
  • midaz_transaction.operation_route: Colección de todas las rutas de operación

​
Línea 5 - Condición if

{%- if op_route.code %}
Verifica si la ruta tiene un código COSIF completo. Las rutas sin código son ignoradas.

​
Línea 6 - Elemento <conta>

<conta codigoConta="{{ op_route.code }}" saldoDia="{% sum_by midaz_transaction.operation by "available_balance_after" if route == op_route.id %}" />
  • codigoConta: Muestra el código COSIF de la ruta actual
  • saldoDia: Usa la etiqueta sum_by para sumar saldos, filtrando solo las operaciones cuya ruta coincide con el identificador de la ruta actual (op_route.id)

​
Líneas 7-8 - Cierre de bloques

{%- endif %}
{%- endfor %}
Cierran la condición y el bucle respectivamente.

​
Referencia de etiquetas y filtros

ElementoTipoFunción
{{ variable }}ExpresiónMuestra el valor de una variable
{% tag %}EtiquetaEjecuta lógica (bucle, condición, agregación)
|slice:":8"FiltroExtrae los primeros 8 caracteres
for ... inEtiquetaItera a través de una colección
ifEtiquetaCondición de ejecución
sum_by ... by ... ifEtiquetaSuma valores con filtro condicional
date_timeEtiquetaGenera 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íe una solicitud POST /v1/reports con el encabezado X-Organization-Id y el siguiente cuerpo: 
{
  "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

CampoDescripción
templateIdIdentificador de la plantilla CADOC 4111 registrada en Reporter
filters.midaz_transaction.operationIndica que el filtro se aplicará a la colección de operaciones
created_at.betweenFiltra 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 sus 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, puede extraer la información requerida para CADOC 4111 y transferirla al formato de diseño requerido por BACEN. Esta plantilla puede ayudar si ya tiene un proveedor que construye archivos CADOC.

​
Ejemplo de plantilla de extracción

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
Puede importar este CSV en una hoja de cálculo o su sistema de conciliación existente para procesar los saldos finales.

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

​
Formato de fecha

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

​
Resumen de componentes

ComponenteFuente de DatosUso en Plantilla
CNPJOrganización (Onboarding)Encabezado del documento
Código COSIFRuta de Operación (Transacción)Identificador de cuenta
SaldoOperación (Transacción)Valor a agregar
Fecha BaseFunción de fecha actualEncabezado 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.