Como Consumir a API de CPF em Swift Usando URLSession

Para consumir a API de CPF da CPFHub.io em Swift, use URLSession com suporte nativo a async/await disponível desde o Swift 5.5. A integração envolve modelar a resposta com Codable, fazer uma requisição GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key, e decodificar o JSON retornado em structs tipadas. O resultado inclui nome, data de nascimento e gênero do titular em menos de um segundo.

Introdução

Swift é a linguagem principal para desenvolvimento de aplicações Apple, e URLSession é a API nativa para realizar requisições HTTP. Ao consumir a API de CPF do CPFHub.io em Swift, você tem acesso a uma integração robusta e type-safe com suporte nativo a async/await desde o Swift 5.5.

Modelando a resposta da API com Codable

O protocolo Codable do Swift permite decodificar JSON diretamente em structs tipadas, eliminando a necessidade de parsing manual.

import Foundation

struct CPFResponse: Codable {
    let success: Bool
    let data: CPFData
}

struct CPFData: Codable {
    let cpf: String
    let name: String
    let nameUpper: String
    let gender: String
    let birthDate: String
    let day: String
    let month: String
    let year: String
}

enum CPFError: Error, LocalizedError {
    case invalidCPF
    case networkError(Error)
    case invalidResponse
    case apiError(Int)
    case decodingError(Error)

    var errorDescription: String? {
    switch self {
    case .invalidCPF:
    return "CPF inválido. Verifique o formato."
    case .networkError(let error):
    return "Erro de rede: \(error.localizedDescription)"
    case .invalidResponse:
    return "Resposta inválida da API."
    case .apiError(let code):
    return "Erro da API: código \(code)"
    case .decodingError(let error):
    return "Erro ao decodificar: \(error.localizedDescription)"
    }
    }
}

• Codable -- protocolo que combina Encodable e Decodable para serialização bidirecional
• LocalizedError -- protocolo que fornece mensagens de erro legíveis ao usuário
• Enum com associated values -- permite carregar dados adicionais em cada caso de erro

Criando o serviço de consulta com async/await

Com Swift 5.5+, URLSession suporta async/await nativamente, tornando o código assíncrono muito mais legível.

import Foundation

class CPFService {
    private let baseURL = "https://api.cpfhub.io/cpf"
    private let apiKey: String
    private let session: URLSession

    init(apiKey: String, session: URLSession = .shared) {
    self.apiKey = apiKey
    self.session = session
    }

    func consultarCPF(_ cpf: String) async throws -> CPFData {
    let cpfLimpo = cpf.replacingOccurrences(
    of: "[^0-9]",
    with: "",
    options: .regularExpression
    )

    guard cpfLimpo.count == 11 else {
    throw CPFError.invalidCPF
    }

    guard let url = URL(string: "\(baseURL)/\(cpfLimpo)") else {
    throw CPFError.invalidCPF
    }

    var request = URLRequest(url: url)
    request.httpMethod = "GET"
    request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
    request.timeoutInterval = 15

    do {
    let (data, response) = try await session.data(for: request)

    guard let httpResponse = response as? HTTPURLResponse else {
    throw CPFError.invalidResponse
    }

    guard (200...299).contains(httpResponse.statusCode) else {
    throw CPFError.apiError(httpResponse.statusCode)
    }

    let decoder = JSONDecoder()
    let cpfResponse = try decoder.decode(CPFResponse.self, from: data)

    guard cpfResponse.success else {
    throw CPFError.invalidResponse
    }

    return cpfResponse.data
    } catch let error as CPFError {
    throw error
    } catch let error as DecodingError {
    throw CPFError.decodingError(error)
    } catch {
    throw CPFError.networkError(error)
    }
    }
}

• async throws -- a função é assíncrona e pode lançar erros, obrigando o chamador a tratar ambos
• session.data(for:) -- versão async do URLSession que retorna uma tupla (Data, URLResponse)
• guard let -- padrão Swift para validação antecipada com saída rápida em caso de falha

Validação local do CPF antes da chamada à API

Antes de consumir a API, é eficiente validar o CPF localmente usando o algoritmo dos dígitos verificadores.

