# Como consumir uma API REST de consulta de CPF em Python > Aprenda a consumir uma API REST de consulta de CPF em Python utilizando requests e httpx. Passo a passo com exemplos práticos! **Publicado:** 17/09/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/consumir-api-rest-cpf-python --- Consumir uma API REST de consulta de CPF em Python é simples: basta instalar a biblioteca `requests` ou `httpx`, configurar o header `x-api-key` e fazer um `GET` para `https://api.cpfhub.io/cpf/{CPF}`. A CPFHub.io retorna nome, gênero e data de nascimento em ~900ms, com plano gratuito de 50 consultas mensais sem cartão de crédito. ## Introdução As **APIs REST** são amplamente utilizadas para integrar sistemas e acessar informações externas de forma programática. Para empresas que precisam validar dados cadastrais de clientes, como fintechs e e-commerces, consumir uma **API de consulta de CPF** pode ser essencial para evitar fraudes e garantir conformidade regulatória. Neste guia, você aprenderá a integrar a **CPFHub.io** utilizando **Python**. Exploraremos exemplos com as bibliotecas **requests** e **httpx**, garantindo que você consiga realizar consultas de forma segura e eficiente. A CPFHub.io oferece suporte a mais de 13 linguagens de programação, incluindo Python, e conta com conformidade LGPD. --- ## 1. Pré-requisitos Antes de começar, você precisará: - **Python instalado** (versão 3.7 ou superior recomendada). - **Conta na CPFHub.io** para obter a chave de API (plano gratuito com 50 consultas/mês, sem necessidade de cartão). - **Bibliotecas requests ou httpx** para fazer chamadas HTTP. Se ainda não tem uma conta, cadastre-se em [**CPFHub.io**](https://www.cpfhub.io/) e obtenha sua API key em menos de 2 minutos. --- ## 2. Instalando as bibliotecas necessárias Caso não tenha a biblioteca requests instalada, execute o seguinte comando: ```bash pip install requests ``` Se preferir utilizar a biblioteca httpx, instale com: ```bash pip install httpx ``` Ambas são excelentes opções para realizar requisições HTTP em Python. --- ## 3. Fazendo uma consulta de CPF com Python ### Usando requests Aqui está um exemplo de como consultar um CPF utilizando a API da CPFHub.io com a biblioteca **requests**: ```python import requests API_KEY = "SUA_CHAVE_DE_API" CPF = "12345678900" URL = f"https://api.cpfhub.io/cpf/{CPF}" headers = { "x-api-key": API_KEY, "Accept": "application/json" } response = requests.get(URL, headers=headers) if response.status_code == 200: print(response.json()) else: print("Erro na consulta:", response.status_code, response.text) ``` ### Usando httpx A biblioteca **httpx** é uma alternativa moderna ao requests, oferecendo suporte assíncrono. ```python import httpx API_KEY = "SUA_CHAVE_DE_API" CPF = "12345678900" URL = f"https://api.cpfhub.io/cpf/{CPF}" headers = { "x-api-key": API_KEY, "Accept": "application/json" } with httpx.Client() as client: response = client.get(URL, headers=headers) if response.status_code == 200: print(response.json()) else: print("Erro na consulta:", response.status_code, response.text) ``` Se quiser rodar a requisição de forma **assíncrona**, use: ```python import httpx import asyncio async def consulta_cpf(): async with httpx.AsyncClient() as client: response = await client.get( "https://api.cpfhub.io/cpf/12345678900", headers={ "x-api-key": "SUA_CHAVE_DE_API", "Accept": "application/json" } ) print(response.json()) asyncio.run(consulta_cpf()) ``` --- ## 4. Exemplo de resposta da API Após a requisição, a API retornará um JSON com as informações do CPF consultado: ```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 } } ``` O que essa resposta indica: * **success**: Se a consulta foi realizada com sucesso. * **cpf**: Número do CPF consultado. * **name**: Nome completo do titular do CPF. * **nameUpper**: Nome completo em letras maiúsculas. * **gender**: Gênero do titular (M ou F). * **birthDate**: Data de nascimento no formato dd/mm/aaaa. * **day, month, year**: Dia, mês e ano de nascimento separados. --- ## 5. Tratamento de erros A API pode retornar erros caso os dados sejam inválidos ou a chave de API esteja incorreta. Veja um exemplo de tratamento de erros: ```python if not response.json().get("success", False): print("Erro na consulta:", response.json().get("message", "Erro desconhecido")) ``` ### Mensagens de erro comuns | Código | Mensagem | Motivo | | --- | --- | --- | | 400 | CPF inválido | O CPF informado não segue o formato correto | | 401 | Chave de API inválida | A chave de API fornecida está errada ou expirada | | 403 | Acesso negado | Sua conta não tem permissão para esta consulta | | 500 | Erro interno | Problema temporário na API | **Dica:** Sempre valide a entrada do usuário antes de enviar uma consulta para evitar erros desnecessários. --- ## 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) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) - [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) --- ## Conclusão Consumir uma **API REST de consulta de CPF** em **Python** é um processo simples e essencial para empresas que desejam validar clientes e evitar fraudes. Utilizando **requests ou httpx**, é possível fazer consultas rápidas e seguras, com tempo de resposta de aproximadamente 900ms. A API retorna dados como nome completo, nome em maiúsculas, gênero e data de nascimento (com dia, mês e ano separados), atendendo às necessidades de validação de identidade com conformidade LGPD. Mais de 1.300 empresas já confiam na CPFHub.io, que oferece 99.9% de uptime. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.