Integración con Shopify

Conecta tu tienda Shopify a IncentIA para que cada pedido cree automáticamente un miembro (si no existe) y sume puntos según las reglas de tu programa.

Caso: ecommerce que quiere premiar a sus clientes con puntos por cada compra, sin desarrollo a medida.

Tiempo: ~15 min · Nivel: intermedio (necesitas acceso admin en Shopify).

Requisitos previos

• Un programa de fidelización ya creado en IncentIA con al menos una earning rule tipo OnPurchase (ver tutorial de puntos).
• Acceso admin a la tienda Shopify.
• URL pública de IncentIA accesible desde internet.

1. Crear la integración en IncentIA

1. Admin → Integraciones → Nueva → tipo Shopify.
2. Nombre: Mi tienda Shopify.
3. Al guardar, IncentIA genera:
   • Webhook URL: https://tu-dominio.app/api/webhooks/shopify/{integrationId}
   • Secret HMAC: cadena aleatoria que Shopify usará para firmar los webhooks.
4. Copia ambos valores.

2. Mapear campos

En la pestaña Mapping dentro de la integración:

Campo Shopify	Campo IncentIA	Obligatorio
email	Member.Email	sí
total_price	importe de la compra	sí
customer.first_name	Member.FirstName	no
customer.last_name	Member.LastName	no
customer.phone	Member.Phone	no
order_number	Transaction.ExternalId	no (para dedup)
line_items	detalle (opcional)	no

El mapping determina qué data llega a IncentIA y cómo se transforma en Member y Transaction.

3. Configurar auto-registro de miembros

Opciones:

• Auto-crear si no existe → el primer pedido del cliente lo registra automáticamente en el programa (sin OTP ni registro manual).
• Match por email existente → si el email ya existe en Members, se asocia la compra; si no, se ignora.

Para un onboarding fluido, Auto-crear suele ser lo mejor.

4. Configurar el webhook en Shopify

En tu admin de Shopify:

1. Settings → Notifications → sección Webhooks.
2. Create webhook:
   • Event: Order paid
   • Format: JSON
   • URL: la URL de IncentIA del paso 1.
3. Guarda.

(Opcional) Añade también Customer updated si quieres sincronizar cambios de perfil.

5. Configurar la firma HMAC

Shopify firma cada webhook. En IncentIA, la integración verifica la firma con el secret del paso 1.

Si el secret es diferente, los webhooks llegarán pero se rechazarán con 401. Revisa logs en Admin → Integraciones → {tu integración} → pestaña Logs.

6. Probar con un pedido real (o sandbox)

1. Crea un pedido de prueba en Shopify (o usa la tienda de desarrollo).
2. Al pagar, Shopify envía el webhook.
3. En IncentIA → Integraciones → Logs: ves la entrada con status 200 y el resumen.
4. Admin → Miembros: el cliente aparece (si era nuevo).
5. Admin → Transacciones: la transacción está registrada.
6. El miembro tiene puntos según tus earning rules.

7. Notificación al miembro

Si el cliente es nuevo, suele ser buena idea enviarle:

• Email de bienvenida al programa (plantilla welcome_email + trigger en flujo).
• Incluir link a su portal para ver puntos: https://tu-dominio.app/member.

Los existentes reciben solo la notificación "has ganado X puntos" si tu configuración lo permite.

8. Reprocessar pedidos antiguos (opcional)

Si quieres importar históricos:

1. Exporta de Shopify los pedidos pagados del último año.
2. Admin → Integraciones → Reprocess → sube el JSON.
3. IncentIA ingesta cada pedido como si llegara ahora (con flag is_backfill para no enviar emails).

Problemas comunes

Síntoma	Causa	Solución
Webhooks llegan pero status 401	Secret HMAC mal copiado	Reset desde Shopify, actualiza en IncentIA
Miembros duplicados	Mismo email en varias tiendas	Activa MatchByEmail y desactiva Auto-crear
Puntos duplicados	Pedido llegado 2 veces (Shopify reintenta)	Activa dedup por ExternalId en mapping
No se crea miembro	Email vacío en Shopify	El webhook se rechaza (email es obligatorio)

Qué has construido

• Shopify envía webhook a IncentIA en cada pedido pagado.
• IncentIA crea miembros automáticamente en el programa.
• Puntos se acumulan según earning rules existentes.
• Historial de transacciones sincronizado.

Próximos pasos

• Integra también WooCommerce o Stripe con el mismo patrón.
• Configura un flujo de comunicaciones para mail post-compra → tutorial comunicaciones.
• Lanza una campaña de cashback que exija evidencia de Shopify para dar un extra → tutorial cashback.