Pular para o conteúdo

Primeiros passos

A unicep consulta vários serviços de CEP por trás de uma única interface. Se um serviço cair, ela passa para o próximo e devolve sempre o mesmo objeto Address. Funciona no navegador e no Node.js 20 ou mais novo.

Janela do terminal
npm install @unicep/core
import { Unicep, defaultProviders } from '@unicep/core';
const unicep = new Unicep({ providers: defaultProviders() });
const address = await unicep.lookup('01310-100'); // com ou sem hífen
// {
// cep: '01310100',
// street: 'Avenida Paulista',
// complement: 'de 612 a 1510 - lado par',
// neighborhood: 'Bela Vista',
// city: 'São Paulo',
// state: 'SP',
// ibgeCode: '3550308',
// provider: 'viacep'
// }

O campo provider diz quem respondeu. complement e ibgeCode podem não vir, porque nem todo serviço devolve esses dados. Em CEPs de cidades inteiras, street e neighborhood vêm vazios.

O core é TypeScript puro. Para React, Vue e Angular há bindings que buscam sozinhos quando o CEP fica válido.

  • Como funciona: fallback, circuit breaker e erros.
  • Core: timeout, retry, cache e cancelamento.
  • Providers: configurar, ordenar ou criar o seu.