CPF inválido, inexistente ou irregular: entenda as diferenças

Validar CPFs parece trivial até o sistema aceitar um número matematicamente correto que não pertence a ninguém — ou rejeitar um CPF real por confusão entre "inválido" e "irregular". A distinção técnica entre esses três estados impacta diretamente onboarding, compliance e prevenção de fraude. A API SmartCPF resolve essa ambiguidade retornando o status exato do documento na Receita Federal, eliminando suposições no seu fluxo de cadastro.

Quando um usuário informa o CPF no seu formulário, três cenários distintos podem ocorrer: o algoritmo de validação falha (dígitos verificadores incorretos), o CPF passa no algoritmo mas não existe na base da Receita, ou o CPF existe mas possui pendências cadastrais. Tratar todos como "CPF inválido" gera falsos positivos que bloqueiam usuários legítimos ou, pior, falsos negativos que deixam fraudes passarem.

O que define cada classificação de CPF

CPF inválido significa falha na verificação matemática dos dígitos verificadores (DV). O algoritmo do Ministério da Fazenda calcula dois dígitos a partir dos nove primeiros; se o número informado não confere, ele é estruturalmente impossível — nunca foi emitido e nunca será. Essa validação é determinística e não requer consulta externa.

CPF inexistente passa na validação matemática mas não consta na base de dados da Receita Federal. Pode ser um número gerado aleatoriamente que "acertou" os DVs, ou um CPF que foi cancelado por óbito/duplicidade e removido da base ativa. A única forma de confirmar é consultar o órgão emissor.

CPF irregular existe na base da Receita mas possui restrições cadastrais: suspenso (pendência de regularização), cancelado (duplicidade, fraude ou óbito não comunicado), ou nulo (decisão judicial). O titular está impedido de exercer direitos civis plenos — abrir conta, emitir nota fiscal, participar de licitações — até regularizar a situação.

Vantagens de distinguir os três estados

1. Prevenção de fraude precisa
Bloquear apenas CPFs inválidos deixa passar números inexistentes gerados por algoritmos. A distinção permite criar regras: rejeitar inválidos na hora, sinalizar inexistentes para revisão manual, e bloquear irregulares conforme política de risco.

2. Redução de falsos positivos no onboarding
Usuários com CPF irregular (ex: pendência de título de eleitor) não são fraudadores. Separar "irregular" de "inválido" evita rejeitar clientes legítimos que precisam apenas regularizar a situação junto à Receita.

3. Conformidade com LGPD e bacen
Reguladores exigem demonstração de due diligence. Registrar o status exato (inválido/inexistente/irregular) com consultId rastreável comprova que sua aplicação não apenas "validou" — consultou a fonte oficial.

4. Otimização de custos de verificação
Consultar a Receita tem custo. Validar matematicamente antes (grátis, offline) filtra 90%+ dos erros de digitação. Só gasta crédito na API quando o CPF passa no algoritmo — economia direta em alto volume.

5. Base para score de risco próprio
Com o status granular, seu motor de risco pode atribuir pesos diferentes: inválido = bloqueio hard; inexistente = score alto de fraude; irregular = score médio + fluxo de regularização.

6. Auditorabilidade completa
Cada consulta retorna consultId único e balance atualizado. Em auditoria, você prova exatamente qual CPF foi consultado, quando, qual status retornou e qual decisão seu sistema tomou.

Desafios ao implementar a distinção

1. Latência da consulta oficial
Validação matemática é instantânea; consulta à Receita adiciona 50-200ms. Em fluxos síncronos (checkout, cadastro em tempo real), isso exige UX assíncrona ou cache inteligente para não degradar conversão.

2. Cache e consistência de dados
Status de CPF muda (irregular → regular após regularização). Cache agressivo serve dados desatualizados. TTL recomendado: 24h para regular, 1h para irregular/inexistente, zero para inválido (determinístico).

3. Falsos inexistentes por formatação
CPFs com máscara incorreta (pontos, traços, espaços) podem falhar na normalização antes da consulta. A API SmartCPF aceita "11111111111", "111.111.111-11" ou "111 111 111 11" — mas seu pré-processamento deve garantir normalização consistente.

4. Tratamento de erros de rede/timeout
Se a consulta falha, qual status assumir? "Inválido" bloqueia usuário legítimo; "válido" arrisca fraude. Padrão recomendado: falha aberta com fila de revisão manual, nunca decisão automática baseada em erro de infraestrutura.

