Como validar um CPF automaticamente com API REST (guia genérico)

Validar um CPF automaticamente com API REST envolve duas etapas complementares: verificar os dígitos verificadores localmente (sem custo e sem latência) e consultar uma API para confirmar que o CPF pertence a uma pessoa real e obter dados cadastrais atualizados. A CPFHub.io oferece um endpoint simples — GET https://api.cpfhub.io/cpf/{CPF} com header x-api-key — que retorna nome, data de nascimento e gênero em ~900ms, com plano gratuito de 50 consultas mensais sem cartão de crédito.

Introdução

A validação de CPF é uma necessidade comum em aplicações brasileiras, desde e-commerces até sistemas governamentais. Embora a verificação dos dígitos verificadores possa ser feita localmente, a consulta a uma API REST permite confirmar que o CPF pertence a uma pessoa real e obter dados cadastrais atualizados.

Etapas da validação completa de CPF

Uma validação robusta de CPF envolve múltiplas etapas complementares:

Exemplo completo com Python

import requests
import re

class ValidadorCPF:
    def __init__(self, api_key: str):
        self.api_key = api_key

    def limpar(self, cpf: str) -> str:
        return re.sub(r'\D', '', cpf)

    def validar_formato(self, cpf: str) -> bool:
        cpf = self.limpar(cpf)
        if len(cpf) != 11:
            return False
        if cpf == cpf[0] * 11:
            return False
        return True

    def validar_digitos(self, cpf: str) -> bool:
        cpf = self.limpar(cpf)
        numeros = [int(d) for d in cpf]

        # Primeiro dígito verificador
        soma = sum(numeros[i] * (10 - i) for i in range(9))
        resto = (soma * 10) % 11
        if resto == 10:
            resto = 0
        if resto != numeros[9]:
            return False

        # Segundo dígito verificador
        soma = sum(numeros[i] * (11 - i) for i in range(10))
        resto = (soma * 10) % 11
        if resto == 10:
            resto = 0
        return resto == numeros[10]

    def consultar_api(self, cpf: str) -> dict:
        cpf = self.limpar(cpf)

        response = requests.get(
            f"https://api.cpfhub.io/cpf/{cpf}",
            headers={"x-api-key": self.api_key},
            timeout=10
        )

        if response.status_code == 200:
            dados = response.json()
            if dados["success"]:
                return {
                    "encontrado": True,
                    "cpf": dados["data"]["cpf"],
                    "nome": dados["data"]["name"],
                    "genero": dados["data"]["gender"],
                    "nascimento": dados["data"]["birthDate"],
                    "dia": dados["data"]["day"],
                    "mes": dados["data"]["month"],
                    "ano": dados["data"]["year"]
                }
        return {"encontrado": False}

    def validar_completo(self, cpf: str) -> dict:
        if not self.validar_formato(cpf):
            return {"valido": False, "etapa": "formato", "msg": "Formato inválido"}

        if not self.validar_digitos(cpf):
            return {"valido": False, "etapa": "digitos", "msg": "Dígitos verificadores inválidos"}

        resultado_api = self.consultar_api(cpf)
        if not resultado_api["encontrado"]:
            return {"valido": False, "etapa": "api", "msg": "CPF não encontrado na base"}

        return {"valido": True, "etapa": "completa", "dados": resultado_api}

# Uso
v = ValidadorCPF("SUA_CHAVE_AQUI")
resultado = v.validar_completo("123.456.789-09")
print(f"Válido: {resultado['valido']}")
if resultado.get("dados"):
    print(f"Nome: {resultado['dados']['nome']}")

Exemplo com cURL para testes rápidos

Para validar rapidamente via terminal sem escrever código:

# Validação simples
curl -s \
  -H "x-api-key: SUA_CHAVE_AQUI" \
  "https://api.cpfhub.io/cpf/12345678909" | python3 -m json.tool

# Validação com verificação de status HTTP
curl -s -o response.json -w "%{http_code}" \
  -H "x-api-key: SUA_CHAVE_AQUI" \
  "https://api.cpfhub.io/cpf/12345678909"

# Extrair apenas o nome
curl -s \
  -H "x-api-key: SUA_CHAVE_AQUI" \
  "https://api.cpfhub.io/cpf/12345678909" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(d['data']['name'] if d['success'] else 'Não encontrado')"

Tratamento de erros e resiliência

Uma integração robusta precisa tratar todos os cenários de falha:

• HTTP 200 + success: true — CPF válido e encontrado, processar dados retornados
• HTTP 200 + success: false — CPF com formato válido mas não encontrado na base
• HTTP 400 — requisição malformada, verificar o formato do CPF enviado
• HTTP 401/403 — chave de API inválida ou expirada, verificar credenciais
• HTTP 500+ — erro no servidor da API, tentar novamente após intervalo

Vale destacar que a CPFHub.io nunca retorna HTTP 429: ao ultrapassar a cota do plano, cada consulta adicional é cobrada automaticamente a R$0,15, e a API continua respondendo normalmente. Reserve o mecanismo de retry exclusivamente para erros 5xx transitórios.

Boas práticas para qualquer integração

Independente da linguagem ou provedor, estas práticas garantem uma integração confiável:

• Sempre valide localmente primeiro — não desperdice chamadas de API com CPFs sintaticamente inválidos
• Configure timeouts — defina tempo máximo de espera para evitar que requisições travem a aplicação
• Implemente retry com backoff — em caso de falha temporária (5xx), tente novamente com intervalos crescentes
• Use cache inteligente — dados de CPF não mudam frequentemente, então cache de 24h é seguro
• Proteja a chave de API — armazene em variáveis de ambiente, nunca no código fonte
• Registre logs mascarados — log CPFs parciais (123..-09) para auditoria sem exposição

Perguntas frequentes

Qual a diferença entre validar e consultar um CPF?

Validar o CPF significa verificar matematicamente se os dígitos verificadores estão corretos — isso pode ser feito localmente, sem chamada de API. Consultar o CPF significa confirmar junto à base de dados que aquele número pertence a uma pessoa real e obter seus dados cadastrais (nome, data de nascimento). Para emissão de documentos, cadastros e prevenção de fraude, a consulta via API é indispensável além da validação local.

A API CPFHub.io funciona para qualquer volume de consultas?

Sim. Ao ultrapassar o limite do plano, a API não bloqueia nem retorna erro — cobra R$0,15 por consulta adicional e continua respondendo normalmente. O plano gratuito cobre 50 consultas mensais sem cartão de crédito. O plano Pro (R$149/mês) inclui 1.000 consultas, ideal para aplicações com fluxo constante de cadastros ou transações.

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 em uma aplicação existente?

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 latência média é de ~900ms. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

Validar CPF automaticamente com API REST é um processo que combina verificação local e consulta remota para garantir precisão e confiabilidade. Com exemplos práticos em Python e cURL, boas práticas de tratamento de erros e estratégias de resiliência, você está preparado para integrar a validação de CPF em qualquer aplicação.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a validar CPFs em produção em menos de 30 minutos.