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

# Integrating with Lerian SPI

> Integrating with Lerian SPI: BACEN's ISO 20022 messages, streaming events, ledger integration, and API conventions for Pix.

Lerian SPI is event-driven. Operations and settlement changes flow as domain events on the platform's streaming backbone. Downstream systems react to these changes without polling. The native rail has no client-facing webhook consumers. Its coordination is internal to the platform.

## Inbound from BACEN

***

The ICOM consumer receives signed ISO 20022 messages from BACEN over the RSFN and passes them to the rail's authenticated internal ingress. A credit-transfer message (`pacs.008`) carries an inbound Pix. A status reply (`pacs.002`) reports a payment you sent. A return message (`pacs.004`) carries a devolução.

The rail validates each inbound message before it applies it. An outbound payment stays open until its `pacs.002` arrives; that reply applies `COMPLETED` or `REJECTED`. An inbound `pacs.008` is recorded pending and is completed or refused by the authenticated client's funding decision. The rail records BACEN's fields verbatim.

## Event flow

***

Each context on the rail publishes and consumes the events it owns:

* The **BR Code** context publishes charge events and the recurring-family (Pix Automático) events. It consumes settlement events to close a charge after its Pix settles.
* The **Core** context consumes participant-confirmation events and settlement completion and termination events. It keeps participant and operation state in step with BACEN.

## Ledger integration

***

Lerian SPI holds no accounting position of its own. The rail emits settlement events on the streaming backbone, and your ledger consumer records the corresponding position. The rail relays each settled value verbatim. Each settlement event carries a stable `ce-id` that identifies the settlement; delivery is at-least-once, so your ledger consumer must deduplicate redeliveries by `ce-id`.

## API conventions

***

* **Auth** follows the platform's standard bearer-token scheme.
* **Payments carry an end-to-end ID.** You read a payment and its history back by E2EID.
* **Returns are sub-resources.** You create and read a devolução under the inbound parent payment it reverses. A return must be requested within 90 days of that payment's settlement and may not push the sum of the Pix's returns past the Pix's own value. A return of a Pix your client sent is issued by the counterparty and arrives inbound.
* **A return concludes on BACEN's answer.** A `pacs.004` the rail dispatched stays in progress until BACEN answers it. A duplicate request for a return already in progress is answered as in progress, and a colliding return identifier is answered as a conflict — never as a receipt.
* **Inbound rail messages are signature-validated.** The rail does not apply a message that fails validation.