Skip to main content
Every Lerian SRC business operation sits under the /v1/src base path. The API Reference documents each operation, with its request and response.

​
Before you start

An operator deploys and configures Lerian SRC for your institution. Environment variables lists the settings, and Operating Lerian SRC 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. Lerian SRC serves one institution, which SRC_CNPJ_BASE8 sets in its configuration.

​
API surface

Operational endpoints sit outside /v1/src.

​
Idempotency

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.
The events travel on the topic lerian.streaming.br-src, with the CloudEvents source br-src. No variable changes the topic. See 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 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.