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

Cada número conectado é uma instância, identificada por id + token na URL. O Client-Token é da sua conta e vai no header das rotas de instância.

Autenticação

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

Header	Uso
`X-RexZap-Account`	Chave de API da conta. Autentica as rotas `/provisionar*`. Gere/veja no painel (card “API do seu sistema”).
`Client-Token`	Token da conta. Vai no header de toda rota de instância (`/instances/...`).

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}" \
  -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.

POST/provisionar

Cria um número novo. Retorna as credenciais da instância e a URL do QR.

Resposta 200

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

Erros

401 chave inválida · 402 sem assinatura ativa · 409 cota esgotada

GET/provisionar/numeros

Lista os números da conta.

Resposta 200

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

DELETE/provisionar/numeros/{id}

Remove um número da conta (desconecta e libera a cota).

Resposta 200

{ "ok": true }

Cota

GET/provisionar/cota

Uso x limite de números da conta.

Resposta 200

{ "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.

POST/instances/{id}/token/{token}/send-text

Body

Campo	Tipo	Descrição
phone req	string	Número do destinatário (só dígitos, com DDI).
message req	string	Texto da mensagem.

Resposta 200

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

Enviar imagem

POST/instances/{id}/token/{token}/send-image

Body

Campo	Tipo	Descrição
phone req	string	Número do destinatário (só dígitos, com DDI).
image req	string	URL pública ou base64 (data URI) da imagem.
caption	string	Legenda (opcional).

Resposta 200

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

Enviar documento

POST/instances/{id}/token/{token}/send-document/{extension}

{extension} na URL = extensão do arquivo (ex.: pdf).

Body

Campo	Tipo	Descrição
phone req	string	Número do destinatário (só dígitos, com DDI).
document req	string	URL pública ou base64 (data URI) do arquivo.
fileName	string	Nome do arquivo (opcional).
caption	string	Legenda (opcional).

Status

GET/instances/{id}/token/{token}/status

Estado da conexão do número.

Resposta 200

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

QR Code

GET/instances/{id}/token/{token}/qr-code/image

QR para parear o WhatsApp, como data URI PNG. Faça poll até o status virar conectado.

Resposta 200

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

Reiniciar / Desconectar

GET/instances/{id}/token/{token}/restart

Reinicia a sessão (gera novo QR se preciso).

GET/instances/{id}/token/{token}/disconnect

Encerra a sessão do número.

Configurar webhooks

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

PUT	Dispara quando
`/update-webhook-received`	Mensagem recebida.
`/update-webhook-received-delivery`	Recebidas + enviadas pelo próprio número.
`/update-webhook-delivery`	Confirmação de entrega.
`/update-webhook-message-status`	Mudança de status da mensagem.
`/update-webhook-connected`	Número conectou.
`/update-webhook-disconnected`	Número desconectou.

Eventos recebidos

O RexZap faz POST na sua URL com estes formatos.

Mensagem de texto

{
  "type": "ReceivedCallback",
  "instanceId": "...", "messageId": "...",
  "phone": "5544999999999", "fromMe": false,
  "momment": 1718000000000, "senderName": "Maria",
  "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", "instanceId": "...", "phone": "...",
  "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", "status": "SENT", "ids": ["..."], "phone": "..." }
{ "type": "ConnectedCallback", "instanceId": "...", "momment": 1718000000000 }

Erros

Código	Significado
`400`	Número desconectado — pareie o QR antes de enviar.
`401`	Credencial inválida (Client-Token ou chave da conta).
`402`	Sem assinatura ou isenção ativa.
`409`	Cota de números esgotada.

Precisa das credenciais de um número? Elas aparecem no painel, na tela do número (Base URL, Instância, Token, Client-Token).