Documentação · API v1

Referência da API VixZap

Base https://api.vixzap.com.br/v1. JSON em camelCase, ids com prefixo, erros em application/problem+json. A especificação OpenAPI é gerada do código e servida pela própria API em /docs; abaixo, o essencial para começar.

Início rápido

  1. Crie a conta no portal, dê um nome à instância e leia o QR.
  2. Em Tokens, crie um token de instância com o escopo messages:send. Guarde: ele só aparece uma vez.
  3. Envie a primeira mensagem:
cURL
curl -X POST https://api.vixzap.com.br/v1/instances/vz_inst_8k3j/messages/text \
  -H "Authorization: Bearer vz_live_9f2k…" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5527999999999", "text": "Olá do VixZap 👋" }'
  1. Em Webhooks, crie um endpoint apontando para o seu sistema e dispare um evento de teste.

Autenticação

Todo pedido leva Authorization: Bearer <token>. Existem dois tipos de token, ambos criados no portal:

TipoAlcanceUso típico
Token de instânciaSó a instância indicadaIntegração de um sistema com um número
Token de contaTodas as instâncias do assinante; pode criar instânciasSoftware houses e parceiros

Escopos: messages:send, messages:read, instances:read, instances:manage, webhooks:manage, events:read, account:manage. Allowlist de IP opcional por token (CIDR). Tokens têm prefixo vz_live_; só o hash fica armazenado.

Convenções

  • Ids com prefixo: vz_inst_…, vz_msg_…, vz_evt_…, vz_dlv_…, vz_whk_….
  • Telefones só com dígitos e DDI: 5527999999999. Chats de grupo usam o id …@g.us.
  • Datas ISO 8601 com fuso. Paginação por cursor: ?limit=50&cursor=… → { items, nextCursor }.
  • Envios aceitam Idempotency-Key (válida por 24 h por token) e respondem 202 com o id e a posição na fila.
  • Nunca expomos nomes internos de instância, chaves ou endereços do motor de conexão.

Erros

Formato RFC 9457 com um código VixZap estável em code:

422 · application/problem+json
{
  "type": "https://www.vixzap.com.br/docs/#erros",
  "title": "Dados inválidos",
  "status": 422,
  "code": "validation_failed",
  "errors": [{ "path": "to", "message": "telefone só com dígitos, com DDI (ex.: 5527999999999)" }]
}
CódigoHTTPQuando
unauthorized401Token ausente, inválido ou revogado
forbidden403Sem o escopo, IP fora da allowlist, instância de outra conta
not_found404Recurso inexistente
instance_disconnected409Envio para instância sem sessão ativa (a mensagem fica na fila se o ritmo estiver em "guardar")
instance_limit_reached / endpoint_limit_reached402Limite do plano
rate_limited429Limite de requisições; veja Retry-After
ip_blocked403IP bloqueado por abuso

Instâncias

GET/instancesinstances:read
POST/instancesinstances:manage · token de conta
GET/instances/{id}instances:read
PATCH/instances/{id}instances:manage
DELETE/instances/{id}instances:manage
GET/instances/{id}/qrinstances:manage
POST/instances/{id}/pairing-codeinstances:manage
POST/instances/{id}/restart · /disconnectinstances:manage
GET/instances/{id}/profile · PATCHinstances:manage

Status possíveis: created, qr, connecting, connected, disconnected, banned. O campo statusReason traz o motivo (logged_out, phone_offline, connection_lost…). settings espelha as opções do número: rejectCalls, ignoreGroups, alwaysOnline, readMessages, readStatus, syncFullHistory. pacing controla o ritmo de envio.

Mensagens

POST/instances/{id}/messages/textmessages:send
POST/instances/{id}/messages/mediaimage · video · audio · document · sticker
POST/instances/{id}/messages/location · /contact · /reactionmessages:send
POST/instances/{id}/messages/poll · /buttons · /listmessages:send
GET/messages/{id}messages:read
mídia por URL
POST /v1/instances/vz_inst_8k3j/messages/media
{
  "to": "5527999999999",
  "type": "document",
  "url": "https://meusite.com.br/notas/1234.pdf",
  "fileName": "nota-1234.pdf",
  "caption": "Sua nota fiscal 📄"
}

