Como Consumir a API de CPF em Kotlin Usando Ktor Client e Retrofit

Aprenda a consumir a API de CPF em Kotlin usando Ktor Client e Retrofit. Comparação completa com exemplos práticos e boas práticas.

Redação CPFHub.io
Redação CPFHub.io
··7 min de leitura
Como Consumir a API de CPF em Kotlin Usando Ktor Client e Retrofit

Para consumir a API de CPF da CPFHub.io em Kotlin, você pode usar Ktor Client — solução multiplataforma da JetBrains, ideal para projetos Kotlin Multiplatform — ou Retrofit, a biblioteca mais popular no ecossistema Android. Ambas se integram nativamente com coroutines e retornam o mesmo modelo de dados, tornando a troca entre elas simples quando necessário.

Introdução

Kotlin oferece duas bibliotecas maduras para consumir APIs REST: Ktor Client, mantido pela JetBrains, e Retrofit, criado pela Square. Ambas são excelentes opções para integrar a API de CPF da CPFHub.io em aplicações Android ou backend Kotlin. A documentação oficial do Kotlin está disponível em kotlinlang.org, onde você encontra referências completas sobre coroutines, serialização e clientes HTTP.


Modelando a resposta da API

Independentemente da biblioteca HTTP escolhida, a modelagem dos dados é a mesma. Use data classes do Kotlin com anotações de serialização.

import kotlinx.serialization.Serializable

@Serializable
data class CPFResponse(
    val success: Boolean,
    val data: CPFData
)

@Serializable
data class CPFData(
    val cpf: String,
    val name: String,
    val nameUpper: String,
    val gender: String,
    val birthDate: String,
    val day: String,
    val month: String,
    val year: String
)

sealed class CPFResult {
    data class Success(val data: CPFData) : CPFResult()
    data class Error(val message: String, val code: Int? = null) : CPFResult()
}
ClasseUsoBiblioteca de serialização
CPFResponseResposta completa da APIkotlinx.serialization
CPFDataDados do CPFkotlinx.serialization
CPFResultSealed class para Result patternNenhuma
  • @Serializable -- anotação do kotlinx.serialization para deserialização automática de JSON
  • Sealed class -- padrão Kotlin para representar resultados com sucesso ou erro de forma type-safe
  • Data class -- gera automaticamente equals, hashCode, toString e copy

Implementação com Ktor Client

Ktor Client é a solução multiplataforma da JetBrains, ideal para projetos Kotlin Multiplatform (KMP).

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.client.request.*
import io.ktor.http.*
import io.ktor.serialization.kotlinx.json.*
import kotlinx.serialization.json.Json

class CPFServiceKtor(private val apiKey: String) {
    private val client = HttpClient(CIO) {
    install(ContentNegotiation) {
    json(Json {
    ignoreUnknownKeys = true
    isLenient = true
    })
    }
    install(HttpTimeout) {
    requestTimeoutMillis = 15_000
    connectTimeoutMillis = 10_000
    }
    defaultRequest {
    header("x-api-key", apiKey)
    }
    }

    suspend fun consultarCPF(cpf: String): CPFResult {
    val cpfLimpo = cpf.replace(Regex("[^0-9]"), "")

    if (cpfLimpo.length != 11) {
    return CPFResult.Error("CPF deve conter 11 dígitos")
    }

    return try {
    val response: CPFResponse = client.get(
    "https://api.cpfhub.io/cpf/$cpfLimpo"
    ).body()

    if (response.success) {
    CPFResult.Success(response.data)
    } else {
    CPFResult.Error("CPF não encontrado")
    }
    } catch (e: ClientRequestException) {
    CPFResult.Error("Erro do cliente: ${e.response.status}", e.response.status.value)
    } catch (e: ServerResponseException) {
    CPFResult.Error("Erro do servidor: ${e.response.status}", e.response.status.value)
    } catch (e: Exception) {
    CPFResult.Error("Erro de conexão: ${e.message}")
    }
    }

    fun close() {
    client.close()
    }
}
  • HttpClient(CIO) -- CIO é o engine coroutine-based do Ktor, ideal para alta concorrência
  • ContentNegotiation -- plugin que configura serialização/deserialização automática de JSON
  • defaultRequest -- aplica o header da API key em todas as requisições automaticamente

Implementação com Retrofit

Retrofit é a biblioteca mais popular no ecossistema Android, baseada em interfaces anotadas.

import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory
import retrofit2.http.GET
import retrofit2.http.Header
import retrofit2.http.Path
import retrofit2.Response
import okhttp3.OkHttpClient
import okhttp3.Interceptor
import java.util.concurrent.TimeUnit

interface CPFApi {
    @GET("cpf/{cpf}")
    suspend fun consultarCPF(
    @Path("cpf") cpf: String
    ): Response<CPFResponseRetrofit>
}

data class CPFResponseRetrofit(
    val success: Boolean,
    val data: CPFDataRetrofit
)

data class CPFDataRetrofit(
    val cpf: String,
    val name: String,
    val nameUpper: String,
    val gender: String,
    val birthDate: String,
    val day: String,
    val month: String,
    val year: String
)

class CPFServiceRetrofit(private val apiKey: String) {
    private val authInterceptor = Interceptor { chain ->
    val request = chain.request().newBuilder()
    .addHeader("x-api-key", apiKey)
    .build()
    chain.proceed(request)
    }

    private val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(authInterceptor)
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(15, TimeUnit.SECONDS)
    .build()

