# WhatsApp Commerce Suite Shopware: guia de instalação e configuração
> Pré-requisitos Shopware 6.5, 6.6 ou 6.7 (base de código única), PHP 8.1 no mínimo Uma conta WhatsApp Business com um número verificado no Meta Business Suite Uma app Meta do…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfwhatsappcommerce-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/dfwhatsappcommerce-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsappcommerce-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/dfwhatsappcommerce-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/dfwhatsappcommerce-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwhatsappcommerce-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsappcommerce-shopware/index.md)
- Índice:
## Pré-requisitos
- Shopware 6.5, 6.6 ou 6.7 (base de código única), PHP 8.1 no mínimo
- Uma conta **WhatsApp Business** com um número verificado no Meta Business Suite
- Uma app Meta do tipo **Business** com o produto WhatsApp ativado
- O worker da fila de mensagens e o runner de tarefas agendadas do Shopware ativos (`messenger:consume` e `scheduled-task:run`)
## Instalação
1. Copie a pasta `DfWhatsAppCommerce` para `custom/plugins/` (ou carregue o zip em Extensões → As minhas extensões).
2. Instale e ative: ``` bin/console plugin:refresh bin/console plugin:install --activate DfWhatsAppCommerce bin/console cache:clear ```
3. Compile a administração e o storefront: ``` bin/build-administration.sh bin/build-storefront.sh ```
A instalação cria 5 tabelas dedicadas com o prefixo `df_wac_` e 2 tarefas agendadas (recuperação de carrinho a cada 15 min, lote de catálogo de hora a hora). Tudo é eliminado corretamente na desinstalação, exceto se marcar «conservar os dados».
## Configuração da Meta Cloud API
### 1. Obter as credenciais
Em [developers.facebook.com](https://developers.facebook.com), crie uma app Business e acrescente o produto WhatsApp. Obtenha: o **token permanente** (utilizador de sistema com as permissões `whatsapp_business_messaging` e `catalog_management`), o **Phone number ID**, o **WABA ID** e o **App secret** (Definições da app → Geral).
### 2. Criar o catálogo
No Meta Commerce Manager, crie um catálogo e ligue-o à sua conta WhatsApp Business. Anote o **ID do catálogo**.
### 3. Configurar o webhook
Na app Meta → WhatsApp → Configuração:
- URL de callback: `https://asualoja.tld/df-wac/webhook`
- Token de verificação: o valor que introduz na configuração da extensão (campo «Webhook verify token»)
- Subscreva o campo `messages`
Preencha o **App secret** na configuração da extensão: sem ele, a assinatura `X-Hub-Signature-256` dos webhooks não é validada.
### 4. Introduzir a configuração no Shopware
Definições → Sistema → Extensões → DataFirefly WhatsApp Commerce Suite. Preencha o cartão «API Meta Cloud» e teste a partir do painel (Marketing → WhatsApp Commerce): botão **Testar a ligação à API** e envio de uma mensagem de teste.
## Os 4 módulos
### Catálogo Meta
Três modos: tempo real (a cada gravação de produto), lote de hora a hora, ou manual. As variantes são enviadas individualmente com o `retailer_id` `sw_{número de artigo}`. Exclua categorias se for necessário. A ressincronização completa (lotes de 100) lança-se a partir do painel.
### Encomenda conversacional
Máquina de estados de 6 níveis. Palavras-chave reconhecidas (FR/EN/DE): `menu`, `panier`, `payer`, `humain`, `reset`, `aide`. O idioma do cliente é detetado automaticamente. A transferência para um humano envia um email ao endereço configurado com a ligação para a conversa.
### Recuperação de carrinho abandonado
3 mensagens configuráveis (60 min, 24 h, 72 h por predefinição) enviadas pela tarefa agendada a cada 15 minutos, aos clientes cujo telefone de facturação é conhecido. O código promocional introduzido na configuração é anexado à 3.ª mensagem e aplicado automaticamente ao carrinho restaurado.
Torne o campo de telefone obrigatório em Definições → Loja → Início de sessão / registo para maximizar a cobertura das mensagens de recuperação.
### Ligação de pagamento assinada e notificações
As ligações de checkout e de recuperação de carrinho são assinadas com HMAC SHA-256 e têm expiração configurável (72 h por predefinição). Notificações automáticas: confirmação de encomenda, expedição (com n.º de seguimento), falha de pagamento.
## Templates HSM a criar no Meta Business Suite
| Template | Variáveis do corpo | Botão |
| --- | --- | --- |
| Mensagem 1 e 2 | {{1}} nome do cliente, {{2}} total do carrinho | URL dinâmico (sufixo = token) |
| Mensagem 3 | {{1}} nome, {{2}} total, {{3}} código promocional | URL dinâmico (sufixo = token) |
| Confirmação | {{1}} nome, {{2}} n.º de encomenda, {{3}} total | — |
| Expedição | {{1}} nome, {{2}} n.º de encomenda, {{3}} n.º de seguimento | CTA de seguimento (opcional) |
| Falha de pagamento | {{1}} nome, {{2}} n.º de encomenda | CTA de nova tentativa (opcional) |
Para as mensagens de recuperação, o botão de URL do template tem de ter como base `https://asualoja.tld/df-wac/cart/restore?token=` com o sufixo dinâmico `{{1}}`. Introduza os nomes dos templates aprovados na configuração da extensão.
## Administração
Marketing → WhatsApp Commerce: painel de KPI (conversas, não lidas, carrinhos, taxa de recuperação, erros), página **Conversas** (fio ao estilo do WhatsApp Web, resposta direta), **Carrinhos abandonados**, **Catálogo** (registo de sincronização) e **Registos** (filtros por nível e canal).
Regra da Meta: as respostas livres a partir da administração só são entregues nas 24 h seguintes à última mensagem do cliente. Depois disso, use um template HSM.
## Resolução de problemas
- **Não aparece nada no frontend**: verifique que o «Número WhatsApp público» está preenchido (o botão flutuante e os CTA dependem dele), e depois `bin/console cache:clear`.
- **Webhook 403**: token de verificação diferente entre a Meta e a extensão, ou App secret errado.
- **Mensagens de recuperação não enviadas**: verifique que o `scheduled-task:run` e o `messenger:consume` estão a correr, que o módulo está ativo e que os templates HSM estão aprovados.
- **Produtos não sincronizados**: consulte a página Catálogo (estados pending/synced/error) e os Registos, canal `catalog`.
## RGPD
Nenhum dado é enviado a terceiros fora da Meta WhatsApp Cloud API. As conversas e os números são guardados localmente nas tabelas `df_wac_` e eliminados na desinstalação.