APIX 001

Reporter te permite generar informes en XML que siguen la estructura oficial APIX, exigida por el Banco Central de Brasil (BACEN). Esta guía recorre la estructura y la lógica utilizadas para generar el informe APIX 001 (Documento 1201) en XML.

Los informes APIX 001 deben seguir estrictamente el esquema XSD definido por el BACEN (versión 2.5). Reporter automatiza la generación del XML, pero tú sigues siendo responsable de validar la salida y de asegurar el cumplimiento de los requisitos regulatorios.

¿Qué es APIX 001?

El APIX 001 es un informe regulatorio mensual que los participantes de Pix —directos o indirectos— deben enviar al Banco Central de Brasil. Consolida las estadísticas operativas del ecosistema Pix de la institución durante un mes determinado.

Qué espera recibir el BACEN

El informe abarca diez secciones de datos:

Sección	Descripción
Transacoes	Volúmenes y valores de transacciones, desglosados por tipo de detalle y finalidad
Devolucoes	Volúmenes y valores de devoluciones (MED y otros motivos)
BloqueiosCautelares	Cantidad y valores de bloqueos cautelares
Receitas	Ingresos derivados de operaciones Pix por fuente y tipo de persona
TemposTransacoes	Percentiles de tiempo de procesamiento de transacciones (P50, P99)
TemposDict	Percentiles de tiempo de operaciones DICT (consultas, registros, portabilidad)
ConsultasDict	Total de consultas DICT en el período
Disponibilidade	Índice de disponibilidad del sistema (porcentaje)
TempoAutorizacoes	Tiempo de procesamiento de autorizaciones (P95)
Autorizacoes	Cantidad y stock de autorizaciones de Pix Automático por tipo de pagador

Requisitos de envío

Documento	Frecuencia	Plazo	Referencia
APIX 001	Mensual	15.º día hábil del mes siguiente	Documento 1201, XSD versión 2.5

Atributos del encabezado

El elemento raíz <APIX001> requiere estos atributos:

Atributo	Descripción	Formato
`DtArquivo`	Fecha de generación del archivo	`YYYY-MM-DD`
`Ano`	Año de referencia	`YYYY`
`Mes`	Mes de referencia	`1`–`12`
`ISPB`	Código ISPB de la institución (primeros 8 dígitos del CNPJ)	8 dígitos numéricos
`NomeResp`	Nombre del responsable	Texto (máx. 200 caracteres)
`EmailResp`	Correo del responsable	Correo válido
`TelResp`	Teléfono del responsable	Texto (máx. 14 caracteres)
`TipoEnvio`	Tipo de envío	`I` (Inclusión) o `S` (Sustitución)

Comprender la estructura de datos

Antes de construir la plantilla, es importante entender cómo se mapean los datos del plugin Pix con cada sección del APIX 001.

Fuentes de datos del plugin Pix

La plantilla consulta datos de las tablas del plugin Pix registradas como fuentes de datos en Reporter. Las entidades principales utilizadas son:

Fuente de datos	Tabla	Contenido
`payment.transfers`	Transferencias Pix	Registros de transacciones con estado, monto, tipo y tarifas
`payment.refunds`	Devoluciones Pix	Registros de devoluciones con estado, monto y código de motivo
`dict.entries`	Entradas DICT	Registros de claves Pix

El plugin Pix no registra consultas al DICT actualmente. La tabla dict.entries almacena registros de claves, no consultas. Para ConsultasDict, obtenga esta métrica desde el monitoreo de infraestructura o logs del API gateway. El placeholder en la plantilla se incluye solo como referencia estructural.

| dict.claims | Reclamos DICT | Reclamos de portabilidad y titularidad |

El prefijo de la fuente de datos (por ejemplo, pix_btg) depende de cómo registres el plugin Pix en Reporter. Reemplázalo por el nombre real de tu fuente de datos.

Estructura de la tabla de transferencias

Campo	Tipo	Descripción
`id`	UUID	Identificador único de la transferencia
`status`	String	Estado de la transacción: `COMPLETED`, `REJECTED`, `PENDING`
`amount`	Decimal	Valor de la transacción en BRL
`transfer_type`	String	`CASHIN` (recepción) o `CASHOUT` (envío)
`destination_person_type`	String	`NATURAL_PERSON` o `LEGAL_PERSON`
`fee_charge`	JSONB	Estructura de tarifas (poblada solo en transacciones CASHIN)
`failed_reason`	String	Código del motivo de rechazo (cuando el estado es REJECTED)
`created_at`	Timestamp	Fecha y hora de creación