    private val api: CPFApi = Retrofit.Builder()
    .baseUrl("https://api.cpfhub.io/")
    .client(okHttpClient)
    .addConverterFactory(GsonConverterFactory.create())
    .build()
    .create(CPFApi::class.java)

    suspend fun consultarCPF(cpf: String): CPFResult {
    val cpfLimpo = cpf.replace(Regex("[^0-9]"), "")

    if (cpfLimpo.length != 11) {
    return CPFResult.Error("CPF deve conter 11 dígitos")
    }

    return try {
    val response = api.consultarCPF(cpfLimpo)
    if (response.isSuccessful && response.body()?.success == true) {
    val body = response.body()!!.data
    CPFResult.Success(CPFData(
    cpf = body.cpf, name = body.name,
    nameUpper = body.nameUpper, gender = body.gender,
    birthDate = body.birthDate, day = body.day,
    month = body.month, year = body.year
    ))
    } else {
    CPFResult.Error("CPF não encontrado", response.code())
    }
    } catch (e: Exception) {
    CPFResult.Error("Erro de conexão: ${e.message}")
    }
    }
}
  • Interface anotada -- Retrofit gera a implementação automaticamente a partir das anotações
  • Interceptor -- middleware do OkHttp que adiciona o header de autenticação em todas as requisições
  • Response wrapper -- permite verificar o status HTTP antes de acessar o body

Comparação entre Ktor Client e Retrofit

A escolha entre as duas bibliotecas depende do contexto do seu projeto.

CritérioKtor ClientRetrofit
Multiplataforma (KMP)SimApenas JVM/Android
ConfiguraçãoPlugins modularesConverters e interceptors
Serialização padrãokotlinx.serializationGson ou Moshi
Curva de aprendizadoModeradaBaixa (popular)
Coroutines nativoSimSim (desde v2.6)
Tamanho do bundleMenorMaior (OkHttp incluso)
// Uso unificado com ambas as implementações
suspend fun main() {
    val apiKey = System.getenv("CPFHUB_API_KEY")
    ?: throw IllegalStateException("API key não configurada")

    // Com Ktor
    val servicoKtor = CPFServiceKtor(apiKey)
    when (val resultado = servicoKtor.consultarCPF("12345678909")) {
    is CPFResult.Success -> println("Ktor: ${resultado.data.name}")
    is CPFResult.Error -> println("Ktor erro: ${resultado.message}")
    }
    servicoKtor.close()

    // Com Retrofit
    val servicoRetrofit = CPFServiceRetrofit(apiKey)
    when (val resultado = servicoRetrofit.consultarCPF("12345678909")) {
    is CPFResult.Success -> println("Retrofit: ${resultado.data.name}")
    is CPFResult.Error -> println("Retrofit erro: ${resultado.message}")
    }
}
  • Ktor Client -- escolha ideal se você precisa de suporte multiplataforma ou já usa Ktor no backend
  • Retrofit -- escolha ideal para projetos Android tradicionais com equipe já familiarizada
  • Sealed class -- ambas as implementações retornam o mesmo tipo, facilitando troca futura

Perguntas frequentes

Qual é a diferença prática entre Ktor Client e Retrofit para consumir a API de CPF?

Ktor Client é a escolha certa para projetos Kotlin Multiplatform (Android, iOS, backend compartilhado), pois funciona em todas as plataformas sem adaptações. Retrofit é mais adequado para projetos Android tradicionais com equipe já familiarizada com o ecossistema OkHttp. Ambas suportam coroutines nativamente e retornam os mesmos dados da API CPFHub.io.

Como configurar timeout corretamente para a latência de ~900ms da API?

Configure requestTimeoutMillis = 15_000 no Ktor ou readTimeout(15, TimeUnit.SECONDS) no OkHttp do Retrofit. A API CPFHub.io responde em cerca de 900ms em condições normais, mas timeouts de 15 segundos garantem margem para variações de rede sem deixar a UI travada.

Como proteger a API key em projetos Android com Kotlin?

Nunca inclua a x-api-key diretamente no código-fonte. Use variáveis de ambiente para backend ou, em Android, armazene a chave no local.properties e acesse via BuildConfig. Para projetos em produção, considere um backend intermediário que faz a chamada à API CPFHub.io sem expor a chave no cliente.

A API CPFHub.io retorna erro quando o limite de consultas é atingido?

Não. A CPFHub.io nunca bloqueia requisições nem retorna erro por limite de consultas. Quando o volume do plano é ultrapassado, a API continua respondendo normalmente e cobra R$0,15 por consulta adicional, debitado automaticamente. O plano gratuito oferece 50 consultas/mês sem cartão de crédito; o Pro inclui 1.000 consultas por R$149/mês.


Conclusão

Tanto Ktor Client quanto Retrofit são opções maduras e confiáveis para consumir a API de CPF em Kotlin. A escolha depende do seu cenário: Ktor Client para projetos multiplataforma e modernos, Retrofit para projetos Android com ecossistema já estabelecido. Independentemente da escolha, a combinação de coroutines do Kotlin com a API da CPFHub.io resulta em integrações limpas, assíncronas e prontas para produção.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF ao seu app Kotlin em menos de 30 minutos.

CPFHub.io

Pronto para integrar a API?

50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

Redação CPFHub.io

Sobre a redação

Redação CPFHub.io

Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.

WhatsAppFale conosco via WhatsApp