SDK Python

SDK oficial para Python 3.8+. Faz a Consulta Simples (GET /cpf/{cpf}) e devolve o JSON da API como dict.

Instalação

bash

pip install cpfhub

Com Poetry:

bash

poetry add cpfhub

Requisitos: Python 3.8+

Inicialização

Python

import os
from cpfhub import CPFHub

client = CPFHub(api_key=os.environ["CPFHUB_API_KEY"])

O cliente envia a chave no header x-api-key e usa timeout de 10 segundos. Também pode ser usado como context manager, que fecha a conexão ao sair do bloco:

Python

with CPFHub(api_key=os.environ["CPFHUB_API_KEY"]) as client:
    result = client.lookup("12345678909")

Parâmetros do construtor

Parâmetro	Tipo	Descrição
`api_key`	`str`	Sua API Key (obrigatório). Vazia, lança `ValueError`

Métodos

`client.lookup(cpf)`

Consulta um CPF e retorna o corpo da resposta da API como dict.

Python

result = client.lookup("123.456.789-09")
print(result["data"]["name"])       # "Fulano de Tal"
print(result["data"]["birthDate"])  # "15/06/1990"

Parâmetros:

Parâmetro	Tipo	Descrição
`cpf`	`str`	CPF com ou sem formatação

Retorno: dict no formato da Consulta Simples:

Python

{
    "success": True,
    "data": {
        "cpf": "12345678909",
        "name": "Fulano de Tal",
        "nameUpper": "FULANO DE TAL",
        "gender": "M",
        "birthDate": "15/06/1990",
        "day": 15,
        "month": 6,
        "year": 1990,
    },
}

A Consulta em Tempo Real e a consulta em lote são feitas pela API REST: POST https://api.cpfhub.io/cpf/realtime e POST https://api.cpfhub.io/cpf/bulk.

⚠

Não use client.get_quota()

A versão 1.0.0 do pacote traz um método get_quota() que chama o endereço errado e não funciona. Para ver o saldo e o plano, chame GET https://api.cpfhub.io/quota direto (não consome crédito).

Tratamento de erros

CPF sem 11 dígitos: lookup lança ValueError antes de chamar a API (sem consumo de crédito).
Respostas 4xx e 5xx: o SDK lança httpx.HTTPStatusError. O status está em e.response.status_code e o corpo da API em e.response.json(). O campo error vem como texto ("...") ou como objeto ({"message": "..."}), conforme o status.

Python

import os
import httpx
from cpfhub import CPFHub

client = CPFHub(api_key=os.environ["CPFHUB_API_KEY"])

try:
    result = client.lookup("12345678909")
except httpx.HTTPStatusError as e:
    print(e.response.status_code)  # 404
    print(e.response.json())       # {"success": False, "data": None, "error": {"message": "CPF não encontrado na base de dados"}}

Status	Motivo
`401`	API Key ausente ou inválida
`403`	Créditos esgotados ou conta bloqueada
`404`	CPF não encontrado (sem consumo de crédito)
`422`	Dígito verificador incorreto (sem consumo de crédito)
`429`	Limite de requisições por minuto: espere os segundos do header `Retry-After`

Lista completa em Códigos de Erro.

Exemplos de integração

FastAPI

Python

import os
import httpx
from fastapi import FastAPI, HTTPException
from cpfhub import CPFHub

app = FastAPI()
client = CPFHub(api_key=os.environ["CPFHUB_API_KEY"])

@app.get("/cpf/{cpf}")
def consultar_cpf(cpf: str):
    try:
        return client.lookup(cpf)["data"]
    except ValueError:
        raise HTTPException(status_code=400, detail="CPF deve conter 11 dígitos")
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 404:
            raise HTTPException(status_code=404, detail="CPF não encontrado")
        if e.response.status_code == 422:
            raise HTTPException(status_code=422, detail="CPF inválido")
        # 401, 403, 429 e 5xx: chave, créditos ou limite. Registre e não exponha ao cliente.
        try:
            detalhe = e.response.json()
        except ValueError:
            detalhe = e.response.text
        print("CPFHub.io", e.response.status_code, detalhe)
        raise HTTPException(status_code=503, detail="Consulta de CPF indisponível no momento")

Django view

Python

import os
import httpx
from django.http import JsonResponse
from cpfhub import CPFHub

client = CPFHub(api_key=os.environ["CPFHUB_API_KEY"])

def consultar_cpf(request, cpf):
    try:
        data = client.lookup(cpf)["data"]
        return JsonResponse({"name": data["name"], "gender": data["gender"]})
    except ValueError:
        return JsonResponse({"error": "CPF deve conter 11 dígitos"}, status=400)
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 404:
            return JsonResponse({"error": "CPF não encontrado"}, status=404)
        if e.response.status_code == 422:
            return JsonResponse({"error": "CPF inválido"}, status=422)
        # 401, 403, 429 e 5xx: chave, créditos ou limite. Não exponha ao cliente.
        return JsonResponse({"error": "Consulta de CPF indisponível no momento"}, status=503)

Validação em formulário

Python

import os
import httpx
from cpfhub import CPFHub

client = CPFHub(api_key=os.environ["CPFHUB_API_KEY"])

def validar_cpf_onboarding(cpf: str) -> dict:
    try:
        data = client.lookup(cpf)["data"]
        return {"valid": True, "name": data["name"]}
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 404:
            return {"valid": False, "name": None}
        raise

Repositório e suporte

github.com/cpfhub/cpfhub-python: código-fonte, issues e contribuições
PyPI: cpfhub: versões

Atualizado em 3 de outubro de 2026