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

> Integrating with Lerian SRC: the API surface, permissions, idempotency, polling and events, errors, and request limits.

Every Lerian SRC business operation sits under the `/v1/src` base path. The [API Reference](/en/reference/rails/src/create-a-consultation) documents each operation, with its request and response.

## Before you start

***

An operator deploys and configures Lerian SRC for your institution. [Environment variables](/en/rails/src/src-environment-variables) lists the settings, and [Operating Lerian SRC](/en/rails/src/src-operations) covers the IBM MQ connection to BACEN.

## Authentication and permissions

***

Every call to `/v1/src` needs a bearer token from Access Manager. Use an application token for your onboarding systems and a user token for your back office. A request without a valid token returns `401`. A token of another type returns `401` with code `SRC-0201`.

Each operation needs one permission on the `src` product. A token without that permission returns `403` with code `SRC-0202`.

| Operations | Resource | Action |
| - | - | - |
| Create a consultation | `consultation` | `write` |
| List, search, and retrieve consultations | `consultation` | `read` |
| Register an institution record | `decision` | `write` |
| Search the evidence trail, retrieve a consultation's evidence trail, and search evidence records | `evidence` | `read` |
| Correct an evidence record | `evidence` | `correct` |
| Retrieve the consultation dashboard | `dashboard` | `read` |
| Retrieve the credential status | `credential` | `read` |
| List and retrieve operator cases | `operator` | `read` |
| Close or acknowledge an operator case | `operator` | `close` |
| Runtime configuration (`/v1/system`) | `system` | `write` |
| Event manifest (`GET /v1/streaming/manifest`) | `streaming` | `read` |

Lerian SRC serves one institution, which `SRC_CNPJ_BASE8` sets in its configuration.

## API surface

***

| Area | Operation | Purpose |
| - | - | - |
| Consultations | `POST /v1/src/consultations` | Create a consultation. |
| Consultations | `GET /v1/src/consultations` | List consultations, with filters. |
| Consultations | `POST /v1/src/consultations/search` | Search consultations, also by document. |
| Consultations | `GET /v1/src/consultations/{id}` | Read one consultation and its outcome. |
| Institution records | `POST /v1/src/consultations/{id}/institution-record` | File the institution record of a consultation. |
| Evidence | `POST /v1/src/evidence` | Find the consultations that have an evidence trail. |
| Evidence | `GET /v1/src/evidence/consultations/{id}` | Read the evidence trail of one consultation. |
| Evidence | `POST /v1/src/evidence/consultations/{id}/corrections` | Correct an evidence record. |
| Evidence | `POST /v1/src/evidence/records` | Find individual evidence records. |
| Dashboard | `GET /v1/src/dashboard/consultations` | Read the consultation totals for a period. |
| Credentials | `GET /v1/src/credentials` | Read the credential status. |
| Operator cases | `GET /v1/src/operator/cases` | List operator cases. |
| Operator cases | `GET /v1/src/operator/cases/{leg}/{caseId}` | Read one operator case. |
| Operator cases | `POST /v1/src/operator/orphan-responses/{caseId}/closure` | Close an orphan-response case. |
| Operator cases | `POST /v1/src/operator/invalid-dispatches/{caseId}/closure` | Acknowledge an invalid-dispatch case. |

Operational endpoints sit outside `/v1/src`.

| Endpoint | Purpose |
| - | - |
| `GET /health` | Liveness. |
| `GET /readyz` | Readiness of the dependencies. |
| `GET /version` | Build version. |
| `/v1/system` | Runtime configuration. |
| `GET /v1/streaming/manifest` | The event manifest. |

<h2 id="idempotency">
  Idempotency
</h2>

***

`POST /v1/src/consultations` needs an `X-Idempotency` header, of at most 255 characters. A request without it returns `400` with code `SRC-0001`.

* The same key with the same body returns `202` with the original consultation id. The response shows the current status of that consultation, so it can be `completed` or `failed`.
* The same key with a different body returns `409` with code `SRC-0003`.

These two rules hold while Lerian SRC keeps the key. The retention sweep can delete a key older than `src.retention.transient_purge_age`, 24 hours by default. A request that reuses a deleted key starts a new consultation.

`POST /v1/src/consultations/{id}/institution-record` takes no idempotency key. A consultation holds one record, so a retry returns `409` with code `SRC-0101`.

An evidence correction is not idempotent. A retried request adds a second correction. Before you retry after a failure that you cannot confirm, read the evidence trail.

## Polling and events

***

A consultation starts `pending`, and `pending` is a normal state. Read the outcome in one of two ways:

* Poll `GET /v1/src/consultations/{id}`. A `completed` consultation carries `verdicts` and `bcbControlCode`. A `failed` consultation carries `rejection`.
* Consume the events that Lerian SRC publishes.

| Event type | Published when | Payload fields |
| - | - | - |
| `studio.lerian.br-src.consulta.accepted` | Lerian SRC accepts a consultation. | `consultationId`, `status`, `documentMasked`, `documentType`, `protectionTypes`, `motivationReference`, `acceptedAt`, `occurredAt` |
| `studio.lerian.br-src.consulta.completed` | BACEN answers a consultation. | `consultationId`, `status`, `bcbControlCode`, `bcbProcessedAt`, `concludedAt`, `verdicts`, `occurredAt` |
| `studio.lerian.br-src.consulta.failed` | A consultation fails. | `consultationId`, `status`, `rejectionCode`, `rejectionClassification`, `rejectionReceivedAt`, `concludedAt`, `occurredAt` |

The events travel on the topic `lerian.streaming.br-src`, with the CloudEvents source `br-src`. No variable changes the topic. See [Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub).

Lerian SRC writes each event to an outbox in the same transaction as the change it reports. With no broker, the events stay pending in the outbox.

## Errors

***

Errors follow RFC 9457 problem details, with the media type `application/problem+json`. Branch on the `code` field, not on the `detail` text. The [SRC error list](/en/reference/rails/src/src-error-list) gives each code, its meaning, and its HTTP status.

## Integration conventions

***

* **Request size.** A request body larger than 1 MiB returns `413`.
* **Time budget.** A request that does not complete in 15 seconds returns `503` with code `SRC-1004`.
* **Pagination.** A list or search returns a page with `nextCursor`. To read the next page, send that value as `cursor`. `nextCursor` is `null` on the last page.
* **Rate limit.** Lerian SRC counts the requests of each client IP address in each replica. The default is 6000 requests per minute, set by `src.rate_limit.ip_max` and `src.rate_limit.ip_window`. Past the limit, the answer is `429` with code `SRC-0401`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.