> ## 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. Uma instalação atende uma instituição. ## 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. | | `/v1/system/{namespace}/{key}` | `scr:system:write` | Ler ou alterar a configuração em tempo de execução. | | `/v1/client-system/{namespace}/{key}` | `scr:client-system:read`, `scr:client-system:write` | Ler ou alterar as definições próprias da instituição. | | `GET /v1/streaming/manifest` | `scr:streaming:read` | O manifesto de eventos. | | `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. `GET /v1/scr/audit` e `GET /v1/scr/consultations/{id}` podem retornar o CPF ou a raiz do CNPJ consultado por completo, no campo `document`. Conceda `scr:audit:read` apenas a pessoas que possam vê-lo. ## Autenticação *** Um consumidor se autentica com um token OAuth2 client-credentials em `Authorization: Bearer`. Com `PLUGIN_AUTH_ENABLED=true`, o servidor de autorização decide cada requisição protegida por gate. Um scope tem o formato `scr::`. Veja [Access Manager](https://docs.lerian.studio/pt/platform/access-manager.md). 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. Um que não responde a tempo responde `SCR-1003`. ## Idempotência *** As duas operações com efeito colateral exigem um header `X-Idempotency`, e uma requisição sem ele responde `SCR-0004`. Quando o Lerian SCR armazena um desfecho 2xx ou 4xx, uma nova tentativa dentro de uma janela de cinco minutos repete esse desfecho e não paga uma segunda tarifa. Uma nova tentativa enquanto a primeira requisição ainda roda responde `SCR-0006`. Envie-a de novo depois de `Retry-After`. Uma chave reutilizada com uma requisição diferente responde `SCR-0003`. Uma resposta acima de 1 MB não é armazenada. Uma nova tentativa sob a chave de uma requisição concluída desse tipo responde `SCR-0007`: a requisição não roda de novo, e nenhuma segunda tarifa é cobrada. Leia o desfecho original em `GET /v1/scr/consultations/{id}` ou na trilha de auditoria. Uma resposta com `X-Idempotency-Fenced: true` retém sua chave durante a janela, e uma nova tentativa com essa chave responde `SCR-0005` sem executar. Um 5xx sem esse header libera a chave, e uma nova tentativa executa a operação de novo. Com `X-Idempotency-Fenced: false`, a requisição pode ter rodado e a chave não está protegida. Concilie o desfecho antes de enviar a requisição de novo. Sem Redis, as duas operações respondem `SCR-9002`. ## Erros *** Uma falha responde `application/problem+json` sob a RFC 9457, com o código e o status. | 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 uma requisição diferente. | | `SCR-0004` | 422 | `X-Idempotency` ausente. | | `SCR-0005` | 422 | Uma requisição anterior com este `X-Idempotency` não tem desfecho registrado. Esta requisição não foi executada. | | `SCR-0006` | 409 | A primeira requisição com este `X-Idempotency` ainda está em execução. Esta requisição não foi executada. | | `SCR-0007` | 409 | A primeira requisição com este `X-Idempotency` foi concluída, e sua resposta era grande demais para ser armazenada. Esta requisição não foi executada. | | `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. A requisição também responde com ele quando esperou além do prazo por uma das duas conexões com o BACEN. Nada foi enviado e a chave é liberada: tente de novo com a mesma chave. Quando o breaker recusa a chamada ou o canal com o BACEN está indisponível, o detail diz `BACEN SCR is unavailable; the consultation was not sent.` | | `SCR-1003` | 504 | O serviço de autorização não respondeu a tempo. Nada chegou ao BACEN. Tente de novo com a mesma chave. | | `SCR-1004` | 502 | A requisição pode ter chegado ao BACEN, e o BACEN não deu uma resposta utilizável. | | `SCR-9000` | 500 | Erro interno inesperado. | | `SCR-9001` | 503 | A gravação de auditoria não fez commit, e a requisição nunca chegou ao BACEN. | | `SCR-9002` | 503 | O armazenamento de idempotência está indisponível, e a operação não foi executada. | ## 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](https://docs.lerian.studio/pt/platform/streaming-hub/what-is-streaming-hub.md). Quando um operador desativa a emissão, o dispatcher não inicia. As linhas permanecem pendentes e são enviadas depois que a emissão volta a ser ativada e o serviço reinicia. ## Convenções de integração *** * **Correlação.** `X-Request-ID` carrega um UUID pelos logs e traces. * **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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.