GSE
GRUPOSILVAENTERPRISE

API v1 · REST + JSON

Documentação da GSE API

API REST para enviar mensagens e áudios pelo WhatsApp e consultar o status da sua instância. Todas as requisições usam JSON, autenticação por Bearer token e retornam a mesma estrutura{ ok, data?, error? }.

Base URL

https://gruposilvaenterprise.lovable.app/api/v1

Autenticação

Cada requisição precisa de uma chave criada no painel em Chaves de API. As chaves têm o formato gse_live_<prefix>_<secret> e só são exibidas uma única vez no momento da criação — guarde em local seguro.

Envie a chave em um destes headers:

# Recomendado — header padrão
Authorization: Bearer gse_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Alternativo — compatível com clientes que não suportam Authorization
apikey: gse_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Escopos

Cada chave carrega um conjunto de escopos que autorizam endpoints específicos. Uma chave sem whatsapp:send não pode chamar /messages/*.

Limites e cota

A GSE API aplica limite por minuto e cota mensal por organização. Toda resposta bem-sucedida inclui os headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 2026-07-24T12:34:00.000Z

Quando o limite estoura, a API responde HTTP 429 com o header Retry-After em segundos.

Formato de resposta

Todas as respostas seguem o mesmo envelope JSON:

Sucesso

{
  "ok": true,
  "data": { /* payload */ }
}

Erro

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "API key inválida."
  }
}

Endpoints

GET/api/v1/instances/statusscope: instances:read

Status da instância WhatsApp

Retorna informações da organização vinculada à chave, incluindo o sessionId da instância WhatsApp, escopos concedidos e limites (rate limit e cota mensal).

Response (200)

{
  "ok": true,
  "data": {
    "orgId": "b1a2...uuid",
    "name": "Minha Empresa",
    "whatsapp": {
      "instanceId": "b1a2...uuid",
      "status": "connected",
      "phoneNumber": "5511999999999",
      "error": null
    },
    "scopes": ["whatsapp:send", "instances:read"],
    "rateLimitPerMinute": 60,
    "monthlyQuota": 100000
  }
}

Exemplo cURL

curl -X GET https://gruposilvaenterprise.lovable.app/api/v1/instances/status \
  -H "Authorization: Bearer gse_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
POST/api/v1/instances/connectscope: instances:write

Conectar instância (gerar QR Code)

Inicia (ou retoma) a sessão WhatsApp da organização. Enquanto o status for `qr`, o campo `qrCode` traz o QR em data URL PNG — basta escanear no WhatsApp. Faça polling neste endpoint ou em `/instances/status` até o status virar `connected`.

Request body

{}

Response (200)

{
  "ok": true,
  "data": {
    "instanceId": "b1a2...uuid",
    "status": "qr",
    "qrCode": "data:image/png;base64,iVBORw0...",
    "phoneNumber": null
  }
}

Exemplo cURL

curl -X POST https://gruposilvaenterprise.lovable.app/api/v1/instances/connect \
  -H "Authorization: Bearer gse_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
POST/api/v1/instances/disconnectscope: instances:write

Desconectar instância

Encerra a sessão do WhatsApp e remove as credenciais em memória da instância.

Request body

{}

Response (200)

{
  "ok": true,
  "data": {
    "instanceId": "b1a2...uuid",
    "status": "disconnected"
  }
}

Exemplo cURL

curl -X POST https://gruposilvaenterprise.lovable.app/api/v1/instances/disconnect \
  -H "Authorization: Bearer gse_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
POST/api/v1/messages/textscope: whatsapp:send

Enviar mensagem de texto

Envia uma mensagem de texto para um contato ou grupo. O campo `to` aceita um JID completo (ex.: `5511999999999@s.whatsapp.net`) ou apenas os dígitos em formato E.164 sem o `+` — o servidor converte automaticamente.

Request body

{
  "to": "5511999999999",
  "text": "Olá do GSE API!"
}

Response (200)

{
  "ok": true,
  "data": {
    "to": "5511999999999@s.whatsapp.net",
    "delivered": true
  }
}

Exemplo cURL

curl -X POST https://gruposilvaenterprise.lovable.app/api/v1/messages/text \
  -H "Authorization: Bearer gse_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999999999","text":"Olá do GSE API!"}'
POST/api/v1/messages/audioscope: whatsapp:send

Enviar áudio (URL ou base64)

Envia um áudio como mensagem de voz (PTT). Use audioUrl com uma URL pública (mp3/ogg) OU audioBase64 com o conteúdo em base64 (aceita data URL). Envie apenas um dos dois; limite de 20MB.

Request body

{
  "to": "5511999999999",
  "audioUrl": "https://cdn.exemplo.com/mensagem.mp3"
}

// ou, enviando o arquivo direto:
{
  "to": "5511999999999",
  "audioBase64": "data:audio/ogg;base64,T2dnUwACAAAA..."
}

Response (200)

{
  "ok": true,
  "data": {
    "to": "5511999999999@s.whatsapp.net",
    "delivered": true
  }
}

Exemplo cURL

curl -X POST https://gruposilvaenterprise.lovable.app/api/v1/messages/audio \
  -H "Authorization: Bearer gse_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999999999","audioBase64":"T2dnUwACAAAA..."}'

Códigos de erro

HTTPCódigoDescrição
401unauthorizedAPI key ausente, inválida, revogada ou com formato incorreto.
403forbiddenA chave não possui o escopo necessário para o endpoint.
400invalid_inputCorpo da requisição não passou na validação (Zod).
400invalid_jsonO corpo enviado não é um JSON válido.
429rate_limitedLimite de requisições por minuto excedido. Veja o header Retry-After.
502whatsapp_errorA instância WhatsApp recusou a entrega ou não está conectada.
500internal_errorErro interno da GSE API. Tente novamente ou fale com o suporte.