Campos comuns: quotedMessageId (responder), delayMs (atraso antes de enviar), scheduledFor (agendar). Status da mensagem: queued → sending → sent → delivered → read, ou failed/canceled. Botões e listas dependem do suporte do WhatsApp ao tipo de conta; documentamos as limitações no portal.

Modelos, agendamento e campanhas

Escreva uma vez com {{variáveis}}, agende qualquer envio e dispare lotes no ritmo da instância (anti-banimento), com relatório por destinatário.

POST/templates{ name, type, payload com {{nome}} } · GET/PATCH/DELETE /templates/{id}
POST/instances/{id}/messages/template{ templateId, to, variables, scheduledFor? }
POST/campaigns{ instanceId, name, templateId | type+payload, recipients[{ to, variables }], scheduledFor?, start }
GET/campaigns/{id} · /campaigns/{id}/messages · POST …/start · …/pause · …/cancelmessages:read / messages:send
lote com variáveis
POST /v1/campaigns
{
  "instanceId": "vz_inst_8k3j",
  "name": "Lembrete de consulta",
  "type": "text",
  "payload": { "text": "Olá {{nome}}, sua consulta é {{dia}} às {{hora}}. Responda SIM para confirmar." },
  "recipients": [
    { "to": "5527999990001", "variables": { "nome": "Ana", "dia": "amanhã", "hora": "14h" } },
    { "to": "5527999990002", "variables": { "nome": "Bruno", "dia": "sexta", "hora": "9h" } }
  ],
  "scheduledFor": "2026-11-08T11:00:00-03:00",
  "start": true
}

Toda mensagem aceita scheduledFor (ISO 8601). Campanhas: até 5 000 destinatários, duplicados removidos, variáveis do modelo obrigatórias em cada destinatário (erro na criação, não no envio), pausa/retomada/cancelamento, progresso em tempo real e exportação CSV no portal. O ritmo e o limite diário da instância continuam valendo.

Fila de envio

GET/instances/{id}/queuemessages:read
POST/instances/{id}/queue/pause · /resume · /clearmessages:send
DELETE/instances/{id}/queue/{messageId}messages:send

Cada instância tem uma fila com ritmo (minDelayMs–maxDelayMs com jitter) e limite diário opcional. Ao desconectar, as mensagens ficam guardadas ou são descartadas conforme pacing.onDisconnect.

Contatos e grupos

POST/instances/{id}/contacts/checkaté 500 números
GET/instances/{id}/groupsinstances:read
GET/instances/{id}/contactsinstances:read

Etiquetas e catálogo (WhatsApp Business)

GET/instances/{id}/labelsinstances:read · etiquetas da conta
POST/instances/{id}/labels/assign{ to, labelId, action: add | remove }
GET/instances/{id}/catalogprodutos do catálogo (preço em milésimos: 59000 = R$ 59,00)

Disponíveis quando o número conectado é WhatsApp Business. Mudanças de etiqueta chegam pelo evento label.updated. Para verificar listas grandes de números, repita contacts/check em blocos de 500 (o SDK faz isso em instances.checkNumbersAll).

Webhooks (hub)

GET/webhookswebhooks:manage
POST/webhooksdevolve o segredo uma vez
GET/webhooks/{id} · PATCH · DELETE
POST/webhooks/{id}/testevento de exemplo
POST/webhooks/{id}/rotate-secret
POST/webhooks/{id}/resumereativa após circuit breaker
criar um endpoint com filtro
POST /v1/webhooks
{
  "instanceIds": ["vz_inst_8k3j"],
  "name": "CRM · leads",
  "url": "https://crm.minhaempresa.com.br/hooks/vixzap",
  "format": "vixzap",
  "destinationKind": "generic",
  "timeoutMs": 10000,
  "filters": [
    {
      "events": ["message.received"],
      "direction": "inbound",
      "chatScope": { "mode": "contacts_only" },
      "content": { "contains": "orçamento" },
      "businessHours": { "timezone": "America/Sao_Paulo", "days": [1,2,3,4,5], "start": "08:00", "end": "18:00" }
    }
  ]
}

Um endpoint tem 1..n filtros: OR entre filtros, AND dentro de cada um. Formatos: vixzap (normalizado), evolution-raw (payload original do motor), zapi-compat (callbacks da Z-API, veja Compatibilidade Z-API). Retry padrão: 10 s, 1 min, 5 min, 30 min, 2 h, 6 h. Respostas 2xx contam como entregue; 4xx (exceto 408/425/429) não são repetidas; 5xx, timeout e erro de rede entram em retry. 50 falhas seguidas pausam o endpoint.

