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.
- 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
ou01001000
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 um
status
. Esse status pode ser utilizado para controlar a ação em cada caso, cada um dos status acompanha ainda uma mensagem amigável sobre o problema
Adicione o trecho abaixo no seu arquivo raiz build.gradle
no final dos seus repositórios:
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
Adicione o trecho abaixo no seu arquivo build.gradle
do seu modulo:
dependencies {
implementation 'com.github.emanuelgalvao:busca-cep:1.0.0'
}
Para realizar a consulta você precisa apenas chamar o método getCepData
da classe SearchCep
passando o valor do CEP.
Esse método irá retornar um objeto do tipo CepCallback
, que pode representar Success
, Error
ou Validation
. A descrição de cada uma das situações vai estar na próxima seção.
IMPORTANTE: Esse método deve ser chamado em um escopo de Coroutine devido a utilizar 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:
val cep = "01.001-000"
val callback = SearchCep.instance.getCepData(cep)
when (callback) {
is CepCallback.Success -> {
handleSuccess(callback.cepModel)
}
is CepCallback.Error -> {
handleError(callback.cepErrorStatus)
}
is CepCallback.Validation -> {
handleValidation(callback.cepValidationStatus)
}
}
Caso ocorra sucesso na consulta será retornado um objeto desse tipo com as informações do CEP na variável cepModel
.
Modelo do conteúdo da variável cepModel
:
data class CepModel(val bairro: String,
val cep: String,
val complemento: String,
val ddd: String,
val gia: String,
val ibge: String,
val localidade: String,
val logradouro: String,
val siafi: String,
val uf: String)
Caso ocorra um erro na consulta do CEP relacionado a problemas no servidor ou o CEP ser inexistente será retornado um objeto desse tipo com o status do erro na variável cepErrorStatus
, a qual possui uma mensagem do motivo do erro.
Possíveis valores da variável cepErrorStatus
:
Status | Mensagem |
---|---|
INVALID_CEP | O CEP informado não foi encontrado. |
SERVER_ERROR | Ocorreu um erro no servidor. |
Caso ocorra um erro na validação do CEP informado antes de realizar a consulta será retornado um objeto desse tipo com o status de validação na variável cepValidationStatus
, a qual possui uma mensagem do motivo do erro de validação,
Possíveis valores da variável cepValidationStatus
:
Status | Mensagem |
---|---|
CEP_NULL | O CEP informado não pode ser nulo. |
CEP_EMPTY | O CEP informado não pode ser vazio. |
CEP_CONTAINS_LETTERS | O CEP informado contém letras ou caracteres especiais. |
CEP_INCORRECT_LENGTH | O CEP informado deve possuir 8 dígitos. |
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.