> ## 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 Pix Lerian

> Integrating with Lerian SPI: 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.

## 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 `spi.payment.settled` to close a charge after its Pix settles and `spi.mandate.resolved` to move a Pix Automático mandate out of `CRIADA`.
* 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. You must request a return within 90 days of that payment's settlement. A return may not push the sum of the Pix's returns past the Pix's own value. The counterparty issues a return of a Pix your client sent. This return 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 receives an in-progress answer. A colliding return identifier receives a conflict answer, never a receipt.
* **Inbound rail messages are signature-validated.** The rail does not apply a message that fails validation.