Documentação API

1. Crie sua conta e escolha o tipo de painel da sua empresa.
2. Conecte o WhatsApp pelo QR Code no painel e confirme o status da conexão.
3. Em Configurações → API e integrações, crie uma chave e copie-a. Apenas o titular pode criar chaves; a chave completa aparece uma única vez.
4. Use a chave somente no servidor do seu sistema. A conta precisa estar ativa, com assinatura ou teste vigente.

URL base: https://zapflowapi.site/api/public/v1. Todas as requisições exigem o cabeçalho Authorization. Os valores abaixo são exemplos, não credenciais reais.

Authorization: Bearer SUA_CHAVE_API
Content-Type: application/json

Até 5 chaves ativas por empresa. Revogar uma chave em Configurações bloqueia as próximas requisições. Limite compartilhado entre chaves: 60 requisições por minuto por empresa; uma resposta 429 inclui Retry-After: 60.

Integração servidor a servidor, sem acesso direto por navegador de outro domínio (CORS). Nunca use senha de login ou token de webhook como chave de API.

GET /instances — lista identificadores e status registrados das conexões da sua empresa, sem número de telefone.

curl "https://zapflowapi.site/api/public/v1/instances" \
  -H "Authorization: Bearer SUA_CHAVE_API"

{
  "data": [
    { "id": "11111111-1111-4111-8111-111111111111", "status": "connected" }
  ]
}

GET /instances/{instance_id}/status — consulta o servidor de WhatsApp em tempo real, sem reconectar ou gerar QR Code.

{
  "data": {
    "instance_id": "11111111-1111-4111-8111-111111111111",
    "status": "connected",
    "checked_at": "2026-11-05T01:00:00.000Z"
  }
}

Status de conexão: connected, connecting ou disconnected. O pareamento continua sendo feito pelo painel.

POST /messages/text — envia uma mensagem individual para uma conversa existente da empresa. Obtenha conversation_id pelo endereço da conversa selecionada no painel; não informe telefone nem user_id.

Campos obrigatórios: conversation_id (UUID) e text (de 1 a 4000 caracteres). A conexão da conversa deve estar conectada. O cabeçalho Idempotency-Key é obrigatório: de 8 a 128 caracteres, usando letras, números, ponto, hífen ou sublinhado.

curl -X POST "https://zapflowapi.site/api/public/v1/messages/text" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: atendimento-001" \
  -d '{"conversation_id":"22222222-2222-4222-8222-222222222222","text":"Olá! Seu atendimento foi recebido."}'

Resposta 201: o servidor de WhatsApp aceitou o envio. Isso não confirma entrega nem leitura.

{
  "data": {
    "request_id": "33333333-3333-4333-8333-333333333333",
    "status": "sent",
    "replayed": false
  }
}

Repita a mesma chave e o mesmo conteúdo para consultar o resultado sem enviar novamente. Uma chave usada com conteúdo diferente retorna 409. A proteção contra duplicidade é compartilhada por todas as chaves da empresa.

Resposta 202 indica processamento ou resultado incerto. Em caso de unknown, não tente outra chave automaticamente: a mensagem pode ter sido enviada mesmo se a confirmação falhou. Confira a conversa no painel.

GET /messages/{request_id} — use o identificador retornado no envio. Retorna apenas metadados, nunca o conteúdo ou o destinatário.

{
  "data": {
    "request_id": "33333333-3333-4333-8333-333333333333",
    "status": "sent",
    "message_id": "44444444-4444-4444-8444-444444444444",
    "created_at": "2026-11-05T01:00:00.000Z"
  }
}

processing: envio reservado; sent: aceito pelo servidor de WhatsApp; unknown: resultado não confirmado; failed: envio não iniciado por falha de registro. Não existe confirmação de entrega ou leitura nesta versão. Um processamento interrompido pode permanecer processing e nunca é reenviado automaticamente.

{
  "error": {
    "code": "unauthorized",
    "message": "Chave ausente, inválida ou revogada."
  }
}

• 400: campos, identificadores ou JSON inválidos.
• 401: chave ausente, inválida ou revogada.
• 403: conta ou assinatura sem acesso vigente.
• 404: recurso inexistente ou pertencente a outra empresa.
• 409: WhatsApp desconectado ou conflito de idempotência.
• 413: corpo maior que 20.000 bytes.
• 415: Content-Type diferente de application/json.
• 429: limite de requisições atingido.
• 503: serviço indisponível; consulte o resultado antes de repetir um envio.

Os webhooks de conexão e pagamento são exclusivos dos provedores e não fazem parte desta API. Nenhum endpoint permite ativar plano ou confirmar pagamento.