Como consumir uma API REST de consulta de CPF em 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 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:

pip install requests

Se preferir utilizar a biblioteca httpx, instale com:

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:

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.

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:

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:

{
    "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:

if not response.json().get("success", False):
    print("Erro na consulta:", response.json().get("message", "Erro desconhecido"))

Mensagens de erro comuns

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

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 — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.