# Como validar um CPF automaticamente com API REST (guia genérico) > Guia genérico para validar CPF automaticamente com API REST. Exemplos em Python, JavaScript e cURL com boas práticas de integração. **Publicado:** 05/04/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/validar-cpf-automaticamente-api-rest-guia-generico --- 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**](https://www.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: | Etapa | Tipo | Onde executar | Objetivo | |---|---|---|---| | Formatação | Limpeza | Cliente/Servidor | Remover pontos, traços e espaços | | Tamanho | Sintática | Cliente/Servidor | Confirmar 11 dígitos | | Dígitos repetidos | Sintática | Cliente/Servidor | Rejeitar 000.000.000-00, etc. | | Dígitos verificadores | Matemática | Cliente/Servidor | Validar algoritmo da Receita | | Existência real | API REST | Servidor | Confirmar que o CPF existe | | Dados cadastrais | API REST | Servidor | Obter nome, nascimento, etc. | --- ## Exemplo completo com Python ```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: ```bash # 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](https://www.gov.br/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. ### Leia também - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) - [Guia de headers HTTP obrigatórios para consumir API de CPF corretamente](https://cpfhub.io/blog/guia-de-headers-http-obrigatorios-para-consumir-api-de-cpf-corretamente) --- ## 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](https://www.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.