Saltar al contenido principal
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 inicia una declaración desde validFrom. POST /regulatory/apix/settled-participants/{settled_participant_id}/end 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} registra la versión 1 de un hecho. POST /regulatory/apix/facts/{fact_type}/{client_request_id}/correct registra una nueva versión. La versión anterior permanece.
  3. Cierra el mes. POST /regulatory/apix001/close congela el informe de un mes que terminó.
  4. Lee el informe. GET /regulatory/apix001/report?period=YYYY-MM devuelve el informe de un mes cerrado.
  5. Cambia un mes cerrado. POST /regulatory/apix001/reopen 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: 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. 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. En BYOC, solo la declaración de permisos de SPI concede estos permisos: consulta Permisos que solo concede la declaración de SPI.

Errores