Pular para o conteúdo

Providers

Um provider é o adaptador de um serviço de CEP. A unicep traz quatro, todos funcionam direto no navegador (os serviços liberam CORS) e devolvem o mesmo Address.

Função Serviço Traz complement Traz ibgeCode
viaCep() ViaCEP sim sim
brasilApi() BrasilAPI (CEP v2) não sim
openCep() OpenCEP sim sim
awesomeApi() AwesomeAPI não sim

O defaultProviders() devolve os quatro, nessa ordem.

A ordem da lista é a prioridade. Passe só os que quiser, na ordem que preferir:

import { Unicep, brasilApi, openCep, viaCep } from '@unicep/core';
const unicep = new Unicep({
providers: [brasilApi(), viaCep(), openCep()],
});

Todos os providers embutidos aceitam as mesmas opções:

Opção O que faz
fetch Sua própria implementação de fetch (padrão: globalThis.fetch). Útil para testes e proxies.
baseUrl Troca o endereço do serviço, para usar um proxy ou uma instância própria.
import { Unicep, brasilApi, viaCep } from '@unicep/core';
const unicep = new Unicep({
providers: [
viaCep({ baseUrl: 'https://meu-proxy.exemplo.com/viacep' }),
brasilApi({ fetch: meuFetch }),
],
});

Para aplicar as mesmas opções a todos de uma vez: defaultProviders({ fetch: meuFetch }).

Para usar um serviço que a unicep não tem, implemente a interface CepProvider:

import { CepNotFoundError, ProviderError, type CepProvider } from '@unicep/core';
const meuProvider: CepProvider = {
name: 'minha-api',
async lookup(cep, { signal }) {
const response = await fetch(`https://minha-api.exemplo.com/cep/${cep}`, { signal });
if (response.status === 404) throw new CepNotFoundError(cep);
if (!response.ok) throw new ProviderError('minha-api', `HTTP ${response.status}`);
const data = await response.json();
return {
cep,
street: data.rua,
neighborhood: data.bairro,
city: data.cidade,
state: data.uf,
};
},
};

Regras:

  • Devolva o endereço sem o campo provider; a unicep preenche com o name.
  • Lance CepNotFoundError quando o CEP não existe e outro erro (de preferência ProviderError) para falhas do serviço. Só falhas contam para o circuit breaker.
  • Repasse o signal ao fetch, para o timeout e o cancelamento funcionarem.
  • O name precisa ser único na instância.

A unicep não fornece, hospeda nem é dona de nenhum dado ou API de CEP. Ela só consulta serviços públicos independentes, cada um com seus termos, limites e disponibilidade, e não é afiliada a nenhum deles.