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
- Crie a conta no portal, dê um nome à instância e leia o QR.
- Em Tokens, crie um token de instância com o escopo
messages:send. Guarde: ele só aparece uma vez. - Envie a primeira mensagem:
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 👋" }'- 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:
| Tipo | Alcance | Uso típico |
|---|---|---|
| Token de instância | Só a instância indicada | Integração de um sistema com um número |
| Token de conta | Todas as instâncias do assinante; pode criar instâncias | Software 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 respondem202com 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:
{
"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ódigo | HTTP | Quando |
|---|---|---|
unauthorized | 401 | Token ausente, inválido ou revogado |
forbidden | 403 | Sem o escopo, IP fora da allowlist, instância de outra conta |
not_found | 404 | Recurso inexistente |
instance_disconnected | 409 | Envio para instância sem sessão ativa (a mensagem fica na fila se o ritmo estiver em "guardar") |
instance_limit_reached / endpoint_limit_reached | 402 | Limite do plano |
rate_limited | 429 | Limite de requisições; veja Retry-After |
ip_blocked | 403 | IP bloqueado por abuso |
Instâncias
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 /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 /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
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
Etiquetas e catálogo (WhatsApp Business)
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)
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
Conta
Envelope do webhook
{
"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
| Tipo | Quando |
|---|---|
message.received | Mensagem recebida de contato ou grupo |
message.sent | Mensagem enviada (pela API ou pelo celular) |
message.status | sent → delivered → read, ou failed |
message.deleted · message.reaction | Apagada para todos · reação |
connection.update | Mudança de estado da instância, com motivo |
qr.updated | Novo QR disponível |
contact.updated · group.updated · group.participants | Cadastro e grupos |
presence.updated · call.received · label.updated | Presenç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.
# 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.
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.
# 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": "…" }<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
| Limite | Start | Pro | Business |
|---|---|---|---|
| Requisições por minuto por token | 600 | 1.200 | 3.000 |
| Endpoints por instância | 2 | 5 | 15 |
| Retenção de eventos | 7 dias | 15 dias | 30 dias |
| Tentativas de entrega | 3 | 6 | 6 + fila morta |
| Payload do webhook | 2 MB (base64 só para arquivos até 10 MB) | ||