Skip to main content
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 starts a declaration from validFrom. POST /regulatory/apix/settled-participants/{settled_participant_id}/end 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} records version 1 of a fact. POST /regulatory/apix/facts/{fact_type}/{client_request_id}/correct records a new version. The previous version stays.
  3. Close the month. POST /regulatory/apix001/close freezes the report of a month that has ended.
  4. Read the report. GET /regulatory/apix001/report?period=YYYY-MM returns the report of a closed month.
  5. Change a closed month. POST /regulatory/apix001/reopen 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: 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. 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. In BYOC, only the SPI permission declaration grants these permissions: see Permissions that only the SPI declaration grants.

Errors