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.
Escolhendo e ordenando
Seção intitulada “Escolhendo e ordenando”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()],});Configurando um provider
Seção intitulada “Configurando um provider”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 }).
Criando o seu provider
Seção intitulada “Criando o seu provider”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 oname. - Lance
CepNotFoundErrorquando o CEP não existe e outro erro (de preferênciaProviderError) para falhas do serviço. Só falhas contam para o circuit breaker. - Repasse o
signalaofetch, para o timeout e o cancelamento funcionarem. - O
nameprecisa ser único na instância.
Usando com responsabilidade
Seção intitulada “Usando com responsabilidade”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.