SDK de Python

SDK oficial para Python 3.8+. Hace la Consulta Simple (GET /cpf/{cpf}) y devuelve el JSON de la API como dict. El CPF es el número de identificación fiscal de personas físicas en Brasil.

Instalación

bash

pip install cpfhub

Con Poetry:

bash

poetry add cpfhub

Requisitos: Python 3.8+

Inicialización

Python

import os
from cpfhub import CPFHub

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

El cliente envía la clave en el header x-api-key y usa un timeout de 10 segundos. También se puede usar como context manager, que cierra la conexión al salir del bloque:

Python

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

Parámetros del constructor

Parámetro	Tipo	Descripción
`api_key`	`str`	Tu clave de API (obligatoria). Si está vacía, lanza `ValueError`

Métodos

`client.lookup(cpf)`

Consulta un CPF y devuelve el cuerpo de la respuesta de la 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	Descripción
`cpf`	`str`	CPF con o sin formato

Retorno: un dict en el formato de la Consulta Simple:

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

La Consulta en Tiempo Real y la consulta por lote se hacen por la API REST: POST https://api.cpfhub.io/cpf/realtime y POST https://api.cpfhub.io/cpf/bulk.

⚠

No uses client.get_quota()

La versión 1.0.0 del paquete trae un método get_quota() que llama a la dirección equivocada y no funciona. Para ver tu saldo y tu plan, llama directamente a GET https://api.cpfhub.io/quota (no consume crédito).

Manejo de errores

CPF sin 11 dígitos: lookup lanza ValueError antes de llamar a la API (no se consume crédito).
Respuestas 4xx y 5xx: el SDK lanza httpx.HTTPStatusError. El status está en e.response.status_code y el cuerpo de la API en e.response.json(). El campo error viene como texto ("...") o como objeto ({"message": "..."}), según el 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"}}  (la API responde en portugués: "CPF no encontrado en la base de datos")

Status	Motivo
`401`	Clave de API ausente o inválida
`403`	Créditos agotados o cuenta bloqueada
`404`	CPF no encontrado (no se consume crédito)
`422`	Dígito verificador incorrecto (no se consume crédito)
`429`	Límite de solicitudes por minuto: espera los segundos indicados en el header `Retry-After`

Lista completa en Códigos de Error.

Ejemplos de integración

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="El CPF debe tener 11 dígitos")
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 404:
            raise HTTPException(status_code=404, detail="CPF no encontrado")
        if e.response.status_code == 422:
            raise HTTPException(status_code=422, detail="CPF inválido")
        # 401, 403, 429 y 5xx: clave, créditos o límite. Regístralo y no lo expongas al cliente.
        try:
            detalle = e.response.json()
        except ValueError:
            detalle = e.response.text
        print("CPFHub.io", e.response.status_code, detalle)
        raise HTTPException(status_code=503, detail="Consulta de CPF no disponible en este 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": "El CPF debe tener 11 dígitos"}, status=400)
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 404:
            return JsonResponse({"error": "CPF no encontrado"}, status=404)
        if e.response.status_code == 422:
            return JsonResponse({"error": "CPF inválido"}, status=422)
        # 401, 403, 429 y 5xx: clave, créditos o límite. No lo expongas al cliente.
        return JsonResponse({"error": "Consulta de CPF no disponible en este momento"}, status=503)

Validación en formulario

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

Repositorio y soporte

github.com/cpfhub/cpfhub-python: código fuente, issues y contribuciones
PyPI: cpfhub: versiones

Actualizado el 3 de octubre de 2026