Como verificar se um CPF está ativo ou inativo via API

Para verificar se um CPF está ativo ou inativo via API, basta enviar uma requisição GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. Se o campo success retornar true e os dados cadastrais estiverem presentes, o CPF existe e está associado a uma pessoa real; se retornar false, o documento não corresponde a um registro válido.

Introdução

Verificar se um CPF está ativo ou inativo é uma etapa essencial em processos de cadastro, onboarding e prevenção de fraudes. Empresas que aceitam documentos sem esse tipo de checagem correm o risco de aprovar cadastros com dados inválidos, o que pode gerar prejuízos financeiros e problemas regulatórios.

Por que verificar se um CPF está ativo?

A verificação de CPF vai além de simplesmente validar os dígitos verificadores. Enquanto a validação sintática confirma que o formato está correto, a consulta via API retorna dados cadastrais reais associados ao documento, permitindo identificar se o CPF pertence a uma pessoa real e se os dados informados são consistentes.

Cenários em que essa verificação é indispensável:

• Onboarding de clientes -- Garantir que o CPF informado no cadastro corresponde a dados reais antes de prosseguir com a abertura de conta ou aprovação de crédito.

• E-commerce -- Validar a identidade do comprador no checkout para reduzir chargebacks e fraudes com cartões clonados.

• Processos de KYC -- Atender exigências regulatórias do Banco Central e demais órgãos de fiscalização.

• Emissão de notas fiscais -- Confirmar que o CPF é válido antes de gerar documentos fiscais, evitando rejeições.

Como funciona a consulta via API

A CPFHub.io oferece um endpoint REST simples que retorna os dados cadastrais associados ao CPF consultado, permitindo verificar em tempo real se o documento corresponde a uma pessoa real.

Endpoint

GET https://api.cpfhub.io/cpf/{CPF_NUMBER}

Headers obrigatórios

Exemplo com cURL

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json" \
    --max-time 10

Resposta de sucesso

Quando o CPF é encontrado na base de dados, a API retorna um objeto com os dados cadastrais:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

Quando o campo success retorna true e os dados cadastrais estão presentes, isso indica que o CPF existe na base e está associado a uma pessoa real.

Resposta quando o CPF não é encontrado

Se o CPF não for encontrado, o campo success retornará false, indicando que o documento não corresponde a um registro válido.

Implementação prática em Python

Abaixo está um exemplo completo de como consultar um CPF e interpretar a resposta em Python:

import requests

def verificar_cpf(cpf):
    url = f"https://api.cpfhub.io/cpf/{cpf}"
    headers = {
    "x-api-key": "SUA_CHAVE_DE_API",
    "Accept": "application/json"
    }

    try:
    response = requests.get(url, headers=headers, timeout=10)
    response.raise_for_status()
    dados = response.json()

    if dados.get("success"):
    print(f"CPF ativo: {dados['data']['name']}")
    return True
    else:
    print("CPF não encontrado na base.")
    return False

    except requests.exceptions.Timeout:
    print("A requisição excedeu o tempo limite.")
    return None
    except requests.exceptions.HTTPError as e:
    print(f"Erro HTTP: {e.response.status_code}")
    return None

# Uso
verificar_cpf("12345678900")

Esse código realiza a consulta, trata os cenários de sucesso e falha, e inclui tratamento de timeout para evitar que a aplicação fique travada em caso de lentidão na rede.

Interpretando os dados retornados

A resposta da API da CPFHub.io inclui campos cadastrais que permitem cruzar as informações com os dados fornecidos pelo usuário durante o cadastro.

Cruzamento de dados para antifraude

Uma boa prática é comparar os dados retornados pela API com os dados informados pelo usuário. Se o nome ou a data de nascimento não coincidirem, é um forte indicativo de tentativa de fraude:

def validar_identidade(cpf, nome_informado, ano_nascimento_informado):
    url = f"https://api.cpfhub.io/cpf/{cpf}"
    headers = {
    "x-api-key": "SUA_CHAVE_DE_API",
    "Accept": "application/json"
    }

    response = requests.get(url, headers=headers, timeout=10)
    dados = response.json()

    if not dados.get("success"):
    return {"valido": False, "motivo": "CPF não encontrado"}

    nome_real = dados["data"]["name"].lower()
    nome_input = nome_informado.lower()

    if nome_real != nome_input:
    return {"valido": False, "motivo": "Nome não confere"}

    if dados["data"]["year"] != ano_nascimento_informado:
    return {"valido": False, "motivo": "Ano de nascimento não confere"}

    return {"valido": True, "motivo": "Dados conferem"}

Boas práticas ao verificar CPFs via API

Para garantir uma integração robusta e eficiente, considere as seguintes recomendações:

• Valide sintaticamente antes de consultar -- Verifique os dígitos verificadores localmente antes de enviar a requisição à API. Isso evita o desperdício de consultas com CPFs claramente inválidos.

• Configure timeout adequado -- Defina um timeout de 10 segundos para evitar que sua aplicação fique bloqueada aguardando uma resposta.

• Implemente cache local -- Se o mesmo CPF for consultado frequentemente, armazene o resultado em cache por um período razoável para economizar requisições.

• Trate todos os códigos de resposta -- A API pode retornar códigos 4xx (erro do cliente) e 5xx (erro do servidor). Cada um exige um tratamento diferente.

• Monitore o consumo de créditos -- Acompanhe quantas consultas já foram realizadas no mês para evitar surpresas, especialmente no plano gratuito com 50 consultas.

Planos disponíveis na CPFHub.io

O plano gratuito é ideal para testes e projetos iniciais, enquanto o plano Pro atende a maioria das aplicações em produção. Para volumes maiores, o plano Corporativo oferece infraestrutura dedicada e suporte prioritário.

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 o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

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 pequenos. 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.

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

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), 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.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

Verificar se um CPF está ativo via API é uma prática fundamental para qualquer sistema que lida com dados de identidade. A consulta retorna dados cadastrais reais que permitem confirmar a existência do documento e cruzar informações com os dados informados pelo usuário, fortalecendo processos de onboarding, antifraude e compliance.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a verificar CPFs em tempo real na sua aplicação hoje mesmo.