Contrato da API
HTTP puro sobre JSON. Sem SDK obrigatório, sem dependência de linguagem. Autenticação por chave de app, isolamento por conta e compatibilidade com o dialeto de provedores populares na ponte /v1/bridge.
Autenticação
Toda chamada (exceto /v1/health) exige a chave do app. Aceita três formas:
# 1) header apikey (recomendado) curl https://wacoreapi.zapboot.com/v1/me -H "apikey: SUA_CHAVE" # 2) Authorization Bearer curl https://wacoreapi.zapboot.com/v1/me -H "Authorization: Bearer SUA_CHAVE" # 3) query (só para teste rápido) curl "https://wacoreapi.zapboot.com/v1/me?apikey=SUA_CHAVE"
Formato de resposta
Sucesso devolve o recurso; erro devolve código e mensagem legível.
// sucesso { "ok": true, "id": "msg_8f21c", "queued": true } // erro { "error": { "code": "BAD_REQUEST", "message": "Número inválido." } }
400 | Dados inválidos |
401 | Chave ausente ou inválida |
403 | Escopo insuficiente |
404 | Instância ou recurso não encontrado |
409 | Conflito de estado (ex.: já conectado) |
429 | Limite da chave ou fila cheia |
Conectar um número e enviar
Quatro chamadas resolvem o caminho inteiro: criar, conectar, acompanhar e enviar.
# 1) cria a instância e recebe o QR curl -X POST https://wacoreapi.zapboot.com/v1/instances \ -H "apikey: SUA_CHAVE" -H "content-type: application/json" \ -d '{"name":"vendas","displayName":"Vendas"}' # 2) conecta (QR em dataURL; ou use /pair com o telefone) curl -X POST https://wacoreapi.zapboot.com/v1/instances/vendas/connect \ -H "apikey: SUA_CHAVE" # 3) acompanha até "open" curl https://wacoreapi.zapboot.com/v1/instances/vendas/status \ -H "apikey: SUA_CHAVE" # 4) envia (a fila aplica ritmo humano) curl -X POST https://wacoreapi.zapboot.com/v1/messages/text \ -H "apikey: SUA_CHAVE" -H "content-type: application/json" \ -d '{"instance":"vendas","number":"5511999999999","text":"Olá!"}'
Receba o que chega no chip
Entrega assinada com HMAC-SHA256, retry exponencial e log de cada tentativa.
Criar
curl -X POST https://wacoreapi.zapboot.com/v1/webhooks \ -H "apikey: SUA_CHAVE" \ -H "content-type: application/json" \ -d '{"url":"https://seu.app/wa-hook"}'
A resposta traz o secret. Guarde: é ele que valida a assinatura.
Validar a assinatura
// Node const esperado = crypto .createHmac('sha256', secret) .update(rawBody) .digest('hex'); if (esperado !== req.headers['x-wacore-signature']) return res.sendStatus(401);
Todos os 36 endpoints principais
A especificação completa e sempre atualizada está em /v1/openapi.json.
| Método | Rota | Descrição |
|---|---|---|
| GET | /v1/health | Saúde do motor (público, sem chave) |
| GET | /v1/openapi.json | Especificação OpenAPI 3.1 gerada do próprio router |
| GET | /v1/me | Identidade do app, readiness, instâncias e limites |
| GET | /v1/instances | Lista as instâncias do app |
| POST | /v1/instances | Cria instância (nome, displayName, proxyId) |
| GET | /v1/instances/:name | Detalha uma instância |
| PATCH | /v1/instances/:name | Edita nome de exibição e proxy |
| DELETE | /v1/instances/:name | Remove a instância e a sessão |
| POST | /v1/instances/:name/connect | Conecta e devolve disponibilidade de QR |
| POST | /v1/instances/:name/pair | Pareamento por código de 8 dígitos |
| POST | /v1/instances/:name/disconnect | Desconecta (logout opcional) |
| POST | /v1/instances/:name/restart | Reinicia o socket |
| GET | /v1/instances/:name/qr | QR em dataURL mais pairing code |
| GET | /v1/instances/:name/status | Estado, quota, fila e health |
| POST | /v1/instances/:name/check-numbers | Valida até 200 números (isExist) |
| POST | /v1/instances/:name/presence | Presença: digitando, gravando, online |
| POST | /v1/instances/:name/read | Marca mensagens como lidas |
| GET | /v1/instances/:name/contacts | Últimos 500 contatos conhecidos |
| POST | /v1/messages | Enfileira mensagem genérica (kind) |
| POST | /v1/messages/text | Enfileira texto |
| POST | /v1/messages/media | Enfileira mídia (URL, base64, path, buffer) |
| POST | /v1/messages/audio | Áudio ou mensagem de voz |
| POST | /v1/messages/sticker | Figurinha |
| POST | /v1/messages/location | Localização |
| POST | /v1/messages/contact | Contato em vCard |
| POST | /v1/messages/poll | Enquete |
| POST | /v1/messages/now | Envio imediato, sem passar pela fila |
| GET | /v1/messages | Histórico com filtros |
| GET | /v1/queue | Estatísticas e itens da fila |
| POST | /v1/queue/:id/retry | Reenfileira um job |
| POST | /v1/queue/:id/cancel | Cancela um job |
| POST | /v1/instances/:name/pause | Pausa os envios da instância |
| POST | /v1/instances/:name/resume | Retoma os envios |
| GET | /v1/webhooks | Lista webhooks do app |
| POST | /v1/webhooks | Cria webhook e devolve o secret HMAC |
| DELETE | /v1/webhooks/:id | Remove webhook |
/v1/bridge expõe o mesmo motor no dialeto de provedores populares (instância no caminho da URL). Migrar é trocar a base e a chave.Quer testar com a sua chave?
Peça o acesso de avaliação descrevendo o cenário. Liberamos uma instância e a chave para você validar a integração antes de contratar.