Eventos e entregas

GET/events · /events/{id}events:read · filtros: instanceId, type, phone, from, to
GET/deliveriesendpointId, eventId, status
POST/deliveries/{id}/retrywebhooks:manage
POST/deliveries/replay{ endpointId, from, to, onlyFailed }

Conta

GET/accountplano e limites
GET/account/usageconsumo do período

Envelope do webhook

formato vixzap · message.received
{
  "id": "vz_evt_2a7c…",
  "type": "message.received",
  "instanceId": "vz_inst_8k3j…",
  "tenantId": "vz_ten_01…",
  "timestamp": "2026-11-05T14:02:10.120-03:00",
  "data": {
    "id": "3EB0A1…",
    "chatId": "[email protected]",
    "from": "5527999999999",
    "fromMe": false,
    "isGroup": false,
    "participant": null,
    "pushName": "Ana",
    "kind": "text",
    "text": "Oi, quero um orçamento",
    "caption": null,
    "media": null,
    "quoted": null,
    "mentions": [],
    "timestamp": "2026-11-05T14:02:09-03:00"
  }
}

Para mídia, data.media traz mimeType, fileName, sizeBytes, url (assinada, 24 h) e base64 (só se o filtro pedir). kind ∈ text, image, video, audio, document, sticker, location, contact, button_reply, list_reply, poll, reaction, other.

Assinatura HMAC

Cabeçalhos em toda entrega: X-VixZap-Signature: t=<unix>,v1=<hex>, X-VixZap-Event, X-VixZap-Delivery-Id, X-VixZap-Instance, X-VixZap-Timestamp. Calcule HMAC-SHA256(secret, t + "." + corpoBruto) e compare em tempo constante; rejeite se |agora − t| > 300 s. Exemplo em Node na página de segurança.

Tipos de evento

TipoQuando
message.receivedMensagem recebida de contato ou grupo
message.sentMensagem enviada (pela API ou pelo celular)
message.statussent → delivered → read, ou failed
message.deleted · message.reactionApagada para todos · reação
connection.updateMudança de estado da instância, com motivo
qr.updatedNovo QR disponível
contact.updated · group.updated · group.participantsCadastro e grupos
presence.updated · call.received · label.updatedPresença, chamadas, etiquetas

Compatibilidade Z-API

Fluxo feito para a Z-API? Troque só a URL base e o token: https://api.z-api.io/instances/{id}/token/{token}/… vira https://api.vixzap.com.br/zapi/instances/{id}/token/{token}/…, com {id} = instância VixZap (vz_inst_…) e {token} = token de API (vz_live_…). O cabeçalho Client-Token é aceito e ignorado. A resposta segue o formato da Z-API.

POST…/send-text · send-image · send-video · send-audio · send-sticker · send-document/{ext}{ phone, message | image | document… }
POST…/send-location · send-contact · send-reaction · send-poll · send-button-list · send-option-listmessages:send
GET…/status · device · qr-code · qr-code/image · restart · disconnectinstances:read / manage
GET…/phone-exists/{phone} · contacts · queuePOST phone-exists-batch · DELETE queue
PUT…/update-webhook-received · -delivery · -message-status · -connected · -disconnected · -chat-presence{ value: url } → endpoint zapi-compat
o mesmo envio, antes e depois
# Z-API
curl -X POST https://api.z-api.io/instances/ID/token/TOKEN/send-text -H "Client-Token: ..." -d '{"phone":"5527999999999","message":"Olá"}'
# VixZap (modo compatível)
curl -X POST https://api.vixzap.com.br/zapi/instances/vz_inst_8k3j/token/vz_live_.../send-text -d '{"phone":"5527999999999","message":"Olá"}'
# → { "zaapId": "vz_msg_…", "messageId": "vz_msg_…", "id": "vz_msg_…" }

Os webhooks apontados por update-webhook-* aparecem no portal como endpoints normais do hub (formato zapi-compat) e entregam os callbacks da Z-API — ReceivedCallback (com text.message, image.imageUrl…), MessageStatusCallback, ConnectedCallback/DisconnectedCallback, PresenceChatCallback — mais vixzapEventId e os cabeçalhos x-vixzap-* assinados. Grupos usam o sufixo -group como na Z-API. Fora do espelho: chats e histórico de mensagens, grupos (GET /v1/instances/{id}/groups) e a API Partner (use POST /v1/instances). Tabela de equivalências →

