Como implementar regras de antifraude baseadas em CPF com machine learning

Para implementar antifraude com CPF e machine learning, combine os dados retornados pela API de validação (nome, data de nascimento, consistência) com features comportamentais — velocidade de digitação, histórico de compras por CPF, frequência de tentativas — e alimente um modelo que classifica transações por nível de risco em tempo real. Segundo o CERT.br, os incidentes de fraude de identidade digital no Brasil crescem ano a ano, tornando a validação de CPF uma camada de proteção cada vez mais essencial para operações online.

Sistemas de antifraude tradicionais operam com regras estáticas -- se o valor excede X, se o CEP é Y, se o horário é Z, a transação é bloqueada. Embora eficazes contra padrões conhecidos, essas regras falham diante de fraudadores que adaptam suas táticas constantemente. O machine learning (ML) oferece uma abordagem dinâmica que aprende com dados históricos e se adapta a novos padrões de fraude.

A validação de CPF via API é uma fonte rica de features (variáveis) para modelos de ML. Os dados retornados -- como nome, gênero e data de nascimento -- combinados com informações da transação e do histórico do CPF, permitem construir modelos preditivos que identificam fraudes com alta precisão e baixa taxa de falsos positivos.

Features derivadas do CPF

A validação de CPF via API fornece dados que, quando processados, geram features valiosas para modelos de ML.

Features diretas

• cpf_valido: se o CPF retornou dados (booleano).
• nome_match: grau de similaridade entre o nome informado e o retornado pela API (0 a 1).
• genero: gênero retornado pela API.
• idade: calculada a partir da data de nascimento.

Features derivadas

• idade_vs_categoria: relação entre a idade do titular e a categoria do produto. Uma compra de fralda por alguém de 20 anos é normal; por alguém de 70, pode ser legítima (avós), mas merece atenção.
• cpf_idade_conta: diferença entre a idade do CPF (data de nascimento) e a idade da conta na plataforma. Contas recentes com CPFs de pessoas mais velhas podem indicar uso de dados de terceiros.
• frequencia_cpf: quantidade de transações do mesmo CPF em determinado período.
• cpf_endereco_match: se o nome associado ao CPF aparece no endereço de entrega (mesmo sobrenome, por exemplo).

Arquitetura do sistema

Pipeline completo

1. Transação chega ao sistema.
2. CPF é validado via API da CPFHub.io.
3. Features são extraídas e calculadas.
4. Modelo de ML calcula o score de risco.
5. Regras de decisão determinam a ação (aprovar, revisar, bloquear).

Exemplo com cURL para alimentar o pipeline

curl -X GET "https://api.cpfhub.io/cpf/12312312300" \
    -H "x-api-key: SUA_API_KEY" \
    -H "Accept: application/json" \
    --timeout 10

Implementação prática

Exemplo em Python com scikit-learn

import requests
import os
import numpy as np
from datetime import datetime
from sklearn.ensemble import GradientBoostingClassifier
from sklearn.model_selection import train_test_split
from sklearn.metrics import classification_report
import joblib

class CPFFeatureExtractor:
    """
    Extrai features de antifraude a partir da validação de CPF.
    """

    API_URL = "https://api.cpfhub.io/cpf"

    def __init__(self):
    self.api_key = os.environ.get("CPFHUB_API_KEY")

    def validar_cpf(self, cpf):
    try:
    response = requests.get(
    f"{self.API_URL}/{cpf}",
    headers={
    "x-api-key": self.api_key,
    "Accept": "application/json",
    },
    timeout=10,
    )
    return response.json()
    except requests.exceptions.RequestException:
    return None

    def extrair_features(self, transacao):
    """
    Extrai features de uma transação para o modelo de ML.
    Retorna array de features numéricas.
    """
    cpf = transacao["cpf"]
    resultado = self.validar_cpf(cpf)

    features = {}

    # Feature 1: CPF válido
    features["cpf_valido"] = 1 if (
    resultado and resultado.get("success")
    ) else 0

    if not resultado or not resultado.get("success"):
    # Preencher com valores padrão para CPF inválido
    features["nome_match"] = 0.0
    features["idade"] = 0
    features["genero_match"] = 0
    features["idade_vs_valor"] = 0.0
    return features

    dados = resultado["data"]

    # Feature 2: Similaridade de nome (0 a 1)
    nome_api = dados["nameUpper"]
    nome_transacao = transacao.get("nome", "").upper().strip()
    if nome_api and nome_transacao:
    # Similaridade simples por tokens
    tokens_api = set(nome_api.split())
    tokens_trans = set(nome_transacao.split())
    if tokens_api:
    features["nome_match"] = len(
    tokens_api & tokens_trans
    ) / len(tokens_api)
    else:
    features["nome_match"] = 0.0
    else:
    features["nome_match"] = 0.0

    # Feature 3: Idade
    if dados.get("year"):
    features["idade"] = datetime.now().year - int(dados["year"])
    else:
    features["idade"] = 0

    # Feature 4: Gênero consistente com o nome informado
    features["genero_match"] = 1 # Simplificado

    # Feature 5: Relação idade vs valor da transação
    valor = transacao.get("valor", 0)
    if features["idade"] > 0:
    features["idade_vs_valor"] = valor / features["idade"]
    else:
    features["idade_vs_valor"] = valor

    return features

