# BotChat G-LINK — API Reference (llms.txt)
# Referência condensada pra ferramentas de IA (Cursor, Claude Code, Copilot etc)
# e pra quem só quer ler tudo rápido sem navegar o site.
# Documentação completa, com exemplos e explicações: SEU-DOMINIO.com/docs.html

## O que é

BotChat G-LINK é uma plataforma de automação de WhatsApp (bot + painel multi-atendente).
Cada conta tem uma chave de API própria (gerada em Integração → Chave de API, dentro do
painel), usada por sistemas externos pra mandar mensagem e consultar status pelo bot — e
um Webhook de Integração (recurso do plano Pro) que faz o bot avisar o sistema do cliente
quando recebe uma mensagem que não bate com nenhuma resposta configurada.

## Autenticação

Toda chamada precisa do header:
  x-api-key: SUA_CHAVE_DE_API
  Content-Type: application/json

A chave só autoriza duas ações: enviarAdmin e statusAdmin. Qualquer outra ação (criar
instância, convidar usuário, trocar plano etc) exige login no painel — a chave nunca dá
acesso administrativo, mesmo se vazar.

Nunca chame a API a partir de código que roda no navegador do cliente (front-end). A
chamada tem que sair do seu servidor.

## Endpoint único

Todas as ações (enviarAdmin e statusAdmin) são POST no mesmo endpoint:
  POST https://SEU-DOMINIO.com/.netlify/functions/evolution-proxy

O corpo (JSON) muda de acordo com a ação, no campo "acao".

### enviarAdmin — mandar uma mensagem de texto

Request body:
  {
    "acao": "enviarAdmin",
    "instancia": "nome-do-seu-bot",   // nome da conexão, igual aparece na aba Conexões
    "numero": "5511999887766",         // DDI+DDD, só dígitos
    "mensagem": "Sua mensagem aqui"
  }

Respostas:
  200  mensagem enviada (resposta bruta da Evolution API, contém "key" quando deu certo)
  400  faltou algum campo (instancia, numero ou mensagem)
  403  essa instância não pertence a essa conta
  409  conexão não está aberta no momento (WhatsApp desconectado — precisa reconectar)
  502  falha ao enviar, tenta de novo em instantes

### statusAdmin — consultar status da conexão em tempo real

Request body:
  { "acao": "statusAdmin", "instancia": "nome-do-seu-bot" }

Response 200:
  { "instancia": "...", "existe": true, "aberto": true, "state": "open" }
  "aberto": true = WhatsApp conectado e pronto pra mandar mensagem.

## Webhook de integração (bot → seu sistema) — recurso do plano Pro

Configure a URL do seu endpoint em Integração, dentro do painel. O bot chama esse
endereço automaticamente quando recebe uma mensagem que não bate com nenhuma resposta
configurada. Seu servidor precisa responder em até 5 segundos.

Payload que seu endpoint recebe (POST, JSON):
  {
    "numero": "5544999887766",
    "mensagem": "consultar fatura",
    "instancia": "minha-loja",
    "timestamp": 1724100000
  }

O que seu endpoint deve devolver:
  Sucesso:  { "resposta": "Ola Joao! Sua fatura de R$ 89,90 vence em 25/08.", "sucesso": true }
  Erro:     { "resposta": "Nao encontrei dados para esse numero.", "sucesso": false }

## Exemplo mínimo (Node.js / Express)

  const express = require('express');
  const app = express();
  app.use(express.json());

  app.post('/api/bot-query', async (req, res) => {
    const { numero, mensagem } = req.body;
    if (!numero || !mensagem) {
      return res.json({ resposta: 'Dados incompletos.', sucesso: false });
    }
    const cliente = await buscarClientePorTelefone(numero);
    if (!cliente) {
      return res.json({ resposta: 'Numero nao cadastrado.', sucesso: false });
    }
    res.json({
      resposta: `Ola ${cliente.nome}! Sua fatura de R$ ${cliente.valor} vence em ${cliente.vencimento}.`,
      sucesso: true,
    });
  });

  app.listen(3000);

(Exemplos completos também em PHP e Python: ver docs.html#exemplo-completo)

## O que a API NÃO faz (ainda)

- Não manda foto, áudio ou documento — só texto. Mídia só pela aba Atendimento, no painel.
- Não lista nem cria instâncias/conexões — só pelo painel (aba Conexões).
- Não convida atendente, não troca plano, não regenera a própria chave — só logado
  como Administrador no painel.

## Limites

- Sem limite de chamadas do nosso lado. O limite prático é a estabilidade da conexão do
  WhatsApp — volume muito alto em pouco tempo aumenta o risco de bloqueio pelo WhatsApp.
- Webhook precisa responder em até 5 segundos, ou o bot avisa o cliente que não
  conseguiu buscar a informação no momento (e não tenta de novo).

## Perguntas frequentes

P: Preciso saber programar pra usar isso?
R: Pra pegar a chave e configurar a URL do webhook, não. Pra fazer seu sistema
   conversar de fato com o bot, sim — alguém precisa programar o endpoint.

P: Meu webhook precisa ser HTTPS?
R: Sim, em produção. Pra testar local, ferramentas como ngrok resolvem.

P: O que acontece se meu sistema demorar pra responder o webhook?
R: O bot espera até 5s; depois disso avisa o cliente que não achou a informação agora.