Prevenção de fraude em e-commerce: validação de CPF na prática

O e-commerce brasileiro perde bilhões anualmente com fraudes de identidade, chargebacks e cadastros falsos. A validação de CPF no momento do cadastro ou checkout é a primeira barreira eficaz — ela confirma que o documento existe, está ativo e pertence à pessoa que o informa. A API SmartCPF resolve isso com uma consulta em tempo real que retorna dados cadastrais completos, status do CPF na Receita Federal e informações de contato verificadas, permitindo decisões automáticas de aprovação, revisão ou bloqueio.

Integrar essa validação cedo no fluxo — seja no cadastro, no login ou antes de autorizar um pagamento — reduz drasticamente tentativas de uso de CPFs inexistentes, de terceiros ou de pessoas falecidas. O retorno estruturado da API permite criar regras de risco baseadas em dados reais (idade, status, consultId para auditoria, balance de créditos) sem depender de bases locais desatualizadas.

Validação de CPF como camada de risco

A validação vai além de conferir o dígito verificador. A consulta à base oficial indica se o CPF está Regular, Suspenso, Cancelado, Titular falecido ou Nulo — cada status exige tratamento diferente. Um CPF "Regular" com nome e data de nascimento compatíveis com o informado pelo usuário aumenta a confiança; status "Suspenso" ou "Cancelado" bloqueiam a operação automaticamente; "Titular falecido" dispara alerta de fraude de identidade. A API também retorna emails e telefones cadastrados, úteis para verificação de posse (envio de OTP) e enriquecimento de perfil de risco.

Vantagens da validação em tempo real

1. Bloqueio imediato de CPFs inválidos
CPFs inexistentes, mal formados ou cancelados são rejeitados antes de gerar custo de processamento de pedido ou análise manual.

2. Detecção de identidade sintética
Cruzando nome, data de nascimento e nome da mãe retornados pela API com os dados informados no cadastro, detecta-se combinações que não existem na base oficial — padrão comum em fraudes de identidade sintética.

3. Controle de custo por consulta O campo balance no retorno mostra o saldo de créditos em tempo real, evitando interrupções de serviço por falta de quota e permitindo alertas automáticos de recarga.

4. Enriquecimento para regras de risco Emails, telefones (com operadora, tipo, WhatsApp) e endereços retornados alimentam motores de risco: telefone VoIP, email temporário ou endereço em CEP de risco aumentam o score de fraude.

5. Integração sem manutenção de base local A API consulta a fonte oficial a cada chamada — não há necessidade de sincronizar, hospedar ou atualizar bases de CPF localmente.

Desafios e o que considerar

1. Falsos positivos por dados desatualizados Usuários que mudaram telefone/email recentemente podem parecer inconsistentes. Trate divergências como "revisão manual" em vez de bloqueio direto.

2. Dependência de disponibilidade da API Implemente circuit breaker e fallback: se a API falhar, aceite o cadastro com flag de "validar depois" e reprocesse em background.

3. Custo por volume alto Modelo de créditos exige planejamento de recarga. Monitore balance e configure alertas (ex.: < 100 créditos) para evitar indisponibilidade.

4. LGPD e consentimento A consulta retorna dados pessoais. Garanta que seu termo de uso autoriza a validação de CPF junto a bureaus/fontes oficiais e que o usuário é informado.

Como implementar com a SmartCPF

O fluxo abaixo valida o CPF no momento do cadastro ou checkout, trata erros de rede e autenticação, e extrai os campos relevantes para decisão de risco. Substitua SUA_API_KEY pela chave gerada no painel da SmartCPF.

/**
 * Valida CPF via API SmartCPF v2
 * Retorna objeto com: aprovado (boolean), dados (result), consultId, balance, erro
 */
async function validarCpfSmartCPF(cpf, apiKey) {
  // Remove formatação: apenas dígitos
  const cpfLimpo = cpf.replace(/\D/g, '');

  // Validação básica de formato antes de chamar a API
  if (cpfLimpo.length !== 11 || /^(\d)\1+$/.test(cpfLimpo)) {
    return { aprovado: false, erro: 'CPF inválido (formato)', dados: null };
  }

  const url = `https://api.smartcpf.com.br/v2/individuals/${cpfLimpo}?package=complete`;

  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'X-API-KEY': apiKey,        // Autenticação obrigatória via header
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      // Timeout de 5s para não travar o checkout
      signal: AbortSignal.timeout(5000)
    });

    const data = await response.json();

    // HTTP 200 mas success=false = CPF não encontrado ou erro de negócio
    if (!data.success) {
      return {
        aprovado: false,
        erro: data.errors?.[0]?.message || 'CPF não encontrado',
        dados: null,
        consultId: data.meta?.consultId,
        balance: data.meta?.balance
      };
    }

    // HTTP erro (401, 403, 429, 5xx)
    if (!response.ok) {
      return {
        aprovado: false,
        erro: `Erro HTTP ${response.status}: ${data.message || 'Falha na consulta'}`,
        dados: null,
        consultId: data.meta?.consultId,
        balance: data.meta?.balance
      };
    }

    const resultado = data.result;
    const meta = data.meta;

    // Regra de negócio: só aprova se status for "Regular"
    const statusRegular = resultado.status === 'Regular';
    const nomeConfere = resultado.name && resultado.name.length > 0;
    const idadeValida = resultado.age && resultado.age >= 18;

    return {
      aprovado: statusRegular && nomeConfere && idadeValida,
      dados: {
        cpf: resultado.cpf,
        nome: resultado.name,
        nascimento: resultado.birthDate,
        idade: resultado.age,
        nomeMae: resultado.motherName,
        genero: resultado.gender,
        status: resultado.status,
        emails: resultado.emails,
        telefones: resultado.phones,
        enderecos: resultado.addresses
      },
      consultId: meta.consultId,
      balance: meta.balance,
      executionTimeMs: meta.executionTimeMs
    };

  } catch (err) {
    // Erro de rede, timeout, CORS, etc.
    if (err.name === 'AbortError' || err.name === 'TimeoutError') {
      return { aprovado: false, erro: 'Timeout na consulta (5s)', dados: null };
    }
    return { aprovado: false, erro: `Erro de rede: ${err.message}`, dados: null };
  }
}

