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

# Integración con Lerian SPI

> Los callbacks entrantes del BACEN, el backbone dirigido por eventos, el punto de contacto con el ledger Midaz y las convenciones de API para construir sobre Lerian SPI.

Lerian SPI está dirigido por eventos. Las operaciones y los cambios de liquidación fluyen como eventos de dominio sobre el backbone de streaming de la plataforma, de modo que los sistemas dependientes de la plataforma reaccionan a los cambios de estado sin sondeo. El riel nativo **no tiene consumidores de webhook orientados al cliente** —su coordinación es interna a la plataforma.

## Entrante desde el BACEN

***

El BACEN publica callbacks XML ISO 20022 firmados sobre la RSFN —un mensaje de transferencia de crédito (`pacs.008`) para un Pix entrante, una respuesta de estado (`pacs.002`) para un pago que enviaste y un mensaje de devolución (`pacs.004`) para una devolución—. El riel valida la firma de cada callback antes de aplicarlo y devuelve una respuesta firmada donde el protocolo lo requiere. Un pago que envías permanece abierto hasta que llega su `pacs.002` y lo mueve a `settled` o `rejected`, con los campos del BACEN proyectados literalmente.

## Flujo de eventos

***

Cada contexto del riel publica y consume los eventos que le pertenecen:

* El contexto **BR Code** publica eventos de cobro y los eventos de la familia recurrente (Pix Automático), y consume eventos de liquidación para cerrar un cobro una vez que su Pix se liquida.
* El contexto **Core** consume eventos de confirmación de participante y eventos de finalización y terminación de liquidación, manteniendo el estado de participantes y operaciones en sincronía con el BACEN.

## Punto de contacto con Midaz

***

La liquidación se registra en el ledger **Midaz**. Lerian SPI no mantiene ninguna posición contable propia —reconcilia su estado consumiendo eventos de liquidación de Midaz, de modo que la vista del riel sobre un pago y los asientos del ledger se mantienen alineados. El riel transporta el mensaje y su estado de liquidación; Midaz registra el dinero.

## Convenciones de API

***

* **La autenticación** sigue el esquema estándar de token bearer de la plataforma.
* **Los pagos se direccionan por end-to-end ID.** Un pago, su historial y su línea de tiempo de operación se leen por E2EID.
* **Las devoluciones son subrecursos.** Una devolución se crea y se lee bajo el pago padre que revierte, de modo que una devolución siempre está atada a una operación liquidada.
* **Los callbacks entrantes se validan por firma.** Un callback que falla la validación de firma no se aplica.