Pular para o conteúdo principal

Feature - Callback Criptografado do WhatsApp Flow

Introdução ao documento​

Este documento descreve a feature responsável por receber, validar e responder requisições criptografadas do WhatsApp Flow no endpoint POST /. Evidência: src/server.ts:102

Versionamento​

  • Versão do documento: 2.0.0.
  • Última atualização: 2026-03-18. Evidência: codex-promts.md:16

Referencial teórico​

  • Implementação de decrypt/encrypt no módulo encryption.ts.
  • Fluxo de roteamento para personal e business. Evidência: src/encryption.ts:3 Evidência: src/server.ts:331

Visão geral​

O endpoint recebe encrypted_aes_key, encrypted_flow_data e initial_vector, valida assinatura (quando aplicável), decripta payload, executa a lógica da tela e devolve payload criptografado. Evidência: src/server.ts:114 Evidência: src/server.ts:128 Evidência: src/server.ts:155 Evidência: src/server.ts:159

Atores​

  • Cliente WhatsApp Flow (origina payload criptografado).
  • Serviço dhedalos-api-onboarding-express (processa e responde). Evidência: src/server.ts:102

Pré-condições​

  • PRIVATE_KEY e PASSPHRASE válidos no ambiente.
  • req.body com os três campos criptografados obrigatórios.
  • Se APP_SECRET estiver definido, header x-hub-signature-256 válido. Evidência: src/server.ts:100 Evidência: src/server.ts:103 Evidência: src/server.ts:116 Evidência: src/server.ts:341

Fluxo principal​

  1. Receber POST /.
  2. Validar campos obrigatórios do corpo.
  3. Validar assinatura HMAC quando configurada.
  4. Decriptar payload com chave RSA + AES.
  5. Processar tela no fluxo personal ou business.
  6. Criptografar e retornar resposta. Evidência: src/server.ts:102 Evidência: src/server.ts:116 Evidência: src/server.ts:128 Evidência: src/server.ts:142 Evidência: src/server.ts:333 Evidência: src/server.ts:159

Fluxos alternativos​

  • action === ping: responde status: active.
  • data.error: responde acknowledged: true.
  • flow_token inválido: retorna tela ERROR.
  • Assinatura inválida: retorna 432 sem corpo.
  • Erro de decrypt: retorna 421 (FlowEndpointException) ou 500. Evidência: src/server.ts:292 Evidência: src/server.ts:302 Evidência: src/server.ts:314 Evidência: src/server.ts:131 Evidência: src/encryption.ts:45

Regras de negócio​

  • Requisição incompleta é rejeitada com 400.
  • Assinatura só é exigida quando APP_SECRET existe; sem segredo, a validação retorna true.
  • flow_token precisa ter formato <course_slug>_<user_id>.
  • Contexto de fluxo é derivado de courseDetail.flow_template_id. Evidência: src/server.ts:116 Evidência: src/server.ts:341 Evidência: src/utils/flowSession.ts:7 Evidência: src/server.ts:327

Estados possíveis (quando houver)​

  • Ação de protocolo: ping, INIT, data_exchange.
  • Resultado de erro: ERROR.
  • Resultado final de fluxo: FINAL (definido nos fluxos internos). Evidência: src/server.ts:292 Evidência: src/flows/personal.ts:61 Evidência: src/flows/business.ts:154 Evidência: src/server.ts:317 Evidência: src/flows/personal.ts:220

Endpoints envolvidos​

  • POST / Evidência: src/server.ts:102

Dados impactados​

  • Sem escrita direta local neste endpoint; impacto de dados ocorre indiretamente pelos fluxos (wpPatchProfile, enrollToCourse, fila de link de grupo).
  • Referência de dados locais: ../data/model.md. Evidência: src/flows/personal.ts:134 Evidência: src/flows/business.ts:342 Evidência: src/flows/personal.ts:207

Pendências​

  • Confirmar contrato oficial de payload de decryptedBody para documentação de schema completo de telas. Evidência: src/server.ts:288 Evidência: src/flows/personal.ts:58 Evidência: src/flows/business.ts:138