# Como verificar se um CPF está ativo ou inativo via API > Aprenda a verificar se um CPF está ativo ou inativo utilizando uma API REST. Veja exemplos práticos de integração e boas práticas. **Publicado:** 22/07/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-verificar-se-um-cpf-esta-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](https://www.bcb.gov.br) 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**](https://www.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 | Header | Valor | | --- | --- | | x-api-key | Sua chave de API | | Accept | application/json | ### Exemplo com cURL ```bash 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: ```json { "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: ```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**](https://www.cpfhub.io/) inclui campos cadastrais que permitem cruzar as informações com os dados fornecidos pelo usuário durante o cadastro. | Campo | Descrição | Uso prático | | --- | --- | --- | | cpf | Número do CPF consultado | Confirmar o documento processado | | name | Nome completo do titular | Cruzar com o nome informado no cadastro | | gender | Gênero (M/F) | Personalização de comunicações | | birthDate | Data de nascimento (DD/MM/YYYY) | Verificação de idade mínima | | day, month, year | Componentes da data de nascimento | Cálculos de idade ou filtros | ### 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: ```python 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 | Plano | Preço | Consultas/mês | SLA | | --- | --- | --- | --- | | Gratuito | R$ 0 | 50 | 80% | | Pro | R$ 149/mês | 1.000 | 99% | | Corporativo | Sob consulta | Personalizado | 99,9% | 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](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? 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. ### 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) - [Como consultar CPF na Receita Federal pelo site oficial](https://cpfhub.io/blog/como-consultar-cpf-na-receita-federal-pelo-site-oficial) - [APIs de CPF: como avaliar o custo-benefício antes de contratar?](https://cpfhub.io/blog/apis-de-cpf-como-avaliar-o-custo-beneficio-antes-de-contratar) --- ## 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](https://www.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.