Equipe BIBlue
Manter contratos individuais com Serasa Experian, SPC Brasil e Boa Vista SCPC significa replicar rotinas de autenticação, mapeamento de campos, tratamento de timeout e circuit breaker em três pontos distintos da esteira de crédito. Quando o SPC Brasil retorna HTTP 503 às 14h23 de uma sexta-feira e o timeout da Serasa sobe para 8 segundos no mesmo instante, o time de engenharia precisa decidir em tempo real se degrada o fluxo, se aciona fallback para Boa Vista ou se enfileira a consulta—tudo isso enquanto a fila de originação cresce e a métrica de SLA pisca em amarelo no dashboard do diretor de risco.
A arquitetura de referência que apresentamos neste artigo consolida Serasa, SPC Brasil e Boa Vista em **uma camada única de API**, abstraindo diferenças de contrato, versionamento e disponibilidade por trás de interface REST padronizada. O desenho técnico privilegia resiliência—fallback automático entre bureaus, cache inteligente de respostas e retry exponencial—e governança: log centralizado de consultas, rate limiting por cliente interno e auditoria nativa para atendimento à Circular 3.909 BACEN (proteção de dados cadastrais).
Se você é CTO ou arquiteto de plataforma em cooperativa de crédito, financeira de veículos ou instituição financeira mid-market que hoje opera integrações ponto-a-ponto com os três bureaus, este artigo detalha componentes, fluxos de decisão e trade-offs de implementação para migrar rumo a hub integrador de produção.
Por Que Unificar Três Bureaus em Camada Única de API
Custos de manutenção e superfície de falha
Cada bureau de crédito publica SDK próprio—Java, .NET ou REST puro—com ciclos de atualização independentes. Serasa Experian versionou a API de pessoa física quatro vezes entre 2021 e 2024; SPC Brasil migrou autenticação de basic para OAuth 2.0 client credentials em janeiro de 2023; Boa Vista SCPC alterou estrutura do JSON de score em março de 2024. Manter três clientes HTTP, três rotinas de parse e três conjuntos de testes de contrato amplia superfície de falha e consome sprints de squad que poderiam estar refinando o motor de regras ou ajustando política de provisão 4966.
SLA composto e degradação graciosa
Quando você chama três bureaus em sequência dentro da mesma requisição síncrona, o SLA efetivo é o **produto** das disponibilidades individuais: 99,5 % × 99,0 % × 99,5 % = 98,0 %. Hub integrador permite topologia de fallback—se Serasa timeout após 3 segundos, tenta SPC Brasil; se SPC retorna 503, consulta Boa Vista—elevando disponibilidade percebida para patamar superior a 99,5 % mesmo quando um fornecedor está degradado.
Governança centralizada e auditoria BACEN
Circular 3.909 e LGPD exigem log de finalidade, timestamp e identificador do operador para cada consulta a dado cadastral. Centralizar chamadas em hub único simplifica geração de trilha de auditoria: um interceptor grava evento no Data Lake com bureau consultado, latência, status HTTP e hash SHA-256 do CPF, atendendo requisito de rastreabilidade sem modificar código de 12 microserviços que consomem dados de crédito.
Componentes da Arquitetura de Referência
API Gateway e gerenciamento de contrato
Porta de entrada REST expõe endpoint POST /credit-bureau/v1/consulta que recebe payload padronizado:
{
"documento": "12345678909",
"tipo_pessoa": "PF",
"produtos": ["score", "restricoes", "cheques"],
"estrategia_fallback": "waterfall"
}
Gateway valida schema JSON, aplica rate limiting por client_id OAuth (100 req/min para originação, 10 req/min para backoffice) e roteia para orquestrador. Implementações típicas usam Kong, AWS API Gateway ou Apigee; camada managed reduz esforço de configuração de certificado mTLS e rotação de secrets.
Orquestrador de bureaus e lógica de fallback
Motor de decisão que traduz "estrategia_fallback": "waterfall" em sequência concreta: tenta Serasa com timeout 4 s; se falha, tenta SPC Brasil timeout 3 s; se falha, tenta Boa Vista timeout 3 s. Estratégia alternativa "parallel_best_of_two" dispara Serasa + SPC em paralelo, retorna primeira resposta HTTP 200 e cancela requisição pendente, privilegiando latência P95 sobre custo de consulta dupla.
Orquestrador mantém **circuit breaker por bureau**: após cinco timeouts consecutivos de SPC Brasil em janela de 60 segundos, abre circuito e desvia tráfego para Boa Vista durante 120 segundos, evitando desperdício de thread pool. Implementação típica usa Resilience4j ou Polly se stack é .NET.
Adaptadores específicos de bureau
Cada bureau exige transformação de entrada e saída:
- Serasa Experian: autenticação Bearer JWT renovado a cada 50 minutos; mapeamento de produto "restricoes" para parâmetro
?includeProtests=true&includeDebts=true; parse de arraypendingIssuespara modelo interno. - SPC Brasil: autenticação client credentials com refresh token; conversão de código de score SPC (1–1.000) para escala padronizada 0–100; extração de nó
informacoesAdicionais.chequesSemFundo. - Boa Vista SCPC: chamada SOAP legada ainda em produção para base histórica pré-2022; adaptador mantém cliente JAX-WS e traduz WSDL para JSON; fallback para REST v2 quando
dataConsulta >= 2022-01-01.
Padrão Adapter isola mudanças de contrato externo: quando Serasa lança API v5, apenas módulo serasa-adapter precisa ser atualizado; orquestrador e gateway permanecem intocados.
Cache distribuído e controle de duplicação
Consultas a bureaus custam entre R$ 0,80 e R$ 3,50 por hit. Cache Redis com TTL 24 horas reduz custo em cenários de re-análise: cliente desiste no meio do fluxo, retorna 4 horas depois e reinicia proposta; sistema consulta cache em vez de cobrar nova consulta. Chave de cache combina SHA-256 do CPF + lista de produtos + data UTC: bureau:12abc...:score-restricoes:2025-01-15.
Política de invalidação respeita SLA de atualização do bureau: Serasa atualiza restrições em D+0, logo TTL de 24 h é seguro; SPC Brasil consolida protestos em D+1, exigindo TTL máximo 18 h para fluxos de compliance rigoroso.
Observabilidade e auditoria
Interceptor grava evento em tópico Kafka credit-bureau-audit com schema Avro:
{
"timestamp": "2025-01-15T10:23:47.123Z",
"client_id": "motor-credito-pf",
"documento_hash": "sha256:9f4b2...",
"bureau": "SERASA",
"produtos": ["score","restricoes"],
"latencia_ms": 1834,
"http_status": 200,
"custo_estimado_brl": 2.10,
"operador_id": "usr_98234"
}
Stream processor agrega métricas por bureau e client_id, alimentando dashboard Grafana: latência P50/P95/P99, taxa de erro 5xx, custo acumulado mês corrente. Alerta dispara quando latência P95 de Serasa ultrapassa 5 s por 10 minutos consecutivos, sinalizando possível degradação.
Fluxo de Requisição: Da Originação ao Log de Auditoria
Passo 1: Cliente interno invoca API unificada
Microserviço motor-credito-pf dispara POST /credit-bureau/v1/consulta com token OAuth obtido via client credentials grant. API Gateway valida token, extrai client_id, verifica cota (95/100 requisições consumidas na janela de 1 min) e encaminha para orquestrador.
Passo 2: Orquestrador consulta cache
Antes de chamar bureau externo, orquestrador monta chave Redis e verifica hit. Se encontra entrada válida (TTL > 0), retorna JSON cached, grava log "source": "cache" e encerra fluxo com latência ~12 ms.
Passo 3: Seleção de bureau e invocação
Cache miss. Orquestrador lê "estrategia_fallback": "waterfall", consulta tabela de prioridade (Serasa > SPC > Boa Vista) e verifica estado do circuit breaker de Serasa: **fechado**. Invoca serasa-adapter.consultaPF(cpf, ["score","restricoes"]) com timeout 4 s.
Adaptador renova JWT se expiração < 5 min, monta query string, dispara HTTP GET, aguarda resposta. Serasa retorna HTTP 200 em 1.834 ms. Adaptador parseia JSON, mapeia para modelo canônico e devolve objeto ConsultaBureauResult.
Passo 4: Circuit breaker registra sucesso
Orquestrador notifica Resilience4j: chamada bem-sucedida, latência 1.834 ms. Circuit breaker incrementa contador de sucessos, zerando sequência de falhas. Se contador estava em warning (3 timeouts nos últimos 60 s), volta para estado normal.
Passo 5: Gravação em cache e auditoria
Orquestrador grava resultado no Redis com SETEX bureau:9f4b2...:score-restricoes:2025-01-15 86400 '{...}'. Em paralelo, publica evento Avro no tópico Kafka. Consumer downstream persiste no Data Lake (S3 + Athena) e atualiza tabela agregada de custo por cliente interno.
Passo 6: Retorno ao solicitante
API Gateway serializa resposta HTTP 200 com payload padronizado:
{
"score": 682,
"restricoes": [
{"tipo": "protesto", "valor_brl": 1500.00, "data": "2024-11-10"}
],
"fonte": "SERASA",
"timestamp_consulta": "2025-01-15T10:23:47Z"
}
Motor de crédito consome resposta e prossegue para próxima etapa da esteira: validação de renda via Open Finance ou consulta SCR BACEN.
Estratégias de Fallback e Trade-Offs
Waterfall sequencial
Tenta bureau A; se timeout ou 5xx, tenta B; se timeout ou 5xx, tenta C. **Vantagem:** custo mínimo—paga apenas consultas efetivamente realizadas. **Desvantagem:** latência P99 pode atingir 12 s (3 timeouts consecutivos de 4 s) em cenário de degradação simultânea.
Parallel race
Dispara A + B em paralelo, retorna primeira resposta HTTP 200, cancela requisição pendente. **Vantagem:** latência P95 cai para ~2 s mesmo quando um bureau está lento. **Desvantagem:** custo dobra—paga duas consultas para obter uma resposta; circuit breaker precisa ser mais sensível para evitar disparo duplo quando ambos estão degradados.
Primary + shadow (canary)
Envia 95 % do tráfego para bureau principal (Serasa), 5 % para secundário (SPC Brasil) em modo shadow: resposta shadow é logada mas descartada. Uso típico: validar novo bureau antes de promover a produção, comparar scores entre fornecedores para calibrar modelo próprio. **Desvantagem:** custo de 5 % de consultas shadow sem retorno funcional imediato.
Considerações de Segurança e Compliance
Proteção de dado sensível em trânsito e repouso
Documentos trafegam hasheados (SHA-256) em logs; payload completo circula apenas entre gateway ↔ orquestrador ↔ adaptador, todos dentro de VPC privada com security group restritivo. Cache Redis ativa encryption-at-rest (AES-256) e encryption-in-transit (TLS 1.3). Secret Manager rotaciona client secrets de bureaus a cada 90 dias, notificando equipe de engenharia via webhook 7 dias antes da expiração.
Auditoria Circular 3.909 BACEN
Log Kafka retém eventos por 2.555 dias (~7 anos), atendendo prazo de guarda de documento cadastral. Query Athena permite responder auditoria: "liste todas as consultas ao CPF 123.456.789-09 realizadas por operador usr_98234 entre 01/03/2024 e 31/03/2024, discriminando bureau, finalidade e timestamp".
Rate limiting e prevenção de abuso
Client_id backoffice-cobranca tem cota 10 req/min; se ultrapassa, API Gateway retorna HTTP 429 com header Retry-After: 42. Detecta padrão de consulta sequencial de CPFs (possível scraping) e bloqueia client_id temporariamente, notificando security officer.
Implementação Incremental: Roadmap de 90 Dias
Sprint 1–3: Gateway + adaptador Serasa
Deploy de API Gateway com endpoint /v1/consulta, autenticação OAuth e rate limiting básico. Implementa adaptador Serasa (bureau com maior volume) e orquestrador simples sem fallback. Migra 10 % do tráfego de originação pessoa física; compara latência e taxa de erro com integração legada.
Sprint 4–6: Adaptadores SPC e Boa Vista + fallback waterfall
Adiciona adaptadores SPC Brasil e Boa Vista. Implementa lógica waterfall no orquestrador e circuit breaker Resilience4j. Migra 50 % do tráfego; ajusta timeouts com base em latência P95 observada em produção.
Sprint 7–9: Cache Redis, auditoria Kafka e observabilidade
Provisiona cluster Redis (master + 2 réplicas) e configura TTL por produto. Implementa interceptor Kafka e dashboard Grafana. Migra 100 % do tráfego, descomissiona integrações ponto-a-ponto legadas.
Resultados Esperados e Métricas de Sucesso
- Disponibilidade efetiva: subida de 98,2 % (SLA composto três bureaus) para 99,6 % (fallback automático).
- Latência P95: redução de 4.800 ms (três chamadas sequenciais sem cache) para 2.100 ms (cache hit 35 %, fallback otimizado).
- Custo de consulta: redução de 18 % via cache (24 h TTL elimina duplicações de re-análise).
- Time to market: nova regra de negócio que consome dado de bureau entra em produção em 2 dias (consome API unificada) vs. 8 dias (implementar cliente novo bureau).
- Auditoria: tempo de resposta a solicitação BACEN cai de 4 horas (query manual em três bancos SQL) para 12 minutos (query Athena no Data Lake).
Perguntas Frequentes
Posso usar hub integrador mesmo mantendo contratos diretos com Serasa, SPC e Boa Vista?
Sim. Arquitetura de referência pressupõe que sua instituição financeira já possui contratos e credenciais de API com os bureaus. Hub atua como camada de abstração interna; você continua pagando diretamente a cada fornecedor conforme consumo medido.
Como lidar com diferenças de modelo de score entre bureaus?
Adaptador de cada bureau mapeia escala proprietária (SPC 1–1.000, Serasa 0–1.000, Boa Vista 0–100) para escala canônica interna 0–100. Motor de regras da esteira de crédito consome apenas escala canônica, isolando mudanças futuras de cálculo de score do fornecedor. Alternativa: expor score bruto + bureau no payload de resposta e deixar motor de regras decidir qual usar.
Fallback automático entre bureaus não gera inconsistência de decisão?
Sim, há trade-off. Cliente A consultado via Serasa recebe score 680; cliente B consultado via SPC (fallback) recebe score 672 para perfil equivalente. Mitigações: (1) calibrar faixas de decisão do motor de regras para tolerar variação ±15 pontos; (2) logar bureau utilizado e incluir em análise de safra para detectar viés; (3) reservar fallback apenas para timeouts/5xx, nunca para HTTP 200 com score fora do esperado.
Quanto tempo de cache é seguro sem violar requisito de dado atualizado?
Depende da política de crédito. Originação de empréstimo pessoal com decisão automática até R$ 5 mil: cache 24 h é aceitável (risco baixo, conveniência alta). Financiamento de veículo R$ 80 mil com margem apertada: cache máximo 1 h ou desabilitar cache e sempre consultar bureau em tempo real. Considere também janela de atualização do bureau: protestos entram em base Serasa com delay D+0 a D+1.
Como garantir que timeout de 4 s não estoura capacity de thread pool?
Configure HTTP client async (não-bloqueante): Java WebClient reativo, .NET HttpClient com async/await, Node.js nativo. Pool de threads dedicado ao I/O de bureaus separado do pool que atende requisições de API; bulkhead Resilience4j limita 50 chamadas concorrentes a bureaus, enfileira excedente e rejeita com HTTP 503 se fila > 200. Monitor alerta quando fila > 50 por 5 min consecutivos, indicando necessidade de escalar pods ou negociar SLA melhor com bureau.
Quer desenhar hub integrador de bureaus adaptado à realidade da sua instituição financeira? Nossa equipe de arquitetura já implementou camadas de abstração para cooperativas de crédito, financeiras de veículos e seguradoras que operam esteiras de 500 a 15.000 propostas/mês. Converse conosco e receba análise de viabilidade técnica sem custo.
