← Voltar para o NodeZap

Documentação da API

Envie WhatsApp via HTTP com poucas linhas de código. Compatível com SGP, IXC, MK-AUTH, Controllr e qualquer sistema que fale HTTP genérico.

Autenticação Enviar mensagem Envio em lote Status da instância Pausar / Retomar Webhooks Erros comuns Compatibilidade

1 Autenticação

Toda requisição precisa de uma chave de API, enviada no header X-Api-Key. Você encontra a chave da sua instância na área do cliente.

X-Api-Key: sua_chave_aqui

Sistemas que não suportam headers customizados (ex: alguns gateways HTTP legados) podem enviar a chave como parâmetro p na query string ou no corpo da requisição.

2 Enviar mensagem

POST/send

Enfileira uma mensagem de texto para envio imediato.

Campo	Tipo	Obrigatório	Descrição
`instance`	string	Sim	Nome da instância
`to`	string	Sim	Número do destinatário (com DDI)
`message`	string	Sim	Texto da mensagem
`priority`	number	Não	0=normal, 1=alta, 2=urgente

curl -X POST https://api.nodeapi.com.br/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sua_chave_aqui" \
  -d '{
    "instance": "sua_instancia",
    "to": "5511999999999",
    "message": "Olá! Essa é uma mensagem de teste."
  }'

{
  "ok": true,
  "success": true,
  "jobId": "1234",
  "instance": "sua_instancia",
  "to": "5511999999999",
  "queuedAt": "2026-08-18T10:00:00.000Z"
}

3 Envio em lote

POST/send/batch

Enfileira várias mensagens em uma única requisição. Limite de 1.000 mensagens por chamada.

curl -X POST https://api.nodeapi.com.br/send/batch \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sua_chave_aqui" \
  -d '{
    "messages": [
      {"instance": "sua_instancia", "to": "5511999999999", "message": "Mensagem 1"},
      {"instance": "sua_instancia", "to": "5511988888888", "message": "Mensagem 2"}
    ]
  }'

{
  "ok": true,
  "queued": 2,
  "failed": 0,
  "results": [
    {"ok": true, "jobId": "1235", "to": "5511999999999"},
    {"ok": true, "jobId": "1236", "to": "5511988888888"}
  ]
}

4 Status da instância

GET/instance/{nome}/status

Retorna o estado da conexão, fila e limites de envio do dia.

curl https://api.nodeapi.com.br/instance/sua_instancia/status \
  -H "X-Api-Key: sua_chave_aqui"

{
  "instance": "sua_instancia",
  "paused": false,
  "dailyCount": 128,
  "evolution": "open",
  "queue": { "waiting": 0, "active": 1, "completed": 340, "failed": 2 }
}

5 Pausar / Retomar envios

POST/instance/{nome}/pause · POST/instance/{nome}/resume

Interrompe ou retoma o processamento da fila de uma instância — útil para pausar disparos em massa sem perder a fila.

curl -X POST https://api.nodeapi.com.br/instance/sua_instancia/pause \
  -H "X-Api-Key: sua_chave_aqui"

6 Webhooks de status

Configure uma URL de webhook na área do cliente para receber notificações em tempo real de entrega, leitura e mudança de conexão da instância.

{
  "event": "MESSAGES_UPDATE",
  "instance": "sua_instancia",
  "data": {
    "key": { "id": "3EB0..." },
    "update": { "status": "DELIVERY_ACK" }
  }
}

Status recebido	Significado
`DELIVERY_ACK` / `DELIVERED`	Mensagem entregue
`READ` / `PLAYED`	Mensagem lida

7 Erros comuns

HTTP	Erro	Causa
401	`Unauthorized`	Chave ausente, incorreta ou instância errada no campo `instance`
400	`Missing required fields`	Faltou `instance`, `to` ou `message` no corpo
400	`Invalid phone number`	Número com menos de 10 dígitos após remover formatação
429	`Rate limit exceeded`	Muitas requisições no último minuto para o mesmo IP

8 Compatibilidade com outros sistemas

A API já entende os formatos nativos desses sistemas de gestão — normalmente basta apontar o campo de "Gateway HTTP" ou "Provedor WhatsApp → Outros" pra sua URL de envio, sem precisar de configuração extra.

SGPIXC SoftMK-AUTHControllrHTTP Genérico