stevo-gestao

SDK oficial (TypeScript/JavaScript) da API de GESTÃO da Stevo — gestão de instâncias WhatsApp, links de acesso, GHL, billing e GHL Agência, direto do seu código ou da sua IA.

📦 Família de SDKs da Stevo: stevo-gestao (gestão da conta — este), stevo-apioficial (API Oficial Meta) e stevosmv2 (servidor SM v2) — em breve. 📚 Referência completa da API: https://tutorial.stevo.chat/public-api-reference 🤖 Prefere plugar uma IA sem escrever código? Use o servidor MCP: https://openapi.stevo.chat/mcp (mesma API key).

Instalação

npm install stevo-gestao

Node 18+ (usa fetch nativo). Funciona em ESM e CommonJS, com tipos inclusos.

Começando

Crie uma API key na aba API Keys do painel da Stevo (a key é da conta, com scopes que você escolhe).

import { Stevo } from 'stevo-gestao';

const stevo = new Stevo('stevo_sk_...');

// Quem sou eu (scopes, rate limit)
const eu = await stevo.me.get();

// Todas as instâncias da conta
const instancias = await stevo.instances.list();

// server_url + token de cada instância = fale direto com o servidor dela
// (envio de mensagem acontece no servidor da instância, não nesta API)
const conectadas = instancias.filter((i) => i.connected);

Instâncias

// Criar (provisiona um SLOT LIVRE da conta — não compra slot novo)
const nova = await stevo.instances.create({ name: 'minha-instancia' });
// engine 'official' (API Oficial Meta) devolve onboarding_url pra abrir no navegador:
const oficial = await stevo.instances.create({ engine: 'official' });

// Reiniciar (recriar/reconectar — leia o QR depois)
await stevo.instances.restart(id);

// Recriar Total (DESTRUTIVO: zera tudo, vira slot vazio)
await stevo.instances.recreateTotal(id);

// Em massa (até 50; falha em uma não interrompe as demais)
const lote = await stevo.instances.recreateTotalBatch([id1, id2, id3]);
console.log(`${lote.succeeded} ok, ${lote.failed} falharam`);

// Configurações (whitelist de campos)
await stevo.instances.updateSettings(id, { group_view: true });

Links, GHL e Billing

// Links de acesso
const wl = await stevo.links.whiteLabel(id, { permanent: true });
const direto = await stevo.links.directAccess(id);

// GHL da instância
const status = await stevo.ghl.status(id);
await stevo.ghl.connect(id, { mode: 'oauth' });          // devolve oauth_url
await stevo.ghl.disconnect(id);                           // idempotente

// Billing — compra com o CARTÃO SALVO (off-session, cobrança real!)
const catalogo = await stevo.billing.plans();
if (catalogo.has_saved_card) {
  await stevo.billing.purchase({ plan: 'stevo3' });
  // StevoVoice (voz com IA, por instância):
  await stevo.billing.purchase({ product: 'stevovoice', instance_id: id, tier: 5 });
}

GHL Agência (monitor de assinatura SaaS)

Monitore a assinatura SaaS (no GHL) de cada location conectado às suas instâncias, com ações automáticas:

// Cadastrar sua agência GHL (token privado a nível de agência)
await stevo.ghlAgency.createAgency({
  name: 'Minha Agência',
  company_id: 'X5KhNv...',
  agency_token: 'pit-...',
});

// Webhook + verificação diária + desconectar GHL sozinho após 7 dias pausado
await stevo.ghlAgency.updateSettings({
  webhook_url: 'https://meu-sistema.com/hook',
  cron_interval_hours: 24,
  auto_disconnect_ghl: true,
  auto_action_after_days: 7,
});

// Verificar agora
const { results } = await stevo.ghlAgency.runCheck();
const pausadas = results.filter((r) => r.is_problem);

Erros

Toda falha vira StevoError com status (HTTP) e code (negócio):

import { StevoError } from 'stevo-gestao';

try {
  await stevo.billing.purchase({ plan: 'stevo3' });
} catch (e) {
  if (e instanceof StevoError) {
    if (e.code === 'no_saved_card') {
      // conta sem cartão — mandar cadastrar no painel
    }
    console.error(e.status, e.code, e.message);
  }
}

Códigos comuns: unauthorized (401), insufficient_scope (403), not_found (404 — recurso de outra conta também), rate_limited (429, com retry automático), no_available_slot (409), no_saved_card / card_declined (402), partner_only / special_access_required (403), already_subscribed (409).

O SDK tenta de novo automaticamente em 429 (respeitando Retry-After) e erros 5xx, até 2 vezes (configurável em maxRetries).

Opções

const stevo = new Stevo('stevo_sk_...', {
  baseUrl: 'https://openapi.stevo.chat', // default
  timeoutMs: 60_000,                     // por request
  maxRetries: 2,                         // retries em 429/5xx
});

Para IAs (Claude, Cursor, Copilot...)

Cole isto no contexto da sua IA e ela implementa a integração sozinha:

Use o pacote npm stevo-gestao (TypeScript, tipos inclusos). Instancie new Stevo(apiKey) com a key stevo_sk_... da aba API Keys do painel Stevo. Recursos: me, instances (list/get/create/restart/recreateTotal/recreateTotalBatch/officialOnboarding/getSettings/updateSettings), links (whiteLabel/directAccess), ghl (status/connect/disconnect), billing (plans/purchase — cobrança real no cartão salvo), ghlAgency (overview/createAgency/updateAgency/deleteAgency/updateSettings/runCheck). Erros são StevoError com .status e .code. Referência completa: https://tutorial.stevo.chat/public-api-reference

Licença

MIT © Stevo