def treinar_modelo(dados_historicos):
    """
    Treina modelo de antifraude com dados históricos.
    """
    extractor = CPFFeatureExtractor()

    X = []
    y = []

    for transacao in dados_historicos:
    features = extractor.extrair_features(transacao)
    feature_vector = [
    features["cpf_valido"],
    features["nome_match"],
    features["idade"],
    features["genero_match"],
    features["idade_vs_valor"],
    ]
    X.append(feature_vector)
    y.append(transacao["fraude"]) # 0 ou 1

    X = np.array(X)
    y = np.array(y)

    X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
    )

    modelo = GradientBoostingClassifier(
    n_estimators=100,
    max_depth=5,
    random_state=42,
    )
    modelo.fit(X_train, y_train)

    # Avaliar
    y_pred = modelo.predict(X_test)
    print(classification_report(y_test, y_pred))

    # Importância das features
    feature_names = [
    "cpf_valido",
    "nome_match",
    "idade",
    "genero_match",
    "idade_vs_valor",
    ]
    for name, importance in zip(
    feature_names, modelo.feature_importances_
    ):
    print(f" {name}: {importance:.4f}")

    # Salvar modelo
    joblib.dump(modelo, "modelo_antifraude.joblib")
    return modelo

def avaliar_transacao(modelo, transacao):
    """
    Avalia uma nova transação usando o modelo treinado.
    """
    extractor = CPFFeatureExtractor()
    features = extractor.extrair_features(transacao)

    feature_vector = np.array([[
    features["cpf_valido"],
    features["nome_match"],
    features["idade"],
    features["genero_match"],
    features["idade_vs_valor"],
    ]])

    probabilidade_fraude = modelo.predict_proba(feature_vector)[0][1]

    # Regras de decisão
    if probabilidade_fraude < 0.3:
    decisao = "aprovar"
    elif probabilidade_fraude < 0.7:
    decisao = "revisar"
    else:
    decisao = "bloquear"

    return {
    "score_fraude": round(probabilidade_fraude, 4),
    "decisao": decisao,
    "features": features,
    }

Regras híbridas: ML + regras estáticas

O melhor sistema de antifraude combina modelos de ML com regras estáticas que capturam padrões conhecidos e inegociáveis.

Regras estáticas de CPF

• CPF inválido (não retorna dados): bloquear imediatamente.
• Nome totalmente divergente (match < 0.3): enviar para revisão.
• Mais de 5 transações do mesmo CPF em 24 horas: sinalizar.
• CPF na blacklist: bloquear imediatamente.

Regras de ML

O modelo avalia o conjunto completo de features e atribui um score contínuo de risco, capturando padrões sutis que regras estáticas não detectam.

Orquestração

Transação -> Regras Estáticas -> [se não bloqueada] -> Modelo ML -> Decisão Final

Se uma regra estática bloquear, o ML nem é consultado. Se a regra estática aprovar, o ML tem a palavra final.

Retreino e monitoramento

Retreino periódico

Modelos de ML degradam com o tempo à medida que fraudadores adaptam suas táticas. O retreino deve ser realizado pelo menos mensalmente, incorporando as transações mais recentes e os resultados das revisões manuais.

Métricas de monitoramento

• Taxa de detecção (recall): percentual de fraudes reais que o modelo identificou.
• Precisão: percentual de alertas que eram realmente fraude.
• Taxa de falsos positivos: clientes legítimos bloqueados erroneamente.
• Tempo de decisão: latência total do pipeline (validação de CPF + ML).

Detecção de drift

Monitorar a distribuição das features ao longo do tempo. Se a distribuição mudar significativamente (por exemplo, aumento repentino de CPFs inválidos), pode indicar um ataque coordenado ou mudança no perfil de clientes.

Performance do sistema

O tempo total do pipeline depende de cada componente:

• Validação de CPF via API: ~900 milissegundos.
• Extração de features: ~10 milissegundos.
• Inferência do modelo ML: ~5 milissegundos.
• Total: menos de 1 segundo por transação.

Esse tempo é compatível com avaliação em tempo real no checkout. A API da CPFHub.io

O plano Pro (R$ 149/mês, 1.000 consultas) atende operações de médio porte, enquanto planos corporativos são disponíveis para grandes volumes.

Perguntas frequentes

Quais dados do CPF são úteis como features para modelos de ML?

Os mais relevantes são: resultado da validação (encontrado/não encontrado), correspondência nome declarado × nome oficial, distância entre data de nascimento declarada e data oficial, frequência de uso do CPF em janelas de tempo e consistência entre CPF e outros dados (e-mail, endereço, telefone).

Quanto de histórico é necessário para treinar um modelo antifraude com CPF?

Depende do volume de transações, mas modelos eficazes geralmente precisam de pelo menos 6 meses de dados com rótulos de fraude confirmada. Em operações menores, regras baseadas em score (sem ML) usando os dados da API já entregam bons resultados.

Machine learning substitui a validação de CPF via API?

Não. O ML usa os dados retornados pela API como entrada. Sem a consulta à base cadastral, o modelo não tem a informação mais importante: se o CPF existe e se os dados declarados correspondem aos oficiais.

Como lidar com falsos positivos em modelos antifraude?

Implemente um fluxo de revisão manual para transações classificadas como risco médio. Compras bloqueadas erroneamente geram abandono de carrinho e reclamações. O threshold ideal equilibra taxa de fraude capturada com taxa de falsos positivos aceitável para o negócio.

Conclusão

A combinação de validação de CPF via API com machine learning cria um sistema de antifraude que é ao mesmo tempo preciso e adaptável. Os dados retornados pela API da CPFHub.io fornecem features valiosas que, alimentando modelos de ML, permitem detectar padrões de fraude que regras estáticas sozinhas não capturam.

A CPFHub.io

Cadastre-se em cpfhub.io