OpenAPI e SDK

Referência interativa (OpenAPI 3.0)

Gerada do código da API: api.vixzap.com.br/docs (JSON em /docs/json). Inclui as rotas /v1, /public e o modo compatível /zapi.

npm@vixnegocios/vixzap-sdkTypeScript · Node, Bun, Deno, Workers, navegador
n8n@vixnegocios/n8n-nodes-vixzapgatilho assinado + ações de envio
MCP@vixnegocios/vixzap-mcpClaude, ChatGPT e agentes enviam e leem pelo seu token
SDK
import { VixZap, parseWebhook } from '@vixnegocios/vixzap-sdk';

const vz = new VixZap({ token: process.env.VIXZAP_TOKEN });
await vz.messages.sendText('vz_inst_8k3j', { to: '5527999999999', text: 'Olá!' }, 'pedido-1234');

// no seu receptor de webhooks (corpo cru + cabeçalhos):
const evento = await parseWebhook(process.env.VIXZAP_WEBHOOK_SECRET, req.headers, rawBody);

n8n: Settings → Community Nodes → @vixnegocios/n8n-nodes-vixzap. O gatilho cria o endpoint no hub sozinho e verifica a assinatura de cada entrega; a ação envia texto, mídia, botões, lista e verifica números. MCP: npx -y @vixnegocios/vixzap-mcp com VIXZAP_TOKEN (e VIXZAP_READ_ONLY=1 para só leitura) no Claude Desktop, Claude Code ou qualquer cliente MCP.

Modo parceiro: subcontas e conexão embutível

Para agências, SaaS e integradores (planos Business e Parceiro). Conecte o WhatsApp dos seus clientes dentro do seu produto, com a sua marca, e organize cada cliente numa subconta.

POST/partner/accounts{ name, externalRef?, ownerEmail? } · idempotente por externalRef
GET/partner/accounts · /partner/accounts/{id} · DELETEaccount:manage
POST/instances/{id}/connect-sessions{ redirectUrl?, expiresInMinutes? } → { url, expiresAt }
PUT/partner/branding{ name, logoUrl, primaryColor, supportUrl, hidePoweredBy }
conectar o número de um cliente sem sair do seu sistema
# 1) crie a subconta do cliente (uma vez)
curl -X POST https://api.vixzap.com.br/v1/partner/accounts -H "Authorization: Bearer vz_live_..." -d '{"name":"Padaria Central","externalRef":"cli-1842"}'
# 2) crie a instância DENTRO da subconta (qualquer rota /v1 aceita X-VixZap-Account)
curl -X POST https://api.vixzap.com.br/v1/instances -H "Authorization: Bearer vz_live_..." -H "X-VixZap-Account: vz_ten_..." -d '{"name":"Atendimento"}'
# 3) gere o link temporário da página de conexão e abra no seu produto
curl -X POST https://api.vixzap.com.br/v1/instances/vz_inst_.../connect-sessions -H "Authorization: Bearer vz_live_..." -H "X-VixZap-Account: vz_ten_..." -d '{"expiresInMinutes":30}'
# → { "url": "https://portal.vixzap.com.br/conectar/…", "expiresAt": "…" }
no seu front (modal pronto)
<script src="https://www.vixzap.com.br/embed/vixzap-connect.js"></script>
<script>
  VixZapConnect.open({ url: sessao.url, onConnected: (i) => alert('Conectado: ' + i.phone) });
</script>

A página mostra o QR (ou código de pareamento), renova sozinha e avisa a sua página por postMessage ({ source: 'vixzap-connect', event: 'connected', phone }). As instâncias das subcontas contam no seu plano; webhooks, eventos e tokens continuam por subconta. A marca (nome, logo, cor) vale para todos os planos pagos; esconder o "com tecnologia VixZap" é do plano Parceiro.

Limites

LimiteStartProBusiness
Requisições por minuto por token6001.2003.000
Endpoints por instância2515
Retenção de eventos7 dias15 dias30 dias
Tentativas de entrega366 + fila morta
Payload do webhook2 MB (base64 só para arquivos até 10 MB)