Estructura de la tabla de devoluciones

Campo	Tipo	Descripción
`id`	UUID	Identificador único de la devolución
`status`	String	Estado de la devolución: `COMPLETED`, `PENDING`
`amount`	Decimal	Valor de la devolución en BRL
`reason`	String	Código de motivo: `FR01`, `BE08`, `MD06`, `SL02`
`created_at`	Timestamp	Fecha y hora de creación

Códigos de motivo de devolución

Código	Significado	Tipo de detalle APIX
`FR01`	Fraude (MED — Mecanismo Especial de Devolución)	1
`BE08`	Error bancario	2
`MD06`	Solicitud del cliente	2
`SL02`	Servicio específico del acreedor (Pix Saque/Troco)	2

Estructura del cargo de tarifa (JSONB)

El campo fee_charge es una columna JSONB poblada solo para transacciones CASHIN (recepción):

{
  "applied": true,
  "calculationType": "FIXED",
  "totalAmount": "1.50",
  "netAmount": "98.50",
  "fees": [
    {
      "type": "TRANSACTION_FEE",
      "amount": "1.50"
    }
  ]
}

Las transacciones CASHOUT no tienen cargos de tarifa en el modelo de producto actual. Los ingresos provenientes de fuentes CASHOUT deben reportarse como cero, a menos que tu implementación cobre tarifas en transferencias salientes.

Mapeo de datos

Tipos de detalle de transacción

Código	Descripción	Mapeo
5	Participante indirecto (liquidado a través de participante directo)	Todas las transacciones completadas a través del socio liquidador
6	Participante directo (liquidación propia)	Cero para participantes indirectos
7	Rechazadas por indicio de fraude	Transacciones con `status == "REJECTED"` filtradas por motivo de fraude (ver aviso abajo)

El detalle tipo 7 debe contabilizar solo rechazos por indicio de fraude — no todas las transacciones rechazadas. La plantilla actual usa status == "REJECTED" como filtro simplificado. En producción, cruce con dict.infraction_reports (filtrando por situation_type de fraude) o aplique códigos específicos de failed_reason. Valide esta lógica con su equipo de ingeniería antes de enviar al BACEN.

Finalidades de transacción

Código	Descripción	Mapeo
1	Transferencia / Compra	Transacciones completadas (`status == "COMPLETED"`)
2	Pix Saque	Cero si no está implementado
3	Pix Troco	Cero si no está implementado
4	Pix Automático	Cero si no está implementado

El informe requiere exactamente 12 entradas de transacción — una por cada combinación de 3 tipos de detalle × 4 finalidades. Las entradas sin datos coincidentes deben aparecer igualmente con valores en cero.

Fuentes de ingresos

Fuente	Descripción	Mapeo
1	Iniciación por persona jurídica (CASHOUT)	`fee_charge.totalAmount` de CASHOUT + `LEGAL_PERSON`
2	Recepción por persona jurídica (CASHIN)	`fee_charge.totalAmount` de CASHIN + `LEGAL_PERSON`
3	Recepción por persona física (CASHIN)	`fee_charge.totalAmount` de CASHIN + `NATURAL_PERSON`
4	Iniciación por persona física (CASHOUT)	`fee_charge.totalAmount` de CASHOUT + `NATURAL_PERSON`

Tipos de detalle de devolución

Código	Descripción	Mapeo
1	Devolución por fraude (MED)	`reason == "FR01"`
2	Otros motivos	`reason != "FR01"` (BE08, MD06, SL02)

Tipos de detalle de bloqueo cautelar

Código	Descripción
1	Solicitado
2	Recibido
3	Cancelado por el solicitante
4	Cancelado por el receptor

Tipos de pagador en autorizaciones (Pix Automático)

Código	Descripción
1	Persona física
2	Persona jurídica

Uso de Reporter

A continuación se muestra la plantilla completa para generar el APIX 001 en Reporter. Este ejemplo utiliza pix_btg como prefijo de la fuente de datos — reemplázalo por el nombre configurado en tu fuente de datos de Reporter.

