Integrando-se ao Lerian SCR

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:<resource>:<action>. Veja Access Manager. 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 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 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-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. 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	A requisição não chegou ao BACEN a tempo.
`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. 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.

​Superfície da API

​Autenticação

​Idempotência

​Erros

​Eventos

​Convenções de integração