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

# Prepare the APIX001 report with Pix Lerian

> Declare the participants you settle for, record the facts only your institution knows, close a month into an immutable report, and read it.

APIX001 is the monthly Pix statistics report that your institution sends to the Central Bank. Pix Lerian helps you build its data. It does not build the XML file, and it does not send the report.

The routes are in the SPI, under `/spi/v1/regulatory`. Each month goes through these steps:

1. **Declare the indirect participants that you settle for.** [`POST /regulatory/apix/settled-participants`](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/declare-an-indirect-participant-the-tenant-settles) starts a declaration from `validFrom`. [`POST /regulatory/apix/settled-participants/{settled_participant_id}/end`](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/end-a-declaration) ends it on `validTo`, the last day it is in force. Send the current `version` of the declaration. A `validTo` one day before `validFrom` voids the declaration.
2. **Record the facts that only your institution knows.** [`POST /regulatory/apix/facts/{fact_type}`](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/record-a-fact-only-the-participant-knows) records version 1 of a fact. [`POST /regulatory/apix/facts/{fact_type}/{client_request_id}/correct`](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/correct-a-recorded-fact-new-version) records a new version. The previous version stays.
3. **Close the month.** [`POST /regulatory/apix001/close`](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/close-a-reference-month-into-an-immutable-report) freezes the report of a month that has ended.
4. **Read the report.** [`GET /regulatory/apix001/report?period=YYYY-MM`](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/get-the-apix001-report-of-a-closed-reference-month) returns the report of a closed month.
5. **Change a closed month.** [`POST /regulatory/apix001/reopen`](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/reopen-a-closed-reference-month) moves the month back to open. The facts and the declarations recorded after the close then enter the next close.

Every write needs `X-Idempotency`. The months are in America/Sao\_Paulo time.

## Facts that you record

***

`fact_type` in the path selects the body, and the `factType` of the body must have the same value. These types are accepted:

| `factType` | What it records |
| - | - |
| `OUTSIDE_SPI_SETTLEMENT` | A Pix that your institution settled outside SPI. |
| `OUTSIDE_SPI_REFUND` | A refund that your institution settled outside SPI. Its `reasonCode` must be `FR01`, `MD06`, `SL02` or `BE08`. |
| `OUTBOUND_FRAUD_REFUSAL` | A sent Pix that your institution refused for fraud. |
| `DICT_SCREEN_STEP` | One step of a DICT screen. |

Any other type is refused. Each fact has a `clientRequestId` that you choose. The same `clientRequestId` with the same content creates nothing and answers the fact already recorded. The same `clientRequestId` with other content is `409` with `PIX-0717`: correct the fact instead. A new `clientRequestId` for a subject that already has a current fact of the same type is `409` with `PIX-0725`.

A fact for a closed month is accepted. It enters a report only after a reopen and a new close.

Recording and correcting a fact is limited to 2 calls in flight for each tenant on each serving instance. Above that limit, the call answers `429` with `PIX-0006` and a `Retry-After` header, and records nothing. Send a backfill one call at a time.

## The close

***

The close fixes a cutoff 60 seconds before an instant that it reads from the database clock. A fact, a correction or a declaration that you record less than 60 seconds before the first attempt of the close is after the cutoff. The report leaves it out, and it counts only after a reopen and a new close. Every resend of the same close reuses the cutoff.

* Only a month that has ended can be closed. A future month is `422` with `PIX-0710`, and the current month is `422` with `PIX-0713`.
* A month that is already closed answers its current report with `200`.
* A close that runs under another `X-Idempotency` key answers `409` with `PIX-0712` and a `Retry-After` header. Send the same request again after that time.
* Each serving instance computes one close for each tenant at a time. When the slot is busy, the call answers `429` with `PIX-0006` and a `Retry-After` header.

The close reads `DATABASE_READ_REPLICA` through a pool of its own, with at most 4 connections for each pod. When `DATABASE_READ_REPLICA` is empty, it reads `DATABASE_URL`. The replica must be a physical standby of the SPI database. A node that is not in recovery answers `503` with `PIX-0727`. A standby that has not applied every commit up to the cutoff answers `503` with `PIX-0715` and a `Retry-After` header. Nothing is frozen, and the month stays open.

## The report

***

The report has the ten blocks of the APIX001 layout, for the ISPB of your tenant. Every block and every indicator carries `coverage`, so a `0.00` that is a filler is not a measured zero. A block that Pix Lerian does not compute comes back `UNAVAILABLE` with a reason.

| Block | Where the data comes from |
| - | - |
| `transactions` | The settlements outside SPI and the refusals that you recorded as facts. |
| `refunds` | The refunds outside SPI that you recorded as facts. |
| `transactionTimes` | The transfers of the SPI, and the settlements that your institution paid. |
| `dictLookups` and the `p99KeyLookupTime` indicator | The key lookups that Pix Lerian recorded on key and QR code initiations. Their coverage is always `PARTIAL` or `UNAVAILABLE`. |

Every other block and every other indicator is `UNAVAILABLE`.

A month that was never closed, or that was reopened and not closed again, answers `404` with `PIX-0711`.

## Permissions

***

The routes act for the whole tenant, and no route takes an account.

| Permission | Action | Routes | Roles |
| - | - | - | - |
| `apix-facts` | `post` | Record and correct a fact. | `editor`, `contributor` |
| `apix-periods` | `post` | Close and reopen a month. | `editor` |
| `apix-reports` | `get` | Read a report. | `editor`, `contributor`, `viewer` |
| `apix-settled-participants` | `post` | Declare and end a declaration. | `editor` |

In BYOC, only the SPI permission declaration grants these permissions: see [Permissions that only the SPI declaration grants](https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-spi.md#permissions-that-only-the-spi-declaration-grants).

## Errors

***

| Code | Status | What it means |
| - | - | - |
| `PIX-0710` | 422 | The reference month has not started. |
| `PIX-0711` | 404 | The month has no closed report. Close it first. |
| `PIX-0712` | 409 | Another close of this month is running. |
| `PIX-0713` | 422 | The current month can be closed only after it ends. |
| `PIX-0714` | 409 | The month is not closed, so there is nothing to reopen. |
| `PIX-0715` | 503 | The read replica has not reached the cutoff. Nothing was frozen. Retry later. |
| `PIX-0717` | 409 | This `clientRequestId` is already recorded with different content. |
| `PIX-0718` | 404 | No fact of this type has this `clientRequestId`. |
| `PIX-0719` | 422 | The declaration is not valid: for example, it names the ISPB of the tenant, its validity overlaps another declaration of the same ISPB, or its end is more than one day before its start. |
| `PIX-0722` | 404 | No declaration has this id. |
| `PIX-0723` | 422 | The body does not match the path. |
| `PIX-0724` | 422 | Pix Lerian does not accept this fact type. |
| `PIX-0725` | 409 | Another current fact of this type covers the same subject. |
| `PIX-0726` | 422 | The refund reason code is not `FR01`, `MD06`, `SL02` or `BE08`. |
| `PIX-0727` | 503 | No APIX read pool is configured, or the read replica is not a standby in recovery. |
| `PIX-0728` | 409 | The declaration is not at the version that you sent. Send its current version. |


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