Skip to main content
Cada operação de negócio do Lerian SRC fica sob o caminho base /v1/src. A Referência da API documenta cada operação, com a requisição e a resposta dela.

​
Antes de começar

Um operador faz o deploy e configura o Lerian SRC para a sua instituição. Variáveis de ambiente lista as configurações, e Operando o Lerian SRC trata da conexão IBM MQ com o BACEN.

​
Autenticação e permissões

Cada chamada a /v1/src precisa de um bearer token do Access Manager. Use um token de aplicação para os seus sistemas de onboarding e um token de usuário para o seu back office. Uma requisição sem um token válido retorna 401. Um token de outro tipo retorna 401 com o código SRC-0201. Cada operação precisa de uma permissão no produto src. Um token sem essa permissão retorna 403 com o código SRC-0202. O Lerian SRC atende uma instituição, que SRC_CNPJ_BASE8 define na configuração dele.

​
Superfície da API

Os endpoints operacionais ficam fora de /v1/src.

​
Idempotência

POST /v1/src/consultations exige um header X-Idempotency, de no máximo 255 caracteres. Uma requisição sem ele retorna 400 com o código SRC-0001.
  • A mesma chave com o mesmo corpo retorna 202 com o id da consulta original. A resposta mostra o status atual dessa consulta, então ele pode ser completed ou failed.
  • A mesma chave com um corpo diferente retorna 409 com o código SRC-0003.
Essas duas regras valem enquanto o Lerian SRC guarda a chave. A varredura de retenção pode excluir uma chave mais antiga que src.retention.transient_purge_age, 24 horas por padrão. Uma requisição que reusa uma chave excluída começa uma nova consulta. POST /v1/src/consultations/{id}/institution-record não recebe chave de idempotência. Uma consulta guarda um registro, então uma nova tentativa retorna 409 com o código SRC-0101. Uma correção de evidência não é idempotente. Uma requisição repetida adiciona uma segunda correção. Antes de repetir depois de uma falha que você não consegue confirmar, leia a trilha de evidências.

​
Polling e eventos

Uma consulta começa como pending, e pending é um estado normal. Leia o resultado de uma de duas formas:
  • Faça polling de GET /v1/src/consultations/{id}. Uma consulta completed leva verdicts e bcbControlCode. Uma consulta failed leva rejection.
  • Consuma os eventos que o Lerian SRC publica.
Os eventos trafegam no tópico lerian.streaming.br-src, com a source CloudEvents br-src. Nenhuma variável muda o tópico. Veja Streaming Hub. O Lerian SRC grava cada evento em um outbox na mesma transação da mudança que ele informa. Sem broker, os eventos ficam pendentes no outbox.

​
Erros

Os erros seguem os problem details da RFC 9457, com o media type application/problem+json. Decida com base no campo code, não no texto de detail. A lista de erros do SRC traz cada código, o significado dele e o status HTTP dele.

​
Convenções de integração

  • Tamanho da requisição. Um corpo de requisição maior que 1 MiB retorna 413.
  • Orçamento de tempo. Uma requisição que não termina em 15 segundos retorna 503 com o código SRC-1004.
  • Paginação. Uma lista ou uma busca retorna uma página com nextCursor. Para ler a próxima página, envie esse valor como cursor. nextCursor é null na última página.
  • Rate limit. O Lerian SRC conta as requisições de cada endereço IP de cliente em cada réplica. O padrão é 6000 requisições por minuto, definido por src.rate_limit.ip_max e src.rate_limit.ip_window. Acima do limite, a resposta é 429 com o código SRC-0401.