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

> Integrating with Lerian SCR: the operation surface, token scopes, idempotency, the error catalog, the consulta events, and the request conventions.

Lerian SCR exposes one REST surface. The institution comes from the token.

## API surface

***

| Operation                        | Scope                    | Purpose                                   |
| -------------------------------- | ------------------------ | ----------------------------------------- |
| `POST /v1/scr/consultations`     | `scr:consultation:write` | Consult a borrower position. Tariffed.    |
| `GET /v1/scr/consultations/{id}` | `scr:audit:read`         | Re-read a consultation, untariffed.       |
| `GET /v1/scr/audit`              | `scr:audit:read`         | List the audit trail.                     |
| `GET /v1/scr/credential`         | `scr:credential:read`    | Read credential status, never the secret. |
| `PUT /v1/scr/credential`         | `scr:credential:write`   | Set or rotate the credential.             |
| `GET /v1/scr/operations/summary` | `scr:dashboard:read`     | Aggregate summary, no personal data.      |
| `GET /health`                    | None                     | Liveness probe.                           |
| `GET /readyz`                    | None                     | Readiness probe, per dependency.          |
| `GET /version`                   | None                     | Build stamp.                              |

The credential operations exist only when a writable vault backs the deployment. Otherwise the credential comes from the environment.

## Authentication and tenancy

***

A consumer authenticates with an OAuth2 client-credentials token in `Authorization: Bearer`. For every gated request the service asks the authorization server for an explicit allow. It never trusts an unverified claim. A scope has the shape `scr:<resource>:<action>`. See [Access Manager](/en/platform/access-manager/access-manager).

The institution comes from the token claims, never from a body field, header, path, or query. A dedicated deployment fixes it per instance.

A missing token answers `SCR-0201`, and a missing scope `SCR-0202`. An unreachable authorization server answers `SCR-1002`, because the gate fails closed.

## Idempotency

***

The two effectful operations accept an `X-Idempotency` header. A retry inside a five-minute window replays the first outcome and pays no second tariff. A key reused with a different body answers `SCR-0003`. Without Redis the gate fails open, and a retry pays the tariff again.

## Errors

***

Every failure answers `application/problem+json` under RFC 9457, with the code, the status, and a trace id.

| Code       | Status | When                                                                  |
| ---------- | ------ | --------------------------------------------------------------------- |
| `SCR-0001` | 400    | Malformed body or query parameters.                                   |
| `SCR-0002` | 422    | Invalid document, date range, or authorization declaration.           |
| `SCR-0003` | 409    | `X-Idempotency` reused with a different body.                         |
| `SCR-0201` | 401    | Missing or invalid access token.                                      |
| `SCR-0202` | 403    | Scope missing for the action.                                         |
| `SCR-0301` | 404    | No such consultation or audit record.                                 |
| `SCR-0401` | 429    | Rate limited. `Retry-After` gives the wait.                           |
| `SCR-1001` | 502    | BACEN platform error, passed through in `details.upstreamViolations`. |
| `SCR-1002` | 503    | Channel unavailable, breaker open, or vault unreachable.              |
| `SCR-1003` | 504    | Upstream timeout.                                                     |
| `SCR-9000` | 500    | Unexpected internal error.                                            |
| `SCR-9001` | 503    | The audit write did not commit. Retry is safe.                        |

## Events

***

Lerian SCR emits one event per terminal consultation through a transactional outbox. The audit row and the event commit together.

* `studio.lerian.br-scr.consulta.completed`: the consultation returned an answer, a position or none.
* `studio.lerian.br-scr.consulta.failed`: the consultation returned no answer.

Both types travel on the topic `lerian.streaming.br-scr`, and poison messages on `lerian.streaming.br-scr.dlq`. No variable sets the topic, so provision both. See [Streaming Hub](/en/streaming-hub/what-is-streaming-hub).

When an operator turns emission off, the dispatcher does not start. The rows stay pending and ship once a broker returns.

## Integration conventions

***

* **Correlation.** `X-Request-ID` carries a UUID through logs, traces, and the audit trail.
* **Reference dates.** Consultation ranges and audit filters use `AAAAMM`, a six-digit year and month. The operational summary takes a date-time range instead.
* **Filters.** The document filter takes 8 to 14 digits, matched through the blind index. Client type `1` is an individual, `2` a company.
* **Pagination.** The audit list takes an opaque `cursor` and a `limit` from 1 to 200, default 50.
* **Coded fields.** A coded field answers `{ code, description }`, with a null description for an unknown code.