APIX 001

O Reporter permite gerar relatórios em XML que seguem a estrutura oficial APIX, exigida pelo Banco Central do Brasil (BACEN). Este guia apresenta a estrutura e a lógica utilizadas para gerar o relatório APIX 001 (Documento 1201) em XML.

Os relatórios APIX 001 devem seguir rigorosamente o esquema XSD definido pelo BACEN (versão 2.5). O Reporter automatiza a geração do XML, mas você continua responsável por validar a saída e garantir a conformidade com os requisitos regulatórios.

O que é o APIX 001?

O APIX 001 é um relatório regulatório mensal que os participantes do Pix — diretos ou indiretos — devem enviar ao Banco Central do Brasil. Ele consolida as estatísticas operacionais do ecossistema Pix da instituição em um determinado mês.

O que o BACEN espera receber

O relatório abrange dez seções de dados:

Seção	Descrição
Transacoes	Volumes e valores de transações, detalhados por tipo de detalhamento e finalidade
Devolucoes	Volumes e valores de devoluções (MED e outros motivos)
BloqueiosCautelares	Quantidades e valores de bloqueios cautelares
Receitas	Receitas de operações Pix por fonte e tipo de pessoa
TemposTransacoes	Percentis de tempo de processamento de transações (P50, P99)
TemposDict	Percentis de tempo de operações DICT (consultas, registros, portabilidade)
ConsultasDict	Total de consultas DICT no período
Disponibilidade	Índice de disponibilidade do sistema (percentual)
TempoAutorizacoes	Tempo de processamento de autorizações (P95)
Autorizacoes	Quantidade e estoque de autorizações de Pix Automático por tipo de pagador

Requisitos de envio

Documento	Frequência	Prazo	Referência
APIX 001	Mensal	15.º dia útil do mês seguinte	Documento 1201, XSD versão 2.5

Atributos do cabeçalho

O elemento raiz <APIX001> exige estes atributos:

Atributo	Descrição	Formato
`DtArquivo`	Data de geração do arquivo	`YYYY-MM-DD`
`Ano`	Ano de referência	`YYYY`
`Mes`	Mês de referência	`1`–`12`
`ISPB`	Código ISPB da instituição (primeiros 8 dígitos do CNPJ)	8 dígitos numéricos
`NomeResp`	Nome do responsável	Texto (máx. 200 caracteres)
`EmailResp`	E-mail do responsável	E-mail válido
`TelResp`	Telefone do responsável	Texto (máx. 14 caracteres)
`TipoEnvio`	Tipo de envio	`I` (Inclusão) ou `S` (Substituição)

Entendendo a estrutura de dados

Antes de construir o template, é importante entender como os dados do plugin Pix se mapeiam para cada seção do APIX 001.

Fontes de dados do plugin Pix

O template consulta dados das tabelas do plugin Pix registradas como fontes de dados no Reporter. As principais entidades utilizadas são:

Fonte de dados	Tabela	Conteúdo
`payment.transfers`	Transferências Pix	Registros de transações com status, valor, tipo e tarifas
`payment.refunds`	Devoluções Pix	Registros de devoluções com status, valor e código de motivo
`dict.entries`	Entradas DICT	Registros de chaves Pix
`dict.claims`	Reivindicações DICT	Reivindicações de portabilidade e titularidade

O plugin Pix não rastreia consultas ao DICT atualmente. A tabela dict.entries armazena registros de chaves, não consultas. Para ConsultasDict, obtenha essa métrica a partir do monitoramento de infraestrutura ou logs do API gateway. O placeholder no template é incluso apenas como referência estrutural.

O prefixo da fonte de dados (por exemplo, pix_btg) depende de como você registra o plugin Pix no Reporter. Substitua-o pelo nome real da sua fonte de dados.

Estrutura da tabela de transferências

Campo	Tipo	Descrição
`id`	UUID	Identificador único da transferência
`status`	String	Status da transação: `COMPLETED`, `REJECTED`, `PENDING`
`amount`	Decimal	Valor da transação em BRL
`transfer_type`	String	`CASHIN` (recebimento) ou `CASHOUT` (envio)
`destination_person_type`	String	`NATURAL_PERSON` ou `LEGAL_PERSON`
`fee_charge`	JSONB	Estrutura de tarifas (preenchida apenas em transações CASHIN)
`failed_reason`	String	Código do motivo de rejeição (quando o status é REJECTED)
`created_at`	Timestamp	Data e hora de criação

