Documentação da API Zapeou

📖 Visão Geral

A API Zapeou é baseada em REST e usa JSON em todas as requisições e respostas. Cada instância (conexão WhatsApp) possui sua própria URL exclusiva e API Key, garantindo isolamento total entre clientes.

Principais recursos

• URL única por instância — cada conexão tem seu próprio endpoint
• API Key isolada — autenticação por instância, não por usuário
• Webhooks em tempo real — receba notificações de mensagens e mudanças de status
• Aquecimento automático — proteção contra banimento do WhatsApp
• Envio em lote — fila inteligente com delay configurável
• Histórico completo — todas as mensagens enviadas e recebidas ficam salvas

⚡ Quick Start

Em menos de 2 minutos você envia sua primeira mensagem. Siga os passos:

curl -X POST https://zapeou.consultacobertura.com.br/5/minha-loja/api/message/send-text \
  -H "Authorization: Bearer SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999990000","text":"Olá! Testando o Zapeou 🚀"}'

🔐 Autenticação

Todas as requisições à API devem incluir o Token da Instância (API Key) no header Authorization como Bearer Token.

Authorization: Bearer [SUA_API_KEY]

Como obter a API Key

1. Acesse o painel
2. Localize a instância desejada
3. Clique em "Copiar" ao lado do campo API KEY

🔗 URL Única da Instância

Cada instância possui uma URL exclusiva no formato:

https://zapeou.consultacobertura.com.br/{user_id}/{instance_slug}/api/{endpoint}

📤 Enviar Mensagem de Texto

Parâmetros do Body (JSON)

{
  "number": "5511999990000",
  "text": "Olá! Sua encomenda foi enviada 📦\nAguarde em casa."
}

Resposta de Sucesso

✓ 200 OK

{
  "success": true,
  "message": "Mensagem enviada com sucesso!",
  "data": {
    "message_id": "3EB0A92F7B1C...",
    "to": "5511999990000",
    "instance_name": "minha-loja",
    "instance_slug": "minha-loja",
    "user_id": 5,
    "api_url": "https://zapeou.consultacobertura.com.br/5/minha-loja/api/message/send-text"
  },
  "warmup": null
}

📨 Envio em Lote (Bulk)

Parâmetros do Body (JSON)

{
  "messages": [
    { "number": "5511999990001", "text": "Olá cliente 1!" },
    { "number": "5511999990002", "text": "Olá cliente 2!" },
    { "number": "5511999990003", "text": "Olá cliente 3!" }
  ],
  "delay_ms": 5000
}

{
  "success": true,
  "message": "3 mensagem(ens) adicionadas à fila!",
  "data": {
    "queued": 3,
    "instance_name": "minha-loja",
    "instance_slug": "minha-loja",
    "user_id": 5
  }
}

📊 Status da Instância

curl https://zapeou.consultacobertura.com.br/5/minha-loja/api/status \
  -H "Authorization: Bearer SUA_API_KEY"

{
  "success": true,
  "data": {
    "instance_name": "minha-loja",
    "instance_slug": "minha-loja",
    "user_id": 5,
    "status": "connected",
    "phone_number": "5511988887777",
    "total_sent": 1247,
    "total_received": 892
  }
}

Status possíveis

🔔 Webhooks

Webhooks permitem que o Zapeou notifique seu sistema em tempo real quando eventos ocorrerem (mensagem recebida, enviada, mudança de status, etc).

Como configurar

1. No painel, clique em "⚙ Detalhes" da instância
2. Clique em "🔗 Webhook"
3. Informe a URL do seu endpoint (deve aceitar POST com JSON)
4. Selecione os eventos que deseja receber
5. Clique em Salvar

Eventos disponíveis

Exemplo de Payload

{
  "event": "message_received",
  "instance_id": 42,
  "instance_name": "minha-loja",
  "instance_slug": "minha-loja",
  "user_id": 5,
  "timestamp": "2026-07-02T14:32:10.123Z",
  "data": {
    "from": "5511999990000",
    "text": "Olá, gostaria de saber o preço",
    "type": "text",
    "timestamp": "2026-07-02T14:32:10.123Z"
  }
}

🔥 Aquecimento de Número

O aquecimento (warmup) é um sistema de proteção que aumenta gradualmente o volume de mensagens enviadas por dia, evitando que números novos sejam banidos pelo WhatsApp.

Limites por dia

Como a API responde quando o limite é atingido

{
  "success": false,
  "message": "Limite diário de aquecimento atingido (30 msg/dia — Dia 5).",
  "warmup": true
}

📋 Respostas da API

Todas as respostas seguem o padrão JSON com os campos:

❌ Códigos de Erro

📦 Exemplos por Linguagem

Node.js (Fetch)

const response = await fetch(
  'https://zapeou.consultacobertura.com.br/5/minha-loja/api/message/send-text',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      number: '5511999990000',
      text: 'Olá via Node.js!'
    })
  }
);
const data = await response.json();
console.log(data);

Python (requests)

import requests

url = "https://zapeou.consultacobertura.com.br/5/minha-loja/api/message/send-text"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}
payload = {
    "number": "5511999990000",
    "text": "Olá via Python!"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

PHP (cURL)

<?php
$url = 'https://zapeou.consultacobertura.com.br/5/minha-loja/api/message/send-text';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $API_KEY
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'number' => '5511999990000',
        'text'   => 'Olá via PHP!'
    ])
]);
$response = curl_exec($ch);
echo $response;

n8n / Typebot

❓ Perguntas Frequentes