CEP Promise

Busca por CEP integrado diretamente aos serviços dos Correios e ViaCEP

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 usar concorrência
• Sem limites de uso (rate limit) conhecidos
• Interface de Promise extremamente simples
• Suporte ao Node.js 0.10.x, 0.12.x, 4.x, 5.x, 6.x e @stable
• 100% de code coverage com testes unitários e E2E
• Desenvolvido utilizando ES6

Como utilizar

Instalação

$ npm 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);

  // {
  //   "zipcode":  "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 cortanto 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);

  // {
  //   "zipcode":  "05010000",
  //   "state":  "SP",
  //   "city":  "São Paulo",
  //   "street":  "Rua Caiubí",
  //   "neighborhood":  "Perdizes",
  // }

Quando o CEP não é encontrado

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);

  // [
  //   {
  //     "type": "range_error",
  //     "message": "CEP não encontrado na base dos Correios",
  //     "service": 'correios'
  //   },
  //   {
  //     "type": "range_error",
  //     "message": "CEP inválido",
  //     "service": "viacep"
  //   }
  // ]

Quando o CEP possui um formato inválido

Neste caso a biblioteca irá rejeitar imediatamente a Promise, sem chegar a consultar nenhum fornecedor.

import cep from 'cep-promise';

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

  // [
  //   {
  //     "type": "type_error",
  //     "message": "CEP deve conter exatamente 8 caracteres",
  //     "service": undefined
  //   }
  // ]

Contribuidores

@lucianopf	@MarcoWorms	@caio-ribeiro-pereira	@chrisbenseler	@luanmuniz	@AlbertoTrindade

Autor

@filipedeschamps