<?xml version="1.0" encoding="UTF-8"?>
<APIX001 DtArquivo="{% date_time 'YYYY-MM-dd' %}"
         Ano="{{ report_params.year }}"
         Mes="{{ report_params.month }}"
         ISPB="{{ midaz_onboarding.organization.0.legal_document|slice:':8' }}"
         NomeResp="{{ report_params.responsible_name }}"
         EmailResp="{{ report_params.responsible_email }}"
         TelResp="{{ report_params.responsible_phone }}"
         TipoEnvio="I">

    <Transacoes>
        <!-- Detail 5: Indirect participant — Purpose 1: Transfer/Purchase -->
        <Transacao>
            <QtdTransacoes>{% count_by pix_btg:payment.transfers if status == "COMPLETED" %}</QtdTransacoes>
            <ValorTransacoes>{% sum_by pix_btg:payment.transfers by "amount" if status == "COMPLETED" %}</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>5</DetalhamentoTransacoes>
            <FinalidadeTransacoes>1</FinalidadeTransacoes>
        </Transacao>

        <!-- Detail 5 — Purpose 2: Pix Saque -->
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>5</DetalhamentoTransacoes>
            <FinalidadeTransacoes>2</FinalidadeTransacoes>
        </Transacao>

        <!-- Detail 5 — Purpose 3: Pix Troco -->
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>5</DetalhamentoTransacoes>
            <FinalidadeTransacoes>3</FinalidadeTransacoes>
        </Transacao>

        <!-- Detail 5 — Purpose 4: Pix Automático -->
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>5</DetalhamentoTransacoes>
            <FinalidadeTransacoes>4</FinalidadeTransacoes>
        </Transacao>

        <!-- Detail 6: Direct participant (own settlement) -->
        <!-- Zero for indirect participants — no transactions settled directly -->
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>6</DetalhamentoTransacoes>
            <FinalidadeTransacoes>1</FinalidadeTransacoes>
        </Transacao>

        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>6</DetalhamentoTransacoes>
            <FinalidadeTransacoes>2</FinalidadeTransacoes>
        </Transacao>

        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>6</DetalhamentoTransacoes>
            <FinalidadeTransacoes>3</FinalidadeTransacoes>
        </Transacao>

        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>6</DetalhamentoTransacoes>
            <FinalidadeTransacoes>4</FinalidadeTransacoes>
        </Transacao>

        <!-- Detail 7: Rejected due to fraud indication -->
        <Transacao>
            <QtdTransacoes>{% count_by pix_btg:payment.transfers if status == "REJECTED" %}</QtdTransacoes>
            <ValorTransacoes>{% sum_by pix_btg:payment.transfers by "amount" if status == "REJECTED" %}</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>7</DetalhamentoTransacoes>
            <FinalidadeTransacoes>1</FinalidadeTransacoes>
        </Transacao>

        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>7</DetalhamentoTransacoes>
            <FinalidadeTransacoes>2</FinalidadeTransacoes>
        </Transacao>

        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>7</DetalhamentoTransacoes>
            <FinalidadeTransacoes>3</FinalidadeTransacoes>
        </Transacao>

        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>7</DetalhamentoTransacoes>
            <FinalidadeTransacoes>4</FinalidadeTransacoes>
        </Transacao>
    </Transacoes>

    <Devolucoes>
        <!-- Detail 1: Fraud refund (MED) — reason FR01 -->
        <Devolucao>
            <QtdDevolucoes>{% count_by pix_btg:payment.refunds if status == "COMPLETED" and reason == "FR01" %}</QtdDevolucoes>
            <ValorDevolucoes>{% sum_by pix_btg:payment.refunds by "amount" if status == "COMPLETED" and reason == "FR01" %}</ValorDevolucoes>
            <DetalhamentoDevolucoes>1</DetalhamentoDevolucoes>
        </Devolucao>

        <!-- Detail 2: Other refund reasons (BE08, MD06, SL02) -->
        <Devolucao>
            <QtdDevolucoes>{% count_by pix_btg:payment.refunds if status == "COMPLETED" and reason != "FR01" %}</QtdDevolucoes>
            <ValorDevolucoes>{% sum_by pix_btg:payment.refunds by "amount" if status == "COMPLETED" and reason != "FR01" %}</ValorDevolucoes>
            <DetalhamentoDevolucoes>2</DetalhamentoDevolucoes>
        </Devolucao>
    </Devolucoes>

    <BloqueiosCautelares>
        <!-- Cautionary blocks — report zeros when entity is not implemented -->
        <BloqueioCautelar>
            <QtdeBloqCaut>0</QtdeBloqCaut>
            <ValorBloqCaut>0.00</ValorBloqCaut>
            <DetalhamentoTransacoesBloqCaut>1</DetalhamentoTransacoesBloqCaut>
        </BloqueioCautelar>

        <BloqueioCautelar>
            <QtdeBloqCaut>0</QtdeBloqCaut>
            <ValorBloqCaut>0.00</ValorBloqCaut>
            <DetalhamentoTransacoesBloqCaut>2</DetalhamentoTransacoesBloqCaut>
        </BloqueioCautelar>

        <BloqueioCautelar>
            <QtdeBloqCaut>0</QtdeBloqCaut>
            <ValorBloqCaut>0.00</ValorBloqCaut>
            <DetalhamentoTransacoesBloqCaut>3</DetalhamentoTransacoesBloqCaut>
        </BloqueioCautelar>

        <BloqueioCautelar>
            <QtdeBloqCaut>0</QtdeBloqCaut>
            <ValorBloqCaut>0.00</ValorBloqCaut>
            <DetalhamentoTransacoesBloqCaut>4</DetalhamentoTransacoesBloqCaut>
        </BloqueioCautelar>
    </BloqueiosCautelares>

    <Receitas>
        <!-- Source 1: Initiation by legal person (CASHOUT) -->
        <Receita>
            <ValorReceita>0.00</ValorReceita>
            <FonteReceita>1</FonteReceita>
        </Receita>

        <!-- Source 2: Receiving by legal person (CASHIN) -->
        <Receita>
            <ValorReceita>{% sum_by pix_btg:payment.transfers by "fee_charge.totalAmount" if transfer_type == "CASHIN" and destination_person_type == "LEGAL_PERSON" and status == "COMPLETED" %}</ValorReceita>
            <FonteReceita>2</FonteReceita>
        </Receita>

        <!-- Source 3: Receiving by natural person (CASHIN) -->
        <Receita>
            <ValorReceita>{% sum_by pix_btg:payment.transfers by "fee_charge.totalAmount" if transfer_type == "CASHIN" and destination_person_type == "NATURAL_PERSON" and status == "COMPLETED" %}</ValorReceita>
            <FonteReceita>3</FonteReceita>
        </Receita>

        <!-- Source 4: Initiation by natural person (CASHOUT) -->
        <Receita>
            <ValorReceita>0.00</ValorReceita>
            <FonteReceita>4</FonteReceita>
        </Receita>
    </Receitas>

    <!-- Time metrics — must be sourced from your SPI/infrastructure monitoring -->
    <TemposTransacoes
        Perc50TempoExpUsuarioLiqSPI="0.00"
        Perc99TempoExpUsuarioLiqSPI="0.00"
        Perc50TempoExpUsuarioLiqForaSPI="0.00"
        Perc99TempoExpUsuarioLiqForaSPI="0.00"
        TempoMaxBloqueioCautelar="0.00" />

    <TemposDict
        Perc99TempoUsuarioConsulta="0.00"
        PercTempoEnvioRegistro="0.00"
        PercTempoExpUsuarioRegistro="0.00"
        PercTempoExpUsuarioExclusao="0.00"
        PercTempoNotificacaoPortabilidade="0.00"
        PercTempoEnvioPortabilidade="0.00"
        PercTempoAberturaMED="0.00" />

    <ConsultasDict QtdConsultas="{% count_by pix_btg:dict.entries %}" />

    <!--
      AVISO: dict.entries armazena registros de chaves Pix, não consultas ao DICT.
      Substitua pela fonte de dados real de consultas DICT ou popule manualmente
      a partir de métricas de infraestrutura.
    -->

    <Disponibilidade IndiceDisponibilidade="0.00" />

    <TempoAutorizacoes Perc95TempoAutorizacao="0.00" />

    <Autorizacoes>
        <!-- Pix Automático — report zeros when not implemented -->
        <Autorizacao>
            <QtdAutorizacoes>0</QtdAutorizacoes>
            <QtdEstoqueAutorizacoes>0</QtdEstoqueAutorizacoes>
            <TipoPagador>1</TipoPagador>
        </Autorizacao>

        <Autorizacao>
            <QtdAutorizacoes>0</QtdAutorizacoes>
            <QtdEstoqueAutorizacoes>0</QtdEstoqueAutorizacoes>
            <TipoPagador>2</TipoPagador>
        </Autorizacao>
    </Autorizacoes>

