CEP Promise

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

Features

Sempre atualizado em tempo-real por se conectar diretamente aos serviços dos Correios, ViaCEP e WideNet.
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 10.x, 11.x, 12.x, 13.x, 14.x e @stable.
Suporte ao Node.js 4.x, 5.x, 6.x, 7.x, 8.x, 9.x, até cep-promise versão 3.0.9.
Suporte ao Node.js 0.10.x e 0.12.x até cep-promise versão 2.0.8.
100% de code coverage com testes unitários e E2E.
Desenvolvido utilizando ES6.

Como utilizar

Teste e aprenda aqui.

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

Options

timeout: Timeout em milisegundos das consultas em cada serviço. O tempo total poderá ser maior devido a limites no paralelismo.
providers: Lista de providers a serem usados na consulta. Default é usar todos os providers disponíveis.

import cep from 'cep-promise'
cep('5010000', { timeout: 5000, providers: ['brasilapi'] })
  .then(console.log)

Instalação

Browser usando CDN

<script src="https://cdn.jsdelivr.net/npm/cep-promise/dist/cep-promise.min.js"></script>

npm

$ npm install --save cep-promise

Bower

$ bower install --save cep-promise

yarn

$ yarn add cep-promise

Angular 2

import * as cep from 'cep-promise'

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

Como contribuir

Leia nosso guia de contribuição aqui

Contribuidores

Autor

br><sub>@filipedeschamps</sub

BrasilAPI / cep-promise

readme