CPFHub.io

SDK Rust

SDK oficial para Rust com suporte a async/await via Tokio, tipagem forte e zero alocações desnecessárias.

Instalação

bash
cargo add cpfhub

Ou adicione ao Cargo.toml:

toml
[dependencies]
cpfhub = "1.0"
tokio = { version = "1", features = ["full"] }

Requerimentos: Rust 1.70+ (edição 2021)

Inicialização

Rust
use cpfhub::CPFHub;

#[tokio::main]
async fn main() {
    let client = CPFHub::new(std::env::var("CPFHUB_API_KEY").unwrap());
}

Com opções avançadas:

Rust
use cpfhub::{CPFHub, Config};
use std::time::Duration;

let client = CPFHub::with_config(Config {
    api_key: std::env::var("CPFHUB_API_KEY").unwrap(),
    timeout: Duration::from_secs(10),
    ..Default::default()
});

Campos de Config

CampoTipoPadrãoDescrição
api_keyString-Sua API Key (obrigatório)
timeoutDuration10sTimeout da requisição
base_urlStringhttps://api.cpfhub.ioURL base da API

Métodos

client.lookup(&str) -> Result<CPFHubResult, CPFHubError>

Rust
let result = client.lookup("12345678909").await?;

println!("{}", result.data.name);   // "João da Silva"
println!("{}", result.data.gender); // "M"

Tipos de retorno:

Rust
pub struct CPFHubResult {
    pub success: bool,
    pub data: CPFData,
}

pub struct CPFData {
    pub cpf: String,
    pub name: String,
    pub name_upper: String,
    pub gender: String,     // "M" | "F"
    pub birth_date: String, // "DD/MM/AAAA"
    pub day: u8,
    pub month: u8,
    pub year: u16,
}

Tratamento de erros

Rust
use cpfhub::{CPFHub, CPFHubError};

match client.lookup("12345678909").await {
    Ok(result) => println!("Nome: {}", result.data.name),
    Err(CPFHubError::NotFound) => println!("CPF não encontrado"),
    Err(CPFHubError::InvalidFormat) => println!("Formato inválido"),
    Err(CPFHubError::Unauthorized) => println!("API Key inválida"),
    Err(CPFHubError::RateLimitExceeded) => println!("Rate limit atingido"),
    Err(e) => eprintln!("Erro: {}", e),
}

Variantes de CPFHubError

VarianteHTTPDescrição
NotFound404CPF não encontrado (sem consumo de crédito)
InvalidFormat400Formato inválido
InvalidDigits422Dígitos verificadores inválidos
Unauthorized401API Key ausente ou inválida
RateLimitExceeded429Limite de taxa excedido
InsufficientCredits403Sem créditos disponíveis
Http(StatusCode, String)-Erro HTTP genérico
Network(reqwest::Error)-Falha de rede

Exemplos de integração

Axum

Rust
use axum::{extract::Path, http::StatusCode, Json, Router};
use cpfhub::{CPFHub, CPFHubError};
use serde_json::{json, Value};

async fn cpf_handler(
    Path(cpf): Path<String>,
) -> Result<Json<Value>, (StatusCode, Json<Value>)> {
    let client = CPFHub::new(std::env::var("CPFHUB_API_KEY").unwrap());
    
    match client.lookup(&cpf).await {
        Ok(result) => Ok(Json(serde_json::to_value(&result.data).unwrap())),
        Err(CPFHubError::NotFound) => {
            Err((StatusCode::NOT_FOUND, Json(json!({"error": "CPF_NOT_FOUND"}))))
        }
        Err(CPFHubError::RateLimitExceeded) => {
            Err((StatusCode::TOO_MANY_REQUESTS, Json(json!({"error": "RATE_LIMIT_EXCEEDED"}))))
        }
        Err(e) => {
            Err((StatusCode::INTERNAL_SERVER_ERROR, Json(json!({"error": e.to_string()}))))
        }
    }
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/cpf/:cpf", axum::routing::get(cpf_handler));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Repositório e suporte


Atualizado em 12 de maio de 2026