5. Edge cases de CPFs especiais
CPFs de estrangeiros (CPF temporário), falecidos recentes (base ainda não atualizada), e decisões judiciais de nulidade criam janelas onde a base oficial diverge da realidade. Monitorar message e status juntos reduz surpresas.

Como implementar com a SmartCPF

A consulta é uma única chamada HTTP GET com autenticação via header X-API-KEY. O parâmetro package define o depth da resposta: basic (apenas status), standard (dados cadastrais), complete (contatos, endereços, score). O exemplo abaixo usa standard — equilíbrio entre custo e informação para decisão de onboarding.

/**
 * Valida CPF via SmartCPF v2 e classifica em: inválido, inexistente, irregular ou regular.
 * Requer: Node 18+ (fetch nativo) ou polyfill.
 */

const API_BASE = 'https://api.smartcpf.com.br/v2';
const API_KEY = process.env.SMARTCPF_API_KEY; // Nunca commite a chave no código

/**
 * Normaliza CPF removendo máscara, espaços e caracteres não numéricos.
 * @param {string} cpfRaw - CPF com ou sem formatação
 * @returns {string} Apenas 11 dígitos
 */
function normalizarCpf(cpfRaw) {
  return cpfRaw.replace(/\D/g, '');
}

/**
 * Validação matemática dos dígitos verificadores (offline, grátis, instantânea).
 * Retorna true se a estrutura é válida, false se inválido.
 * @param {string} cpf - 11 dígitos numéricos
 * @returns {boolean}
 */
function validarDigitosVerificadores(cpf) {
  if (cpf.length !== 11 || /^(\d)\1{10}$/.test(cpf)) return false; // Todos iguais = inválido

  let soma = 0;
  for (let i = 0; i < 9; i++) soma += parseInt(cpf[i]) * (10 - i);
  let dv1 = 11 - (soma % 11);
  if (dv1 >= 10) dv1 = 0;
  if (dv1 !== parseInt(cpf[9])) return false;

  soma = 0;
  for (let i = 0; i < 10; i++) soma += parseInt(cpf[i]) * (11 - i);
  let dv2 = 11 - (soma % 11);
  if (dv2 >= 10) dv2 = 0;
  if (dv2 !== parseInt(cpf[10])) return false;

  return true;
}

/**
 * Consulta a API SmartCPF e retorna status interpretado.
 * @param {string} cpf - 11 dígitos numéricos
 * @returns {Promise<{status: string, dados: object, consultId: string, balance: number}>}
 */
async function consultarCpfSmartcpf(cpf) {
  const url = `${API_BASE}/individuals/${cpf}?package=standard`;

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'X-API-KEY': API_KEY,        // Autenticação obrigatória via header
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();

  if (!response.ok) {
    // Erros HTTP 4xx/5xx: rede, auth, rate limit, CPF não encontrado na base
    const erro = new Error(`SmartCPF ${response.status}: ${data.message || 'Erro desconhecido'}`);
    erro.statusCode = response.status;
    erro.consultId = data.meta?.consultId;
    throw erro;
  }

  // Sucesso HTTP 200 — interpretar status do resultado
  const { result, meta } = data;
  const statusReceita = result?.status; // "Regular", "Irregular", "Suspenso", "Cancelado", "Nulo"

  let classificacao;
  if (statusReceita === 'Regular') classificacao = 'regular';
  else if (['Irregular', 'Suspenso', 'Cancelado', 'Nulo'].includes(statusReceita)) classificacao = 'irregular';
  else classificacao = 'inexistente'; // API retorna 200 mas status não reconhecido = não consta

  return {
    status: classificacao,
    dados: result,
    consultId: meta.consultId,
    balance: meta.balance
  };
}

/**
 * Fluxo completo: valida offline → consulta API → decide ação.
 * @param {string} cpfInput - CPF digitado pelo usuário
 * @returns {Promise<object>} Decisão para o front-end
 */
