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