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

# APIX 001

> Gere o relatório APIX-001 do Banco Central do Brasil no Reporter, cumprindo a exigência mensal com dados consolidados e formato validado.

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.

<Danger>
  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.
</Danger>

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

<Warning>
  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.
</Warning>

<Note>
  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.
</Note>

### 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):

```json theme={null}
{
  "applied": true,
  "calculationType": "FIXED",
  "totalAmount": "1.50",
  "netAmount": "98.50",
  "fees": [
    {
      "type": "TRANSACTION_FEE",
      "amount": "1.50"
    }
  ]
}
```

<Warning>
  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.
</Warning>

## 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) |

<Warning>
  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.
</Warning>

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

<Info>
  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.
</Info>

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

<Warning>
  A requisição de relatório do Reporter (`POST /v1/reports`) aceita apenas `templateId` e `filters` — não existe entrada para parâmetros arbitrários de template. Defina o ano e o mês de referência (`Ano`, `Mes`) e os dados do responsável (`NomeResp`, `EmailResp`, `TelResp`) diretamente no template antes de cada envio, da mesma forma que `TipoEnvio` é definido.
</Warning>

<CodeGroup>
  ```tpl Template theme={null}
  <?xml version="1.0" encoding="UTF-8"?>
  <APIX001 DtArquivo="{% date_time 'YYYY-MM-dd' %}"
           Ano="2026"
           Mes="3"
           ISPB="{{ midaz_onboarding.organization.0.legal_document|slice:':8' }}"
           NomeResp="João Silva"
           EmailResp="joao.silva@institution.com.br"
           TelResp="11999998888"
           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>
  ```
</CodeGroup>

## Detalhamento do código

***

### Elemento raiz

```tpl theme={null}
<APIX001 DtArquivo="{% date_time 'YYYY-MM-dd' %}"
         Ano="2026"
         Mes="3"
         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 — valores estáticos que você atualiza no template antes de cada envio (a requisição de relatório não transporta parâmetros de template)
* `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:

```tpl theme={null}
<!-- 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`:

```tpl theme={null}
<!-- 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:

```tpl theme={null}
<!-- 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>
```

<Info>
  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.
</Info>

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

```tpl theme={null}
<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 theme={null}
<?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 seguinte corpo:

<CodeGroup>
  ```json Request theme={null}
  {
    "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"]
          }
        }
      }
    }
  }
  ```
</CodeGroup>

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

<Info>
  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.
</Info>

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

<Warning>
  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.
</Warning>

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

<Warning>
  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.
</Warning>