Estrutura da tabela de devoluções

Campo	Tipo	Descrição
`id`	UUID	Identificador único da devolução
`status`	String	Status da devolução: `COMPLETED`, `PENDING`
`amount`	Decimal	Valor da devolução em BRL
`reason`	String	Código do motivo: `FR01`, `BE08`, `MD06`, `SL02`
`created_at`	Timestamp	Data e hora de criação

Códigos de motivo de devolução

Código	Significado	Tipo de detalhamento APIX
`FR01`	Fraude (MED — Mecanismo Especial de Devolução)	1
`BE08`	Erro bancário	2
`MD06`	Solicitação do cliente	2
`SL02`	Serviço específico do credor (Pix Saque/Troco)	2

Estrutura do encargo de tarifa (JSONB)

O campo fee_charge é uma coluna JSONB preenchida apenas para transações CASHIN (recebimento):

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

As transações CASHOUT não possuem encargos de tarifa no modelo atual do produto. As receitas provenientes de fontes CASHOUT devem ser reportadas como zero, a menos que sua implementação cobre tarifas em transferências de saída.

Mapeamento de dados

Tipos de detalhamento de transação

Código	Descrição	Mapeamento
5	Participante indireto (liquidado via participante direto)	Todas as transações concluídas via parceiro liquidante
6	Participante direto (liquidação própria)	Zero para participantes indiretos
7	Rejeitadas por indício de fraude	Transações com `status == "REJECTED"` filtradas por motivo de fraude (veja aviso abaixo)

O detalhamento 7 deve contabilizar apenas rejeições por indício de fraude — não todas as transações rejeitadas. O template atual usa status == "REJECTED" como filtro simplificado. Em produção, cruze com dict.infraction_reports (filtrando por situation_type de fraude) ou aplique códigos específicos de failed_reason. Valide essa lógica com sua equipe de engenharia antes de enviar ao BACEN.

Finalidades de transação

Código	Descrição	Mapeamento
1	Transferência / Compra	Transações concluídas (`status == "COMPLETED"`)
2	Pix Saque	Zero se não implementado
3	Pix Troco	Zero se não implementado
4	Pix Automático	Zero se não implementado

O relatório exige exatamente 12 entradas de transação — uma para cada combinação de 3 tipos de detalhamento × 4 finalidades. Entradas sem dados correspondentes ainda devem aparecer com valores zero.

Fontes de receita

Fonte	Descrição	Mapeamento
1	Iniciação por pessoa jurídica (CASHOUT)	`fee_charge.totalAmount` de CASHOUT + `LEGAL_PERSON`
2	Recebimento por pessoa jurídica (CASHIN)	`fee_charge.totalAmount` de CASHIN + `LEGAL_PERSON`
3	Recebimento por pessoa física (CASHIN)	`fee_charge.totalAmount` de CASHIN + `NATURAL_PERSON`
4	Iniciação por pessoa física (CASHOUT)	`fee_charge.totalAmount` de CASHOUT + `NATURAL_PERSON`

Tipos de detalhamento de devolução

Código	Descrição	Mapeamento
1	Devolução por fraude (MED)	`reason == "FR01"`
2	Outros motivos	`reason != "FR01"` (BE08, MD06, SL02)

Tipos de detalhamento de bloqueio cautelar

Código	Descrição
1	Solicitado
2	Recebido
3	Cancelado pelo solicitante
4	Cancelado pelo receptor

Tipos de pagador em autorizações (Pix Automático)

Código	Descrição
1	Pessoa física
2	Pessoa jurídica

Usando o Reporter

Abaixo está o template completo para gerar o APIX 001 no Reporter. Este exemplo usa pix_btg como prefixo da fonte de dados — substitua pelo nome configurado na sua fonte de dados do 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>

Detalhamento do código

Elemento raiz

<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: data de geração do arquivo, inserida dinamicamente via date_time
Ano e Mes: ano e mês de referência, passados como parâmetros do relatório
ISPB: primeiros 8 dígitos do CNPJ da instituição, extraídos com o filtro slice a partir dos dados de onboarding do Midaz
TipoEnvio: I para inclusão, S para substituição de dados previamente aprovados