async function validarCpfCompleto(cpfInput) {
  const cpf = normalizarCpf(cpfInput);

  // 1. Validação matemática instantânea — rejeita inválidos sem gastar crédito
  if (!validarDigitosVerificadores(cpf)) {
    return { acao: 'rejeitar', motivo: 'CPF inválido (dígitos verificadores incorretos)', cpf };
  }

  try {
    // 2. Consulta oficial — gasta 1 crédito, retorna status real
    const { status, dados, consultId, balance } = await consultarCpfSmartcpf(cpf);

    // 3. Decisão baseada no status granular
    switch (status) {
      case 'regular':
        return { acao: 'aprovar', motivo: 'CPF regular na Receita Federal', cpf, consultId, balance, dados };
      case 'irregular':
        return { acao: 'revisar', motivo: `CPF ${dados.status.toLowerCase()} na Receita Federal`, cpf, consultId, balance, dados };
      case 'inexistente':
        return { acao: 'rejeitar', motivo: 'CPF não encontrado na base da Receita Federal', cpf, consultId, balance };
      default:
        return { acao: 'revisar', motivo: 'Status indeterminado — revisão manual', cpf, consultId, balance };
    }
  } catch (err) {
    // 4. Falha de infraestrutura — não decidir automaticamente
    console.error('[SmartCPF] Erro na consulta:', err.message);
    return {
      acao: 'revisar',
      motivo: 'Falha na consulta à Receita — fila manual',
      cpf,
      erro: err.message,
      consultId: err.consultId
    };
  }
}

// Exemplo de uso
(async () => {
  const cpfsTeste = [
    '111.111.111-11', // CPF válido matematicamente (exemplo)
    '123.456.789-00', // CPF inválido (DV errado)
    '000.000.000-00'  // CPF inválido (todos iguais)
  ];

  for (const cpf of cpfsTeste) {
    const resultado = await validarCpfCompleto(cpf);
    console.log(`\nCPF: ${cpf}`);
    console.log(`Ação: ${resultado.acao.toUpperCase()} | Motivo: ${resultado.motivo}`);
    if (resultado.consultId) console.log(`ConsultID: ${resultado.consultId} | Saldo: ${resultado.balance}`);
    if (resultado.dados) console.log(`Nome: ${resultado.dados.name} | Status Receita: ${resultado.dados.status}`);
  }
})();

Resposta da API

{
  "meta": {
    "searchType": "CPF C",
    "consultId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user": "Sistema Onboarding",
    "message": "CPF encontrado com sucesso",
    "ip": "203.0.113.45",
    "success": true,
    "apiVersion": "v2",
    "date": "2026-08-11T14:32:17.891Z",
    "executionTimeMs": 74.1,
    "balance": 987.44
  },
  "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-8888",
        "blockedTelemarketing": false,
        "operator": "VIVO",
        "type": "CELULAR",
        "whatsapp": true
      }
    ],
    "addresses": [
      {
        "zipCode": "01310-100",
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Sala 1201",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "type": "RESIDENCIAL"
      }
    ]
  },
  "success": true,
  "errors": []
}

O fluxo demonstrado resolve na prática:

• Validação offline elimina 90%+ de erros de digitação sem consumir créditos (balance preservado)
• consultId único (a1b2c3d4-e5f6-7890-abcd-ef1234567890) rastreia cada decisão para auditoria LGPD/Bacen
• Status granular (result.status: "Regular", "Irregular", "Suspenso", "Cancelado", "Nulo") permite regras de risco por categoria
• Dados completos (name, birthDate, addresses, phones) alimentam KYC sem chamadas adicionais
• executionTimeMs (74.1ms) monitora SLA da integração em produção

Por que usar a SmartCPF para validação de CPF

Latência previsível — média de 70-120ms em produção, com SLA de 99.9% uptime. Não há variação de performance entre horários de pico e valle.

Integração zero-dependency — REST + JSON nativo, sem SDKs pesados, WebSockets ou gRPC. Funciona em qualquer stack: Node, Python, Go, PHP, Java, .NET, serverless, edge.

Modelo de créditos transparente — balance retornado em toda resposta. Sem assinatura, sem mínimo mensal, sem expiração. Você paga apenas pelo que consulta, e o saldo nunca expira.

Escalabilidade nativa — arquitetura stateless na Cloudflare. Suporta de 10 req/dia a 10M req/dia sem mudança de código ou infraestrutura. Rate limit generoso (1000 req/min por IP) com burst controlado.

Dados enriquecidos opcionais — package=complete adiciona score de risco, Óbitos, Serasa, protestos, processos judiciais e dados veiculares na mesma chamada. Um endpoint, múltiplas fontes.

Conclusão

Tratar "CPF inválido", "inexistente" e "irregular" como sinônimos custa caro: fraudes que passam, usuários legítimos bloqueados, auditorias que falham. A distinção técnica exige duas etapas — validação matemática offline (grátis, instantânea) e consulta à base oficial (custo controlado, fonte de verdade). A API SmartCPF entrega essa consulta com latência baixa, autenticação simples via X-API-KEY, e resposta estruturada que mapeia direto para suas regras de negócio: consultId para rastreabilidade, balance para controle de custo, status para decisão granular.

Crie sua conta na SmartCPF e faça sua primeira consulta em minutos.