SDK Swift
SDK oficial para Swift 5.9+ com async/await nativo, Codable e suporte a SPM (Swift Package Manager).
Instalação
Swift Package Manager
Adicione ao Package.swift:
Swift
dependencies: [
.package(url: "https://github.com/cpfhub/cpfhub-swift.git", from: "1.0.0"),
],
targets: [
.target(
name: "MeuApp",
dependencies: ["CPFHub"]
),
]Ou via Xcode: File → Add Package Dependencies e cole a URL do repositório.
Requerimentos: Swift 5.9+, macOS 13+ / iOS 16+ / Linux
Inicialização
Swift
import CPFHub
let client = CPFHubClient(apiKey: ProcessInfo.processInfo.environment["CPFHUB_API_KEY"]!)Com opções avançadas:
Swift
let client = CPFHubClient(
apiKey: "sua-api-key",
timeout: 10, // segundos, opcional
baseURL: URL(string: "https://api.cpfhub.io")! // opcional
)Métodos
client.lookup(_ cpf: String) async throws -> CPFHubResult
Swift
let result = try await client.lookup("12345678909")
print(result.data.name) // "João da Silva"
print(result.data.gender) // "M"Tipos de retorno:
Swift
public struct CPFHubResult: Codable {
public let success: Bool
public let data: CPFData
}
public struct CPFData: Codable {
public let cpf: String
public let name: String
public let nameUpper: String
public let gender: String // "M" | "F"
public let birthDate: String // "DD/MM/AAAA"
public let day: Int
public let month: Int
public let year: Int
}Tratamento de erros
Swift
import CPFHub
do {
let result = try await client.lookup("12345678909")
print(result.data.name)
} catch let error as CPFHubError {
print(error.code) // "CPF_NOT_FOUND"
print(error.message) // "CPF not found in our database"
print(error.statusCode) // 404
} catch {
print("Erro de rede: \(error)")
}Códigos de erro
error.code | error.statusCode | 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
SwiftUI - ViewModel
Swift
import SwiftUI
import CPFHub
@Observable
class CPFViewModel {
var cpfData: CPFData?
var errorMessage: String?
var isLoading = false
private let client = CPFHubClient(apiKey: "sua-api-key")
func lookup(_ cpf: String) async {
isLoading = true
defer { isLoading = false }
do {
let result = try await client.lookup(cpf)
cpfData = result.data
errorMessage = nil
} catch let error as CPFHubError {
errorMessage = error.code == "CPF_NOT_FOUND"
? "CPF não encontrado"
: "Erro: \(error.code)"
} catch {
errorMessage = "Erro de conexão"
}
}
}
struct ContentView: View {
@State private var vm = CPFViewModel()
@State private var cpf = ""
var body: some View {
VStack {
TextField("CPF", text: $cpf)
Button("Consultar") {
Task { await vm.lookup(cpf) }
}
if let data = vm.cpfData {
Text(data.name)
}
if let error = vm.errorMessage {
Text(error).foregroundStyle(.red)
}
}
}
}Vapor (servidor)
Swift
import Vapor
import CPFHub
func routes(_ app: Application) throws {
let cpfhub = CPFHubClient(apiKey: Environment.get("CPFHUB_API_KEY")!)
app.get("cpf", ":cpf") { req async throws -> Response in
let cpf = try req.parameters.require("cpf")
do {
let result = try await cpfhub.lookup(cpf)
return try Response(body: .init(data: JSONEncoder().encode(result.data)))
} catch let error as CPFHubError {
let body = try Response.Body(data: JSONEncoder().encode(["error": error.code]))
return Response(status: .init(statusCode: error.statusCode), body: body)
}
}
}Repositório e suporte
- github.com/cpfhub/cpfhub-swift - código-fonte, issues e contribuições
Atualizado em 12 de maio de 2026