> ## 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 el informe APIX001 con Pix Lerian

> Declara los participantes que liquidas, registra los hechos que solo tu institución conoce, cierra un mes en un informe inmutable y léelo.

El APIX001 es el informe mensual de estadísticas de Pix que tu institución envía al Banco Central. Pix Lerian ayuda a armar sus datos. No arma el archivo XML y no envía el informe.

Las rutas están en el SPI, bajo `/spi/v1/regulatory`. Cada mes pasa por estos pasos:

1. **Declara los participantes indirectos que liquidas.** [`POST /regulatory/apix/settled-participants`](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/declare-an-indirect-participant-the-tenant-settles) inicia una declaración desde `validFrom`. [`POST /regulatory/apix/settled-participants/{settled_participant_id}/end`](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/end-a-declaration) la termina en `validTo`, el último día en que rige. Envía la `version` actual de la declaración. Un `validTo` un día antes de `validFrom` anula la declaración.
2. **Registra los hechos que solo tu institución conoce.** [`POST /regulatory/apix/facts/{fact_type}`](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/record-a-fact-only-the-participant-knows) registra la versión 1 de un hecho. [`POST /regulatory/apix/facts/{fact_type}/{client_request_id}/correct`](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/correct-a-recorded-fact-new-version) registra una nueva versión. La versión anterior permanece.
3. **Cierra el mes.** [`POST /regulatory/apix001/close`](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/close-a-reference-month-into-an-immutable-report) congela el informe de un mes que terminó.
4. **Lee el informe.** [`GET /regulatory/apix001/report?period=YYYY-MM`](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/get-the-apix001-report-of-a-closed-reference-month) devuelve el informe de un mes cerrado.
5. **Cambia un mes cerrado.** [`POST /regulatory/apix001/reopen`](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/reopen-a-closed-reference-month) vuelve el mes a abierto. Los hechos y las declaraciones registrados después del cierre entran entonces en el siguiente cierre.

Toda escritura exige `X-Idempotency`. Los meses están en horario de America/Sao\_Paulo.

## Hechos que registras

***

`fact_type` en la ruta selecciona el cuerpo, y el `factType` del cuerpo debe tener el mismo valor. Se aceptan estos tipos:

| `factType` | Qué registra |
| - | - |
| `OUTSIDE_SPI_SETTLEMENT` | Un Pix que tu institución liquidó fuera del SPI. |
| `OUTSIDE_SPI_REFUND` | Una devolución que tu institución liquidó fuera del SPI. Su `reasonCode` debe ser `FR01`, `MD06`, `SL02` o `BE08`. |
| `OUTBOUND_FRAUD_REFUSAL` | Un Pix enviado que tu institución rechazó por fraude. |
| `DICT_SCREEN_STEP` | Un paso de una verificación del DICT. |

Cualquier otro tipo se rechaza. Cada hecho tiene un `clientRequestId` que tú eliges. El mismo `clientRequestId` con el mismo contenido no crea nada y responde el hecho ya registrado. El mismo `clientRequestId` con otro contenido es `409` con `PIX-0717`: corrige el hecho. Un nuevo `clientRequestId` para un asunto que ya tiene un hecho actual del mismo tipo es `409` con `PIX-0725`.

Un hecho de un mes cerrado se acepta. Entra en un informe solo después de una reapertura y de un nuevo cierre.

Registrar y corregir un hecho está limitado a 2 llamadas en curso por tenant en cada instancia que atiende. Por encima de ese límite, la llamada responde `429` con `PIX-0006` y un header `Retry-After`, y no registra nada. Envía una carga retroactiva una llamada a la vez.

## El cierre

***

El cierre fija un corte 60 segundos antes de un instante que lee del reloj de la base de datos. Un hecho, una corrección o una declaración que registras menos de 60 segundos antes del primer intento del cierre queda después del corte. El informe lo deja fuera, y solo cuenta después de una reapertura y de un nuevo cierre. Todo reenvío del mismo cierre reutiliza el corte.

* Solo se puede cerrar un mes que terminó. Un mes futuro es `422` con `PIX-0710`, y el mes actual es `422` con `PIX-0713`.
* Un mes que ya está cerrado responde el informe actual con `200`.
* Un cierre que corre con otra clave `X-Idempotency` responde `409` con `PIX-0712` y un header `Retry-After`. Envía de nuevo la misma solicitud después de ese tiempo.
* Cada instancia que atiende calcula un cierre por tenant a la vez. Cuando el espacio está ocupado, la llamada responde `429` con `PIX-0006` y un header `Retry-After`.

