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

​
Superfície da API

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

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