WPP API Gateway — Documentação

Para que serve?

Centralizar o envio e gerenciamento de WhatsApp para vários projetos, sem expor o WPPConnect diretamente na internet.

Como isola clientes?

Cada cliente tem uma API Key. Essa chave só acessa as sessões vinculadas a ele. Uma barbearia não consegue usar a sessão de outra.

Onde fica o WPPConnect?

Rodando internamente na VPS, normalmente em http://127.0.0.1:21465. A porta 21465 não deve ser pública.

Autenticação

Todos os endpoints operacionais exigem uma chave válida:

GET https://apiwpp.escotilhaprodutora.com.br/health
X-API-KEY: SUA_API_KEY

Também é aceito:

Authorization: Bearer SUA_API_KEY

Não use chaves na URL

Evite ?api_key=.... URL costuma aparecer em histórico, logs, analytics e prints.

O que é HMAC e para que serve?

HMAC é uma assinatura criptográfica gerada com um segredo compartilhado entre o sistema consumidor e a API. Ela prova que a requisição foi feita por quem conhece o segredo e que o corpo da requisição não foi alterado no caminho.

Na prática, a API Key identifica o cliente. O HMAC adiciona uma segunda camada: além da chave, cada requisição precisa vir assinada com X-Timestamp e X-Signature.

Quando usar?

Integrações financeiras Sistemas de terceiros APIs públicas em produção Não é obrigatório no começo

Como a assinatura é montada nesta API

message = METHOD + "\n" + ROUTE + "\n" + TIMESTAMP + "\n" + RAW_BODY
signature = "sha256=" + HMAC_SHA256(message, HMAC_SECRET)

Exemplo conceitual em PHP

$timestamp = time();
$body = json_encode([
    'phone' => '5585999999999',
    'message' => 'Teste assinado'
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

$route = '/sessions/c1_barbearia/send-message';
$message = "POST\n{$route}\n{$timestamp}\n{$body}";
$signature = 'sha256=' . hash_hmac('sha256', $message, 'SEU_HMAC_SECRET');

Para ativar, configure security.hmac.enabled = true e troque o segredo no config.php.

O que é Webhook e para que serve?

Webhook é uma URL que recebe eventos automaticamente. Em vez do seu sistema ficar perguntando o tempo todo "chegou mensagem?", o WPPConnect envia um aviso para a URL configurada quando algo acontece.

Exemplos de eventos

mensagem recebida status de sessão QR Code atualizado desconexão ack/status de mensagem

Endpoint de webhook nesta API

POST https://apiwpp.escotilhaprodutora.com.br/webhook/{session}
X-WEBHOOK-SECRET: SEU_WEBHOOK_SECRET

O segredo do webhook evita que qualquer pessoa envie eventos falsos para sua API. Troque o valor padrão no config.php.

Para o painel da barbearia, o webhook pode ser usado depois para atualizar conversas, exibir mensagens recebidas, detectar queda do WhatsApp e criar automações mais inteligentes.

Endpoints principais

GET/healthVerifica se a API está online.

POST/admin/clientsCria cliente. Exige API Key admin.

POST/admin/clients/{id}/keysGera API Key de cliente.

GET/sessionsLista sessões permitidas para a API Key.

POST/sessionsCria uma sessão WhatsApp para o cliente.

POST/sessions/{session}/startInicia a sessão e prepara QR Code.

GET/sessions/{session}/qrcodeRetorna QR Code da sessão.

GET/sessions/{session}/statusConsulta status da sessão.

POST/sessions/{session}/send-messageEnvia mensagem simples.

ANY/sessions/{session}/proxy/{endpoint}Proxy genérico para endpoints permitidos do WPPConnect.

Enviar mensagem

curl -X POST "https://apiwpp.escotilhaprodutora.com.br/sessions/c1_barbearia/send-message" \
-H "Content-Type: application/json" \
-H "X-API-KEY: SUA_API_KEY" \
-d "{\"phone\":\"5585999999999\",\"message\":\"Olá! Seu horário está confirmado.\"}"

Fluxo para conectar WhatsApp

1. POST /sessions
2. POST /sessions/{session}/start
3. GET  /sessions/{session}/qrcode
4. Cliente escaneia no WhatsApp
5. GET  /sessions/{session}/status
6. Status CONNECTED
7. Sistema pode enviar mensagens

Modelo multi-barbearia

Barbearia A
→ API Key A
→ Sessão c1_barbearia-a
→ WhatsApp A

Barbearia B
→ API Key B
→ Sessão c2_barbearia-b
→ WhatsApp B

Teste no Postman

Importe a collection e o environment da pasta postman/.

Configure as variáveis:

base_url = https://apiwpp.escotilhaprodutora.com.br
api_key = SUA_API_KEY
session = c1_barbearia
phone = 5585999999999

Comece por Health, depois List Sessions, depois Create Session, Start Session, QRCode e Send Message.

Checklist de produção

Ativar HTTPS Trocar webhook secret Não expor porta 21465 Usar API Key por cliente Definir CORS HMAC opcional Whitelist de IP opcional

'security' => [
    'require_https' => true,
    'cors' => [
        'enabled' => true,
        'allowed_origins' => [
            'https://painel.seudominio.com.br'
        ],
    ],
],

'webhook' => [
    'secret' => 'SEGREDO_FORTE_DO_WEBHOOK',
],

Documentação pública da API de WhatsApp

Base URL

Status público