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

# Cómo funciona Lerian SPI

> La secuencia de habilitación, los flujos de envío y recepción, las devoluciones, las claves y reivindicaciones de DICT, los cobros BR Code, Pix Automático y las disputas MED que componen la superficie de mensajería de Pix.

Lerian SPI expone la superficie de mensajería de Pix como un conjunto de operaciones tipadas. Cada flujo persiste su trabajo antes de despachar, devuelve un estado aceptado-pero-no-liquidado y reconcilia contra la respuesta asíncrona del BACEN.

## Habilitación y disponibilidad

***

Un participante se registra por su ISPB y se activa antes de poder operar. La disponibilidad luego se ejecuta en un orden obligatorio, y un envío intentado antes de que pase es rechazado.

1. **Sube** un certificado Pix —solo el `.cer` público—. Una clave privada subida es rechazada.
2. Confirma que el riel reporta que está listo (`ready`).
3. Pasa una **prueba de conectividad**.
4. Los envíos ya están permitidos.

Los participantes se suspenden y se dan de baja a lo largo de su ciclo de vida a través de la misma superficie Core.

## Enviar un Pix

***

Creas una orden de pago; la plataforma construye el mensaje ISO 20022 de transferencia de crédito (`pacs.008`), persiste la operación y la despacha. El BACEN devuelve un callback de estado asíncrono (`pacs.002`) que el riel valida y aplica, moviendo el pago a `settled` o `rejected`. Un pago se lee por su end-to-end ID, junto con su historial y una línea de tiempo por operación.

## Recibir un Pix

***

El BACEN publica un callback XML `pacs.008` firmado para un Pix entrante. El riel valida la firma, aplica el pago y devuelve una respuesta `pacs.002` firmada. Los participantes listan los Pix que han recibido.

## Devolución

***

Sobre un pago liquidado, inicias una devolución (`pacs.004`) como subrecurso de la operación padre, y luego lees el estado de la devolución. Una devolución es la vía de movimiento de dinero de MED —la forma en que los fondos regresan a un pagador por una disputa completada o un error.

## Ciclo de vida de las claves DICT

***

Las claves Pix se gestionan directamente contra el directorio DICT: registrar, listar, buscar, consultar, actualizar y eliminar una clave, y verificar por lote si un conjunto de claves existe. El riel también lee las estadísticas de claves de DICT y las estadísticas antifraude del BACEN, tanto por clave como por persona.

## Reivindicaciones de DICT

***

Una reivindicación mueve una clave Pix entre participantes por portabilidad o titularidad. Inicias una reivindicación contra un participante y luego la mueves por su ciclo de vida —acknowledge, confirmar o rechazar, completar o cancelar— entre los lados donante y reclamante. Los plazos de las reivindicaciones se procesan automáticamente para que ninguna se estanque más allá de su ventana del BACEN.

## BR Code y cobros

***

Un QR siempre apunta a un cobro, así que creas el cobro primero y luego generas el payload que resuelve a él.

* Crea un cobro: **Cob** (inmediato), **CobV** (con vencimiento, con intereses y multa) o un **lote** de cobros con vencimiento.
* Genera el payload **QR EMV dinámico**, que enlaza al cobro por su txid o localizador y resuelve como un JWS firmado.

La generación de QR estático, la decodificación, la validación y el registro del perfil del receptor (recebedor) también forman parte de la superficie.

## Pix Automático (recurrente)

***

Pix Automático autoriza pagos recurrentes y programados a través de la familia recurrente de ISO 20022:

* **Crea** una autorización recurrente (recorrência) o una solicitud de una, que lleva un QR compuesto.
* **Confirma** el mandato (`pain.009`), **cancélalo** (`pain.011`) o **acéptalo / recházalo** (`pain.012`).
* **Programa** una instrucción (`pain.013`) y **acéptala / recházala** (`pain.014`).
* **Solicita la cancelación** de una instrucción programada (`camt.055`) y **resuelve** una cancelación recibida (`camt.029`).
* **Solicita un reintento de liquidación** (retentativa) cuando un cobro programado falla.

## Disputas MED

***

La superficie MED (Mecanismo Especial de Devolución) tramita casos de fraude y error de extremo a extremo:

* **Abre** un caso MED, **analízalo** y luego **resuélvelo**, **ciérralo** o **cancélalo** con evidencia adjunta.
* Presenta **reportes de infracción**, **solicitudes de devolución**, **marcas de fraude** y solicitudes de **recuperación de fondos** de DICT, cada una rastreada a lo largo de su grafo de ciclo de vida.
* Reporta los Pix liquidados internamente mediante el reporte de liquidación de MED 2.0.

## Reporte de la Conta PI

***

Solicitas un reporte de cuenta (`camt.060`) y luego lees el resultado de saldo, extracto o asientos que devuelve el BACEN (`camt.052` / `camt.053` / `camt.054`). Los reportes síncronos de volumetria (solo conteo), pagos rechazados, saldo y extracto completan la superficie de reporte, cada uno acotado a su período de referencia.
