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()
}
| Classe | Uso | Biblioteca de serialização |
|---|---|---|
| CPFResponse | Resposta completa da API | kotlinx.serialization |
| CPFData | Dados do CPF | kotlinx.serialization |
| CPFResult | Sealed class para Result pattern | Nenhuma |
- @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ério | Ktor Client | Retrofit |
|---|---|---|
| Multiplataforma (KMP) | Sim | Apenas JVM/Android |
| Configuração | Plugins modulares | Converters e interceptors |
| Serialização padrão | kotlinx.serialization | Gson ou Moshi |
| Curva de aprendizado | Moderada | Baixa (popular) |
| Coroutines nativo | Sim | Sim (desde v2.6) |
| Tamanho do bundle | Menor | Maior (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.
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.



