cep-promise

    4.1.1 • Public • Published

    CEP Promise

    Known Vulnerabilities

    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


    @lucianopf

    @MarcoWorms

    @caio-ribeiro-pereira

    @chrisbenseler

    @luanmuniz

    @AlbertoTrindade

    @pedrro

    @petronetto

    @olegon

    @jhonnymoreira

    @claytonsilva

    @thiamsantos

    @flyingluscas

    @otaviopace

    @vagnercardosoweb

    @murilohns

    @dominguetigs

    @fontebasso

    Autor


    @filipedeschamps

    Install

    npm i cep-promise

    DownloadsWeekly Downloads

    8,641

    Version

    4.1.1

    License

    MIT

    Unpacked Size

    76.1 kB

    Total Files

    8

    Last publish

    Collaborators

    • filipedeschamps
    • lucianopf