​

Troubleshooting

​

Problemas de Conexão

​

Instância não conecta

curl -X GET "https://api.wapizap.com/api/v2/instances/{id}/status" \
  -H "Authorization: Bearer SEU_TOKEN"

curl -X POST "https://api.wapizap.com/api/v2/instances/{id}/connect" \
  -H "Authorization: Bearer SEU_TOKEN"

# Desconectar
curl -X POST "https://api.wapizap.com/api/v2/instances/{id}/disconnect" \
  -H "Authorization: Bearer SEU_TOKEN"

# Aguardar 5 segundos e reconectar
curl -X POST "https://api.wapizap.com/api/v2/instances/{id}/connect" \
  -H "Authorization: Bearer SEU_TOKEN"

​

QR code expira antes de escanear

1. Deixe o WhatsApp aberto na tela de escanear código ANTES de gerar o QR
2. Gere o QR code
3. Escaneie imediatamente

​

Instância desconecta frequentemente

• Muitos dispositivos conectados (máximo 4)
• Atividade suspeita detectada pelo WhatsApp
• Problemas de rede

1. Remova dispositivos não utilizados no WhatsApp
2. Reduza a frequência de mensagens
3. Verifique logs de erro para padrões

​

Problemas com Mensagens

​

Mensagem não enviada

curl -X POST "https://api.wapizap.com/api/v2/contacts/check" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "instanceId": "sua-instancia",
    "numbers": ["5511999999999"]
  }'

curl -X GET "https://api.wapizap.com/api/v2/instances/{id}/status" \
  -H "Authorization: Bearer SEU_TOKEN"

​

Erro “Invalid number”

1. Verifique o formato (deve ser 5511999999999)
2. Use /contacts/check para validar
3. Confirme que o número tem WhatsApp ativo

​

Mídia não enviada

1. URL da mídia é acessível publicamente?
2. Formato é suportado?
3. Tamanho está dentro do limite?

curl -I "https://sua-url.com/imagem.jpg"
# Deve retornar HTTP 200

​

Problemas com Webhooks

​

Webhook não recebe dados

curl -X GET "https://api.wapizap.com/api/v2/webhooks?instanceId=sua-instancia" \
  -H "Authorization: Bearer SEU_TOKEN"

curl -X POST "https://seu-servidor.com/webhook" \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

curl -X POST "https://api.wapizap.com/api/v2/webhooks/{id}/test" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{"instanceId": "sua-instancia"}'

​

Webhook recebe duplicatas

1. Responda com HTTP 200 em menos de 5 segundos
2. Processe dados de forma assíncrona
3. Use messageId para deduplicação:

const processedMessages = new Set();

app.post('/webhook', (req, res) => {
  const messageId = req.body.data?.key?.id;

  if (processedMessages.has(messageId)) {
    return res.status(200).json({ duplicate: true });
  }

  processedMessages.add(messageId);

  // Processar de forma assíncrona
  processMessageAsync(req.body);

  res.status(200).json({ received: true });
});

​

Webhook localhost não funciona

# ngrok
npx ngrok http 3000
# Copie a URL https://xxxx.ngrok.io

# ou Cloudflare Tunnel
cloudflared tunnel --url http://localhost:3000

​

Problemas de Autenticação

​

Erro 401 Unauthorized

1. O token está no formato correto?
   Copy

   Authorization: Bearer sk_live_xxxxx
   
2. O token é válido e não expirou?
3. Está usando o ambiente correto (live vs test)?

curl -X GET "https://api.wapizap.com/api/v2/instances" \
  -H "Authorization: Bearer SEU_TOKEN"

​

Erro 403 Forbidden

1. Verifique as permissões da API key no dashboard
2. Gere uma nova key com as permissões necessárias

​

Rate Limiting

​

Erro 429 Too Many Requests

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After') || 60;
  await sleep(retryAfter * 1000);
  // Retry
}

1. Implemente queue de mensagens
2. Distribua envios ao longo do tempo
3. Use múltiplas instâncias para volume alto

​

Ferramentas de Diagnóstico

​

Verificar status geral

# Status de todas as instâncias
curl -X GET "https://api.wapizap.com/api/v2/instances" \
  -H "Authorization: Bearer SEU_TOKEN"

# Status de instância específica
curl -X GET "https://api.wapizap.com/api/v2/instances/{id}/status" \
  -H "Authorization: Bearer SEU_TOKEN"

​

Logs de webhook

• Requisições enviadas
• Respostas recebidas
• Erros e retries

​

Testar conectividade

# Ping na API
curl -w "\nTempo: %{time_total}s\n" \
  -X GET "https://api.wapizap.com/health"

​

Checklist de Diagnóstico

• API key está correta e válida?
• Instância está conectada?
• Número está no formato internacional?
• URL do webhook é pública e acessível?
• Não excedeu rate limits?
• Mídia está dentro dos limites de tamanho?

​

Contatar Suporte

• ID da instância
• Endpoint usado
• Código de erro
• Request/Response de exemplo
• Timestamp do problema