Como consumir APIs REST de CPF em Python usando requests

Para consumir a API de CPF da CPFHub.io em Python, instale a biblioteca requests, configure o header x-api-key com sua chave e faça uma requisição GET para https://api.cpfhub.io/cpf/{CPF}. O retorno é um JSON com nome, data de nascimento e gênero do titular, disponível em menos de 200ms. A ANPD orienta que dados de identificação pessoal devem ser tratados com finalidade declarada e armazenamento mínimo — o que se aplica diretamente ao uso de dados retornados por APIs de CPF.

Introdução

Python é uma das linguagens mais populares para desenvolvimento web, automação e análise de dados. A biblioteca requests é a forma mais simples e elegante de fazer requisições HTTP em Python. Este tutorial mostra como integrar a API da CPFHub.io com código pronto para produção.

Pré-requisitos

• Python 3.8+

• Biblioteca requests (pip install requests)

• Conta gratuita na CPFHub.io para obter sua API key.

Código básico

import os
import requests

cpf = '12345678900'
api_key = os.environ['CPFHUB_API_KEY']

url = f'https://api.cpfhub.io/cpf/{cpf}'
headers = {
    'x-api-key': api_key,
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers, timeout=10)

if response.status_code == 200:
    data = response.json()
    if data['success']:
    print(f"Nome: {data['data']['name']}")
    print(f"Nascimento: {data['data']['birthDate']}")
    print(f"Genero: {data['data']['gender']}")
    else:
    print('CPF nao encontrado na base.')
else:
    print(f'Erro: HTTP {response.status_code}')

Resposta esperada

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

Versão com função reutilizável e tratamento de erros

import os
import re
import requests

class CpfHubClient:
    BASE_URL = 'https://api.cpfhub.io'

    def __init__(self, api_key: str = None):
    self.api_key = api_key or os.environ['CPFHUB_API_KEY']
    self.session = requests.Session()
    self.session.headers.update({
    'x-api-key': self.api_key,
    'Accept': 'application/json'
    })

    def consultar(self, cpf: str) -> dict:
    cpf = re.sub(r'\D', '', cpf)

    if len(cpf) != 11:
    raise ValueError('CPF deve ter 11 digitos')

    response = self.session.get(
    f'{self.BASE_URL}/cpf/{cpf}',
    timeout=10
    )

    if response.status_code == 200:
    data = response.json()
    if data.get('success'):
    return data['data']
    return None
    elif response.status_code == 400:
    raise ValueError('CPF com formato invalido')
    elif response.status_code == 401:
    raise PermissionError('Chave de API invalida')
    else:
    raise RuntimeError(f'Erro HTTP {response.status_code}')

# Uso
client = CpfHubClient()

try:
    dados = client.consultar('123.456.789-00')
    if dados:
    print(f"Nome: {dados['name']}")
    print(f"Nascimento: {dados['birthDate']}")
    else:
    print('CPF nao encontrado.')
except ValueError as e:
    print(f'Erro de validacao: {e}')
except PermissionError as e:
    print(f'Erro de autenticacao: {e}')
except RuntimeError as e:
    print(f'Erro: {e}')

Usando com Session para múltiplas consultas

A classe requests.Session() reaproveita conexões TCP, melhorando a performance quando você precisa fazer múltiplas consultas:

client = CpfHubClient()

cpfs = ['12345678900', '98765432100', '11122233344']
for cpf in cpfs:
    try:
    dados = client.consultar(cpf)
    if dados:
    print(f"{cpf}: {dados['name']}")
    except RuntimeError as e:
    print(f"{cpf}: {e}")

Boas práticas

• Variáveis de ambiente -- Use os.environ para a chave de API, nunca hardcode.

• Timeout -- Sempre configure timeout para evitar requisições travadas.

• Sanitização -- Remova pontos e traços do CPF antes de enviar.

• Consultas em lote -- Para processar listas de CPFs, adicione um intervalo entre chamadas com time.sleep() para distribuir o tráfego de forma uniforme.

• Retry -- Para erros 5xx, implemente retry com backoff exponencial usando a biblioteca tenacity.

• LGPD -- Não armazene dados pessoais além do necessário.

Perguntas frequentes

Como instalar e verificar a biblioteca requests no Python?

Execute pip install requests no terminal. Para verificar a instalação, rode python -c "import requests; print(requests.__version__)". Em projetos com virtualenv ou Poetry, adicione requests ao arquivo de dependências (requirements.txt ou pyproject.toml) para garantir reprodutibilidade entre ambientes.

Como fazer múltiplas consultas de CPF em Python sem sobrecarregar a API?

Use requests.Session() para reaproveitar conexões TCP e reduzir latência. Para lotes grandes, distribua as chamadas com time.sleep() entre cada requisição. Se o volume exceder o limite do plano, a API não bloqueia — cobra R$0,15 por consulta adicional, então o serviço continua operando sem interrupção.

Como usar variáveis de ambiente para proteger a API key em Python?

Defina a variável no terminal com export CPFHUB_API_KEY="sua_chave" (Linux/macOS) ou via painel do seu servidor em produção. No código, acesse com os.environ['CPFHUB_API_KEY']. Para desenvolvimento local, use a biblioteca python-dotenv com um arquivo .env que não deve ser versionado no Git.

Como tratar erros de rede ao consumir a API de CPF em Python?

Configure timeout=10 na chamada requests.get() para evitar que requisições fiquem presas indefinidamente. Envolva a chamada em bloco try/except para capturar requests.exceptions.Timeout e requests.exceptions.ConnectionError separadamente. Para erros 5xx, implemente retry com backoff exponencial usando a biblioteca tenacity.

Conclusão

Consumir a API da CPFHub.io em Python com a biblioteca requests exige poucos passos: instalar a dependência, configurar o header de autenticação e interpretar o JSON de resposta. Com a classe CpfHubClient apresentada neste tutorial, o código fica reutilizável, testável e pronto para escalar de projetos de automação até sistemas de onboarding em produção.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito.