> ## 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-se ao Lerian SCR

> Integrando-se ao Lerian SCR: a superfície de operações, os scopes do token, a idempotência, o catálogo de erros, os eventos de consulta e as convenções de requisição.

O Lerian SCR expõe uma única superfície REST. A instituição vem do token.

## Superfície da API

***

| Operação                         | Scope                    | Finalidade                                   |
| -------------------------------- | ------------------------ | -------------------------------------------- |
| `POST /v1/scr/consultations`     | `scr:consultation:write` | Consultar uma posição de tomador. Tarifado.  |
| `GET /v1/scr/consultations/{id}` | `scr:audit:read`         | Reler uma consulta, não tarifado.            |
| `GET /v1/scr/audit`              | `scr:audit:read`         | Listar a trilha de auditoria.                |
| `GET /v1/scr/credential`         | `scr:credential:read`    | Ler o status da credencial, nunca o segredo. |
| `PUT /v1/scr/credential`         | `scr:credential:write`   | Definir ou rotacionar a credencial.          |
| `GET /v1/scr/operations/summary` | `scr:dashboard:read`     | Resumo agregado, sem dados pessoais.         |
| `GET /health`                    | Nenhum                   | Probe de liveness.                           |
| `GET /readyz`                    | Nenhum                   | Probe de prontidão, por dependência.         |
| `GET /version`                   | Nenhum                   | Carimbo de build.                            |

As operações de credencial existem apenas quando um vault gravável dá suporte ao deployment. Caso contrário, a credencial vem do ambiente.

## Autenticação e tenancy

***

Um consumidor se autentica com um token OAuth2 client-credentials em `Authorization: Bearer`. Para cada requisição protegida por gate, o serviço pede ao servidor de autorização uma permissão explícita. Ele nunca confia em um claim não verificado. Um scope tem o formato `scr:<resource>:<action>`. Veja [Access Manager](/pt/platform/access-manager).

A instituição vem dos claims do token, nunca de um campo do corpo, header, path ou query. Um deployment dedicado a fixa por instância.

Um token ausente responde `SCR-0201`, e um scope ausente `SCR-0202`. Um servidor de autorização inalcançável responde `SCR-1002`, porque o gate falha de forma fechada.

## Idempotência

***

As duas operações com efeito colateral aceitam um header `X-Idempotency`. Uma nova tentativa dentro de uma janela de cinco minutos repete o primeiro desfecho e não paga uma segunda tarifa. Uma chave reutilizada com um corpo diferente responde `SCR-0003`. Sem Redis, o gate falha de forma aberta, e uma nova tentativa paga a tarifa novamente.

## Erros

***

Toda falha responde `application/problem+json` sob a RFC 9457, com o código, o status e um trace id.

| Código     | Status | Quando                                                                  |
| ---------- | ------ | ----------------------------------------------------------------------- |
| `SCR-0001` | 400    | Corpo ou parâmetros de query malformados.                               |
| `SCR-0002` | 422    | Documento, intervalo de datas ou declaração de autorização inválidos.   |
| `SCR-0003` | 409    | `X-Idempotency` reutilizado com um corpo diferente.                     |
| `SCR-0201` | 401    | Token de acesso ausente ou inválido.                                    |
| `SCR-0202` | 403    | Scope ausente para a ação.                                              |
| `SCR-0301` | 404    | Consulta ou registro de auditoria inexistente.                          |
| `SCR-0401` | 429    | Limitado por rate limit. `Retry-After` informa a espera.                |
| `SCR-1001` | 502    | Erro de plataforma do BACEN, repassado em `details.upstreamViolations`. |
| `SCR-1002` | 503    | Canal indisponível, breaker aberto, ou vault inalcançável.              |
| `SCR-1003` | 504    | Timeout do upstream.                                                    |
| `SCR-9000` | 500    | Erro interno inesperado.                                                |
| `SCR-9001` | 503    | A gravação de auditoria não fez commit. Repetir é seguro.               |

## Eventos

***

O Lerian SCR emite um evento por consulta terminal por meio de um outbox transacional. A linha de auditoria e o evento fazem commit juntos.

* `studio.lerian.br-scr.consulta.completed`: a consulta retornou uma resposta, uma posição ou nenhuma.
* `studio.lerian.br-scr.consulta.failed`: a consulta não retornou nenhuma resposta.

Os dois tipos trafegam no tópico `lerian.streaming.br-scr`, e mensagens poison em `lerian.streaming.br-scr.dlq`. Nenhuma variável define o tópico, então provisione ambos. Veja [Streaming Hub](/pt/platform/streaming-hub/what-is-streaming-hub).

Quando um operador desativa a emissão, o dispatcher não inicia. As linhas permanecem pendentes e são enviadas assim que um broker retorna.

## Convenções de integração

***

* **Correlação.** `X-Request-ID` carrega um UUID pelos logs, traces e a trilha de auditoria.
* **Datas de referência.** Intervalos de consulta e filtros de auditoria usam `AAAAMM`, um ano e mês de seis dígitos. O resumo operacional usa um intervalo de data-hora em vez disso.
* **Filtros.** O filtro de documento aceita de 8 a 14 dígitos, correspondidos por meio do índice cego. O tipo de cliente `1` é uma pessoa física, `2` uma pessoa jurídica.
* **Paginação.** A lista de auditoria aceita um `cursor` opaco e um `limit` de 1 a 200, padrão 50.
* **Campos codificados.** Um campo codificado responde `{ code, description }`, com uma descrição nula para um código desconhecido.