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

> Integrating with Lerian SPB: STR operation event families, ledger integration, webhook delivery, and API conventions.

Lerian SPB is event-driven. Event emission is not guaranteed for every operation or lifecycle change: some emitters are optional or best effort, and `EMISSION_REQUIRED` defaults to `false`. Set `EMISSION_REQUIRED=true` in a deployment whose downstream systems depend on these events. Bootstrap then fails closed unless event emission is fully wired.

Registered webhooks receive durable control-plane events. The `settlement.*` and `spb.ldl.*` families go to the streaming backbone only. Downstream systems read settlement state from `settlement.*` streaming events and do not poll.

## Event families

***

| Family                       | Emitted on                                                                                                                                                                                                                                                                                   |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `str.operation.*`            | Operation lifecycle — `accepted`, `received`, `returnRequested`, `cancelRequested`                                                                                                                                                                                                           |
| `str.readiness.changed`      | The rail's readiness state changes                                                                                                                                                                                                                                                           |
| `str.certificate.*`          | Certificate lifecycle — `rotated`, `expiring`, `counterpartyChanged`, `activationRequested`                                                                                                                                                                                                  |
| `str.approval.*`             | A queued approval emits `signed` or `denied`; when it reaches quorum and changes from `PENDING_APPROVAL` to `SUBMITTED`, it emits `quorumReached` exactly once                                                                                                                               |
| `str.reconciliation.*`       | A reconciliation case is `opened` or `resolved`                                                                                                                                                                                                                                              |
| `str.schedule.changed`       | The operating-window grades change                                                                                                                                                                                                                                                           |
| `str.message.*`              | Message-level `received`, `sent`, `submitted`, `failed`, `rejected`                                                                                                                                                                                                                          |
| `str.emoney.transferAdvised` | A new third-party electronic-money advice (`SME0001R2`, `SME0002R2`, or `SME0004R2`) is recorded. Delivered through streaming and registered webhooks                                                                                                                                        |
| `spb.ldl.*`                  | SILOC deposit-advisory and deposit-command facts, including `deposit-commanded`, `deposit-confirmed`, and `deposit-failed`. Delivered on the streaming backbone only, not on webhooks                                                                                                        |
| `settlement.*`               | The final settlement position: `settled` once the inbound R-leg confirms an operation, `returned` when a confirmed return reverses a settled original, `failed` on a rejection or on the cancellation of a never-settled original. Delivered on the streaming backbone only, not on webhooks |

## Ledger integration

***

Your ledger consumer must receive both the `str.operation.*` and `settlement.*` families on the streaming backbone. The `str.operation.accepted` event signals dispatch acceptance, not BACEN settlement, so use it to record a pending posting.

Record the final position from the `settlement.*` facts on the streaming backbone. The business transition behind `settlement.settled` occurs when the inbound R-leg moves the operation to `CONFIRMED`. Broker delivery is at-least-once and can redeliver the fact. The `ce-id` is deterministic, so deduplicate on the `(ce-source, ce-id)` pair.

The `settlement.failed` event fires when BACEN rejects the operation or a cancellation reverses a never-settled original. The `settlement.returned` event fires when a confirmed return reverses a settled original. A return follows the same pattern: `str.operation.returnRequested` signals the return's dispatch acceptance, and the parent posting reverses on `settlement.returned`. Lerian SPB holds no accounting position. The rail carries the message and its settlement state, and your ledger records the money.

## Webhooks

***

Webhook consumers self-register on the canonical event constants. They negotiate payload shapes from a shared event catalog. Delivery is durable. You can retry a failed delivery manually. A dead-letter path handles the deliveries that exhaust their retries.

## API conventions

***

* **Auth** is a bearer token.
* **Writes are idempotent** through an idempotency key. A retried submit does not double-dispatch.
* **Message-log reads do not expose the signed on-wire frame.** You read a single message by its NUOp for structured data. When the rail retained a frame, read its reconstructed XML through the dedicated, separately authorized frame route. It does not separately retain the literal sent bytes.
* **Unknown ids return a uniform not-found.** The response never reveals whether an operation exists that your institution does not own.