Projeto derivado de filipedeschamps/cep-promise, modernizado e mantido independentemente por @Rafa-MKR2 através do pacote @rafa-mkr2/zipcode-br.

Features

• Sempre atualizado em tempo-real por se conectar diretamente aos serviços ViaCEP, BrasilAPI e Cep Aberto.
• 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 conhecidos de uso (verifique os termos do serviço em uso, pois o ViaCEP pode aplicar limites).
• Interface de Promise extremamente simples.
• Suporte ao Node.js 18+ (LTS).
• Suporte opcional ao Cep Aberto mediante token configurável (cepAbertoToken).
• Cobertura de código 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.

import cep from '@rafa-mkr2/zipcode-br'

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

  // {
  //   "cep":  "05010000",
  //   "state":  "SP",
  //   "city":  "São Paulo",
  //   "street":  "Rua Caiubi",
  //   "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 '@rafa-mkr2/zipcode-br'

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

  // {
  //   "cep":  "05010000",
  //   "state":  "SP",
  //   "city":  "São Paulo",
  //   "street":  "Rua Caiubi",
  //   "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.

Os serviços consultados dependem do ambiente e da configuração: no Node o padrão é ViaCEP + BrasilAPI; o Cep Aberto entra somente quando createCepPromise é usado com cepAbertoToken; no browser o padrão é ViaCEP + BrasilAPI (CORS).

Correios foi descontinuado: o endpoint público apps.correios.com.br retorna 403 desde 2024, tornando o serviço inoperante. Ele foi removido dos fornecedores ativos e o código ficou preservado em src/services/correios.js para uma futura reabilitação (ver docs/melhorias-pendentes.md #1).

import cep from '@rafa-mkr2/zipcode-br'

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

  // {
  //     name: 'CepPromiseError',
  //     message: 'Todos os serviços de CEP retornaram erro.',
  //     type: 'service_error',
  //     errors: [{
  //       message: 'CEP não encontrado na base do ViaCEP.',
  //       service: 'viacep'
  //     }, {
  //       message: 'CEP não encontrado na base do BrasilAPI.',
  //       service: 'brasilapi'
  //     }]
  // }

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 '@rafa-mkr2/zipcode-br'

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

Instalação

Browser usando CDN

<script src="https://cdn.jsdelivr.net/npm/@rafa-mkr2/zipcode-br/dist/cep-promise.min.js"></script>
<script>
  // O script expõe a função global `cep`, diretamente chamável
  cep('05010000').then(console.log)
</script>

npm

$ npm install --save @rafa-mkr2/zipcode-br

Angular

import cep from '@rafa-mkr2/zipcode-br'

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

CommonJS (Node.js)

const cep = require('@rafa-mkr2/zipcode-br')

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

Personalizando o comportamento com createCepPromise

O export default é criado na carga do módulo com opções padrão (timeout de 10s, sem token do Cep Aberto). Para customizar, use createCepPromise:

import { createCepPromise } from '@rafa-mkr2/zipcode-br'

// com timeout personalizado e token do Cep Aberto
const cep = createCepPromise(undefined, {
  timeout: 5000,
  cepAbertoToken: process.env.CEP_ABERTO_TOKEN
})

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

Tratando erros com CepPromiseError

A classe de erro é exportada para você usar instanceof nos handlers:

import cep, { CepPromiseError } from '@rafa-mkr2/zipcode-br'

cep('00000000').catch((error) => {
  if (error instanceof CepPromiseError) {
    console.log(error.type, error.errors)
  }
})

O resgate deste código (bastidores)

Este pacote é um fork do clássico cep-promise que ficou anos sem manutenção. Revivê-lo significou enfrentar problemas como: o pacote não carregava em nenhum consumidor (require retornava {}; import dava SyntaxError), um token de API exposto no código-fonte, serviços de terceiros mortos, um endpoint dos Correios retornando 403 e bugs escondidos que só apareceram contra as APIs reais e num navegador de verdade.

📖 Leia o relato completo em docs/revivendo-o-codigo.md — os problemas, as dificuldades e as lições de reviver código legado.

Testes

Os testes unitários são offline (usam fetch-mock e não dependem de internet); os testes E2E consultam os serviços reais (ViaCEP, BrasilAPI e, opcionalmente, Cep Aberto).

# Instalação
npm install

# Lint (standard)
npm run lint-check

# Testes unitários + cobertura (offline)
npm test                # build + testes unitários
npm run test-coverage   # testes unitários com relatório de cobertura

# Testes E2E (serviços reais: ViaCEP + BrasilAPI no Node)
npm run test-e2e

# Smoke test de consumo: empacota com npm pack e valida require/import/UMD
npm run smoke-test

Testando o Cep Aberto (3º fornecedor)

O Cep Aberto exige um token (cepAbertoToken). Por segurança, o token nunca é versionado — o teste E2E do Cep Aberto lê a variável de ambiente CEP_ABERTO_TOKEN e é pulado automaticamente quando ela não está definida:

# 1. Obtenha um token gratuito em https://cepaberto.com (cadastro simples)
# 2. Exporte a variável e rode o E2E
CEP_ABERTO_TOKEN=seu-token npm run test-e2e

Esse teste usa createCepPromise com cepAbertoToken e um fetch custom que faz os demais fornecedores falharem, garantindo que a resposta venha do Cep Aberto contra a API real (exercício determinístico do 3º fornecedor).

Os testes unitários do Cep Aberto (test/unit/services.spec.js) usam token fictício e não precisam da variável de ambiente.

Como contribuir

Leia nosso guia de contribuição aqui

Documentação técnica em docs/: revivendo-o-codigo.md (relato do resgate), manutencao.md, divergencias.md e melhorias-pendentes.md.

Contribuidores

| @lucianopf | @MarcoWorms | @caio-ribeiro-pereira | @chrisbenseler | @luanmuniz | @AlbertoTrindade | |:-:|:-:|:-:|:-:|:-:|:-:| | @pedrro | @petronetto | @olegon | @jhonnymoreira | @claytonsilva | @thiamsantos | | @flyingluscas | @otaviopace |

Créditos

Este projeto foi originalmente baseado no excelente projeto filipedeschamps/cep-promise.

A implementação original serviu como base desta biblioteca.

Esta versão realiza principalmente:

• atualização para versões modernas do Node.js;
• remoção de dependências e ferramentas legadas;
• modernização do processo de build;
• manutenção contínua;
• futuras correções e melhorias.

Todo o mérito pela ideia e implementação inicial pertence ao autor original e aos contribuidores do projeto.

Autor original

| @filipedeschamps | | :---: |

Manutenção deste projeto

| @Rafa-MKR2 | | :---: |

Rafael Do Carmo

Responsável pela manutenção deste projeto, atualização para versões modernas do Node.js, modernização da infraestrutura e evolução contínua da biblioteca.