SUEDAPI_
VERIFICANDO…

SUED API / DEVELOPER PLATFORM

Documentação que funciona.

Do primeiro acesso à integração com seu aplicativo. Rotas REST, exemplos de código, autenticação e webhooks, com uma referência ligada ao contrato publicado.

Base URL HTTPS

https://suedapi.com.br/api

Guia rápido

Integre em quatro passos

O caminho básico é simples. Comece criando sua instância no painel e avance até receber eventos no seu sistema.

01

Crie sua instância

Dê um nome ao número do WhatsApp que será conectado.

Minhas instâncias
02

Conecte o WhatsApp

Abra a instância e leia o QR Code com o celular.

Abrir conexão
03

Gere a chave e envie

Escolha as permissões da chave e faça seu primeiro teste.

Criar chave
04

Receba eventos

Cadastre o endereço do seu sistema para receber webhooks.

Configurar webhook

Importante: criar, renomear e arquivar instâncias são ações de usuário autenticado. Para integrações automáticas, use uma chavesued_live_*com as permissões necessárias para consultar, enviar mensagens e configurar webhooks.

Segurança

Autenticação e chaves

Toda chamada protegida utiliza Authorization: Bearer. Gere sua chave no painel, defina as permissões e guarde o segredo; ele não será mostrado novamente.

Chave de API

Para seus sistemas e automações. Permissões por ambiente: leitura de instâncias, envio de mensagens, webhooks e outros escopos.

Gerar chave de API
Login de usuário

O JWT da sessão SUED é exigido para operações administrativas como criar ou arquivar instâncias. Não compartilhe esse token.

Gerenciar instâncias

Autenticação · Listar instâncias

curl -X GET "https://suedapi.com.br/api/instances" \
  -H "Authorization: Bearer SUA_CHAVE_SUED"

Não coloque chaves em links, páginas públicas ou código do navegador. Os exemplos em JavaScript e Python são destinados à execução no servidor.

WhatsApp

Instâncias e conexão

Cada instância identifica uma conexão WhatsApp dentro do seu ambiente. Crie pelo painel e use a API para consultar estados e iniciar a conexão.

Criar

POST /api/instances

JWT de usuário obrigatório

Conectar

POST /api/instances/{instanceId}/connect

Solicita o início da conexão

QR Code

GET /api/instances/{instanceId}/qr

Código temporário, sem cache

Uma chamada de conexão aceita não significa que o WhatsApp já esteja online. Consulte GET /api/instances/{instanceId}/status até a instância estar conectada. Pareamento por código também está documentado na referência abaixo.

Mensageria

Envie sua primeira mensagem

Com a instância conectada e uma chave com messages:send, envie uma mensagem para um número autorizado. A API responde com um identificador para acompanhar o processamento.

Enviar texto · POST /messages

curl -X POST "https://suedapi.com.br/api/instances/SEU_INSTANCE_ID/messages" \
  -H "Authorization: Bearer SUA_CHAVE_SUED" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: teste-mensagem-0000001" \
  -d '{"to":"5545999999999","type":"text","text":"Olá! Testando a SUED."}'

Evite mensagens duplicadas

O cabeçalho idempotency-key é obrigatório. Reutilize a mesma chave apenas ao repetir exatamente a mesma solicitação; para outra mensagem, crie uma chave nova.

Exemplo de resposta · HTTP 202

{
  "data": {
    "id": "123e4567-e89b-42d3-a456-426614174000",
    "status": "queued"
  }
}

A resposta 202 / queued indica entrada na fila, não entrega ao destinatário. Consulte GET /api/instances/{instanceId}/messages/{messageId}. Mensagens recebidas ficam em /inbox e também podem gerar webhooks. O contrato inclui mídias, localização, contato e reação, sujeitos à validação do WhatsApp conectado.

Automação

Webhooks e eventos

Seu sistema, CRM, n8n ou Make fornece uma URL HTTPS pública. A SUED envia os eventos para esse endereço; o link não é gerado pela SUED.

1. Escolha onde receber

Crie um endpoint HTTPS no seu aplicativo ou na plataforma de automação. Cole esse endereço em Webhooks no painel SUED.

2. Ative uma assinatura segura

Informe um segredo de 16 a 200 caracteres, selecione os eventos e salve. Valide o HMAC-SHA256 antes de tratar qualquer solicitação recebida.

Configurar pelo REST · PUT /webhook

