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

# Preparar o relatório APIX001 com o Pix Lerian

> Declare os participantes que você liquida, registre os fatos que só a sua instituição conhece, feche um mês em um relatório imutável e leia-o.

O APIX001 é o relatório mensal de estatísticas do Pix que a sua instituição envia ao Banco Central. O Pix Lerian ajuda a montar os dados dele. Ele não monta o arquivo XML e não envia o relatório.

As rotas estão no SPI, em `/spi/v1/regulatory`. Cada mês passa por estes passos:

1. **Declare os participantes indiretos que você liquida.** [`POST /regulatory/apix/settled-participants`](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/declare-an-indirect-participant-the-tenant-settles) inicia uma declaração a partir de `validFrom`. [`POST /regulatory/apix/settled-participants/{settled_participant_id}/end`](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/end-a-declaration) a encerra em `validTo`, o último dia em que ela vale. Envie a `version` atual da declaração. Um `validTo` um dia antes de `validFrom` anula a declaração.
2. **Registre os fatos que só a sua instituição conhece.** [`POST /regulatory/apix/facts/{fact_type}`](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/record-a-fact-only-the-participant-knows) registra a versão 1 de um fato. [`POST /regulatory/apix/facts/{fact_type}/{client_request_id}/correct`](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/correct-a-recorded-fact-new-version) registra uma nova versão. A versão anterior permanece.
3. **Feche o mês.** [`POST /regulatory/apix001/close`](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/close-a-reference-month-into-an-immutable-report) congela o relatório de um mês que terminou.
4. **Leia o relatório.** [`GET /regulatory/apix001/report?period=YYYY-MM`](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/get-the-apix001-report-of-a-closed-reference-month) devolve o relatório de um mês fechado.
5. **Altere um mês fechado.** [`POST /regulatory/apix001/reopen`](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/reopen-a-closed-reference-month) volta o mês para aberto. Os fatos e as declarações registrados depois do fechamento entram então no próximo fechamento.

Toda escrita exige `X-Idempotency`. Os meses estão no horário de America/Sao\_Paulo.

## Fatos que você registra

***

`fact_type` no caminho seleciona o corpo, e o `factType` do corpo deve ter o mesmo valor. Estes tipos são aceitos:

| `factType` | O que registra |
| - | - |
| `OUTSIDE_SPI_SETTLEMENT` | Um Pix que a sua instituição liquidou fora do SPI. |
| `OUTSIDE_SPI_REFUND` | Uma devolução que a sua instituição liquidou fora do SPI. O `reasonCode` dela deve ser `FR01`, `MD06`, `SL02` ou `BE08`. |
| `OUTBOUND_FRAUD_REFUSAL` | Um Pix enviado que a sua instituição recusou por fraude. |
| `DICT_SCREEN_STEP` | Uma etapa de uma triagem do DICT. |

Qualquer outro tipo é recusado. Cada fato tem um `clientRequestId` que você escolhe. O mesmo `clientRequestId` com o mesmo conteúdo não cria nada e responde o fato já registrado. O mesmo `clientRequestId` com outro conteúdo é `409` com `PIX-0717`: corrija o fato. Um novo `clientRequestId` para um assunto que já tem um fato atual do mesmo tipo é `409` com `PIX-0725`.

Um fato de um mês fechado é aceito. Ele entra em um relatório somente depois de uma reabertura e de um novo fechamento.

Registrar e corrigir um fato é limitado a 2 chamadas em andamento por tenant em cada instância que atende. Acima desse limite, a chamada responde `429` com `PIX-0006` e um header `Retry-After`, e não registra nada. Envie uma carga retroativa uma chamada por vez.

## O fechamento

***

O fechamento fixa um corte 60 segundos antes de um instante que ele lê do relógio do banco de dados. Um fato, uma correção ou uma declaração que você registra menos de 60 segundos antes da primeira tentativa do fechamento está depois do corte. O relatório o deixa de fora, e ele só conta depois de uma reabertura e de um novo fechamento. Todo reenvio do mesmo fechamento reutiliza o corte.

* Só um mês que terminou pode ser fechado. Um mês futuro é `422` com `PIX-0710`, e o mês atual é `422` com `PIX-0713`.
* Um mês que já está fechado responde o relatório atual com `200`.
* Um fechamento que roda com outra chave `X-Idempotency` responde `409` com `PIX-0712` e um header `Retry-After`. Envie de novo a mesma requisição depois desse tempo.
* Cada instância que atende calcula um fechamento por tenant de cada vez. Quando o espaço está ocupado, a chamada responde `429` com `PIX-0006` e um header `Retry-After`.

