# WhatsApp Commerce Suite Shopware — Guía de instalación y configuración

> Requisitos Shopware 6.5, 6.6 o 6.7 (un solo código), PHP 8.1 mínimo Una cuenta WhatsApp Business con un número verificado en Meta Business Suite Una app de Meta de tipo…

- Página: <https://www.datafirefly.com/es/documentation/dfwhatsappcommerce-shopware/>
- Idioma: es
- Actualizado el: 2026-08-06
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/dfwhatsappcommerce-shopware/index.md), [en](https://www.datafirefly.com/en/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), [pt](https://www.datafirefly.com/pt/documentation/dfwhatsappcommerce-shopware/index.md)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

## Requisitos

- Shopware 6.5, 6.6 o 6.7 (un solo código), PHP 8.1 mínimo
- Una cuenta **WhatsApp Business** con un número verificado en Meta Business Suite
- Una app de Meta de tipo **Business** con el producto WhatsApp activado
- El worker de colas y el runner de tareas programadas de Shopware activos (`messenger:consume` y `scheduled-task:run`)

## Instalación

1. Copie la carpeta `DfWhatsAppCommerce` en `custom/plugins/` (o suba el zip vía Extensiones → Mis extensiones).
2. Instale y active: ``` bin/console plugin:refresh bin/console plugin:install --activate DfWhatsAppCommerce bin/console cache:clear ```
3. Compile la administración y el storefront: ``` bin/build-administration.sh bin/build-storefront.sh ```

La instalación crea 5 tablas dedicadas con prefijo `df_wac_` y 2 tareas programadas (recordatorios de carrito cada 15 min, lote de catálogo cada hora). Todo se elimina limpiamente al desinstalar, salvo que marque «conservar los datos».

## Configuración de la Meta Cloud API

### 1. Obtener las credenciales

En [developers.facebook.com](https://developers.facebook.com), cree una app Business y añada el producto WhatsApp. Obtenga: el **token permanente** (usuario de sistema con permisos `whatsapp_business_messaging` y `catalog_management`), el **Phone number ID**, el **WABA ID** y el **App secret** (Configuración de la app → Básica).

### 2. Crear el catálogo

En Meta Commerce Manager, cree un catálogo y conéctelo a su cuenta WhatsApp Business. Anote el **ID del catálogo**.

### 3. Configurar el webhook

En la app de Meta → WhatsApp → Configuración:

- URL de devolución de llamada: `https://sutienda.tld/df-wac/webhook`
- Token de verificación: el valor que introduzca en la configuración del plugin (campo «Webhook verify token»)
- Suscríbase al campo `messages`

Introduzca el **App secret** en la configuración del plugin: sin él, la firma `X-Hub-Signature-256` de los webhooks no se valida.

### 4. Introducir la configuración en Shopware

Configuración → Sistema → Plugins → DataFirefly WhatsApp Commerce Suite. Rellene la tarjeta «API Meta Cloud» y pruebe desde el panel (Marketing → WhatsApp Commerce): botón **Probar conexión API** y envío de un mensaje de prueba.

## Los 4 módulos

### Catálogo Meta

Tres modos: tiempo real (con cada guardado de producto), lote horario, o manual. Las variantes se envían individualmente con el `retailer_id` `sw_{número de artículo}`. Excluya categorías si es necesario. La resincronización completa (lotes de 100) se lanza desde el panel.

### Pedidos conversacionales

Máquina de estados de 6 niveles. Palabras clave reconocidas (FR/EN/DE): `menu`, `cart`, `pay`, `human`, `reset`, `help`. El idioma del cliente se detecta automáticamente. La transferencia humana envía un correo a la dirección configurada con el enlace de la conversación.

### Recuperación de carritos abandonados

3 recordatorios configurables (60 min, 24 h, 72 h por defecto) enviados por la tarea programada cada 15 minutos, a los clientes cuyo teléfono de facturación se conoce. El código promocional introducido en la configuración se adjunta al 3.er recordatorio y se aplica automáticamente al carrito restaurado.

Haga obligatorio el campo teléfono en Configuración → Tienda → Inicio de sesión / registro para maximizar la cobertura de los recordatorios.

### Enlace de pago firmado y notificaciones

Los enlaces de checkout y de recuperación de carrito están firmados HMAC SHA-256 con caducidad configurable (72 h por defecto). Notificaciones automáticas: confirmación de pedido, envío (con número de seguimiento), fallo de pago.

## Plantillas HSM a crear en Meta Business Suite

| Plantilla | Variables del cuerpo | Botón |
| --- | --- | --- |
| Recordatorio 1 y 2 | {{1}} nombre del cliente, {{2}} total del carrito | URL dinámica (sufijo = token) |
| Recordatorio 3 | {{1}} nombre, {{2}} total, {{3}} código promocional | URL dinámica (sufijo = token) |
| Confirmación | {{1}} nombre, {{2}} nº de pedido, {{3}} total | — |
| Envío | {{1}} nombre, {{2}} nº de pedido, {{3}} nº de seguimiento | CTA de seguimiento (opcional) |
| Fallo de pago | {{1}} nombre, {{2}} nº de pedido | CTA de reintento (opcional) |

Para los recordatorios, el botón URL de la plantilla debe tener como base `https://sutienda.tld/df-wac/cart/restore?token=` con sufijo dinámico `{{1}}`. Introduzca los nombres de las plantillas aprobadas en la configuración del plugin.

## Administración

Marketing → WhatsApp Commerce: panel de KPI (conversaciones, no leídos, carritos, tasa de recuperación, errores), página **Conversaciones** (hilo estilo WhatsApp Web, respuesta directa), **Carritos abandonados**, **Catálogo** (registro de sincronización) y **Registros** (filtros por nivel/canal).

Regla de Meta: las respuestas libres desde el admin solo se entregan dentro de las 24 h siguientes al último mensaje del cliente. Más allá, utilice una plantilla HSM.

## Solución de problemas

- **No aparece nada en el frontal**: compruebe que el «Número de WhatsApp público» está configurado (el botón flotante y los CTA dependen de él), luego `bin/console cache:clear`.
- **Webhook 403**: token de verificación distinto entre Meta y el plugin, o App secret erróneo.
- **Recordatorios no enviados**: compruebe que `scheduled-task:run` y `messenger:consume` están en marcha, que el módulo está activo y que las plantillas HSM están aprobadas.
- **Productos no sincronizados**: consulte la página Catálogo (estados pending/synced/error) y los Registros, canal `catalog`.

## RGPD

No se envía ningún dato a terceros fuera de la Meta WhatsApp Cloud API. Las conversaciones y los números se almacenan localmente en las tablas `df_wac_` y se eliminan al desinstalar.