El cierre lee `DATABASE_READ_REPLICA` por un pool propio, con como máximo 4 conexiones por pod. Cuando `DATABASE_READ_REPLICA` está vacío, lee `DATABASE_URL`. La réplica debe ser un standby físico de la base de datos del SPI. Un nodo que no está en recuperación responde `503` con `PIX-0727`. Un standby que no aplicó todos los commits hasta el corte responde `503` con `PIX-0715` y un header `Retry-After`. No se congela nada, y el mes sigue abierto.

## El informe

***

El informe tiene los diez bloques del layout del APIX001, para el ISPB de tu tenant. Todo bloque y todo indicador lleva `coverage`, así que un `0.00` que es relleno no es un cero medido. Un bloque que Pix Lerian no calcula vuelve `UNAVAILABLE` con un motivo.

| Bloque | De dónde vienen los datos |
| - | - |
| `transactions` | Las liquidaciones fuera del SPI y los rechazos que registraste como hechos. |
| `refunds` | Las devoluciones fuera del SPI que registraste como hechos. |
| `transactionTimes` | Las transferencias del SPI y las liquidaciones que tu institución pagó. |
| `dictLookups` y el indicador `p99KeyLookupTime` | Las consultas de clave que Pix Lerian registró en las iniciaciones por clave y por código QR. Su cobertura es siempre `PARTIAL` o `UNAVAILABLE`. |

Todo otro bloque y todo otro indicador es `UNAVAILABLE`.

Un mes que nunca se cerró, o que se reabrió y no se cerró de nuevo, responde `404` con `PIX-0711`.

## Permisos

***

Las rutas actúan para el tenant completo, y ninguna ruta recibe una cuenta.

| Permiso | Acción | Rutas | Roles |
| - | - | - | - |
| `apix-facts` | `post` | Registrar y corregir un hecho. | `editor`, `contributor` |
| `apix-periods` | `post` | Cerrar y reabrir un mes. | `editor` |
| `apix-reports` | `get` | Leer un informe. | `editor`, `contributor`, `viewer` |
| `apix-settled-participants` | `post` | Declarar y terminar una declaración. | `editor` |

En BYOC, solo la declaración de permisos de SPI concede estos permisos: consulta [Permisos que solo concede la declaración de SPI](https://docs.lerian.studio/es/interfaces/pix-lerian/pix-lerian-spi.md#permissions-that-only-the-spi-declaration-grants).

## Errores

***

| Código | Estado | Qué significa |
| - | - | - |
| `PIX-0710` | 422 | El mes de referencia aún no empezó. |
| `PIX-0711` | 404 | El mes no tiene informe cerrado. Ciérralo antes. |
| `PIX-0712` | 409 | Otro cierre de este mes está en ejecución. |
| `PIX-0713` | 422 | El mes actual solo puede cerrarse cuando termine. |
| `PIX-0714` | 409 | El mes no está cerrado, así que no hay nada que reabrir. |
| `PIX-0715` | 503 | La réplica de lectura no alcanzó el corte. No se congeló nada. Reintenta más tarde. |
| `PIX-0717` | 409 | Este `clientRequestId` ya está registrado con contenido distinto. |
| `PIX-0718` | 404 | Ningún hecho de este tipo tiene este `clientRequestId`. |
| `PIX-0719` | 422 | La declaración no es válida: por ejemplo, nombra el ISPB del tenant, su vigencia se superpone con otra declaración del mismo ISPB, o su fin es más de un día anterior a su inicio. |
| `PIX-0722` | 404 | Ninguna declaración tiene este id. |
| `PIX-0723` | 422 | El cuerpo no coincide con la ruta. |
| `PIX-0724` | 422 | Pix Lerian no acepta este tipo de hecho. |
| `PIX-0725` | 409 | Otro hecho actual de este tipo cubre el mismo asunto. |
| `PIX-0726` | 422 | El código de motivo de la devolución no es `FR01`, `MD06`, `SL02` ni `BE08`. |
| `PIX-0727` | 503 | No hay un pool de lectura del APIX configurado, o la réplica de lectura no es un standby en recuperación. |
| `PIX-0728` | 409 | La declaración no está en la versión que enviaste. Envía su versión actual. |


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