How Lerian SRC works

A consultation has one of three statuses: pending, completed, or failed. Lerian SRC accepts the consultation at once and works with BACEN after it answers your request.

Consultation request

Your system sends POST /v1/src/consultations with an X-Idempotency header. The body names one document and the questions to ask about it.

Field	Meaning
`document`	The CPF or CNPJ to consult.
`documentType`	`CPF` or `CNPJ`. It must match the document.
`protectionTypes`	`account_opening`, `ownership_change`, or both.
`motivation`	The reason for the consultation. `motivation.reference` is required.
`subjectRole`	Optional: `individual`, `company`, `holder`, or `representative`. Without it, Lerian SRC takes the role from `documentType`.
`companyConsultationId`	The id of the company consultation. Required for `holder` and `representative`.

A holder or a representative is a person that you consult for a company. Send the company consultation first. Then send the person’s consultation, with companyConsultationId set to the id that the company consultation returned. A request that breaks these rules returns 422 with a code from SRC-0004 to SRC-0008. Lerian SRC checks the request before it accepts it. It checks the check digits, the document type, the protection types, and the motivation. A request that fails one of these checks returns 422 with code SRC-0002, and Lerian SRC sends nothing to BACEN. An accepted request returns 202 with the consultation id and the status pending. Lerian SRC stores the consultation before it sends anything to BACEN, and it publishes the accepted event.

SRC0001: the consultation to BACEN

Lerian SRC sends each accepted consultation to BACEN as an SRC0001 message. Every 15 seconds, it takes up to 25 consultations that wait to go. Each message carries the operation number of the consultation. The API returns it as regulatoryOperationNumber. Lerian SRC checks each message against BACEN’s message schema before it sends the message. If the message is not valid for BACEN, Lerian SRC does not send it. The consultation ends failed with the rejection code SRC-OUTBOUND-INVALID, and Lerian SRC opens an invalid_outbound operator case.

SRC0001R1: BACEN’s answer

BACEN answers with an SRC0001R1 message. The answer carries BACEN’s control code and one verdict for each protection type. Lerian SRC matches the answer to its consultation and stores the verdicts. The consultation becomes completed, and Lerian SRC publishes the completed event. A verdict with permitted set to false means an active restriction. An answer that matches no consultation of the deployment opens an orphan_response operator case.

SRC0001E: BACEN’s rejection

BACEN can reject a consultation with an SRC0001E message. Lerian SRC puts the rejection code in one of three classes:

transient: the code names a temporary state of the rail. Lerian SRC sends the consultation again, within the attempt budget. The transient codes are EGEN0021, EGEN0050, EGEN0152, EGEN0300, EGEN0301, and EGEN1105.
permanent: the consultation ends failed. Fix the cause and send a new request.
unknown: Lerian SRC does not recognize the code. The consultation ends failed, as for a permanent code.

A failed consultation carries the code as BACEN sent it, in rejection.code, and its class in rejection.classification. Lerian SRC publishes the failed event.

Retries and BACEN unavailability

When a send fails, or BACEN gives a transient rejection, Lerian SRC sends the consultation again. If BACEN does not answer in time, Lerian SRC also sends the consultation again. Each send counts as one attempt. Three runtime configuration keys set the attempt budget:

Key	Default	Meaning
`src.dispatch.max_attempts`	`8`	Attempts for each consultation, from 1 to 20.
`src.dispatch.backoff_initial`	`1m`	Wait before the first retry, from `1s` to `1h`.
`src.dispatch.backoff_ceiling`	`30m`	Longest wait between two attempts, from `1m` to `24h`.

The wait doubles after each attempt, up to the ceiling. Lerian SRC waits for an answer for 30 minutes, or for the ceiling when the ceiling is longer. When a consultation uses its whole budget, Lerian SRC stops sending it and opens a budget_exhausted operator case. The consultation stays pending. When BACEN or the IBM MQ channel is unavailable, the API does not return an error. Lerian SRC keeps accepting consultations, and they stay pending.

Institution record

After a consultation completes with an active restriction, your institution files one record with POST /v1/src/consultations/{id}/institution-record. The record has one of two kinds:

Kind	When to file it	Fields it needs
`exceptional_proceed`	Your institution went ahead with the contract despite the active restriction.	`justification` and `circumstance`
`refusal_explanation`	Your institution refused, and the record holds the explanation it gave to the interested party.	`explanation`

Both kinds also need registeredBy, which names who files the record. A successful filing returns 201. The record does not change the verdicts. A consultation holds one record. A second record returns 409 with code SRC-0101. A consultation that did not complete with an active restriction returns 409 with code SRC-0102.

Evidence trail

Lerian SRC keeps an evidence trail for each consultation.

Operation	What it returns
`GET /v1/src/evidence/consultations/{id}`	The trail of one consultation, record by record.
`POST /v1/src/evidence`	The consultations that have a trail, found by period, consultation id, BACEN control code, or document.
`POST /v1/src/evidence/records`	The individual records, found by document or by record kind.

To correct a record, send POST /v1/src/evidence/consultations/{id}/corrections. Put the position of the record in correctsSequence, and the reason in reason. Lerian SRC adds the correction to the trail as a new record and returns 201. If a concurrent correction of the same trail takes the position first, the request returns 409 with code SRC-0104. Lerian SRC writes nothing. Retry the correction.

Operator cases

An operator case is an item that your back office must see. Each case names its leg. For example:

Leg	What happened	What closing the case does
`invalid_outbound`	Lerian SRC refused to send a message that is not valid for BACEN. BACEN did not receive it.	It records that a person saw the case. Lerian SRC repairs nothing and sends nothing. Fix the cause and send a new request.
`orphan_response`	A message from BACEN matched no consultation of the deployment.	It records that a person examined the message.
`budget_exhausted`	A consultation used its whole attempt budget.	You cannot close it. If BACEN’s answer arrives later, Lerian SRC records the answer and the case leaves the queue.

Operating Lerian SRC explains how to list and close cases. Lerian SRC also publishes an event at each change of status. Integrating with Lerian SRC lists the events.

​Consultation request

​SRC0001: the consultation to BACEN

​SRC0001R1: BACEN’s answer

​SRC0001E: BACEN’s rejection

​Retries and BACEN unavailability

​Institution record

​Evidence trail

​Operator cases