Conceitos B\u00e1sicos

Entenda os conceitos fundamentais da plataforma ZapFlare.

Vis\u00e3o Geral da Arquitetura

O ZapFlare \u00e9 uma plataforma completa para integra\u00e7\u00e3o com WhatsApp, constru\u00edda com tecnologia Edge Computing da Cloudflare.

graph TB
    A[Cliente] -->|API REST| B[ZapFlare API]
    B --> C[Inst\u00e2ncia Manager]
    C --> D[WhatsApp Web]
    B --> E[Webhooks]
    E --> F[Seu Servidor]

Conceitos Principais

Tenant (Conta)

Um tenant representa uma conta no ZapFlare. Cada tenant pode ter:

• M\u00faltiplas inst\u00e2ncias WhatsApp
• API Keys para integra\u00e7\u00e3o
• Configura\u00e7\u00f5es de webhook
• Plano de assinatura

Inst\u00e2ncia

Uma inst\u00e2ncia \u00e9 uma conex\u00e3o individual com o WhatsApp. Caracter\u00edsticas:

• Cada inst\u00e2ncia conecta a um n\u00famero de telefone
• Funciona como um "dispositivo conectado" no WhatsApp
• Mant\u00e9m sess\u00e3o persistente
• Pode enviar e receber mensagens
• Tem seu pr\u00f3prio webhook para eventos

API Keys

As API Keys s\u00e3o credenciais para acessar a API programaticamente:

• Produ\u00e7\u00e3o: zpk_live_... - Para uso em produ\u00e7\u00e3o
• Teste: zpk_test_... - Limitada a 10 mensagens/dia

Webhooks

Webhooks s\u00e3o notifica\u00e7\u00f5es HTTP enviadas quando eventos ocorrem:

• Mensagem recebida
• Status de conex\u00e3o alterado
• Mensagem lida/entregue
• Eventos de grupos

Fluxo de Trabalho T\u00edpico

1. Configura\u00e7\u00e3o Inicial

sequenceDiagram
    participant U as Usu\u00e1rio
    participant Z as ZapFlare
    participant W as WhatsApp

    U->>Z: Criar conta
    Z->>U: Conta criada
    U->>Z: Criar inst\u00e2ncia
    Z->>U: QR Code
    U->>W: Escanear QR
    W->>Z: Conex\u00e3o estabelecida
    Z->>U: Inst\u00e2ncia conectada

2. Enviando Mensagens

sequenceDiagram
    participant A as Sua Aplica\u00e7\u00e3o
    participant Z as ZapFlare API
    participant W as WhatsApp

    A->>Z: POST /v1/messages/send
    Z->>Z: Validar API Key
    Z->>Z: Verificar limites
    Z->>W: Enviar mensagem
    W->>Z: Confirma\u00e7\u00e3o
    Z->>A: Resposta com messageId

3. Recebendo Mensagens

sequenceDiagram
    participant W as WhatsApp
    participant Z as ZapFlare
    participant S as Seu Servidor

    W->>Z: Nova mensagem
    Z->>Z: Processar mensagem
    Z->>S: POST webhook
    S->>Z: 200 OK

Tipos de Mensagens

Mensagens de Texto

• Texto simples
• Texto com formata\u00e7\u00e3o (negrito, it\u00e1lico)
• Texto com emojis
• Links

Mensagens de M\u00eddia

• Imagens: JPEG, PNG (m\u00e1x 5MB)
• V\u00eddeos: MP4 (m\u00e1x 16MB)
• \u00c1udios: MP3, OGG (m\u00e1x 16MB)
• Documentos: PDF, DOC, XLS, etc (m\u00e1x 100MB)

Mensagens Interativas

• Listas: Op\u00e7\u00f5es selecion\u00e1veis
• Bot\u00f5es: A\u00e7\u00f5es r\u00e1pidas (descontinuado)
• Enquetes: Pesquisas interativas

Mensagens de Localiza\u00e7\u00e3o

• Coordenadas GPS
• Nome do local
• Endere\u00e7o

Limites e Quotas

Limites por Plano

Recurso	Starter	Pro	Enterprise
Inst\u00e2ncias	1	5	50
Mensagens/dia	Ilimitado	Ilimitado	Ilimitado
API Keys	5	20	Ilimitado
Webhooks	1 por inst\u00e2ncia	1 por inst\u00e2ncia	1 por inst\u00e2ncia
Suporte	Comunidade	Priorit\u00e1rio	Dedicado

Rate Limiting

Para garantir a estabilidade da plataforma:

• API P\u00fablica: 60 requisi\u00e7\u00f5es/minuto
• Mensagens: 5 mensagens/segundo por inst\u00e2ncia
• Webhooks: 1000 eventos/minuto

Seguran\u00e7a

Criptografia

• Todas as comunica\u00e7\u00f5es s\u00e3o via HTTPS
• Mensagens mantidas criptografadas
• Sess\u00f5es protegidas com tokens seguros

Autentica\u00e7\u00e3o

• API Keys com prefixos identificadores
• Cookies httpOnly para dashboard
• Tokens JWT com expira\u00e7\u00e3o

Valida\u00e7\u00e3o de Webhooks

• Assinatura HMAC-SHA256
• Timestamp para evitar replay
• IP allowlist (opcional)

Status da Inst\u00e2ncia

Estados Poss\u00edveis

stateDiagram-v2
    [*] --> created: Criar inst\u00e2ncia
    created --> qr: Gerar QR
    qr --> connected: Escanear QR
    qr --> qr: Novo QR (expira\u00e7\u00e3o)
    connected --> disconnected: Desconex\u00e3o
    disconnected --> qr: Reconectar
    connected --> banned: Ban WhatsApp
    banned --> [*]

Descri\u00e7\u00e3o dos Status

• created: Inst\u00e2ncia rec\u00e9m criada
• qr: Aguardando leitura do QR Code
• connected: Conectado e operacional
• disconnected: Desconectado temporariamente
• banned: N\u00famero banido pelo WhatsApp

Boas Pr\u00e1ticas

1. Gerenciamento de Inst\u00e2ncias

• Monitore o status regularmente
• Implemente reconex\u00e3o autom\u00e1tica
• Mantenha logs de eventos

2. Envio de Mensagens

• Respeite os limites do WhatsApp
• Evite spam e mensagens n\u00e3o solicitadas
• Use templates para mensagens recorrentes

3. Webhooks

• Responda rapidamente (< 5s)
• Implemente idempot\u00eancia
• Trate erros graciosamente

4. Seguran\u00e7a

• Nunca exponha API Keys
• Valide todos os webhooks
• Use HTTPS sempre

Pr\u00f3ximos Passos

Agora que voc\u00ea entende os conceitos b\u00e1sicos:

1. Crie sua primeira inst\u00e2ncia
2. Configure webhooks
3. Explore a API de mensagens
4. Implemente autentica\u00e7\u00e3o