</APIX001>

Desglose del código

Elemento raíz

<APIX001 DtArquivo="{% date_time 'YYYY-MM-dd' %}"
         Ano="{{ report_params.year }}"
         Mes="{{ report_params.month }}"
         ISPB="{{ midaz_onboarding.organization.0.legal_document|slice:':8' }}"
         ...
         TipoEnvio="I">

DtArquivo: fecha de generación del archivo, insertada dinámicamente mediante date_time
Ano y Mes: año y mes de referencia, pasados como parámetros del informe
ISPB: primeros 8 dígitos del CNPJ de la institución, extraídos con el filtro slice desde los datos de onboarding de Midaz
TipoEnvio: I para inclusión, S para sustitución de datos previamente aprobados

Sección de transacciones

La plantilla declara explícitamente las 12 entradas requeridas (3 tipos de detalle × 4 finalidades). Se utilizan consultas dinámicas cuando hay datos disponibles:

<!-- Detail 5: Indirect participant — Purpose 1: Transfer/Purchase -->
<Transacao>
    <QtdTransacoes>{% count_by pix_btg:payment.transfers if status == "COMPLETED" %}</QtdTransacoes>
    <ValorTransacoes>{% sum_by pix_btg:payment.transfers by "amount" if status == "COMPLETED" %}</ValorTransacoes>
    <ValorEspecie>0.00</ValorEspecie>
    <DetalhamentoTransacoes>5</DetalhamentoTransacoes>
    <FinalidadeTransacoes>1</FinalidadeTransacoes>
