Requisição de consulta
Um consumidor envia uma consulta com o documento do tomador, o tipo de cliente e um intervalo de datas de referência. A requisição também declara a autorização do titular sob a LC 105/2001. Essa declaração é uma flag obrigatória, e o registro de consentimento fica com a instituição. A chamada é síncrona. O resultado decodificado chega no corpo da resposta da mesma requisição, e não há um fluxo de criar-e-depois-consultar. A resposta carrega um identificador para uma releitura posterior. O BACEN cobra por cliente e por data de referência, então um intervalo estreito custa menos. Cada requisição carrega uma chave de idempotência, e uma nova tentativa que repete um desfecho armazenado não paga uma segunda tarifa.
Resolução de credencial e proteções de canal
O Lerian SCR resolve a credencial de canal da instituição antes de abrir o caminho do circuit breaker. Uma falha de credencial é uma falha local, e uma indisponibilidade do vault nunca aciona o breaker do canal. O adapter então emite um
GET HTTPS para a operação /wsscr2n/cliente/resumo do BACEN e define HTTP Basic na requisição. O canal autentica apenas o servidor, pelo pool de certificados do sistema do host, com TLS 1.2 como piso e sem certificado de cliente.
Três guardas ficam na frente da chamada, nesta ordem. A consolidação de Single-flight funde consultas concorrentes idênticas em uma única chamada upstream. Um circuit breaker então decide se a chamada prossegue. Dentro do breaker, um semáforo limita as conexões concorrentes a duas. Por padrão, o breaker aciona após cinco falhas consecutivas, ou após uma taxa de falha de 0,5 em pelo menos dez requisições. Em seguida, ele entra em um período de resfriamento de 30 segundos.
Uma falha de transporte, um erro de plataforma do BACEN ou uma resposta que o serviço não consegue ler aciona o breaker. Uma resposta de “sem posição” e uma rejeição do lado do cliente não o fazem. Um breaker aberto retorna SCR-1002 de imediato e não chama o BACEN.
Cache de resultado e tarifa
O Lerian SCR lê um cache Redis antes de chamar o BACEN. O cache mantém uma entrada por tomador e mês de referência. A chave traz o tomador apenas como um índice cego. Cada valor carrega o mesmo envelope AES-256-GCM em repouso que a linha de auditoria. Um hit completo pula a chamada ao BACEN e a tarifa, e ainda assim audita e emite. Um hit parcial busca um intervalo que cobre todos os meses ausentes, então um mês em cache dentro desse intervalo é buscado e cobrado de novo. Uma requisição que pede dados atualizados pula a leitura e paga a tarifa. Por padrão, uma entrada para o mês corrente vive quatro horas, e uma entrada para um mês fechado vive 720 horas. Um mês que o BACEN omite se torna um marcador de sem posição, então uma repetição do mesmo intervalo não paga por esse mês novamente. Quando o BACEN responde depois que a requisição já respondeu
SCR-1004, o serviço ainda grava essa resposta no cache.
Uma entrada ilegível conta como um miss. Uma gravação em cache é best-effort e nunca falha uma consulta. Um deployment sem Redis recusa consultas com SCR-9002.
Decodificação
O BACEN responde com códigos de modalidade, fonte de recursos, indexador, variação cambial, segmento do credor, tipo de garantia e tipo de informação adicional. O Lerian SCR resolve cada código em relação às tabelas de anexo do SCR, que vêm embutidas no serviço, e retorna um par
{ code, description }.
Um código desconhecido mantém o código, retorna uma descrição nula e incrementa uma métrica de código desconhecido. Ele nunca falha a consulta. Um código vazio retorna um código vazio sem descrição e não dispara nenhuma métrica.
O decodificador lê apenas códigos de domínio. Ele nunca vê o documento do tomador.
Auditoria e eventos
Todo desfecho terminal grava uma linha de auditoria. A linha e seu evento de outbox fazem commit em uma única transação, então nenhuma consulta sai sem seu rastro. Uma gravação com falha falha a consulta. Ela responde
SCR-9001, um 503 que permite nova tentativa, quando a requisição nunca chegou ao BACEN, e SCR-1004, um 502, quando chegou. O consumidor nunca recebe uma posição de crédito não auditada. A linha mantém seus dados pessoais sob criptografia AES-256-GCM e um índice cego HMAC-SHA256, com duas chaves independentes.
O outbox carrega dois tipos de evento: studio.lerian.br-scr.consulta.completed para uma consulta atendida, e studio.lerian.br-scr.consulta.failed para uma malsucedida. O dispatcher publica ambos no tópico lerian.streaming.br-scr, com lerian.streaming.br-scr.dlq para mensagens poison.
Um operador pode desativar a emissão. As linhas então ficam pendentes no outbox e são enviadas depois que a emissão volta a ser ativada e o serviço reinicia.