Como consumir uma API REST de consulta de CPF em Python

Introdução

As APIs REST são amplamente utilizadas para integrar sistemas e acessar informações externas de forma programática. Para empresas que precisam validar dados cadastrais de clientes, como fintechs e e-commerces, consumir uma API de consulta de CPF pode ser essencial para evitar fraudes e garantir conformidade regulatória.

Neste guia, explicamos passo a passo como consumir a API da CPFHub.io utilizando Python. Exploraremos exemplos com as bibliotecas requests e httpx, garantindo que você consiga realizar consultas de forma segura e eficiente.

1. Pré-requisitos

Antes de começar, você precisará:

✅ Python instalado (versão 3.7 ou superior recomendada).
✅ Conta na CPFHub.io para obter a chave de API.
✅ Bibliotecas requests ou httpx para fazer chamadas HTTP.

2. Instalando as bibliotecas necessárias

Caso não tenha a biblioteca requests instalada, execute o seguinte comando:

pip install requests

Se preferir utilizar a biblioteca httpx, instale com:

pip install httpx

Ambas são excelentes opções para realizar requisições HTTP em Python.

3. Fazendo uma consulta de CPF com Python

Usando requests

Aqui está um exemplo de como consultar um CPF utilizando a API da CPFHub.io com a biblioteca requests:

import requests

API_KEY = "SUA_CHAVE_DE_API"
URL = "https://api.cpfhub.io/api/cpf"

payload = {
    "cpf": "123.456.789-00",
    "birthDate": "15/06/1990"
}

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

response = requests.post(URL, json=payload, headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print("Erro na consulta:", response.status_code, response.text)

Usando httpx

A biblioteca httpx é uma alternativa moderna ao requests, oferecendo suporte assíncrono.

import httpx

API_KEY = "SUA_CHAVE_DE_API"
URL = "https://api.cpfhub.io/api/cpf"

payload = {
    "cpf": "123.456.789-00",
    "birthDate": "15/06/1990"
}

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

with httpx.Client() as client:
    response = client.post(URL, json=payload, headers=headers)
    if response.status_code == 200:
        print(response.json())
    else:
        print("Erro na consulta:", response.status_code, response.text)

Se quiser rodar a requisição de forma assíncrona, use:

import httpx
import asyncio

async def consulta_cpf():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.cpfhub.io/api/cpf",
            json={"cpf": "123.456.789-00", "birthDate": "15/06/1990"},
            headers={"Content-Type": "application/json", "x-api-key": "SUA_CHAVE_DE_API"}
        )
        print(response.json())

asyncio.run(consulta_cpf())

4. Exemplo de resposta da API

Após a requisição, a API retornará um JSON com as informações do CPF consultado:

{
  "success": true,
  "data": {
    "name": "João da Silva",
    "status": "Regular",
    "situation": "Ativo",
    "birthDate": "15/06/1990",
    "cpfNumber": "12345678900",
    "registrationDate": "anterior a 10/11/1990",
    "verificationDigit": "03",
    "receipt": {
      "emissionTime": "22:08:26",
      "emissionDate": "13/01/2025",
      "controlCode": "XXXX.XXXX.XXXX.XXXX"
    },
    "validationUrl": "https://servicos.receita.fazenda.gov.br/Servicos/CPF/ca/ResultadoAut.asp?cp=12345678900&cc=XXXXXX&de=13012025&he=220826&dv=03&em=01",
    "validationHtmlUrl": "https://api.cpfhub.io/api/view-proof/12345678900/XXXXXXXXXXXXX"
  }
}

✅ O que essa resposta indica?

• success: Se a consulta foi realizada com sucesso.

• name: Nome completo do titular do CPF.

• status: Indica se o CPF está regular ou irregular.

• situation: Situação cadastral do CPF.

• birthDate: Data de nascimento associada ao CPF.

• validationUrl: Link direto para consulta na Receita Federal.

5. Tratamento de erros

A API pode retornar erros caso os dados sejam inválidos ou a chave de API esteja incorreta. Veja um exemplo de tratamento de erros:

if not response.json().get("success", False):
    print("Erro na consulta:", response.json().get("message", "Erro desconhecido"))

Mensagens de erro comuns:

✅ Dica: Sempre valide a entrada do usuário antes de enviar uma consulta para evitar erros desnecessários.

Conclusão

Consumir uma API REST de consulta de CPF em Python é um processo simples e essencial para empresas que desejam validar clientes e evitar fraudes. Utilizando requests ou httpx, é possível fazer consultas rápidas e seguras.