</Transacao>

count_by cuenta los registros que cumplen la condición del filtro
sum_by ... by "field" suma un campo específico entre los registros coincidentes
ValorEspecie es 0.00 para transferencias estándar (solo distinto de cero para Pix Saque/Troco)

Las entradas para las finalidades 2, 3 y 4 (Pix Saque, Troco, Automático) usan ceros codificados cuando esas funciones no están implementadas. El tipo de detalle 6 (liquidación de participante directo) también usa ceros para participantes indirectos.

Sección de devoluciones

Las devoluciones se separan por código de motivo a través del campo reason:

<!-- Detail 1: Fraud refund (MED) -->
<Devolucao>
    <QtdDevolucoes>{% count_by pix_btg:payment.refunds if status == "COMPLETED" and reason == "FR01" %}</QtdDevolucoes>
    <ValorDevolucoes>{% sum_by pix_btg:payment.refunds by "amount" if status == "COMPLETED" and reason == "FR01" %}</ValorDevolucoes>
    <DetalhamentoDevolucoes>1</DetalhamentoDevolucoes>
</Devolucao>

<!-- Detail 2: Other reasons (BE08, MD06, SL02) -->
<Devolucao>
    <QtdDevolucoes>{% count_by pix_btg:payment.refunds if status == "COMPLETED" and reason != "FR01" %}</QtdDevolucoes>
    <ValorDevolucoes>{% sum_by pix_btg:payment.refunds by "amount" if status == "COMPLETED" and reason != "FR01" %}</ValorDevolucoes>
    <DetalhamentoDevolucoes>2</DetalhamentoDevolucoes>
</Devolucao>

FR01 se mapea al tipo de detalle 1 del BACEN (fraude vía MED)
Todos los demás códigos de motivo (BE08, MD06, SL02) se mapean al tipo de detalle 2

Sección de ingresos

Los ingresos se extraen del campo JSONB fee_charge.totalAmount, filtrando por tipo de transferencia y tipo de persona:

<!-- Source 2: Receiving by legal person (CASHIN) -->
<Receita>
    <ValorReceita>{% sum_by pix_btg:payment.transfers by "fee_charge.totalAmount" if transfer_type == "CASHIN" and destination_person_type == "LEGAL_PERSON" and status == "COMPLETED" %}</ValorReceita>
    <FonteReceita>2</FonteReceita>
</Receita>

El campo JSONB fee_charge utiliza sintaxis de ruta de campo anidada (fee_charge.totalAmount). El motor Pongo2 de Reporter recorre la estructura JSON para acceder al valor anidado.

Métricas de tiempo y disponibilidad

Las métricas de tiempo (tiempos de procesamiento de transacciones, tiempos de operación DICT) y el índice de disponibilidad deben obtenerse de tu sistema de monitoreo de infraestructura — no derivan de datos transaccionales. Completa estos valores a partir de tus logs del SPI y del monitoreo de uptime.

Consultas DICT

<ConsultasDict QtdConsultas="{% count_by pix_btg:dict.entries %}" />

    <!--
      AVISO: dict.entries armazena registros de chaves Pix, não consultas ao DICT.
      Substitua pela fonte de dados real de consultas DICT ou popule manualmente
      a partir de métricas de infraestrutura.
    -->

