Saltar al contenido principal

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.

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ónDescripción
TransacoesVolúmenes y valores de transacciones, desglosados por tipo de detalle y finalidad
DevolucoesVolúmenes y valores de devoluciones (MED y otros motivos)
BloqueiosCautelaresCantidad y valores de bloqueos cautelares
ReceitasIngresos derivados de operaciones Pix por fuente y tipo de persona
TemposTransacoesPercentiles de tiempo de procesamiento de transacciones (P50, P99)
TemposDictPercentiles de tiempo de operaciones DICT (consultas, registros, portabilidad)
ConsultasDictTotal de consultas DICT en el período
DisponibilidadeÍndice de disponibilidad del sistema (porcentaje)
TempoAutorizacoesTiempo de procesamiento de autorizaciones (P95)
AutorizacoesCantidad y stock de autorizaciones de Pix Automático por tipo de pagador

Requisitos de envío

DocumentoFrecuenciaPlazoReferencia
APIX 001Mensual15.º día hábil del mes siguienteDocumento 1201, XSD versión 2.5

Atributos del encabezado

El elemento raíz <APIX001> requiere estos atributos:
AtributoDescripciónFormato
DtArquivoFecha de generación del archivoYYYY-MM-DD
AnoAño de referenciaYYYY
MesMes de referencia112
ISPBCódigo ISPB de la institución (primeros 8 dígitos del CNPJ)8 dígitos numéricos
NomeRespNombre del responsableTexto (máx. 200 caracteres)
EmailRespCorreo del responsableCorreo válido
TelRespTeléfono del responsableTexto (máx. 14 caracteres)
TipoEnvioTipo de envíoI (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 datosTablaContenido
payment.transfersTransferencias PixRegistros de transacciones con estado, monto, tipo y tarifas
payment.refundsDevoluciones PixRegistros de devoluciones con estado, monto y código de motivo
dict.entriesEntradas DICTRegistros 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

CampoTipoDescripción
idUUIDIdentificador único de la transferencia
statusStringEstado de la transacción: COMPLETED, REJECTED, PENDING
amountDecimalValor de la transacción en BRL
transfer_typeStringCASHIN (recepción) o CASHOUT (envío)
destination_person_typeStringNATURAL_PERSON o LEGAL_PERSON
fee_chargeJSONBEstructura de tarifas (poblada solo en transacciones CASHIN)
failed_reasonStringCódigo del motivo de rechazo (cuando el estado es REJECTED)
created_atTimestampFecha y hora de creación

Estructura de la tabla de devoluciones

CampoTipoDescripción
idUUIDIdentificador único de la devolución
statusStringEstado de la devolución: COMPLETED, PENDING
amountDecimalValor de la devolución en BRL
reasonStringCódigo de motivo: FR01, BE08, MD06, SL02
created_atTimestampFecha y hora de creación

Códigos de motivo de devolución

CódigoSignificadoTipo de detalle APIX
FR01Fraude (MED — Mecanismo Especial de Devolución)1
BE08Error bancario2
MD06Solicitud del cliente2
SL02Servicio 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ódigoDescripciónMapeo
5Participante indirecto (liquidado a través de participante directo)Todas las transacciones completadas a través del socio liquidador
6Participante directo (liquidación propia)Cero para participantes indirectos
7Rechazadas por indicio de fraudeTransacciones 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ódigoDescripciónMapeo
1Transferencia / CompraTransacciones completadas (status == "COMPLETED")
2Pix SaqueCero si no está implementado
3Pix TrocoCero si no está implementado
4Pix AutomáticoCero 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

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

Tipos de detalle de devolución

CódigoDescripciónMapeo
1Devolución por fraude (MED)reason == "FR01"
2Otros motivosreason != "FR01" (BE08, MD06, SL02)

Tipos de detalle de bloqueo cautelar

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

Tipos de pagador en autorizaciones (Pix Automático)

CódigoDescripción
1Persona física
2Persona 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"]
        }
      }
    }
  }
}
CampoDescripción
templateIdIdentificador de la plantilla APIX 001 registrada en Reporter
filters.pix_btg.payment.transfersFiltro de fecha para la colección de transferencias
filters.pix_btg.payment.refundsFiltro de fecha para la colección de devoluciones
created_at.betweenFiltra 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:
CampoRestricción
Valores monetariosHasta 15 dígitos en total, 2 decimales, mínimo 0
CantidadesEntero, mínimo 0, máximo 999.999.999.999
Valores de tiempoHasta 8 dígitos en total, 2 decimales, 0–999.999 segundos
DisponibilidadPorcentaje, 0,00–100,00
ISPBExactamente 8 dígitos numéricos
Entradas de transacciónExactamente 12 (3 tipos de detalle × 4 finalidades)
Entradas de devoluciónExactamente 2
Entradas de bloqueo cautelarExactamente 4
Entradas de ingresosExactamente 4
Entradas de autorizaciónExactamente 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.