Como começar com Python requests
Uma integração de API CPF em Python pode utilizar a biblioteca requests. Instale-a em seu ambiente virtual com python -m pip install requests e defina APICPF_KEY no servidor. A chamada cadastral documentada é GET https://api.apicpf.dev/consulta?cpf= e requer a credencial em X-API-KEY. O guia oficial descreve as demais rotas e respostas.
Exemplo completo com timeout e tratamento de falhas
import os
import re
import requests
API_KEY = os.environ["APICPF_KEY"]
def consultar_cpf(cpf: str) -> dict:
digitos = re.sub(r"\D", "", cpf)
if len(digitos) != 11:
raise ValueError("CPF deve ter 11 dígitos")
response = requests.get(
"https://api.apicpf.dev/consulta",
params={"cpf": digitos},
headers={"X-API-KEY": API_KEY, "Accept": "application/json"},
timeout=(3, 10),
)
response.raise_for_status()
payload = response.json()
if not isinstance(payload, dict) or not isinstance(payload.get("data"), dict):
raise ValueError("Resposta JSON inesperada")
return payload["data"]
try:
dados = consultar_cpf("52998224725")
print("Consulta executada:", bool(dados.get("nome")))
except requests.exceptions.Timeout:
print("Timeout na comunicação")
except requests.exceptions.HTTPError as exc:
print("HTTP:", exc.response.status_code)
except (requests.exceptions.RequestException, ValueError):
print("Não foi possível concluir a consulta")
O CPF é um exemplo da documentação, não uma recomendação para testar dados reais. Em produção, substitua os print por mensagens adequadas e não registre dados pessoais ou credenciais no log de erros.
Por que passar timeout=(3, 10)?
O primeiro valor limita a tentativa de conexão; o segundo limita a espera de leitura em operações de socket. Isso não é um prazo global rígido de 13 segundos. Ajuste ao tempo aceitável do seu endpoint e trate Timeout separadamente de HTTPError.
Uma falha de timeout não garante que o provedor não processou a consulta. Antes de tentar novamente, considere o consumo de créditos e verifique o contrato da API.
O que fazer com 401, 402, 404 e 429
401 sugere chave ausente ou inválida; não repita usando a mesma credencial. 402 exige revisão do saldo de créditos. 404 requer verificar URL, rota e mensagem de resposta, pois não comprova por si só inexistência do cadastro. 429 indica limitação de taxa: reduza a concorrência e espere antes de repetir, com limite de tentativas.
Para detalhar as decisões por código, leia o manual de erros HTTP.
Quando validar antes de consultar
A rota /v1/validate?cpf= checa dígitos verificadores e formato sem gastar crédito de consulta, conforme o serviço. Use-a antes da consulta completa, mas não trate valid: true como confirmação de identidade, situação cadastral ou permissão legal para obter dados.
Perguntas frequentes
requests é a única biblioteca possível?
Não. httpx e a biblioteca padrão também podem executar requests HTTP. O importante é tratar timeout, HTTP e conteúdo malformado.
Preciso guardar a resposta completa?
Não por padrão. Guarde somente o estritamente necessário à finalidade e aplique prazos de retenção e controles de acesso.