Este placeholder cuenta entradas DICT (registros de claves) como referencia estructural. En producción, reemplace dict.entries con la fuente de datos real de consultas al DICT o complete QtdConsultas manualmente desde métricas de infraestructura.

Ejemplo renderizado

<?xml version="1.0" encoding="UTF-8"?>
<APIX001 DtArquivo="2026-04-15"
         Ano="2026"
         Mes="3"
         ISPB="12345678"
         NomeResp="João Silva"
         EmailResp="joao.silva@institution.com.br"
         TelResp="11999998888"
         TipoEnvio="I">

    <Transacoes>
        <Transacao>
            <QtdTransacoes>150000</QtdTransacoes>
            <ValorTransacoes>75000000.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>5</DetalhamentoTransacoes>
            <FinalidadeTransacoes>1</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>5</DetalhamentoTransacoes>
            <FinalidadeTransacoes>2</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>5</DetalhamentoTransacoes>
            <FinalidadeTransacoes>3</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>5</DetalhamentoTransacoes>
            <FinalidadeTransacoes>4</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>6</DetalhamentoTransacoes>
            <FinalidadeTransacoes>1</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>6</DetalhamentoTransacoes>
            <FinalidadeTransacoes>2</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>6</DetalhamentoTransacoes>
            <FinalidadeTransacoes>3</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>6</DetalhamentoTransacoes>
            <FinalidadeTransacoes>4</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>320</QtdTransacoes>
            <ValorTransacoes>160000.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>7</DetalhamentoTransacoes>
            <FinalidadeTransacoes>1</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>7</DetalhamentoTransacoes>
            <FinalidadeTransacoes>2</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>7</DetalhamentoTransacoes>
            <FinalidadeTransacoes>3</FinalidadeTransacoes>
        </Transacao>
        <Transacao>
            <QtdTransacoes>0</QtdTransacoes>
            <ValorTransacoes>0.00</ValorTransacoes>
            <ValorEspecie>0.00</ValorEspecie>
            <DetalhamentoTransacoes>7</DetalhamentoTransacoes>
            <FinalidadeTransacoes>4</FinalidadeTransacoes>
        </Transacao>
    </Transacoes>

    <Devolucoes>
        <Devolucao>
            <QtdDevolucoes>45</QtdDevolucoes>
            <ValorDevolucoes>22500.00</ValorDevolucoes>
            <DetalhamentoDevolucoes>1</DetalhamentoDevolucoes>
        </Devolucao>
        <Devolucao>
            <QtdDevolucoes>230</QtdDevolucoes>
            <ValorDevolucoes>115000.00</ValorDevolucoes>
            <DetalhamentoDevolucoes>2</DetalhamentoDevolucoes>
        </Devolucao>
    </Devolucoes>

    <BloqueiosCautelares>
        <BloqueioCautelar>
            <QtdeBloqCaut>0</QtdeBloqCaut>
            <ValorBloqCaut>0.00</ValorBloqCaut>
            <DetalhamentoTransacoesBloqCaut>1</DetalhamentoTransacoesBloqCaut>
        </BloqueioCautelar>
        <BloqueioCautelar>
            <QtdeBloqCaut>0</QtdeBloqCaut>
            <ValorBloqCaut>0.00</ValorBloqCaut>
            <DetalhamentoTransacoesBloqCaut>2</DetalhamentoTransacoesBloqCaut>
        </BloqueioCautelar>
        <BloqueioCautelar>
            <QtdeBloqCaut>0</QtdeBloqCaut>
            <ValorBloqCaut>0.00</ValorBloqCaut>
            <DetalhamentoTransacoesBloqCaut>3</DetalhamentoTransacoesBloqCaut>
        </BloqueioCautelar>
        <BloqueioCautelar>
            <QtdeBloqCaut>0</QtdeBloqCaut>
            <ValorBloqCaut>0.00</ValorBloqCaut>
            <DetalhamentoTransacoesBloqCaut>4</DetalhamentoTransacoesBloqCaut>
        </BloqueioCautelar>
    </BloqueiosCautelares>

    <Receitas>
        <Receita>
            <ValorReceita>0.00</ValorReceita>
            <FonteReceita>1</FonteReceita>
        </Receita>
        <Receita>
            <ValorReceita>85000.00</ValorReceita>
            <FonteReceita>2</FonteReceita>
        </Receita>
        <Receita>
            <ValorReceita>12000.00</ValorReceita>
            <FonteReceita>3</FonteReceita>
        </Receita>
        <Receita>
            <ValorReceita>0.00</ValorReceita>
            <FonteReceita>4</FonteReceita>
        </Receita>
    </Receitas>

    <TemposTransacoes
        Perc50TempoExpUsuarioLiqSPI="1.20"
        Perc99TempoExpUsuarioLiqSPI="4.50"
        Perc50TempoExpUsuarioLiqForaSPI="2.30"
        Perc99TempoExpUsuarioLiqForaSPI="8.10"
        TempoMaxBloqueioCautelar="0.00" />

    <TemposDict
        Perc99TempoUsuarioConsulta="0.80"
        PercTempoEnvioRegistro="1.50"
        PercTempoExpUsuarioRegistro="2.00"
        PercTempoExpUsuarioExclusao="1.80"
        PercTempoNotificacaoPortabilidade="3.00"
        PercTempoEnvioPortabilidade="2.50"
        PercTempoAberturaMED="5.00" />

    <ConsultasDict QtdConsultas="500000" />

    <Disponibilidade IndiceDisponibilidade="99.85" />

    <TempoAutorizacoes Perc95TempoAutorizacao="0.00" />

    <Autorizacoes>
        <Autorizacao>
            <QtdAutorizacoes>0</QtdAutorizacoes>
            <QtdEstoqueAutorizacoes>0</QtdEstoqueAutorizacoes>
            <TipoPagador>1</TipoPagador>
        </Autorizacao>
        <Autorizacao>
            <QtdAutorizacoes>0</QtdAutorizacoes>
            <QtdEstoqueAutorizacoes>0</QtdEstoqueAutorizacoes>
            <TipoPagador>2</TipoPagador>
        </Autorizacao>
    </Autorizacoes>

