Pular para conteúdo

WhatsApp Entrypoint

O whatsapp-entrypoint é a porta de entrada e saída de dados entre a plataforma EcomSmart e a Meta Cloud API. Ele atua como um túnel puro: valida webhooks, descriptografa payloads de WhatsApp Flows, roteia mensagens para os agentes downstream e expõe endpoints padronizados para envio de mensagens ativas.

O serviço opera de forma totalmente agnóstica a regras de negócio: não manipula carrinhos nem mantém FSMs, limitando-se a traduzir o protocolo da Meta e distribuí-lo com segurança na rede interna.


Papel na Plataforma

flowchart LR
    meta[Meta Cloud API] -->|Webhook público| wpp[WhatsApp Entrypoint]
    wpp -->|Dedup & Roteamento| redis[(Redis)]
    wpp -->|POST /api/v1/events/| b2c[Agente B2C]
    wpp -->|POST /api/v1/events/| b2b[Agente B2B]
    wpp <-->|POST /api/v1/flow-exchange/| b2c
    wpp <-->|POST /api/v1/flow-exchange/| b2b
    b2c -->|POST /send-*| wpp
    b2b -->|POST /send-*| wpp
    wpp -->|Graph API / HTTPS| meta

    style meta fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
    style wpp fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#0369a1
    style redis fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
    style b2c fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
    style b2b fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8

Limites de Responsabilidade

É responsabilidade do Entrypoint NÃO é responsabilidade do Entrypoint
Validar assinaturas HMAC-SHA256 (x-hub-signature-256) em todas as entradas. Processar FSM de conversa ou intenção semântica do cliente.
Deduplicação de eventos de mensagens repetidas pela Meta via Redis. Persistir dados de pedidos, catálogos ou clientes.
Criptografia RSA-OAEP e AES-GCM bidirecional para WhatsApp Flows. Decidir regras de frete, pagamento ou checkout.
Roteamento multi-tenant por phone_number_id (loja B2C vs número central B2B). Gerar cópias de copywriting ou prompts de IA.
Envio de mensagens unificadas (texto, botões, listas, templates, Flows). Armazenar histórico definitivo de pedidos.
Gerenciamento de ciclo de vida de Flows e templates na Meta Graph API.

Fluxo de Ingress e Deduplicação

A Meta exige confirmação HTTP rápida (tempo limite padrão de 15 segundos). Para evitar timeouts e processamento duplicado, o serviço processa em duas fases:

sequenceDiagram
    autonumber
    actor Meta as Meta Cloud API
    participant EP as WhatsApp Entrypoint
    participant Redis as Redis (Dedup)
    participant Downstream as Agente (B2C / B2B)

    Meta->>EP: POST /api/v1/webhook/ (HMAC assinado)
    EP->>EP: Valida X-Hub-Signature-256
    EP->>Redis: SET NX whatsapp:msg:{id} (TTL 24h)
    alt Chave já existia no Redis
        EP-->>Meta: 200 OK (Descarte idempotente)
    else Chave nova registrada
        EP-->>Meta: 200 OK (Confirmação imediata)
        EP-)Downstream: BackgroundTask: POST /api/v1/events/
    end
  1. Assinatura HMAC: Rejeita requisições forjadas ou sem assinatura correspondente ao META_APP_SECRET.
  2. Deduplicação Atômica: SET whatsapp:msg:{id} 1 NX EX 86400 no Redis. Se a chave já existir (retry da Meta), o evento é descartado com 200 OK.
  3. Resolução de Tenant: Identifica se o phone_number_id pertence a um lojista cadastrado (encaminha para o Agente B2C) ou ao número central da plataforma (encaminha para o Agente B2B).
  4. Despacho em Background: O handshake HTTP com a Meta fecha em < 50ms; o processamento pesado ocorre via BackgroundTasks.

Criptografia de WhatsApp Flows

Os WhatsApp Flows exigem cifragem ponta a ponta entre a Meta e o backend pelo endpoint /api/v1/webhook/flow/:

