Documentação da API

A API ZAP Trievo permite conectar números de WhatsApp ao seu sistema e enviar e receber mensagens por HTTP. Ela segue o padrão de rotas da Evolution API v2, então bibliotecas e integrações existentes funcionam trocando apenas a URL base e a chave.

Visão geral

URL base	`https://zap.trievo.com.br/api/v1`
Formato	JSON (`Content-Type: application/json`)
Autenticação	Header `apikey` com sua chave `zt_...`
Instância	Cada número conectado é uma instância, identificada por um nome que você escolhe.

As rotas seguem o formato /{recurso}/{ação}/{instancia}. Exemplo: /message/sendText/minha-loja.

Autenticação

Envie sua chave em todas as requisições. Você pode usar o header apikey (padrão Evolution) ou Authorization: Bearer.

apikey: zt_sua_chave_aqui
# ou
Authorization: Bearer zt_sua_chave_aqui

Sua chave dá acesso apenas às instâncias da sua conta. Nunca a exponha em aplicativos front-end ou repositórios públicos. Se ela vazar, peça ao suporte para gerar uma nova.

Limites e erros

Cada conta tem um limite de requisições por minuto, informado nos headers X-RateLimit-Limit e X-RateLimit-Remaining. Quando excedido, a API responde 429 com o header Retry-After.

Código	Significado
`401`	Chave ausente ou inválida.
`403`	Conta suspensa/expirada, IP não autorizado ou limite de instâncias do plano atingido.
`404`	Instância não pertence à sua conta ou rota inexistente.
`409`	Nome de instância já em uso.
`429`	Limite de requisições por minuto excedido.
`502/504`	Serviço de WhatsApp temporariamente indisponível ou lento.

{
  "status": 404,
  "error": "Requisição recusada",
  "response": { "message": ["Instância \"x\" não encontrada na sua conta."] }
}

Criar e conectar uma instância

POST/instance/create

Cria uma nova instância (respeitando o limite do seu plano). O nome deve ter de 2 a 64 caracteres: letras, números, _, - ou ..

curl -X POST https://zap.trievo.com.br/api/v1/instance/create \
  -H "apikey: zt_sua_chave" -H "Content-Type: application/json" \
  -d '{ "instanceName": "minha-loja", "integration": "WHATSAPP-BAILEYS", "qrcode": true }'

A resposta traz o QR Code em qrcode.base64 (imagem PNG em base64) para exibir ao usuário.

GET/instance/connect/{instancia}

Gera um novo QR Code (ou código de pareamento, se informado ?number=5511999999999).

GET/instance/connectionState/{instancia}

Retorna o estado da conexão: open (conectado), connecting ou close.

Gerenciar instâncias

Rota	Descrição
GET `/instance/fetchInstances`	Lista as instâncias da sua conta.
POST `/instance/restart/{instancia}`	Reinicia a conexão.
DELETE `/instance/logout/{instancia}`	Desconecta o número (mantém a instância).
DELETE `/instance/delete/{instancia}`	Remove a instância e libera a vaga do plano.
POST `/settings/set/{instancia}`	Define comportamento (rejeitar chamadas, ignorar grupos, sempre online...).

Enviar texto

POST/message/sendText/{instancia}

{
  "number": "5511999999999",
  "text": "Olá, tudo bem?",
  "delay": 1200,
  "linkPreview": true
}

O número deve estar no formato internacional, apenas dígitos (DDI + DDD + número). Para grupos, use o JID do grupo (1203...@g.us).

Enviar mídia

POST/message/sendMedia/{instancia}

{
  "number": "5511999999999",
  "mediatype": "document",        // image | video | audio | document
  "mimetype": "application/pdf",
  "media": "https://exemplo.com/nota.pdf", // URL ou base64
  "fileName": "nota-fiscal.pdf",
  "caption": "Sua nota fiscal"
}

POST/message/sendWhatsAppAudio/{instancia}

Envia áudio como mensagem de voz gravada: { "number": "...", "audio": "https://.../audio.mp3" }.

Outros tipos de mensagem

Rota	Uso
`/message/sendLocation/{instancia}`	Localização (latitude, longitude, nome, endereço).
`/message/sendContact/{instancia}`	Cartão de contato.
`/message/sendReaction/{instancia}`	Reação com emoji a uma mensagem.
`/message/sendPoll/{instancia}`	Enquete.
`/message/sendList/{instancia}`	Mensagem com lista de opções.
`/message/sendSticker/{instancia}`	Figurinha.
`/message/sendStatus/{instancia}`	Publicar status.

Webhooks

POST/webhook/set/{instancia}

Configure a URL que receberá os eventos da instância.

{
  "webhook": {
    "enabled": true,
    "url": "https://seusistema.com.br/webhook/whatsapp",
    "byEvents": false,
    "base64": false,
    "events": ["MESSAGES_UPSERT", "MESSAGES_UPDATE", "CONNECTION_UPDATE", "QRCODE_UPDATED"]
  }
}

Principais eventos: MESSAGES_UPSERT (mensagem recebida/enviada), MESSAGES_UPDATE (entregue/lida), CONNECTION_UPDATE (conectou/desconectou), QRCODE_UPDATED (novo QR Code), SEND_MESSAGE, CONTACTS_UPSERT, GROUPS_UPSERT.

GET/webhook/find/{instancia}

Consulta a configuração atual do webhook.

Referência completa

Todas as rotas por instância da Evolution API v2 estão disponíveis em /api/v1 — incluindo /chat (conversas, mensagens, contatos, fotos de perfil, marcar como lida), /group (criar, participantes, convites) e integrações (/typebot, /chatwoot, /openai...). Consulte a referência oficial da Evolution API v2 e substitua a URL base por https://zap.trievo.com.br/api/v1.

Rotas administrativas globais (que não pertencem a uma instância específica) não estão disponíveis pela API pública. Fale com o suporte se precisar de algo além das rotas por instância.