</APIX001>

Ejemplo de solicitud con filtro de fecha

Para generar el APIX 001 de un mes específico, envía una solicitud POST /v1/reports con el encabezado X-Organization-Id y el siguiente cuerpo:

{
  "templateId": "APIX_001_TEMPLATE_ID",
  "filters": {
    "pix_btg": {
      "payment.transfers": {
        "created_at": {
          "between": ["2026-03-01T00:00:00Z", "2026-03-31T23:59:59Z"]
        }
      },
      "payment.refunds": {
        "created_at": {
          "between": ["2026-03-01T00:00:00Z", "2026-03-31T23:59:59Z"]
        }
      }
    }
  }
}

Campo	Descripción
`templateId`	Identificador de la plantilla APIX 001 registrada en Reporter
`filters.pix_btg.payment.transfers`	Filtro de fecha para la colección de transferencias
`filters.pix_btg.payment.refunds`	Filtro de fecha para la colección de devoluciones
`created_at.between`	Filtra los registros creados dentro del mes especificado

Las fechas deben estar en formato ISO 8601 con zona horaria UTC (Z). Asegúrate de cubrir todo el mes de referencia — desde el primer hasta el último segundo.

Reglas de validación XSD

Restricciones clave del XSD oficial APIX 001 (versión 2.5) que tus datos deben cumplir:

Campo	Restricción
Valores monetarios	Hasta 15 dígitos en total, 2 decimales, mínimo 0
Cantidades	Entero, mínimo 0, máximo 999.999.999.999
Valores de tiempo	Hasta 8 dígitos en total, 2 decimales, 0–999.999 segundos
Disponibilidad	Porcentaje, 0,00–100,00
ISPB	Exactamente 8 dígitos numéricos
Entradas de transacción	Exactamente 12 (3 tipos de detalle × 4 finalidades)
Entradas de devolución	Exactamente 2
Entradas de bloqueo cautelar	Exactamente 4
Entradas de ingresos	Exactamente 4
Entradas de autorización	Exactamente 2

El BACEN valida tanto la estructura como la cardinalidad. Si tu informe tiene menos o más entradas de las esperadas en cualquier sección, el envío será rechazado.

Buenas prácticas

Entradas con valor cero

Aunque no haya transacciones para una combinación dada, la entrada debe seguir apareciendo en el informe con valores en cero. El BACEN exige las 12 entradas de transacción, las 4 entradas de ingresos, las 4 entradas de bloqueo cautelar y las 2 entradas de autorización — independientemente de si existen datos.

Envíos de sustitución

