Como implementar scoring de risco baseado em CPF para aprovação automática de pedidos

Implementar scoring de risco baseado em CPF significa atribuir uma pontuação automática a cada pedido cruzando os dados cadastrais retornados pela API CPFHub.io com variáveis da transação — nome, data de nascimento, valor e histórico do cliente. Com esse modelo, e-commerces reduzem a dependência de revisão manual, aprovam pedidos legítimos mais rápido e bloqueiam fraudes antes do despacho.

Introdução

A análise manual de pedidos é um gargalo que limita a escalabilidade de qualquer operação de e-commerce. Quando cada transação precisa ser revisada por um analista humano, o tempo entre a compra e o despacho aumenta, a experiência do cliente é prejudicada e os custos operacionais crescem. A solução é implementar um sistema de scoring de risco que avalie automaticamente cada pedido com base em múltiplos fatores, incluindo a validação de CPF.

O que é scoring de risco para pedidos

O scoring de risco é uma técnica que atribui uma pontuação numérica a cada pedido com base em fatores que indicam a probabilidade de a transação ser legítima ou fraudulenta. A decisão de aprovar, revisar ou bloquear o pedido é automatizada com base nessa pontuação.

Fatores típicos de um modelo de scoring

• Validação de identidade — Verificar se o CPF existe e se os dados conferem.

• Histórico do cliente — Número de compras anteriores, reclamações, devoluções.

• Comportamento da sessão — Tempo de navegação, número de tentativas de pagamento, dispositivo utilizado.

• Valor do pedido — Pedidos de alto valor representam maior risco.

• Dados de pagamento — Consistência entre o titular do cartão e o comprador.

• Geolocalização — Divergência entre o IP de acesso e o endereço de entrega.

O papel da validação de CPF no scoring

A consulta à API da CPFHub.io permite verificar dados cadastrais reais do titular do CPF. Esses dados são fundamentais para o scoring porque permitem cruzamentos que um fraudador dificilmente conseguiria burlar:

Quando o nome informado pelo comprador corresponde exatamente ao nome retornado pela API, a pontuação de confiança aumenta significativamente. Quando há divergência, o sistema pode escalar para revisão manual ou solicitar verificação adicional.

Arquitetura do sistema de scoring

O sistema funciona em três camadas:

Camada 1 — Coleta de dados

O front-end coleta CPF, nome, data de nascimento e dados de pagamento. Uma validação sintática do CPF é feita no navegador para evitar envios de formatos inválidos.

Camada 2 — Enriquecimento via API

O back-end consulta a API da CPFHub.io e enriquece os dados do pedido com as informações cadastrais reais. Essa etapa fornece os dados necessários para a comparação.

Camada 3 — Cálculo do score e decisão

Um algoritmo calcula a pontuação com base nos fatores definidos e aplica as regras de decisão para aprovar, revisar ou bloquear o pedido.

Implementação em Python

import requests
from difflib import SequenceMatcher
from datetime import datetime

CPFHUB_API_KEY = 'SUA_CHAVE_DE_API'

PESOS = {
    'nome': 35,
    'nascimento': 25,
    'cpf_ativo': 15,
    'valor': 15,
    'historico': 10,
}

def consultar_cpf(cpf: str) -> dict:
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    headers = {
    'x-api-key': CPFHUB_API_KEY,
    'Accept': 'application/json'
    }
    response = requests.get(url, headers=headers, timeout=10)
    return response.json()

def similaridade_nome(nome_a: str, nome_b: str) -> float:
    return SequenceMatcher(
    None,
    nome_a.upper().strip(),
    nome_b.upper().strip()
    ).ratio()

