Pular para o conteúdo principal

Feature - Envio de Template de Flow

Introdução ao documento​

Este documento cobre o envio de template WhatsApp com botão FLOW pelo endpoint /sendtemplate. Evidência: src/routes/sendTemplate.ts:8

Versionamento​

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

Referencial teórico​

  • Handler HTTP de envio (sendTemplate.ts).
  • Cliente Meta Graph API (sendFlowTemplate.ts). Evidência: src/routes/sendTemplate.ts:1 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:1

Visão geral​

A feature recebe parâmetros de template/flow e dispara mensagem WhatsApp com componente FLOW para iniciar o onboarding no cliente. Evidência: src/routes/sendTemplate.ts:9 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:43 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:50

Atores​

  • Serviço interno chamador com token de serviço.
  • API WhatsApp Cloud da Meta.
  • Usuário destinatário da mensagem. Evidência: src/routes/sendTemplate.ts:8 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:10 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:14

Pré-condições​

  • Authorization válido (middleware verifyServiceToken).
  • Campos obrigatórios: phone, flow_token, template_id, name, image_url.
  • WHATSAPP_API_TOKEN e WHATSAPP_PHONE_ID configurados. Evidência: src/routes/sendTemplate.ts:8 Evidência: src/routes/sendTemplate.ts:11 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:2 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:4

Fluxo principal​

  1. Receber POST /sendtemplate.
  2. Validar campos obrigatórios.
  3. Montar payload de template com header image, body com primeiro nome e botão FLOW.
  4. Enviar para Graph API.
  5. Retornar 201 quando ok=true. Evidência: src/routes/sendTemplate.ts:8 Evidência: src/routes/sendTemplate.ts:11 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:22 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:34 Evidência: src/routes/sendTemplate.ts:17

Fluxos alternativos​

  • Campos faltando: 400.
  • Falha de autenticação de serviço: 401/403.
  • Erro na Graph API: 500. Evidência: src/routes/sendTemplate.ts:12 Evidência: src/auth/serviceToken.ts:22 Evidência: src/auth/serviceToken.ts:30 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:74

Regras de negócio​

  • O primeiro nome é derivado por name.split(" ")[0] no payload.
  • O template usa idioma fixo pt_BR.
  • O componente de botão é do subtipo FLOW com flow_token informado. Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:38 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:19 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:44

Estados possíveis (quando houver)​

  • Enviado com sucesso (201, ok=true).
  • Rejeitado por validação (400).
  • Falha operacional (500, ok=false ou exceção). Evidência: src/routes/sendTemplate.ts:17 Evidência: src/routes/sendTemplate.ts:12 Evidência: src/routes/sendTemplate.ts:19

Endpoints envolvidos​

Dados impactados​

  • Não há persistência local de dados nesta feature.
  • Referência de dados locais: ../data/model.md. Evidência: src/routes/sendTemplate.ts:8 Evidência: src/models/otp.ts:18

Pendências​

  • Confirmar estratégia de retry para falhas de envio (atualmente sem fila dedicada para este endpoint). Evidência: src/routes/sendTemplate.ts:16 Evidência: src/services/groupLinkDispatchQueue.ts:24