Integrating with Lerian SCR

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

​API surface

​Authentication and tenancy

​Idempotency

​Errors

​Events

​Integration conventions