Documentação da API

API REST para integrar o WhatsApp ao seu sistema: provisione números, envie e receba mensagens e mídias, e receba eventos por webhook.

Visão geral

Todas as requisições usam a base URL abaixo e retornam JSON. Há dois conjuntos de rotas: as da conta (provisionar/gerenciar números, autenticadas pela chave da conta) e as da instância (enviar/receber, no padrão de mercado, autenticadas pelo Client-Token).

Base URL

https://api.rexzap.rexsuite.com

Autenticação

Não há login por OAuth: cada conjunto de rotas usa um cabeçalho próprio.

Início rápido

Em quatro passos: provisione um número, mostre o QR, espere conectar e envie.

# 1) provisione um número (retorna id, token, clientToken e a URL do QR)
curl -X POST https://api.rexzap.rexsuite.com/provisionar \
  -H "X-RexZap-Account: SUA_CHAVE_DA_CONTA"

# 2) pegue o QR (data:image/png;base64,...) e exiba no seu sistema
curl https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/qr-code/image \
  -H "Client-Token: {clientToken}"

# 3) verifique a conexão até status = conectado
curl https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/status \
  -H "Client-Token: {clientToken}"

# 4) envie a primeira mensagem
curl -X POST https://api.rexzap.rexsuite.com/instances/{id}/token/{token}/send-text \
  -H "Client-Token: {clientToken}" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5544999999999","message":"olá 👋"}'

Provisionar números

Rotas da conta — header X-RexZap-Account. Seu sistema cria e gerencia números sem entrar no painel.

{
  "id": "34DEA54FF15492214CB8FAD5470C62F8",
  "token": "9E8937994C27C132E835A0680B194C21",
  "clientToken": "92912E057CE1...",
  "status": "desconectado",
  "qrCodeUrl": "/instances/{id}/token/{token}/qr-code/image",
  "statusUrl": "/instances/{id}/token/{token}/status"
}

[
  { "id": "...", "token": "...", "clientToken": "...",
    "numero": "5544999999999", "status": "conectado" }
]

{ "ok": true }

Cota

{ "used": 1, "limit": 10, "active": true, "status": "active" }

Enviar texto

Rotas de instância — path /instances/{id}/token/{token} + header Client-Token. A resposta de envio traz os ids da mensagem.

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar imagem

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar documento

Enviar áudio

{ "zaapId": "...", "messageId": "...", "id": "..." }

Enviar vídeo

{ "zaapId": "...", "messageId": "...", "id": "..." }

Status

{ "connected": true, "status": "conectado" }

QR Code

{ "value": "data:image/png;base64,iVBORw0KG..." }
{ "value": null }

Reiniciar / Desconectar

{ "value": true }

{ "value": true }

Configurar webhooks

Defina as URLs que receberão os eventos. Rotas PUT de instância, body { "value": "https://sua-app/webhook" }.

Eventos recebidos

O RexZap faz POST na sua URL com estes formatos.

Mensagem de texto

{
  "type": "ReceivedCallback", "status": "RECEIVED",
  "instanceId": "...", "messageId": "...",
  "phone": "5544999999999", "fromMe": false,
  "momment": 1718000000000,
  "senderName": "Maria", "chatName": "Maria",
  "participantPhone": null, "photo": null, "broadcast": false,
  "text": { "message": "olá" }
}

Mídia (imagem, áudio, vídeo, documento, sticker)

Mesma estrutura, com um objeto por tipo. A URL é um link estável do RexZap (o arquivo fica em armazenamento privado).

{
  "type": "ReceivedCallback", "status": "RECEIVED", "instanceId": "...",
  "phone": "...", "fromMe": false, "momment": 1718000000000, "broadcast": false,
  "image":    { "imageUrl": "https://api.rexzap.rexsuite.com/media/...", "caption": "...", "mimeType": "image/jpeg" },
  "audio":    { "audioUrl": "...", "mimeType": "audio/ogg" },
  "video":    { "videoUrl": "...", "caption": "...", "mimeType": "video/mp4" },
  "document": { "documentUrl": "...", "mimeType": "application/pdf", "fileName": "nota.pdf" },
  "sticker":  { "stickerUrl": "...", "mimeType": "image/webp" }
}

Status / conexão

{ "type": "MessageStatusCallback", "instanceId": "...", "status": "SENT", "ids": ["..."], "phone": "...", "momment": 1718000000000 }
{ "type": "ConnectedCallback", "instanceId": "...", "momment": 1718000000000 }
{ "type": "DisconnectedCallback", "instanceId": "...", "momment": 1718000000000 }

Erros