# 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.

## Instalação

```bash
npm install @unicep/core
```

```bash
pnpm add @unicep/core
```

```bash
yarn add @unicep/core
```

```bash
bun add @unicep/core
```

## Sua primeira consulta

```ts
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.

## Com o seu framework

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

[React](/docs/react)
  [Vue](/docs/vue)
  [Angular](/docs/angular)
  [Implementar com IA](/docs/ai)
## Próximos passos

- [Como funciona](/docs/how-it-works): fallback, circuit breaker e erros.
- [Core](/docs/core): timeout, retry, cache e cancelamento.
- [Providers](/docs/providers): configurar, ordenar ou criar o seu.