> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vzaps.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação

> Como instalar, autenticar e configurar o SDK TypeScript oficial da VZaps

O SDK TypeScript oficial da VZaps encapsula autenticação, chamadas HTTP, headers obrigatórios, eventos realtime e os principais recursos da API pública.

Use este SDK quando quiser integrar a VZaps em aplicações Node.js, workers, backends TypeScript, CLIs ou automações server-to-server.

## Requisitos

| Recurso         | Versão                  |
| --------------- | ----------------------- |
| Node.js         | 18 ou superior          |
| TypeScript      | 5.x recomendado         |
| Package manager | `npm`, `yarn` ou `pnpm` |

<Tip>
  Não exponha `clientSecret` nem `instanceToken` em front-end público. Prefira usar o SDK em backend, API routes, jobs e automações server-to-server.
</Tip>

## Instalar

```bash theme={null}
npm install @vzaps/sdk
```

```bash theme={null}
yarn add @vzaps/sdk
```

```bash theme={null}
pnpm add @vzaps/sdk
```

## Criar o cliente

```ts theme={null}
import { VZapsClient } from '@vzaps/sdk';

const vzaps = new VZapsClient({
  clientToken: process.env.VZAPS_CLIENT_TOKEN!,
  clientSecret: process.env.VZAPS_CLIENT_SECRET!,
});
```

## Credenciais

O SDK trabalha com dois tipos de credenciais:

| Credencial      | Onde usar                    | Descrição                                                        |
| --------------- | ---------------------------- | ---------------------------------------------------------------- |
| `clientToken`   | `new VZapsClient()`          | Token público da conta, usado também no header `X-Client-Token`. |
| `clientSecret`  | `new VZapsClient()`          | Segredo usado pelo SDK para obter e renovar o JWT.               |
| `instanceToken` | Em cada chamada da instância | Token da instância, enviado como `X-Instance-Token`.             |

O `instanceToken` não fica no cliente global. Passe sempre na chamada que opera uma instância:

```ts theme={null}
await vzaps.messages.sendText({
  instanceId: 'VZ...',
  instanceToken: process.env.VZAPS_INSTANCE_TOKEN!,
  phone: '5511999999999',
  message: 'Olá pela VZaps',
});
```

## Autenticação automática

O SDK obtém o JWT automáticamente usando `clientToken` e `clientSecret`, guarda o token em memória e renova antes do vencimento.

Você raramente precisa chamar o token manualmente. Quando precisar integrar com código HTTP próprio:

```ts theme={null}
const accessToken = await vzaps.auth.getAccessToken();
```

## Opções do cliente

| Opção              | Tipo               | Padrão                                | Uso                                                           |
| ------------------ | ------------------ | ------------------------------------- | ------------------------------------------------------------- |
| `clientToken`      | `string`           | -                                     | Obrigatório. Token da conta.                                  |
| `clientSecret`     | `string`           | -                                     | Obrigatório. Segredo da conta.                                |
| `timeoutMs`        | `number`           | `30000`                               | Timeout HTTP em milissegundos.                                |
| `tokenSkewMs`      | `number`           | `60000`                               | Renovar JWT antes do vencimento real.                         |
| `fetch`            | `FetchLike`        | `globalThis.fetch`                    | Customizar transporte HTTP em testes ou runtimes específicos. |
| `webSocketFactory` | `WebSocketFactory` | `ws` no Node / `WebSocket` no browser | Customizar WebSocket.                                         |
| `userAgent`        | `string`           | -                                     | Header `User-Agent` em requests HTTP.                         |

## ESM e CommonJS

ESM:

```ts theme={null}
import { VZapsClient } from '@vzaps/sdk';
```

CommonJS:

```js theme={null}
const { VZapsClient } = require('@vzaps/sdk');
```

## Variáveis recomendadas

```bash theme={null}
VZAPS_CLIENT_TOKEN=seu-client-token
VZAPS_CLIENT_SECRET=seu-client-secret
VZAPS_INSTANCE_ID=VZ...
VZAPS_INSTANCE_TOKEN=token-da-instância
```

## Tipagem de respostas

Por padrão, respostas usam `unknown` porque a API pode evoluir. Você pode tipar a resposta esperada com generics:

```ts theme={null}
interface InstanceListResponse {
  data: Array<{
    id: string;
    name: string;
    billingStatus: string;
  }>;
}

const instances = await vzaps.instances.list<InstanceListResponse>({
  page: 1,
  pageSize: 20,
});
```

## Próximos passos

* Siga o [Starter Guide](/pt-BR/sdk/typescript/starter-guide) para criar uma instância, assinar, parear e enviar a primeira mensagem.
* Veja [Mensagens](/pt-BR/sdk/typescript/messages) para todos os tipos de envio.
* Veja [Instâncias e billing](/pt-BR/sdk/typescript/instances-and-billing), [Sessão](/pt-BR/sdk/typescript/session) e [Chats](/pt-BR/sdk/typescript/chats) para recursos centrais da instância.
* Veja [Webhooks](/pt-BR/sdk/typescript/webhooks), [Filas](/pt-BR/sdk/typescript/queues), [Grupos](/pt-BR/sdk/typescript/groups), [TypeBot](/pt-BR/sdk/typescript/typebot) e [Chatwoot](/pt-BR/sdk/typescript/chatwoot) para configuração e integrações.