CEP Promise
Busca por CEP integrado diretamente aos serviços dos Correios, ViaCEP e outros (Node.js e Browser)
Features
- Sempre atualizado em tempo-real por se conectar diretamente aos serviços dos Correios, ViaCEP e outros.
- Possui alta disponibilidade por usar vários serviços como fallback.
- Sempre retorna a resposta mais rápida por fazer as consultas de forma concorrente.
- Sem limites de uso (rate limits) conhecidos.
- Interface de Promise extremamente simples.
- Suporte ao Node.js
4.x
,5.x
,6.x
,7.x
,8.x
,9.x
e@stable
. - Suportou ao Node.js
0.10.x
e0.12.x
até cep-promise versão2.0.8
. - 100% de code coverage com testes unitários e E2E.
- Desenvolvido utilizando ES6.
Como utilizar
Realizando uma consulta
Por ser multifornecedor, a biblioteca irá resolver a Promise com o fornecedor que mais rápido lhe responder.
// {// "cep": "05010000",// "state": "SP",// "city": "São Paulo",// "street": "Rua Caiubí",// "neighborhood": "Perdizes",// }
Você também poderá passar o CEP como Inteiro
Em muitos sistemas o CEP é utilizado erroneamente como um Inteiro (e com isto cortando todos os zeros à esquerda). Caso este seja o seu caso, não há problema, pois a biblioteca irá preencher os caracteres faltantes na String, por exemplo:
// enviando sem ter um zero à esquerda do CEP "05010000"// {// "cep": "05010000",// "state": "SP",// "city": "São Paulo",// "street": "Rua Caiubí",// "neighborhood": "Perdizes",// }
Quando o CEP não é encontrado
Neste caso será retornado um "service_error"
e por ser multifornecedor, a biblioteca irá rejeitar a Promise apenas quando tiver a resposta negativa de todos os fornecedores.
// {// name: 'CepPromiseError',// message: 'Todos os serviços de CEP retornaram erro.',// type: 'service_error',// errors: [{// message: 'CEP NAO ENCONTRADO',// service: 'correios'// }, {// message: 'CEP não encontrado na base do ViaCEP.',// service: 'viacep'// }, {// message: 'CEP não encontrado na base do Cep Aberto.',// service: 'cepaberto'// }]// }
Quando o CEP possui um formato inválido
Neste caso será retornado um "validation_error"
e a biblioteca irá rejeitar imediatamente a Promise, sem chegar a consultar nenhum fornecedor.
// {// name: 'CepPromiseError',// message: 'CEP deve conter exatamente 8 caracteres.',// type: 'validation_error',// errors: [{// message: 'CEP informado possui mais do que 8 caracteres.',// service: 'cep_validation'// }]// }
Instalação
Browser usando CDN
<script src="https://cdn.jsdelivr.net/npm/cep-promise/dist/cep-promise-browser.min.js"></script>
npm
$ npm install --save cep-as-promised
Webpack
É possível configurar o webpack.config.js
trocando caminho do cep-promise para usar o caminho correto da forma abaixo e com isto o import cep from 'cep-as-promised'
deverá funcionar como o esperado:
const path = require('path')
// ...
resolve: {
alias: {
"cep-promise": path.join(__dirname, 'node_modules', 'cep-promise', 'dist', 'cep-promise-browser.min.js')
}
}
Angular 2
cep'05010000'.thenconsole.log
Como contribuir
Leia nosso guia de contribuição aqui
Contribuidores
@lucianopf |
@MarcoWorms |
@caio-ribeiro-pereira |
@chrisbenseler |
@luanmuniz |
@AlbertoTrindade |
---|---|---|---|---|---|
@pedrro |
@petronetto |
@olegon |
@jhonnymoreira |
@claytonsilva |
@thiamsantos |
Autor
@filipedeschamps |
---|