CEP em aplicativos mobile: integração e boas práticas

CEP em apps: desafios específicos do mobile

Integrar CEP em aplicativos mobile tem particularidades que não existem na web: teclado que ocupa metade da tela, conexão instável, e a possibilidade de usar a localização do dispositivo como alternativa ao CEP.

Busca por CEP via API REST

A forma mais simples é consumir a API REST do CepRua diretamente do app:

Android (Kotlin + Retrofit)

interface CepService {
    @GET("api/cep/{cep}")
    suspend fun buscar(@Path("cep") cep: String): Response<CepResponse>
}
data class CepResponse(
    val cep: String,
    val logradouro: String,
    val bairro: String,
    val cidade: String,
    val uf: String,
    val ibge: String?
)
// Uso
val response = cepService.buscar(cepLimpo)
if (response.isSuccessful) {
    val dados = response.body()
    // preencher campos
}

iOS (Swift + URLSession)

struct CepResponse: Codable {
    let cep: String
    let logradouro: String
    let bairro: String
    let cidade: String
    let uf: String
}
func buscarCep(_ cep: String) async throws -> CepResponse {
    let url = URL(string: "https://ceprua.com.br/api/cep/\(cep)")!
    let (data, _) = try await URLSession.shared.data(from: url)
    return try JSONDecoder().decode(CepResponse.self, from: data)
}

Localização como alternativa ao CEP

Em vez de digitar o CEP, o usuário pode permitir que o app detecte a localização atual e busque o endereço correspondente. Essa é uma alternativa excelente para apps de entrega e serviços locais. O fluxo seria:

1. Solicitar permissão de localização
2. Obter latitude e longitude via GPS
3. Fazer geocodificação reversa (coordenadas → endereço)
4. Preencher os campos com o resultado A geocodificação reversa pode ser feita via Google Maps Geocoding API ou alternativas como Nominatim (OpenStreetMap).

Use localização como complemento, não como substituto. Nem todo usuário concede a permissão, e a precisão do GPS pode variar.

Teclado numérico no campo CEP

Configure o campo para abrir o teclado numérico automaticamente: Android:

<EditText
    android:inputType="number"
    android:maxLength="9"
    android:hint="00000-000" />

iOS:

textField.keyboardType = .numberPad

Tratamento de conexão instável

Em mobile, a conexão pode cair durante a requisição. Implemente:

• Timeout curto — 5 segundos é o suficiente; se demorar mais, algo está errado
• Fallback manual — se a requisição falhar, libere os campos para preenchimento manual sem travar o fluxo
• Retry discreto — tente uma vez automaticamente antes de exibir mensagem de erro

Cache local no dispositivo

CEPs consultados recentemente podem ser armazenados localmente para funcionar offline ou em situações de conexão lenta:

// Android — SharedPreferences simples
val cached = prefs.getString("cep_$cepLimpo", null)
if (cached != null) {
    val dados = gson.fromJson(cached, CepResponse::class.java)
    preencherCampos(dados)
} else {
    val dados = buscarNaApi(cepLimpo)
    prefs.edit().putString("cep_$cepLimpo", gson.toJson(dados)).apply()
    preencherCampos(dados)
}

Acessibilidade em telas pequenas

• Campos de endereço devem ter tamanho mínimo de toque de 44×44pt (iOS) ou 48×48dp (Android)
• Labels visíveis — não dependa só de placeholder, que some quando o usuário começa a digitar
• Ordem de foco lógica: CEP → Rua → Número → Complemento → Bairro → Cidade → Estado