> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrando com o Lerian SRC

> Integrando com o Lerian SRC: a superfície da API, permissões, idempotência, polling e eventos, erros e limites de requisição.

Cada operação de negócio do Lerian SRC fica sob o caminho base `/v1/src`. A [Referência da API](/pt/reference/rails/src/create-a-consultation) 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](/pt/rails/src/src-environment-variables) lista as configurações, e [Operando o Lerian SRC](/pt/rails/src/src-operations) trata da conexão IBM MQ com o BACEN.

<h2 id="authentication-and-permissions">
  Autenticação e permissões
</h2>

***

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

| Operações | Recurso | Ação |
| - | - | - |
| Criar uma consulta | `consultation` | `write` |
| Listar, buscar e obter consultas | `consultation` | `read` |
| Cadastrar um registro da instituição | `decision` | `write` |
| Buscar a trilha de evidências, obter a trilha de evidências de uma consulta e buscar registros de evidência | `evidence` | `read` |
| Corrigir um registro de evidência | `evidence` | `correct` |
| Obter o dashboard de consultas | `dashboard` | `read` |
| Obter o status da credencial | `credential` | `read` |
| Listar e obter casos de operador | `operator` | `read` |
| Fechar ou reconhecer um caso de operador | `operator` | `close` |
| Configuração em runtime (`/v1/system`) | `system` | `write` |
| Manifesto de eventos (`GET /v1/streaming/manifest`) | `streaming` | `read` |

O Lerian SRC atende uma instituição, que `SRC_CNPJ_BASE8` define na configuração dele.

## Superfície da API

***

| Área | Operação | Finalidade |
| - | - | - |
| Consultas | `POST /v1/src/consultations` | Criar uma consulta. |
| Consultas | `GET /v1/src/consultations` | Listar consultas, com filtros. |
| Consultas | `POST /v1/src/consultations/search` | Buscar consultas, também por documento. |
| Consultas | `GET /v1/src/consultations/{id}` | Ler uma consulta e o resultado dela. |
| Registros da instituição | `POST /v1/src/consultations/{id}/institution-record` | Enviar o registro da instituição de uma consulta. |
| Evidências | `POST /v1/src/evidence` | Encontrar as consultas que têm uma trilha de evidências. |
| Evidências | `GET /v1/src/evidence/consultations/{id}` | Ler a trilha de evidências de uma consulta. |
| Evidências | `POST /v1/src/evidence/consultations/{id}/corrections` | Corrigir um registro de evidência. |
| Evidências | `POST /v1/src/evidence/records` | Encontrar registros de evidência individuais. |
| Dashboard | `GET /v1/src/dashboard/consultations` | Ler os totais de consultas de um período. |
| Credenciais | `GET /v1/src/credentials` | Ler o status da credencial. |
| Casos de operador | `GET /v1/src/operator/cases` | Listar casos de operador. |
| Casos de operador | `GET /v1/src/operator/cases/{leg}/{caseId}` | Ler um caso de operador. |
| Casos de operador | `POST /v1/src/operator/orphan-responses/{caseId}/closure` | Fechar um caso de resposta órfã. |
| Casos de operador | `POST /v1/src/operator/invalid-dispatches/{caseId}/closure` | Reconhecer um caso de envio inválido. |

Os endpoints operacionais ficam fora de `/v1/src`.

| Endpoint | Finalidade |
| - | - |
| `GET /health` | Liveness. |
| `GET /readyz` | Readiness das dependências. |
| `GET /version` | Versão de build. |
| `/v1/system` | Configuração em runtime. |
| `GET /v1/streaming/manifest` | O manifesto de eventos. |

<h2 id="idempotency">
  Idempotência
</h2>

***

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

<h2 id="polling-and-events">
  Polling e eventos
</h2>

***

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.

| Tipo de evento | Publicado quando | Campos do payload |
| - | - | - |
| `studio.lerian.br-src.consulta.accepted` | O Lerian SRC aceita uma consulta. | `consultationId`, `status`, `documentMasked`, `documentType`, `protectionTypes`, `motivationReference`, `acceptedAt`, `occurredAt` |
| `studio.lerian.br-src.consulta.completed` | O BACEN responde a uma consulta. | `consultationId`, `status`, `bcbControlCode`, `bcbProcessedAt`, `concludedAt`, `verdicts`, `occurredAt` |
| `studio.lerian.br-src.consulta.failed` | Uma consulta falha. | `consultationId`, `status`, `rejectionCode`, `rejectionClassification`, `rejectionReceivedAt`, `concludedAt`, `occurredAt` |

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](/pt/platform/streaming-hub/what-is-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](/pt/reference/rails/src/src-error-list) 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.