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.
`/v1/system/{namespace}/{key}`	`scr:system:write`	Read or change runtime configuration.
`GET /v1/streaming/manifest`	`scr:streaming:read`	The event manifest.
`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. With PLUGIN_AUTH_ENABLED=true, the authorization server decides every gated request. 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 require an X-Idempotency header, and a request without it answers SCR-0004. A retry inside a five-minute window replays a 2xx or 4xx outcome and pays no second tariff. After a 5xx outcome the key is free, and a retry runs the operation again. A key reused with a different body answers SCR-0003. Without Redis both operations answer SCR-9002.

Errors

A failure answers application/problem+json under RFC 9457, with the code and the status.

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-0004`	422	`X-Idempotency` missing.
`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.
`SCR-9002`	503	The idempotency store is unavailable, and the operation did not run.

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 they ship after emission is back on and the service restarts.

Integration conventions

Correlation. X-Request-ID carries a UUID through logs and traces.
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