Seção de transações

O template declara explicitamente todas as 12 entradas obrigatórias (3 tipos de detalhamento × 4 finalidades). Consultas dinâmicas são utilizadas onde existem dados:

<!-- 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 conta os registros que correspondem à condição do filtro
sum_by ... by "field" soma um campo específico entre os registros correspondentes
ValorEspecie é 0.00 para transferências padrão (somente diferente de zero para Pix Saque/Troco)

As entradas para as finalidades 2, 3 e 4 (Pix Saque, Troco, Automático) usam zeros fixos quando essas funcionalidades não estão implementadas. O tipo de detalhamento 6 (liquidação de participante direto) também usa zeros para participantes indiretos.

Seção de devoluções

As devoluções são separadas pelo código de motivo por meio do 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 é mapeado para o tipo de detalhamento 1 do BACEN (fraude via MED)
Todos os demais códigos de motivo (BE08, MD06, SL02) são mapeados para o tipo de detalhamento 2

Seção de receitas

As receitas são extraídas do campo JSONB fee_charge.totalAmount, filtradas por tipo de transferência e tipo de pessoa:

<!-- 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>

O campo JSONB fee_charge utiliza sintaxe de caminho de campo aninhado (fee_charge.totalAmount). O motor Pongo2 do Reporter percorre a estrutura JSON para acessar o valor aninhado.

Métricas de tempo e disponibilidade

As métricas de tempo (tempos de processamento de transações, tempos de operação DICT) e o índice de disponibilidade devem vir do seu sistema de monitoramento de infraestrutura — não são derivados de dados transacionais. Preencha esses valores a partir dos seus logs do SPI e do monitoramento 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 conta entradas DICT (registros de chaves) como referência estrutural. Em produção, substitua dict.entries pela fonte de dados real de consultas ao DICT ou popule QtdConsultas manualmente a partir de métricas de infraestrutura.

Exemplo 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>

Exemplo de requisição com filtro de data

Para gerar o APIX 001 de um mês específico, envie uma requisição POST /v1/reports com o cabeçalho X-Organization-Id e o seguinte corpo:

