Busca Cep SDK

O SDK Busca Cep é um projeto desenvolvido visando facilitar a consulta das informações de determinado CEP.

O projeto utiliza a API do ViaCEP para realizar as consultas das informações.

Características

• A consulta dos CEP's é feita utilizando Coroutines e Retrofit para realizar as requisições a API.
• O SDK realiza o ajuste do CEP para o formato correto, então você pode inserir CEP's nos formatos 01.001-000, 01001-000, 01001 000 ou 01001000 e ele realizará a formatação antes de realizar a consulta.
• Além disso o SDK também realiza algumas validações para validar o CEP, como:
  • Verificação de CEP nulo ou vazio
  • Verificação de quantidade de dígitos
  • Verificação se o CEP contém apenas números
• No caso de alguma falha na validação ou na consulta dos dados será retornado uma mensagem de erro clara, que pode ser repassada facilmente ao usuário para explciar o problema.

Pré-requisitos

Adicione o trecho abaixo no seu arquivo raiz build.gradle no final dos seus repositórios:

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Adicionando o SDK ao seu projeto

Adicione o trecho abaixo no seu arquivo build.gradle do seu modulo:

dependencies {
    implementation 'com.github.emanuelgalvao:busca-cep:2.0.0'
}

Como usar

Para realizar a consulta você possui duas opções para escolher a que melhor se adapta a sua necessidade:

1. Chamar o método getCepData da classe SearchCep passando o valor do CEP. Esse método irá retornar uma resposta do tipo CepResponse, que pode ser um Success, com um objeto CepData com as informações do CEP ou ser um Error, com uma mensagem explicando o que aconteceu.
2. Chamar o método getCepDataOrNull da classe SearchCep passando o valor do CEP. Esse método irá retornar um objeto CepData se conseguir realizar a consulta das informações, caso não consiga irá simplesmente retornar null.

IMPORTANTE: Esses métodos devem ser chamados em um escopo de Coroutine devido a utilizarem uma suspend fun para fazer a requisição.

Você pode verificar um exemplo de implementação no modulo app desse projeto, fique a vontade para clonar e rodar a aplicação.

Exemplo de utilização:

• getCepData

val cep = "01.001-000"

val response = SearchCep.getCepData(cep)

when (response) {
   is CepResponse.Success -> {
       handleSuccess(response.data)
   }
   is CepResponse.Error -> {
       handleError(response.message)
   }
}

• getCepDataOrNull

val cep = "01.001-000"

val cepData = SearchCep.getCepDataOrNull(cep)

if (cepData != null) {
   handleCepData(cepData)
}

Contribuição

Caso deseje contribuir com esse projeto realize o fork desse repositório e contribua utilizando os pull requests.

Qualquer contribuição é bem-vinda.

Caso tenha alguma dúvida ou problema durante a utilização pode abrir uma issue.