Guia de Integração

1

Obtenha a chave de API

Após registrar sua conta na VZD Application, você recebe uma chave de API (algo como vzd_SUA_CHAVE_AQUI em produção).

Guarde essa chave com segurança — ela identifica sua conta e permite ler/enviar mensagens.

2

Cadastre origem de retorno (webhook)

Registre a URL aonde você quer receber eventos em tempo real (mensagens, status, erros).

curl -X POST https://api.vzdapplication.com/api/whatsapp/connect-origins \
  -H "Authorization: Bearer vzd_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "https://seu-dominio.com.br",
    "label": "Produção CRM"
  }'

Resposta: ID da origem registrada. Use este ID para revogar depois, se necessário.

Por que é importante? Webhooks permitem que você receba eventos em tempo real sem fazer polling. Se não registrar, você só verá mensagens via GET /messages.

3

Crie uma sessão de conexão

Inicie uma sessão para conectar o WhatsApp Business do cliente. A sessão gera uma URL que o cliente acessa no navegador.

curl -X POST https://api.vzdapplication.com/api/whatsapp/connect-sessions \
  -H "Authorization: Bearer vzd_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "onboarding_mode": "COEXISTENCE",
    "return_url": "https://seu-dominio.com.br/sucesso",
    "label": "Salão Beleza"
  }'

Resposta 201:
{
  "connect_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "connect_url": "https://app.vzdapplication.com/connect?session=550e8400-...",
  "expires_at": "2024-01-15T14:00:00.000Z"
}

4

Redirecione o cliente para conectar WhatsApp

Leve o cliente até a connect_url. Ele fará login na conta de WhatsApp Business dele com QR Code e o celular continuará funcionando (Coexistência).

Atenção: A sessão expira em 15 minutos. Se passar, crie uma nova.

5

Consulte o resultado da conexão

Após o cliente confirmar, consulte o status da sessão:

curl https://api.vzdapplication.com/api/whatsapp/connect-sessions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer vzd_SUA_CHAVE_AQUI"

Resposta 200 (sucesso):
{
  "status": "CONNECTED",
  "channel": {
    "phone_number_id": "5511999887766",
    "waba_id": "100234567890",
    "phone_number": "+55 (11) 99988-7766",
    "display_name": "Beleza ABC",
    "status": "CONNECTED"
  }
}

6

Envie a primeira mensagem de template

Templates são mensagens pré-aprovadas pela Meta. São obrigatórios fora da janela de 24 horas desde a última mensagem do cliente.

curl -X POST https://api.vzdapplication.com/api/whatsapp/messages/template \
  -H "Authorization: Bearer vzd_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "5511999887766",
    "to": "5511987654321",
    "template_name": "confirmacao_agendamento",
    "language_code": "pt_BR",
    "sync": true
  }'

Resposta 201 (primeiro envio):
{
  "status": "sent",
  "wamid": "wamid.HhBmRGVmAUH7AglMkZGVzQ==",
  "message_id": "msg_2024_001"
}

Sem template? Crie um em GET /templates ou direto no Gerenciador de Negócios da Meta.

7

Registre webhook de retorno

Agora configure a URL para receber eventos. VZD enviará POST assinado com cada mensagem, status e erro.

curl -X PUT https://api.vzdapplication.com/api/whatsapp/webhook \
  -H "Authorization: Bearer vzd_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://seu-dominio.com.br/webhooks/whatsapp"
  }'

Resposta 200:
{
"webhook_url": "https://seu-dominio.com.br/webhooks/whatsapp",
"webhook_secret": "sk_whk_xxxx"
}

Importante: O segredo aparece uma única vez. Guarde com segurança — você vai precisar para validar as assinaturas dos webhooks.

8

Receba eventos em tempo real

Seu endpoint receberá POST com estrutura:

POST /webhooks/whatsapp HTTP/1.1
Host: seu-dominio.com.br
X-VZD-Signature: sha256=abc123...
Content-Type: application/json

{
  "event": "whatsapp.message.received",
  "event_id": "evt_9f2c0a1b",
  "occurred_at": "2024-01-15T10:00:00.000Z",
  "channel": {
    "phone_number_id": "5511999887766",
    "waba_id": "100234567890"
  },
  "data": {
    "wamid": "wamid.HhBm...",
    "from": "5511987654321",
    "direction": "INBOUND",
    "origin": "CLOUD_API",
    "type": "text",
    "text": "Olá! Qual é o horário?"
  }
}

Próximo passo: Valide a assinatura HMAC-SHA256 usando o segredo. Leia Webhooks de Origem para validação passo a passo.