SDK Python

SDK oficial com suporte a Python 3.8+, tipagem completa via dataclasses e compatível com asyncio.

Instalação

bash

pip install cpfhub

Com Poetry:

bash

poetry add cpfhub

Requerimentos: Python 3.8+

Inicialização

Python

from cpfhub import CPFHub

client = CPFHub(
    api_key="sua-api-key",
    # timeout=10,  # opcional, padrão: 10 segundos
)

Usando variável de ambiente:

Python

import os
from cpfhub import CPFHub

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

Parâmetros do construtor

Parâmetro	Tipo	Padrão	Descrição
`api_key`	`str`	-	Sua API Key (obrigatório)
`timeout`	`float`	`10`	Timeout em segundos
`base_url`	`str`	`https://api.cpfhub.io`	URL base da API

Métodos

`client.lookup(cpf)`

Consulta um CPF e retorna os dados de identidade.

Python

result = client.lookup("12345678909")

Parâmetros:

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

Retorno: CPFHubResult

Python

@dataclass
class CPFHubResult:
    success: bool
    data: CPFData

@dataclass
class CPFData:
    cpf: str
    name: str
    name_upper: str
    gender: Literal["M", "F"]
    birth_date: str    # "DD/MM/AAAA"
    day: int
    month: int
    year: int

`await client.lookup_async(cpf)`

Versão assíncrona para uso com asyncio:

Python

import asyncio
from cpfhub import AsyncCPFHub

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

async def main():
    result = await client.lookup("12345678909")
    print(result.data.name)

asyncio.run(main())

Tratamento de erros

O SDK lança CPFHubError para todos os erros da API:

Python

from cpfhub import CPFHub, CPFHubError

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

try:
    result = client.lookup("12345678909")
except CPFHubError as e:
    print(e.code)        # "CPF_NOT_FOUND"
    print(e.message)     # "CPF not found in our database"
    print(e.status_code) # 404

Códigos de erro

`e.code`	`e.status_code`	Descrição
`CPF_NOT_FOUND`	`404`	CPF não encontrado (sem consumo de crédito)
`INVALID_CPF_FORMAT`	`400`	Formato inválido
`INVALID_CPF_DIGITS`	`422`	Dígitos verificadores inválidos
`MISSING_API_KEY`	`401`	API Key ausente
`INVALID_API_KEY`	`401`	API Key inválida
`RATE_LIMIT_EXCEEDED`	`429`	Limite de taxa excedido
`INSUFFICIENT_CREDITS`	`403`	Sem créditos disponíveis

Exemplos de integração

FastAPI

Python

from fastapi import FastAPI, HTTPException
from cpfhub import CPFHub, CPFHubError

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

@app.get("/cpf/{cpf}")
def consultar_cpf(cpf: str):
    try:
        result = client.lookup(cpf)
        return result.data
    except CPFHubError as e:
        raise HTTPException(status_code=e.status_code, detail=e.code)

Django view

Python

from django.http import JsonResponse
from cpfhub import CPFHub, CPFHubError

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

def consultar_cpf(request, cpf):
    try:
        result = client.lookup(cpf)
        return JsonResponse({"name": result.data.name, "gender": result.data.gender})
    except CPFHubError as e:
        return JsonResponse({"error": e.code}, status=e.status_code)

Validação em formulário

Python

from cpfhub import CPFHub, CPFHubError

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

def validar_cpf_onboarding(cpf: str) -> dict:
    try:
        result = client.lookup(cpf)
        return {"valid": True, "name": result.data.name}
    except CPFHubError as e:
        if e.code == "CPF_NOT_FOUND":
            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 e changelog

Atualizado em 12 de maio de 2026