curl -X PUT "https://suedapi.com.br/api/instances/SEU_INSTANCE_ID/webhook" \
  -H "Authorization: Bearer SUA_CHAVE_SUED" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://meusistema.com/webhooks/sued","enabled":true,"events":["message.received","message.sent","instance.connected"],"secret":"SEU_SEGREDO_FORTE_COM_NO_MINIMO_16_CARACTERES"}'
Configurar no painelDepois de ativar, use “Enviar evento de teste” e consulte o histórico.
Ver exemplo do evento recebido e como validar a assinatura

Cada POST contém X-Sued-Timestamp,X-Sued-Event-Id eX-Sued-Signature. A assinatura usa HMAC-SHA256 sobre o timestamp, ponto e o corpo JSON original.

Exemplo ilustrativo · message.received

{
  "eventId": "123e4567-e89b-42d3-a456-426614174001",
  "event": "message.received",
  "timestamp": "2026-10-14T18:00:00.000Z",
  "instanceId": "123e4567-e89b-42d3-a456-426614174002",
  "workspaceId": "123e4567-e89b-42d3-a456-426614174003",
  "payload": {
    "id": "MENSAGEM_DO_WHATSAPP",
    "from": "5545999999999",
    "chatId": "5545999999999@s.whatsapp.net",
    "groupId": null,
    "type": "text",
    "text": "Olá",
    "hasMedia": false
  }
}

Node.js · validar HMAC no servidor

import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";
const secret = process.env.SUED_WEBHOOK_SECRET;

createServer(async (req, res) => {
  if (req.method !== "POST" || req.url !== "/webhooks/sued") {
    res.writeHead(404).end(); return;
  }
  const parts = [];
  for await (const chunk of req) parts.push(chunk);
  const raw = Buffer.concat(parts);
  const ts = String(req.headers["x-sued-timestamp"] || "");
  const received = String(req.headers["x-sued-signature"] || "");
  const validTime = /^\d+$/.test(ts) && Math.abs(Date.now()/1000 - Number(ts)) <= 300;
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(ts + "." + raw.toString("utf8")).digest("hex");
  const a = Buffer.from(received), b = Buffer.from(expected);
  if (!validTime || a.length !== b.length || !timingSafeEqual(a, b)) {
    res.writeHead(401).end(); return;
  }
  const event = JSON.parse(raw.toString("utf8"));
  console.log(event.event, event.payload);
  // Deduplicate by X-Sued-Event-Id before processing.
  res.writeHead(200).end();
}).listen(3000); // Publish behind HTTPS

Publique o receptor atrás de HTTPS, limite o tamanho das requisições e evite processar o mesmo X-Sued-Event-Id duas vezes. Respostas HTTP 2xx confirmam recebimento; falhas temporárias podem ser reenviadas até cinco tentativas.

Referência REST

Todos os endpoints

Métodos, parâmetros, permissões e exemplos a partir do contrato OpenAPI público da SUED.

OpenAPI JSON

Carregando a referência de endpoints...

Suporte técnico

Erros e respostas

A SUED usa códigos HTTP para informar o resultado de cada chamada. Confira o status e a mensagem retornada antes de repetir uma operação.

200Operação concluída ou consulta respondida.
201Recurso criado com sucesso.
202Aceito para processamento. Consulte o status da operação.
400Parâmetro inválido: revise o corpo JSON e a documentação da rota.
401Token ausente, expirado ou inválido.
403Permissão insuficiente ou operação restrita ao usuário.
404Identificador incorreto, recurso inexistente ou inacessível.
409Estado incompatível: WhatsApp desconectado, conflito de chave ou de operação.
429Limite de requisições. Reenvie com controle de espera.
503Serviço dependente temporariamente indisponível.

Perguntas frequentes

Onde encontro a chave da API?

Acesse Chaves de API no painel, gere uma chave e selecione os escopos necessários. O segredo é exibido apenas na criação.

A SUED gera minha URL de webhook?

Não. A URL pertence ao aplicativo que receberá os eventos. A SUED envia notificações para ela.

Por que a mensagem está na fila?

HTTP 202 confirma o enfileiramento, não a entrega. Consulte o status da mensagem e a conexão da instância.

Preciso usar /v1 ou /v2?

Não para a integração comercial. Utilize o endereço documentado em /api; as rotas internas permanecem separadas.

Pronto para integrar?

Comece pela instância ou abra o contrato técnico completo.