flowchart TD
    req[Payload Cifrado da Meta] --> rsa[Descriptografa chave AES com RSA Privada]
    rsa --> aes[Descriptografa payload JSON com AES-GCM]
    aes --> dispatch[POST /api/v1/flow-exchange/ para B2C ou B2B]
    dispatch --> resp[Recebe tela/dados da próxima etapa]
    resp --> cifrar[Cifra resposta com AES-GCM + IV novo]
    cifrar --> ret[Retorna payload criptografado para a Meta]

    style req fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
    style rsa fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
    style aes fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
    style dispatch fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
    style cifrar fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
    style ret fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b

Contratos de API

Webhooks da Meta

Método Rota Finalidade Autenticação
GET /api/v1/webhook/ Handshake de verificação do tenant central. hub.verify_token
GET /api/v1/webhook/{tenant_id}/ Handshake de verificação por lojista específico. hub.verify_token
POST /api/v1/webhook/ Recebe mensagens, status de entrega e carrinhos. X-Hub-Signature-256
POST /api/v1/webhook/flow/ Data Endpoint interativo de WhatsApp Flows. Criptografia RSA/AES

Envio de Mensagens (Consumidores Internos)

Todos os endpoints de envio exigem o cabeçalho X-Internal-Key com o valor de WPP_API_KEY:

Método Rota Descrição do Payload
POST /api/v1/send-messages/send-text Texto simples com número de destino e token do WhatsApp.
POST /api/v1/send-messages/send-buttons Mensagem interativa com até 3 botões de ação rápida.
POST /api/v1/send-messages/send-list Lista interativa estruturada em seções e linhas selecionáveis.
POST /api/v1/send-messages/send-flow Disparo de WhatsApp Flow nativo (ex: endereço B2C ou catálogo B2B).
POST /api/v1/send-messages/send-template Disparo de template HSM aprovado pela Meta.
POST /api/v1/send-messages/send-cta-url Botão interativo de redirecionamento para link externo de checkout.
POST /api/v1/send-messages/send-product-list Carrossel de catálogo nativo com produtos e variações.

Registry & Provisionamento

Método Rota Uso
POST /api/v1/registry/flows/create Pipeline completo de criação, upload de JSON e publicação de Flow.
POST /api/v1/registry/templates/create Submissão de novos templates para aprovação na Graph API.
POST /api/v1/onboarding/embedded-signup Conexão de WABA e número do lojista via Embedded Signup.

Configuração Essencial

Variável Descrição Crítica
WPP_API_KEY Chave de proteção das rotas internas de envio de mensagens. Sim
META_APP_SECRET Segredo do aplicativo Meta para validar assinaturas HMAC. Sim
META_VERIFY_TOKEN Token do handshake de verificação de webhooks. Sim
META_FLOW_PRIVATE_KEY Chave privada RSA (PEM) usada para abrir interações de Flows. Sim
META_FLOW_PRIVATE_KEY_PASSPHRASE Senha da chave privada RSA (se aplicável). Opcional
REDIS_URL Conexão para deduplicação atômica e cache temporário. Sim
PLATFORM_API_URL URL do serviço de dados para resolver lojistas por phone_number_id. Sim
B2C_URL Endereço interno do container do Agente B2C. Sim
B2B_URL Endereço interno do container do Agente B2B. Sim

Diagnóstico Rápido

  1. A Meta acusa erro de webhook: Verifique se o META_APP_SECRET confere exatamente com o painel de desenvolvedores da Meta. Assinaturas inválidas geram log HMAC signature verification failed e resposta 401.
  2. Mensagens duplicadas sendo processadas: Inspecione a conectividade com o Redis. Se o Redis estiver indisponível, o serviço falha em modo aberto (processa sem dedup) para não perder vendas, gerando log de alerta.
  3. Falhas de tela em WhatsApp Flows: Verifique se a chave pública registrada na Meta corresponde à chave privada configurada em META_FLOW_PRIVATE_KEY. Erros de descriptografia quebram o Flow imediatamente no cliente.
  4. Mensagens downstream não entregues: Verifique se o phone_number_id recebido no webhook existe no platform_api. Números não mapeados são registrados como Inbound webhook for unknown phone_number_id e ignorados.