MultiZap.

Introdução

Bem-vindo à API do MultiZap Gateway. O MultiZap possibilita que você envie notificações transacionais e mensagens interativas via WhatsApp usando instâncias Baileys isoladas por estabelecimento. Todas as chamadas para as rotas da API usam o formato de dados JSON.

Autenticação

A API do MultiZap utiliza Bearer Tokens ou parâmetros de consulta na URL para autenticação de requisições. Seu token de acesso é gerado exclusivamente para a sua loja e pode ser enviado de duas formas: 1. Pelo cabeçalho HTTP: `Authorization: Bearer SEU_TOKEN` 2. Pela URL (Query Param): `?token=SEU_TOKEN` (ótimo para testes rápidos no navegador para rotas GET)

Parâmetros da Requisição

ParâmetroDescrição
Authorization
headeropcional
Deve conter a string "Bearer SEU_TOKEN_AQUI"
token
query parameteropcional
Alternativa ao cabeçalho (ex: https://multizap.online/api/stores/1?token=SEU_TOKEN)

Obter Dados da Loja

GET/api/stores/{storeId}

Retorna as informações de cadastro, webhook configurado e chaves da loja.

Parâmetros da Requisição

ParâmetroDescrição
storeId
integer (path)obrigatório
ID numérico da loja

Atualizar Dados da Loja

PUT/api/stores/{storeId}

Atualiza o nome, telefone ou URL de webhook da loja.

Parâmetros da Requisição

ParâmetroDescrição
storeId
integer (path)obrigatório
ID numérico da loja
name
stringopcional
Novo nome da loja
phone
stringopcional
Novo telefone de contato da loja
webhook_url
stringopcional
URL do endpoint para receber webhooks

Status do WhatsApp (QR)

GET/api/stores/{storeId}/qr/status

Obtém o estado atual da conexão de WhatsApp (ex: disconnected, connecting, open) e dados do aparelho.

Parâmetros da Requisição

ParâmetroDescrição
storeId
integer (path)obrigatório
ID numérico da loja

Iniciar Conexão (QR)

POST/api/stores/{storeId}/qr/connect

Inicia o socket de pareamento com o WhatsApp. Use em seguida a rota de status para monitorar a geração de novos códigos QR.

Parâmetros da Requisição

ParâmetroDescrição
storeId
integer (path)obrigatório
ID numérico da loja

Desconectar WhatsApp

POST/api/stores/{storeId}/qr/disconnect

Desconecta o WhatsApp da loja e remove a sessão de autenticação do servidor.

Parâmetros da Requisição

ParâmetroDescrição
storeId
integer (path)obrigatório
ID numérico da loja

Obter Logs de Envio

GET/api/stores/{storeId}/logs

Retorna a lista de logs recentes de requisições de webhook despachadas para a loja.

Parâmetros da Requisição

ParâmetroDescrição
storeId
integer (path)obrigatório
ID numérico da loja

Enviar Mensagem de Texto

POST/api/messages/send

Envia uma mensagem de texto padrão para um número de telefone cadastrado no WhatsApp.

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número de telefone de destino, incluindo DDI e DDD, sem formatação (ex: "5511999998888")
text
stringobrigatório
Conteúdo em texto da mensagem

Enviar Imagem

POST/api/messages/send

Envia uma imagem hospedada em uma URL pública com legenda opcional.

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.image.url
stringobrigatório
URL pública da imagem (.jpg, .png)
options.caption
stringopcional
Legenda da imagem

Enviar Vídeo

POST/api/messages/send

Envia um arquivo de vídeo hospedado em uma URL pública.

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.video.url
stringobrigatório
URL pública do vídeo (.mp4)
options.caption
stringopcional
Legenda do vídeo

Enviar Documento

POST/api/messages/send

Envia arquivos PDF, planilhas ou outros documentos informando o tipo MIME.

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.document.url
stringobrigatório
URL pública do documento
options.mimetype
stringobrigatório
Tipo MIME do arquivo (ex: "application/pdf")
options.fileName
stringobrigatório
Nome do arquivo de exibição

Enviar Áudio

POST/api/messages/send

Envia áudios e permite simular que a mensagem foi gravada na hora (Push-to-Talk).

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.audio.url
stringobrigatório
URL pública do áudio (.mp3, .ogg)
options.ptt
booleanopcional
Se verdadeiro, o áudio aparece como gravado ao vivo (PTT)

Enviar Localização

POST/api/messages/send

Envia uma marcação geográfica no mapa de conversas.

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.location.degreesLatitude
numberobrigatório
Latitude
options.location.degreesLongitude
numberobrigatório
Longitude

Enviar Contato (vCard)

POST/api/messages/send

Envia um ou mais cartões de contato formatados em padrão vCard.

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.contacts.displayName
stringobrigatório
Nome exibido no card
options.contacts.contacts
arrayobrigatório
Coleção de objetos vCard [{ vcard: string }]

Enviar Botões

POST/api/messages/send

Envia botões interativos de clique rápido (Quick Reply buttons).

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.text
stringobrigatório
Texto base acima dos botões
options.buttons
arrayobrigatório
Lista de botões [{ buttonId: string, buttonText: { displayText: string } }]

Simular Estado de Presença

POST/api/messages/send

Atualiza o estado de digitação ou gravação no chat do cliente.

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.presence
stringobrigatório
Tipo: "composing" (digitando), "recording" (gravando áudio), "paused", "available"

Enviar Enquete

POST/api/messages/send

Envia enquetes interativas para o chat.

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.poll.name
stringobrigatório
Pergunta da enquete
options.poll.values
arrayobrigatório
Alternativas como string (ex: ["Opção A", "Opção B"])
options.poll.selectableCount
numberopcional
Quantidade máxima de escolhas

Enviar Reações

POST/api/messages/send

Reage a uma mensagem recebida com um caractere Unicode (emoji).

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.react.text
stringobrigatório
Caractere da reação (ex: U+1F44D para positivo)
options.react.key
objectobrigatório
Chave da mensagem de origem (key do payload de mensagem recebida)

Visualização Única (View Once)

POST/api/messages/send

Envia fotos ou vídeos configurados para visualização única (View Once).

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número do destinatário
options.image.url
stringobrigatório
URL pública da imagem
options.viewOnce
booleanobrigatório
Deve ser igual a true

Menções (@JID)

POST/api/messages/send

Mencione contatos de forma destacada em mensagens.

Parâmetros da Requisição

ParâmetroDescrição
to
stringobrigatório
Número de telefone / ID do grupo
options.text
stringobrigatório
Mensagem contendo marcações (ex: "@5511988887777")
options.mentions
arrayobrigatório
Lista de JIDs que serão marcados (ex: ["5511988887777@s.whatsapp.net"])

Gatilhos de Eventos

O MultiZap despacha chamadas HTTP POST para o webhook cadastrado para notificar eventos em tempo real.

Parâmetros da Requisição

ParâmetroDescrição
message.received
eventopcional
Disparado ao receber nova mensagem no WhatsApp
message.sent
eventopcional
Disparado como recibo de mensagem enviada pela API
status
eventopcional
Notifica alterações no estado da sessão (open, connecting, disconnected)
qr
eventopcional
Disparado quando um novo código QR é gerado para pareamento

Exemplo de Recebimento

Exemplo detalhado do payload enviado ao seu webhook quando o cliente envia uma mensagem de texto.

Configuração de Faturas & Callbacks

POST/api/webhooks/pixup

O MultiZap expõe um endpoint público unificado para receber notificações de pagamentos e infrações MED em tempo real da PixUp / BSPay. Para configurar: 1. Acesse o painel de parceiro da PixUp. 2. Cadastre a URL de Webhook: `https://seu-dominio.com/api/webhooks/pixup`. 3. Obtenha seu `Callback Secret` e cadastre-se no painel administrativo do MultiZap (`/admin/pixup-bspay/config`) para habilitar autenticação automática de assinaturas HMAC das faturas.

Parâmetros da Requisição

ParâmetroDescrição
event
stringobrigatório
Gatilho do webhook: cashin.confirmed, cashout.confirmed, infraction.created
transaction_id
stringobrigatório
Código identificador da transação
amount
numberobrigatório
Valor monetário em BRL

Exemplo de Requisição (CURL)

bash
# Nenhuma chamada HTTP necessária
# Acesse o dashboard para obter suas credenciais
Dica de IntegraçãoSubstitua SEU_TOKEN pelo Bearer Token ativo da sua loja obtido na aba de credenciais do painel. A URL base deve apontar para a porta ativa do servidor gateway.