# Como implementar regras de antifraude baseadas em CPF com machine learning

> Aprenda a combinar validação de CPF via API com modelos de machine learning para criar regras de antifraude inteligentes no e-commerce.

**Publicado:** 28/06/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/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](https://www.cert.br/stats/), 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

```bash
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

```python
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**](https://www.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.

### Leia também

- [Golpe do CPF clonado em compras online: como detectar e prevenir](https://cpfhub.io/blog/golpe-cpf-clonado-compras-online-detectar-prevenir)
- [Score antifraude com validação de CPF: como funciona](https://cpfhub.io/blog/score-antifraude-com-validacao-de-cpf-como-funciona)
- [APIs antifraude com validação de CPF: como funcionam](https://cpfhub.io/blog/apis-antifraude-com-validacao-de-cpf-como-funcionam)
- [Como detectar compras fraudulentas com validação de CPF](https://cpfhub.io/blog/como-detectar-compras-fraudulentas-com-validacao-de-cpf)

---

## 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**](https://www.cpfhub.io/)

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)