API da Extensão

Endpoints que a extensão do Chrome consome e que o painel administrativo expõe: licença, perfil e agente de IA por instalação, além de conta, checkout e gestão administrativa. Todas as respostas são application/json (exceto redirects).

Autenticação

As rotas /admin/* exigem a senha de administrador, enviada no cabeçalho x-admin-pass (ou no corpo, campo adminPass). As rotas da extensão (/extensao/api/*) e de usuário são públicas — a vinculação é feita pelo installId e/ou pelo número de WhatsApp conectado.

# Exemplo de chamada autenticada (admin)
curl -H "x-admin-pass: SUA_SENHA" \
     https://www.geracaoderesultado.com.br/admin/licencas

Instalar e ativar a API

A API não é um servidor que você aponta e usa: ela conversa com o WhatsApp Web aberto no computador do atendente, através da extensão. Por isso a ativação tem três peças, e as três precisam estar de pé.

curl -s "https://bridge.geracaoderesultado.com.br/api/listar-etiquetas/SEU_TOKEN"

WhatsApp — enviar mensagens

Estas rotas ficam no bridge, não no site: é ele que leva o comando até o WhatsApp Web onde a extensão está conectada. O token vai no caminho e identifica o assinante — é ele que decide por qual WhatsApp a mensagem sai.

O token é gerado na própria extensão (trilha → API → botão ↻). Ninguém digita nem cola: quem emite é o servidor. Gerar um novo invalida o anterior. Não compartilhe — quem tiver o token manda mensagem pelo seu número.

curl -X POST "https://bridge.geracaoderesultado.com.br/api/enviar-texto/SEU_TOKEN" \
  -H "content-type: application/json" \
  -d '{"numero":"5511988880001","texto":"Olá!"}'

{ "ok": true }

curl -X POST ".../api/enviar-documento/SEU_TOKEN" \
  -H "content-type: application/json" \
  -d '{"numero":"5511988880001",
       "url":"https://cdn.seu-site.com/boleto.pdf",
       "nomeArquivo":"boleto.pdf"}'

{ "ok": true }

WhatsApp — etiquetas e notas

{ "ok": true, "etiquetas": [
  { "id": "1", "nome": "Fazer Matrícula", "cor": "#64C4FF" }
]}

{
  "numeros": ["5511988880001", "5511988880002"],
  "etiquetaId": "1",
  "acao": "adicionar"
}

{ "ok": true, "resultados": [
  { "numero": "5511988880001", "ok": true }
]}

{ "numero": "5511988880001", "texto": "Ligar amanhã" }

{ "mensagemId": "true_5511999999999@c.us_ABC123", "paraTodos": true }

WhatsApp — grupos e comunidades

Para o WhatsApp, uma comunidade é um grupo que tem subgrupos — por isso as duas coisas usam as mesmas rotas. Na listagem, ehComunidade distingue.

O identificador de um grupo termina em @g.us. Ele também serve como destino de envio: mande em chatId (ou grupo) nas rotas de envio, em vez de numero.

{ "ok": true, "grupos": [
  { "chatId": "1203630000000001@g.us",
    "nome": "Turma 2026",
    "participantes": 42,
    "ehComunidade": false,
    "subgrupos": 0 }
]}

{ "ok": true, "membros": [
  { "numero": "5511988880001", "nome": "Ana", "admin": true }
]}

{ "nome": "Turma 2026",
  "numeros": ["5511988880001", "5511988880002"] }

{ "ok": true,
  "chatId": "1203630000000001@g.us" }

{ "chatId": "1203630000000001@g.us",
  "numeros": ["5511988880003"],
  "acao": "promover" }

{ "ok": true, "subgrupos": ["1203630000000002@g.us"] }

{ "chatId": "1203630000000001@g.us",
  "texto": "Aviso para a turma" }

WhatsApp — erros e limites

Webhooks — a extensão avisa o seu sistema

Caminho inverso da API de envio: aqui é a extensão que chama você. Para cada evento marcado, ela faz um POST na URL configurada em trilha → WebHook, com Content-Type: application/json. Não há resposta esperada além de um 2xx.

{
  "evento": "mensagem_recebida",
  "timestamp": "2026-07-22T14:40:00.000Z",
  "numero": "5511958254568",
  "nome": "Vitória Eduarda",
  "foto": "https://...",
  "etiqueta": "Estágios",
  "perfil": { "isBusiness": false },
  "dados": { "id": "ABCD", "texto": "Olá", "tipo": "chat",
             "ts": 1784750700, "direcao": "recebida" },
  "usuario": { "numero": "551133387242" }
}

Webhooks — eventos e o que vem em dados

Em mensagem_recebida com mídia, dados.midia traz só os metadados — { mimetype, tamanho, duracao, nomeArquivo, isVoz }. Os bytes não vão no webhook (um áudio de 10 MB em base64 no corpo de cada evento inviabilizaria o recebimento). Peça o arquivo depois, com o dados.id da mensagem:

GET /api/baixar-midia/SEU_TOKEN
      ?mensagemId=ABCD123

{ "ok": true,
  "base64": "data:audio/ogg;base64,T2dnUw...",
  "mimetype": "audio/ogg; codecs=opus",
  "tamanho": 48213 }

Webhooks — entrega e segurança

Em trilha → WebHook há um campo Chave secreta (com botão Gerar). Preenchido, todo POST leva X-GR-Signature. Guarde a mesma chave do seu lado e recuse o que não bater — é o que impede alguém que descobriu a sua URL de inventar leads e mensagens no seu sistema.

A assinatura é o HMAC-SHA256 de <timestamp>.<corpo cru>. O timestamp entra na conta de propósito: assinar só o corpo deixaria alguém capturar uma entrega válida e reenviá-la para sempre.

// Node/Express — o corpo tem de ser o RAW, antes de virar JSON
app.post("/webhook/gr", express.raw({ type: "application/json" }), (req, res) => {
  const ts  = req.get("X-GR-Timestamp");
  const sig = req.get("X-GR-Signature");
  const esperada = "sha256=" + crypto.createHmac("sha256", SEGREDO)
    .update(ts + "." + req.body).digest("hex");

  // timingSafeEqual, não ==: comparar string a string vaza o segredo aos poucos
  if (!sig || sig.length !== esperada.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(esperada)))
    return res.sendStatus(401);

  // recusa o que for velho: sem isso a assinatura continua válida para sempre
  if (Math.abs(Date.now()/1000 - Number(ts)) > 300) return res.sendStatus(401);

  // dedupe: a MESMA entrega pode chegar de novo se a sua resposta se perdeu
  if (jaProcessei(req.get("X-GR-Entrega"))) return res.sendStatus(200);

  res.sendStatus(200);          // responda ANTES de processar
  processarEmFila(JSON.parse(req.body));
});

# PHP
$corpo = file_get_contents('php://input');
$ts    = $_SERVER['HTTP_X_GR_TIMESTAMP'];
$esperada = 'sha256=' . hash_hmac('sha256', $ts . '.' . $corpo, $SEGREDO);
if (!hash_equals($esperada, $_SERVER['HTTP_X_GR_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

Falhou, a extensão tenta de novo: 1, 2, 10 e 30 minutos depois (cinco tentativas no total, contando a primeira). A fila é conferida uma vez por minuto e fica gravada em disco, então ela sobrevive ao navegador ser fechado e reaberto.

Ainda assim, responda 2xx rapidamente e processe em fila do seu lado: a retentativa é rede de segurança, não substituto de um recebimento rápido.

Os últimos 30 envios ficam registrados na extensão (trilha → WebHook), com status HTTP, erro e o corpo enviado — incluindo quando a próxima tentativa vai sair e quando desistimos. É por ali que se depura uma integração que parou de receber.

Pegue uma URL descartável em webhook.site, cole na extensão, marque mensagem_recebida e todos os campos, ative e mande uma mensagem para o número conectado. O POST chega na hora — e com todos os campos marcados você vê o payload máximo, que é o que o seu recebimento deve suportar.

API da Extensão

A extensão consulta estes endpoints ao instalar e a cada 30 minutos (sincronização).

# 
GET /extensao/api/config/abc123?whatsapp=5554999480043

{
  "success": true,
  "status": "ativa",
  "perfil": {
    "nome": "Lauro",
    "email": "lauro@ger.com",
    "segmento": "educacao"
  },
  "licenca": {
    "ativa": true,
    "plano": "Premium",
    "validade": "2026-08-12T22:46:50.465Z",
    "diasRestantes": 24
  },
  "ia": { "ativa": false },
  "tutoriaisUrl": "…/extensao/tutoriais",
  "painelUrl": "…/extensao",
  "docUrl": "…/extensao/api"
}

{ "success": true, "url": "https://www.geracaoderesultado.com.br/extensao/" }

# 302 Redirect

Conta & Licenças

{
  "nome": "Lauro",
  "email": "lauro@ger.com",
  "whatsapp": "5554999480043",
  "senha": "••••••",
  "codigoLicenca": "A1B2C3D4"
}

{ "ok": true }

// 400
{ "ok": false,
  "error": "licença inválida ou já usada" }

{
  "email": "lauro@ger.com",
  "senha": "••••••"
}

{
  "ok": true,
  "usuario": {
    "nome": "Lauro",
    "email": "lauro@ger.com",
    "whatsapp": "5554999480043",
    "plano": "Premium",
    "diasRestantes": 24,
    "ativaAte": "2026-08-12T…"
  },
  "downloadUrl": "…/extensao/wa-eadcom.zip"
}

{
  "total": 1079,
  "descricao": "Base + Extensão",
  "email": "lauro@ger.com",
  "recorrencia": "mensal"
}

{ "ok": true,
  "url": "https://checkout.stripe.com/…" }

// sem Stripe
{ "ok": false,
  "error": "stripe_nao_configurado" }

{ "received": true }

Admin

Todas as rotas abaixo exigem o cabeçalho x-admin-pass. Respondem 401 se a senha estiver incorreta.

{ "adminPass": "SUA_SENHA" }

{ "ok": true }

{
  "plano": "mensal",
  "dias": 30
}

{
  "ok": true,
  "licenca": {
    "codigo": "A1B2C3D4",
    "plano": "mensal",
    "dias": 30
  }
}

{
  "nome": "Lauro",
  "email": "lauro@ger.com",
  "whatsapp": "5554999480043",
  "senha": "••••••",
  "segmento": "educacao",
  "plano": "Premium",
  "dias": 30
}

{
  "ok": true,
  "usuario": { "id": "…",
    "email": "lauro@ger.com",
    "ativaAte": "2026-08-12T…" }
}

{
  "config": {
    "status": "ativa",
    "downloadUrl": "…/wa-eadcom.zip"
  }
}

{ "ok": true,
  "config": { /* config atualizada */ } }