{
  "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	Descrição
`templateId`	Identificador do template APIX 001 registrado no Reporter
`filters.pix_btg.payment.transfers`	Filtro de data para a coleção de transferências
`filters.pix_btg.payment.refunds`	Filtro de data para a coleção de devoluções
`created_at.between`	Filtra os registros criados dentro do mês especificado

As datas devem estar no formato ISO 8601 com fuso horário UTC (Z). Garanta que todo o mês de referência seja coberto — do primeiro ao último segundo.

Regras de validação XSD

Restrições essenciais do XSD oficial do APIX 001 (versão 2.5) que seus dados precisam atender:

Campo	Restrição
Valores monetários	Até 15 dígitos no total, 2 casas decimais, mínimo 0
Quantidades	Inteiro, mínimo 0, máximo 999.999.999.999
Valores de tempo	Até 8 dígitos no total, 2 casas decimais, 0–999.999 segundos
Disponibilidade	Percentual, 0,00–100,00
ISPB	Exatamente 8 dígitos numéricos
Entradas de transação	Exatamente 12 (3 tipos de detalhamento × 4 finalidades)
Entradas de devolução	Exatamente 2
Entradas de bloqueio cautelar	Exatamente 4
Entradas de receita	Exatamente 4
Entradas de autorização	Exatamente 2

O BACEN valida tanto a estrutura quanto a cardinalidade. Se o seu relatório tiver menos ou mais entradas do que o esperado em qualquer seção, o envio será rejeitado.

Boas práticas

Entradas com valor zero

Mesmo quando não há transações para uma combinação específica, a entrada deve aparecer no relatório com valores zero. O BACEN exige todas as 12 entradas de transação, todas as 4 entradas de receita, todas as 4 entradas de bloqueio cautelar e todas as 2 entradas de autorização — independentemente da existência de dados.

Envios de substituição

Use TipoEnvio="S" apenas para substituir um envio previamente aprovado. Se o seu primeiro envio foi rejeitado, reenvie com TipoEnvio="I".

Precisão dos valores

Todos os valores monetários devem ter exatamente 2 casas decimais. Use os recursos de formatação do Reporter ou garanta que sua fonte de dados forneça valores já formatados.

Origem das métricas de tempo

Os percentis de tempo de transação e os tempos de operação DICT devem vir do seu monitoramento de infraestrutura — não de dados transacionais. Essas métricas refletem a experiência real do usuário desde a iniciação do pagamento até a confirmação da liquidação. O BACEN pode auditar esses valores em comparação com os logs do SPI.

Campos aninhados em JSONB

Os cálculos de receita usam caminhos de campo aninhados (por exemplo, fee_charge.totalAmount) para acessar valores dentro de colunas JSONB. Garanta que sua versão do Reporter suporte a leitura de campos aninhados em funções de agregação.

Sempre valide o XML renderizado contra o XSD oficial do BACEN antes do envio. Você pode baixar o esquema no portal de documentos regulatórios do BACEN.

Introdução

Exemplos de templates

Templates brasileiros

O que é o APIX 001?

O que o BACEN espera receber

Requisitos de envio

Atributos do cabeçalho

Entendendo a estrutura de dados

Fontes de dados do plugin Pix

Estrutura da tabela de transferências

Estrutura da tabela de devoluções

Códigos de motivo de devolução

Estrutura do encargo de tarifa (JSONB)

Mapeamento de dados

Tipos de detalhamento de transação

Finalidades de transação

Fontes de receita

Tipos de detalhamento de devolução

Tipos de detalhamento de bloqueio cautelar

Tipos de pagador em autorizações (Pix Automático)

Usando o Reporter

Detalhamento do código

Elemento raiz

Seção de transações

Seção de devoluções

Seção de receitas

Métricas de tempo e disponibilidade

Consultas DICT

Exemplo renderizado

Exemplo de requisição com filtro de data

Regras de validação XSD

Boas práticas

Entradas com valor zero

Envios de substituição

Precisão dos valores

Origem das métricas de tempo

Campos aninhados em JSONB

Introdução

Exemplos de templates

Templates brasileiros

Documentation Index

​O que é o APIX 001?

​O que o BACEN espera receber

​Requisitos de envio

​Atributos do cabeçalho

​Entendendo a estrutura de dados

​Fontes de dados do plugin Pix

​Estrutura da tabela de transferências

​Estrutura da tabela de devoluções

​Códigos de motivo de devolução

​Estrutura do encargo de tarifa (JSONB)

​Mapeamento de dados

​Tipos de detalhamento de transação

​Finalidades de transação

​Fontes de receita

​Tipos de detalhamento de devolução

​Tipos de detalhamento de bloqueio cautelar

​Tipos de pagador em autorizações (Pix Automático)

​Usando o Reporter

​Detalhamento do código

​Elemento raiz

​Seção de transações

​Seção de devoluções

​Seção de receitas

​Métricas de tempo e disponibilidade

​Consultas DICT

​Exemplo renderizado

​Exemplo de requisição com filtro de data

​Regras de validação XSD

​Boas práticas

​Entradas com valor zero

​Envios de substituição

​Precisão dos valores

​Origem das métricas de tempo

​Campos aninhados em JSONB

O que é o APIX 001?

O que o BACEN espera receber

Requisitos de envio

Atributos do cabeçalho

Entendendo a estrutura de dados

Fontes de dados do plugin Pix

Estrutura da tabela de transferências

Estrutura da tabela de devoluções

Códigos de motivo de devolução

Estrutura do encargo de tarifa (JSONB)

Mapeamento de dados

Tipos de detalhamento de transação

Finalidades de transação

Fontes de receita

Tipos de detalhamento de devolução

Tipos de detalhamento de bloqueio cautelar

Tipos de pagador em autorizações (Pix Automático)

Usando o Reporter

Detalhamento do código

Elemento raiz

Seção de transações

Seção de devoluções

Seção de receitas

Métricas de tempo e disponibilidade

Consultas DICT

Exemplo renderizado

Exemplo de requisição com filtro de data

Regras de validação XSD

Boas práticas

Entradas com valor zero

Envios de substituição

Precisão dos valores

Origem das métricas de tempo

Campos aninhados em JSONB