Tutorial

API de CPF em Python: requests, timeout e exceções

Exemplo completo de API CPF em Python com requests, autenticação, timeout, tratamento de erros e JSON.

Imagem editorial sobre Python requests em produção
Python requests em produção.

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.

Continue aprendendo