def calcular_score(pedido: dict) -> dict:
    score = 0
    detalhes = []

    # 1. Consultar CPF
    resultado = consultar_cpf(pedido['cpf'])

    if not resultado.get('success'):
    return {
    'score': 0,
    'risco': 'CRITICO',
    'decisao': 'BLOQUEAR',
    'detalhes': ['CPF nao encontrado na base']
    }

    dados = resultado['data']

    # 2. Verificar nome
    sim = similaridade_nome(pedido['nome'], dados['name'])
    if sim >= 0.9:
    score += PESOS['nome']
    detalhes.append(f'Nome confere ({sim:.0%})')
    elif sim >= 0.7:
    score += PESOS['nome'] * 0.5
    detalhes.append(f'Nome parcialmente confere ({sim:.0%})')
    else:
    detalhes.append(f'Nome divergente ({sim:.0%})')

    # 3. Verificar data de nascimento
    if pedido.get('nascimento') == dados['birthDate']:
    score += PESOS['nascimento']
    detalhes.append('Data de nascimento confere')
    elif pedido.get('nascimento'):
    detalhes.append('Data de nascimento divergente')
    else:
    score += PESOS['nascimento'] * 0.3
    detalhes.append('Data de nascimento nao informada')

    # 4. CPF ativo
    score += PESOS['cpf_ativo']
    detalhes.append('CPF encontrado na base')

    # 5. Valor do pedido
    valor = pedido.get('valor', 0)
    if valor <= 300:
    score += PESOS['valor']
    detalhes.append('Valor baixo risco')
    elif valor <= 1500:
    score += PESOS['valor'] * 0.6
    detalhes.append('Valor risco moderado')
    else:
    detalhes.append('Valor alto risco')

    # 6. Historico do cliente
    compras_anteriores = pedido.get('compras_anteriores', 0)
    if compras_anteriores >= 5:
    score += PESOS['historico']
    detalhes.append('Cliente recorrente')
    elif compras_anteriores >= 1:
    score += PESOS['historico'] * 0.5
    detalhes.append('Cliente com historico limitado')
    else:
    detalhes.append('Primeira compra')

    # Decisao
    if score >= 75:
    decisao = 'APROVAR'
    risco = 'BAIXO'
    elif score >= 45:
    decisao = 'REVISAR'
    risco = 'MEDIO'
    else:
    decisao = 'BLOQUEAR'
    risco = 'ALTO'

    return {
    'score': round(score),
    'risco': risco,
    'decisao': decisao,
    'detalhes': detalhes
    }

# Exemplo de uso
pedido = {
    'cpf': '12345678900',
    'nome': 'Joao da Silva',
    'nascimento': '15/06/1990',
    'valor': 250.00,
    'compras_anteriores': 3
}

resultado = calcular_score(pedido)
print(resultado)

Regras de decisão recomendadas

Essas faixas devem ser calibradas com base nos dados reais da sua operação. Comece com valores conservadores e ajuste conforme acumula histórico de fraudes e transações legítimas. A FEBRABAN recomenda revisão periódica dos modelos antifraude para adaptação a novos padrões de ataque.

Calibração e evolução do modelo

Métricas de acompanhamento

Para garantir que o modelo funcione corretamente, monitore:

• Taxa de falsos positivos — Pedidos legítimos bloqueados incorretamente. Se estiver alta, relaxe os critérios.

• Taxa de falsos negativos — Fraudes que passaram pelo sistema. Se estiver alta, reforce os critérios.

• Distribuição de scores — Analise como os scores se distribuem para identificar concentrações em faixas específicas.

Ajuste contínuo

• Revise os pesos mensalmente com base nos resultados reais.

• Adicione novos fatores conforme identifica padrões de fraude (por exemplo, faixas de horário, tipos de produto).

• Considere utilizar machine learning para ajustar os pesos automaticamente quando o volume de dados for suficiente.

Integração com plataformas de e-commerce

O sistema de scoring pode ser integrado como um middleware que intercepta a criação de cada pedido:

• Shopify / WooCommerce — Webhook que dispara a análise antes de confirmar o pedido.

• Magento / VTEX — Plugin customizado que chama o serviço de scoring no checkout.

• Plataforma própria — Middleware no back-end que processa a validação antes de enviar para o gateway de pagamento.

Em todos os casos, o fluxo é o mesmo: receber os dados do pedido, consultar a API da CPFHub.io, calcular o score e retornar a decisão.

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna nome do titular, data de nascimento e gênero em cerca de 900ms, permitindo cruzamento em tempo real durante o checkout.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos menores. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional, sem interrupção do serviço.

Como garantir conformidade com a LGPD ao usar uma API de CPF para scoring?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário, implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Como calibrar o modelo de scoring para meu negócio específico?

Comece com os pesos sugeridos (nome 35%, nascimento 25%, CPF ativo 15%, valor 15%, histórico 10%) e colete dados por pelo menos 30 dias. Em seguida, compare os resultados com as fraudes confirmadas e pedidos legítimos para ajustar os pesos. Revisões mensais são recomendadas nas primeiras fases do modelo.

Conclusão

Um sistema de scoring de risco baseado em validação de CPF permite que e-commerces automatizem a aprovação de pedidos com segurança, reduzindo a dependência de análises manuais e acelerando o processamento de transações legítimas. A chave está em combinar a validação de identidade com outros fatores de risco e calibrar o modelo continuamente.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a construir seu sistema de scoring de risco com dados cadastrais reais hoje mesmo.