extension String {
    var isCPFValid: Bool {
    let numbers = self.replacingOccurrences(
    of: "[^0-9]",
    with: "",
    options: .regularExpression
    )

    guard numbers.count == 11 else { return false }

    let digits = numbers.compactMap { Int(String($0)) }

    // Rejeitar sequências repetidas
    if Set(digits).count == 1 { return false }

    // Validar primeiro dígito verificador
    let sum1 = (0..<9).reduce(0) { $0 + digits[$1] * (10 - $1) }
    let remainder1 = sum1 % 11
    let check1 = remainder1 < 2 ? 0 : 11 - remainder1
    guard digits[9] == check1 else { return false }

    // Validar segundo dígito verificador
    let sum2 = (0..<10).reduce(0) { $0 + digits[$1] * (11 - $1) }
    let remainder2 = sum2 % 11
    let check2 = remainder2 < 2 ? 0 : 11 - remainder2
    guard digits[10] == check2 else { return false }

    return true
    }
}

// Uso combinado com o serviço
func validarEConsultar(cpf: String) async throws -> CPFData {
    guard cpf.isCPFValid else {
    throw CPFError.invalidCPF
    }

    let service = CPFService(apiKey: "sua-chave-aqui")
    return try await service.consultarCPF(cpf)
}

• Extension -- adiciona funcionalidade ao tipo String sem herança, padrão idiomático do Swift
• compactMap -- converte caracteres em inteiros descartando valores nil de forma segura
• reduce -- acumula a soma ponderada dos dígitos de forma funcional e concisa

A documentação oficial da Apple sobre URLSession e concorrência estruturada é a referência para boas práticas com async/await em aplicações iOS.

Tratamento avançado com retry e timeout

Em produção, é importante implementar lógica de retry para lidar com falhas transitórias de rede.

extension CPFService {
    func consultarComRetry(
    _ cpf: String,
    maxTentativas: Int = 3,
    delayBase: TimeInterval = 1.0
    ) async throws -> CPFData {
    var ultimoErro: Error?

    for tentativa in 0..<maxTentativas {
    do {
    return try await consultarCPF(cpf)
    } catch CPFError.invalidCPF {
    throw CPFError.invalidCPF
    } catch {
    ultimoErro = error
    if tentativa < maxTentativas - 1 {
    let delay = delayBase * pow(2.0, Double(tentativa))
    try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
    }
    }
    }

    throw ultimoErro ?? CPFError.invalidResponse
    }
}

• Exponential backoff -- o delay dobra a cada tentativa para não sobrecarregar a API
• Task.sleep -- suspende a task atual sem bloquear a thread
• Erros não retentáveis -- CPF inválido é lançado imediatamente, sem retry

Perguntas frequentes

Como configurar a API key do CPFHub.io de forma segura em um app Swift?

Armazene a API key no Info.plist do projeto como uma variável de ambiente, nunca no código-fonte. Acesse via Bundle.main.object(forInfoDictionaryKey: "CPFHUB_API_KEY") as? String. Para projetos com maior rigor de segurança, utilize o Keychain para armazenar e recuperar a chave após o primeiro acesso.

A API retorna HTTP 429 quando o limite de consultas é atingido?

Não. A CPFHub.io nunca bloqueia requisições nem retorna HTTP 429. Quando o limite do plano é atingido, cada consulta adicional é cobrada a R$0,15. O plano gratuito inclui 50 consultas mensais sem cartão de crédito; o plano Pro oferece 1.000 consultas por R$149/mês. Seu código não precisa tratar o status 429.

Como testar a integração com URLSession sem fazer chamadas reais à API?

Injete uma URLSession customizada no inicializador do CPFService usando o padrão de injeção de dependência já mostrado no guia. Em testes unitários, use URLProtocol para interceptar requisições e retornar respostas mockadas, evitando chamadas reais à API e consumo de cota durante o desenvolvimento.

Qual é a latência esperada da API CPFHub.io em apps iOS?

A latência média da API é de ~900ms em condições normais de rede. Em apps iOS, configure request.timeoutInterval = 15 para tolerar variações de conectividade mobile. A lógica de retry com exponential backoff cobre eventuais falhas transitórias sem impactar a experiência do usuário.

Conclusão

Consumir a API de CPF em Swift com URLSession é uma tarefa direta graças ao suporte nativo a async/await e ao protocolo Codable. Com a modelagem tipada da resposta, validação local do CPF, tratamento robusto de erros e lógica de retry, você tem uma integração pronta para produção em qualquer aplicação Apple. A combinação de segurança de tipos do Swift com a simplicidade da API da CPFHub.io resulta em código limpo, testável e de fácil manutenção.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e publique sua primeira consulta de CPF em Swift em menos de 30 minutos.