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 cpfhubOu 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
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
api_key | String | - | Sua API Key (obrigatório) |
timeout | Duration | 10s | Timeout da requisição |
base_url | String | https://api.cpfhub.io | URL 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
| Variante | HTTP | Descrição |
|---|---|---|
NotFound | 404 | CPF não encontrado (sem consumo de crédito) |
InvalidFormat | 400 | Formato inválido |
InvalidDigits | 422 | Dígitos verificadores inválidos |
Unauthorized | 401 | API Key ausente ou inválida |
RateLimitExceeded | 429 | Limite de taxa excedido |
InsufficientCredits | 403 | Sem 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
- github.com/cpfhub/cpfhub-rust - código-fonte, issues e contribuições
- crates.io: cpfhub - versões e changelog
- docs.rs/cpfhub - documentação de referência
Atualizado em 12 de maio de 2026