CEP Promise

Busca por CEP integrado diretamente aos serviços dos Correios e ViaCEP (Node.js e Browser)

Features

• Sempre atualizado em tempo-real por se conectar diretamente aos serviços dos Correios ou ViaCEP
• Possui alta disponibilidade por usar 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 0.10.x, 0.12.x, 4.x, 5.x, 6.x, 7.x, 8.x e 9.x
• 100% de code coverage com testes unitários e E2E
• Desenvolvido utilizando ES6

Como utilizar

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-promise

OBS:

Detalhes para utilização da lib no browser quando utilizar o npm como gerenciador da dependência.

Lembrar de apontar para o arquivo /dist/cep-promise-browser.min.js quando quiser importar a lib.

Se estiverem utilizando webpack é possível configurar o webpack.config.js trocando caminho do cep-promise para usar o caminho correto da seguinte forma:

  const path = require('path')
  // ...

  resolve: {
    alias: {
      "cep-promise": path.join(__dirname, 'node_modules', 'cep-promise', 'dist', 'cep-promise-browser.min.js')
    }
  }

Com isto o import cep from 'cep-promise' deve funcionar como o esperado

Bower

$ bower install --save cep-promise

Realizando uma consulta

Por ser multifornecedor, a biblioteca irá resolver a Promise com o fornecedor que mais rápido lhe responder.

import cep from 'cep-promise'

cep('05010000')
  .then(console.log)

  // {
  //   "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:

import cep from 'cep-promise'

// enviando sem ter um zero à esquerda do CEP "05010000"
cep(5010000)
  .then(console.log)

  // {
  //   "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.

import cep from 'cep-promise'

cep('99999999')
  .catch(console.log)

  // {
  //     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'
  //     }]
  // }

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.

import cep from 'cep-promise'

cep('123456789123456789')
  .catch(console.log)

  // {
  //     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'
  //     }]
  // }

Usando com Angular 2

import * as cep from 'cep-promise'

...

cep('05010000')
  .then(console.log)

Como contribuir

Leia nosso guia de contribuição aqui

Contribuidores

@lucianopf	@MarcoWorms	@caio-ribeiro-pereira	@chrisbenseler	@luanmuniz	@AlbertoTrindade
@pedrro	@petronetto	@olegon	@jhonnymoreira	@claytonsilva

Autor

@filipedeschamps