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/apiGuia 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.
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.
Para seus sistemas e automações. Permissões por ambiente: leitura de instâncias, envio de mensagens, webhooks e outros escopos.
Gerar chave de APIO JWT da sessão SUED é exigido para operações administrativas como criar ou arquivar instâncias. Não compartilhe esse token.
Gerenciar instânciasAutenticaçã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.
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/instancesJWT de usuário obrigatório
Conectar
POST /api/instances/{instanceId}/connectSolicita o início da conexão
QR Code
GET /api/instances/{instanceId}/qrCó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"}'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 HTTPSPublique 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.
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.