O fechamento lê `DATABASE_READ_REPLICA` por um pool próprio, com no máximo 4 conexões por pod. Quando `DATABASE_READ_REPLICA` está vazio, ele lê `DATABASE_URL`. A réplica deve ser um standby físico do banco de dados do SPI. Um nó que não está em recuperação responde `503` com `PIX-0727`. Um standby que não aplicou todos os commits até o corte responde `503` com `PIX-0715` e um header `Retry-After`. Nada é congelado, e o mês continua aberto.

## O relatório

***

O relatório tem os dez blocos do layout do APIX001, para o ISPB do seu tenant. Todo bloco e todo indicador carrega `coverage`, então um `0.00` que é preenchimento não é um zero medido. Um bloco que o Pix Lerian não calcula volta `UNAVAILABLE` com um motivo.

| Bloco | De onde vêm os dados |
| - | - |
| `transactions` | As liquidações fora do SPI e as recusas que você registrou como fatos. |
| `refunds` | As devoluções fora do SPI que você registrou como fatos. |
| `transactionTimes` | As transferências do SPI e as liquidações que a sua instituição pagou. |
| `dictLookups` e o indicador `p99KeyLookupTime` | As consultas de chave que o Pix Lerian registrou nas iniciações por chave e por QR code. A cobertura delas é sempre `PARTIAL` ou `UNAVAILABLE`. |

Todo outro bloco e todo outro indicador é `UNAVAILABLE`.

Um mês que nunca foi fechado, ou que foi reaberto e não foi fechado de novo, responde `404` com `PIX-0711`.

## Permissões

***

As rotas agem para o tenant inteiro, e nenhuma rota recebe uma conta.

| Permissão | Ação | Rotas | Papéis |
| - | - | - | - |
| `apix-facts` | `post` | Registrar e corrigir um fato. | `editor`, `contributor` |
| `apix-periods` | `post` | Fechar e reabrir um mês. | `editor` |
| `apix-reports` | `get` | Ler um relatório. | `editor`, `contributor`, `viewer` |
| `apix-settled-participants` | `post` | Declarar e encerrar uma declaração. | `editor` |

No BYOC, só a declaração de permissões do SPI concede estas permissões: veja [Permissões que só a declaração do SPI concede](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-spi.md#permissions-that-only-the-spi-declaration-grants).

## Erros

***

| Código | Status | O que significa |
| - | - | - |
| `PIX-0710` | 422 | O mês de referência ainda não começou. |
| `PIX-0711` | 404 | O mês não tem relatório fechado. Feche-o antes. |
| `PIX-0712` | 409 | Outro fechamento deste mês está rodando. |
| `PIX-0713` | 422 | O mês atual só pode ser fechado depois que terminar. |
| `PIX-0714` | 409 | O mês não está fechado, então não há nada a reabrir. |
| `PIX-0715` | 503 | A réplica de leitura não alcançou o corte. Nada foi congelado. Tente de novo mais tarde. |
| `PIX-0717` | 409 | Este `clientRequestId` já está registrado com conteúdo diferente. |
| `PIX-0718` | 404 | Nenhum fato deste tipo tem este `clientRequestId`. |
| `PIX-0719` | 422 | A declaração não é válida: por exemplo, ela cita o ISPB do tenant, a sua vigência se sobrepõe a outra declaração do mesmo ISPB, ou o seu fim é mais de um dia anterior ao seu início. |
| `PIX-0722` | 404 | Nenhuma declaração tem este id. |
| `PIX-0723` | 422 | O corpo não corresponde ao caminho. |
| `PIX-0724` | 422 | O Pix Lerian não aceita este tipo de fato. |
| `PIX-0725` | 409 | Outro fato atual deste tipo cobre o mesmo assunto. |
| `PIX-0726` | 422 | O código de motivo da devolução não é `FR01`, `MD06`, `SL02` nem `BE08`. |
| `PIX-0727` | 503 | Nenhum pool de leitura do APIX está configurado, ou a réplica de leitura não é um standby em recuperação. |
| `PIX-0728` | 409 | A declaração não está na versão que você enviou. Envie a versão atual dela. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.