CPFHub.io

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.codeerror.statusCodeDescrição
CPF_NOT_FOUND404CPF não encontrado (sem consumo de crédito)
INVALID_CPF_FORMAT400Formato inválido
INVALID_CPF_DIGITS422Dígitos verificadores inválidos
MISSING_API_KEY401API Key ausente
INVALID_API_KEY401API Key inválida
RATE_LIMIT_EXCEEDED429Limite de taxa excedido
INSUFFICIENT_CREDITS403Sem 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


Atualizado em 12 de maio de 2026