// Exemplo de uso no fluxo de cadastro/checkout
async function processarCadastro(usuario) {
  const apiKey = process.env.SMARTCPF_API_KEY; // Nunca hardcode a chave
  const validacao = await validarCpfSmartCPF(usuario.cpf, apiKey);

  if (!validacao.aprovado) {
    // Log para auditoria com consultId (se houver)
    console.warn('[CADASTRO BLOQUEADO]', {
      cpf: usuario.cpf.replace(/\d(?=\d{4})/g, '*'),
      motivo: validacao.erro,
      consultId: validacao.consultId,
      balanceRestante: validacao.balance
    });
    throw new Error(`Cadastro não autorizado: ${validacao.erro}`);
  }

  // CPF válido e regular — prossegue com criação de conta/pedido
  console.info('[CADASTRO APROVADO]', {
    cpf: usuario.cpf.replace(/\d(?=\d{4})/g, '*'),
    consultId: validacao.consultId,
    balanceRestante: validacao.balance,
    tempoRespostaMs: validacao.executionTimeMs
  });

  // Dados enriquecidos disponíveis em validacao.dados para salvar no perfil
  return { ...usuario, cpfValidado: true, dadosCpf: validacao.dados };
}

Resposta da API

{
  "meta": {
    "searchType": "CPF C",
    "consultId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user": "Minha Loja Ltda",
    "message": "CPF encontrado com sucesso",
    "ip": "203.0.113.45",
    "success": true,
    "apiVersion": "v2",
    "date": "2026-08-10T14:32:11.123Z",
    "executionTimeMs": 74.1,
    "balance": 987.50
  },
  "result": {
    "cpf": "111.111.111-11",
    "name": "João da Silva",
    "birthDate": "10/09/1992",
    "age": 33,
    "motherName": "Maria da Silva",
    "gender": "M",
    "status": "Regular",
    "emails": ["[email protected]"],
    "phones": [
      {
        "number": "(11) 99999-9999",
        "blockedTelemarketing": false,
        "operator": "VIVO",
        "type": "CELULAR",
        "whatsapp": true
      }
    ],
    "addresses": [
      {
        "cep": "01310-100",
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Sala 501",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP"
      }
    ]
  },
  "success": true,
  "errors": []
}

O fluxo demonstrado resolve na prática:

• Bloqueia CPFs inexistentes ou irregulares antes de criar conta ou autorizar pagamento (campo status ≠ "Regular")
• Garante maioridade via age ≥ 18 para cumprir políticas de venda restrita
• Auditoria completa com consultId em cada log, permitindo rastrear qual consulta liberou ou bloqueou cada transação
• Monitoramento de custo via balance retornado a cada chamada — integra-se a alertas de recarga automática
• Enriquecimento de perfil com emails, phones (incluindo operator, type, whatsapp) e addresses para regras de risco e comunicação futura
• Resiliência com timeout de 5s, tratamento de erros HTTP e de rede, evitando travamento do checkout

Por que usar a SmartCPF

• Latência baixa (~70ms médio) com SLA de 99,9% — não impacta conversão no checkout
• Integração REST simples — uma única chamada GET com header X-API-KEY, sem OAuth, tokens ou fluxos complexos
• Modelo de créditos pré-pagos — paga apenas pelo que usa, sem mensalidade mínima; balance em tempo real no retorno
• Escala horizontal — suporta picos de Black Friday, lançamentos e campanhas sem degradação
• Dados sempre atuais — consulta direta na fonte oficial a cada requisição, sem cache stale ou bases desatualizadas

Conclusão

Validar CPF em tempo real com a SmartCPF transforma a prevenção de fraude de um processo reativo (análise pós-chargeback) para uma barreira ativa no momento do cadastro ou pagamento. O retorno estruturado — status oficial, dados cadastrais, consultId para auditoria e balance para controle de custo — dá ao time de produto e risco os insumos necessários para decisões automáticas, seguras e auditáveis. Crie sua conta na SmartCPF e faça sua primeira consulta em minutos.