Usa TipoEnvio="S" solamente para sustituir un envío previamente aprobado. Si tu primer envío fue rechazado, vuelve a enviarlo con TipoEnvio="I".

Precisión de valores

Todos los valores monetarios deben tener exactamente 2 decimales. Usa las funciones de formato de Reporter o asegúrate de que tu fuente de datos entregue valores ya formateados.

Origen de las métricas de tiempo

Los percentiles de tiempo de transacción y los tiempos de operación DICT deben provenir de tu monitoreo de infraestructura — no de datos transaccionales. Estas métricas reflejan la experiencia real del usuario desde la iniciación del pago hasta la confirmación de la liquidación. El BACEN puede auditar estos valores contra los logs del SPI.

Campos anidados en JSONB

Los cálculos de ingresos utilizan rutas de campo anidadas (por ejemplo, fee_charge.totalAmount) para acceder a valores dentro de columnas JSONB. Asegúrate de que tu versión de Reporter admita el análisis de campos anidados en funciones de agregación.

Valida siempre el XML renderizado contra el XSD oficial del BACEN antes del envío. Puedes descargar el esquema desde el portal de documentos regulatorios del BACEN.

Resumen

Guías

Console

¿Qué es APIX 001?

Qué espera recibir el BACEN

Requisitos de envío

Atributos del encabezado

Comprender la estructura de datos

Fuentes de datos del plugin Pix

Estructura de la tabla de transferencias

Estructura de la tabla de devoluciones

Códigos de motivo de devolución

Estructura del cargo de tarifa (JSONB)

Mapeo de datos

Tipos de detalle de transacción

Finalidades de transacción

Fuentes de ingresos

Tipos de detalle de devolución

Tipos de detalle de bloqueo cautelar

Tipos de pagador en autorizaciones (Pix Automático)

Uso de Reporter

Desglose del código

Elemento raíz

Sección de transacciones

Sección de devoluciones

Sección de ingresos

Métricas de tiempo y disponibilidad

Consultas DICT

Ejemplo renderizado

Ejemplo de solicitud con filtro de fecha

Reglas de validación XSD

Buenas prácticas

Entradas con valor cero

Envíos de sustitución

Precisión de valores

Origen de las métricas de tiempo

Campos anidados en JSONB

​¿Qué es APIX 001?

​Qué espera recibir el BACEN

​Requisitos de envío

​Atributos del encabezado

​Comprender la estructura de datos

​Fuentes de datos del plugin Pix

​Estructura de la tabla de transferencias

​Estructura de la tabla de devoluciones

​Códigos de motivo de devolución

​Estructura del cargo de tarifa (JSONB)

​Mapeo de datos

​Tipos de detalle de transacción

​Finalidades de transacción

​Fuentes de ingresos

​Tipos de detalle de devolución

​Tipos de detalle de bloqueo cautelar

​Tipos de pagador en autorizaciones (Pix Automático)

​Uso de Reporter

​Desglose del código

​Elemento raíz

​Sección de transacciones

​Sección de devoluciones

​Sección de ingresos

​Métricas de tiempo y disponibilidad

​Consultas DICT

​Ejemplo renderizado

​Ejemplo de solicitud con filtro de fecha

​Reglas de validación XSD

​Buenas prácticas

​Entradas con valor cero

​Envíos de sustitución

​Precisión de valores

​Origen de las métricas de tiempo

​Campos anidados en JSONB

¿Qué es APIX 001?

Qué espera recibir el BACEN

Requisitos de envío

Atributos del encabezado

Comprender la estructura de datos

Fuentes de datos del plugin Pix

Estructura de la tabla de transferencias

Estructura de la tabla de devoluciones

Códigos de motivo de devolución

Estructura del cargo de tarifa (JSONB)

Mapeo de datos

Tipos de detalle de transacción

Finalidades de transacción

Fuentes de ingresos

Tipos de detalle de devolución

Tipos de detalle de bloqueo cautelar

Tipos de pagador en autorizaciones (Pix Automático)

Uso de Reporter

Desglose del código

Elemento raíz

Sección de transacciones

Sección de devoluciones

Sección de ingresos

Métricas de tiempo y disponibilidad

Consultas DICT

Ejemplo renderizado

Ejemplo de solicitud con filtro de fecha

Reglas de validación XSD

Buenas prácticas

Entradas con valor cero

Envíos de sustitución

Precisión de valores

Origen de las métricas de tiempo

Campos anidados en JSONB