# Como consumir APIs REST de CPF em Python usando requests

> Tutorial completo para consumir a API de consulta de CPF da CPFHub.io em Python usando a biblioteca requests. Código pronto para usar.

**Publicado:** 17/05/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/consumir-api-cpf-python-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](https://www.gov.br/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](https://www.cpfhub.io/) para obter sua API key.

---

## Código básico

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

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

---

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

```python
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:

```python
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`.

### Leia também

- [Como consumir a API da CPFHub.io em PHP usando cURL](https://cpfhub.io/blog/como-consumir-a-api-da-cpfhub-io-em-php-usando-curl)
- [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 validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [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)

---

## Conclusão

Consumir a API da [**CPFHub.io**](https://www.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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.