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 |
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.
Instalar
Criar o cliente
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. |
instanceToken não fica no cliente global. Passe sempre na chamada que opera uma instância:
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:
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:
import { VZapsClient } from '@vzaps/sdk';
const { VZapsClient } = require('@vzaps/sdk');
Variáveis recomendadas
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:
interface InstanceListResponse {
data: Array<{
id: string;
name: string;
billingStatus: string;
}>;
}
const instances = await vzaps.instances.list<InstanceListResponse>({
page: 1,
pageSize: 20,
});
Próximos passos
