Inicio rápido (5 min)
- Instala desde la Shopify App Store → busca "Flowgration" → Añadir app. Shopify te guía por la pantalla de consentimiento OAuth.
- Tras la instalación, la app embebida se abre en Apps → Flowgration dentro del admin de Shopify.
- Elige una opción:
- Ya tengo una cuenta en Flowgration → pega una clave API desde Ajustes → Claves API (debe empezar por sk_live_).
- Todavía no tengo cuenta → haz clic en Incorporación automática. La app envía un enlace mágico al email del propietario principal de la tienda.
- Haz clic en el enlace mágico. Flowgration crea la organización, el usuario y el CRM inicial y te devuelve a la app embebida.
- El panel de la tienda se pone verde y los webhooks empiezan a fluir en ~10 segundos.
Dos formas de conectar
Flujo A — cuenta existente
Shopify (embedded app) Flowgration
│ │
│ POST /onboarding/initiate (mode=connect, api_key=sk_live_…)
├─────────────────────────────►│
│ │ verify key → upsert PluginIntegration
│ ◄────────────────────────────┤ 200 { review_url, suggested_mappings }
│
│ redirect to /app/integrations?integration_id=…- Genera una clave API en Flowgration.
- Pégala en el panel «Conectar cuenta existente» de la app embebida.
- La app hace POST a /api/plugin/onboarding/initiate con mode=connect, platform=shopify, store.url=<myshop>.myshopify.com.
- Flowgration actualiza la fila PluginIntegration y devuelve una URL para revisar los mapeos.
Flujo B — automático (enlace mágico)
Shopify Flowgration Store owner inbox
│ │ │
│ POST /onboarding/initiate (mode=auto) │
├────────────────────►│ │
│ │ create PluginOnboarding │
│ ├──── magic-link email ─────►│
│ │ │
│ │ ◄── owner clicks link ─────┤
│ │ materialize_crm
│ │ 302 → /plugin-callback- La app analiza la tienda (recuentos, divisa, dominio principal, temas).
- Envía el payload de descubrimiento más el email del propietario a /onboarding/initiate.
- El propietario hace clic en el enlace de un solo uso (TTL 24h).
- Flowgration crea la organización + usuario + CRM, genera una clave API y redirige a /plugin-callback.
- La app embebida consulta /onboarding/blueprint?token=… y muestra la pantalla de carga mientras el CRM se materializa.
Compatibilidad
- Shopify Admin API Shopify Admin API versión 2024-10 (rota trimestralmente; la app actualiza la versión con cada ventana de lanzamiento de Shopify).
- App embebida — se ejecuta dentro del iframe del admin de Shopify. UI de Polaris para coherencia visual.
- App Bridge App Bridge v4 para navegación, notificaciones y selectores de recursos.
- Niveles de plan — funciona en Basic Shopify o superior. Las funciones de Shopify Plus (multi-tienda, operaciones masivas con GraphQL) aún no están expuestas; el backfill sigue funcionando via REST.
Qué se sincroniza
| Evento | Topic | Cuándo se dispara | Qué hace Flowgration |
|---|---|---|---|
order.created | orders/create | Se realiza un nuevo pedido (cualquier estado) | Crea el Pedido + líneas de pedido, vincula al Contacto |
order.updated | orders/updated | Pedido editado | Actualiza el Pedido; el diff se escribe en el registro de Actividad |
order.cancelled | orders/cancelled | Pedido cancelado | Marca el Pedido como cancelado, dispara el trigger del journey |
order.fulfilled | orders/fulfilled | Envío creado | Marca el Pedido como enviado, dispara el trigger del journey |
customer.created | customers/create | Nuevo registro de cliente | Crea el Contacto con los campos mapeados |
customer.updated | customers/update | Cliente editado | Actualiza el Contacto |
product.created | products/create | Nuevo producto publicado | Espeja el producto en el catálogo de Flowgration |
product.updated | products/update | Producto editado | Actualiza la fila del catálogo |
product.deleted | products/delete | Producto eliminado | Elimina la fila del catálogo de forma lógica |
cart.abandoned | checkouts/update | Checkout abandonado ≥30 min, email conocido | Dispara el trigger cart.abandoned para los journeys |
Cada payload de webhook tiene clave de idempotencia mediante X-Shopify-Webhook-Id, por lo que los reintentos de Shopify (que pueden repetirse durante 48h) se deduplicarán.
Descubrimiento
En la primera conexión, Flowgration llama a la API REST de Shopify para leer metadatos no identificables:
- Recuentos — orders.count, customers.count, products.count, abandoned_checkouts.count.
- Divisa — divisa base de la tienda desde /shop.json.
- Temas — nombre y versión del tema activo.
- Dominio principal — se usa como identificador de la tienda en PluginIntegration.
En este paso no se leen datos de clientes, pedidos ni productos — llegan más tarde mediante webhooks (y el backfill opcional).
Backfill
La página de integración tiene un botón Backfill por objeto (Pedidos, Clientes, Productos). Este botón:
- Usa la paginación REST de Shopify (250 por página, tamaño máximo de página).
- Envía cada página por el mismo pipeline /sync que los webhooks en vivo.
- Guarda el cursor en el servidor; si se interrumpe, reanuda desde el último cursor al volver a hacer clic.
- Deduplica contra PluginEventLog, por lo que volver a ejecutarlo es seguro.
Rendimiento típico: ~2 000 registros/minuto dentro del límite de velocidad REST de Shopify (40 llamadas en ráfaga, 2/s sostenido).
Webhooks obligatorios del RGPD
Shopify exige que toda app pública implemente tres webhooks. Se configuran en shopify.app.toml y se registran automáticamente al instalar.
| Webhook | Disparador | Qué hace Flowgration |
|---|---|---|
customers/data_request | El cliente solicita sus datos | Pone en cola un trabajo; envía al comerciante por email una exportación JSON de todos los Contactos + Pedidos + Actividades vinculados al email del cliente en los últimos 30 días. |
customers/redact | El cliente solicita la supresión (30 días de gracia) | Borra los datos personales (first_name, last_name, email, phone, street, city, country, postal_code, job_title, company_name, notes) del Contacto correspondiente. Conserva la fila para que los Pedidos/Actividades que la referencian no se rompan. |
shop/redact | Tienda desinstalada (48h de gracia) | Borra toda la PluginIntegration, revoca la clave API y aplica una supresión al estilo customers/redact en todos los Contactos originados en esta tienda. |
Los tres devuelven HTTP 200 dentro de la ventana de 5 segundos impuesta por Shopify al poner el trabajo en cola y procesarlo en un worker.
Permisos requeridos
Estos son los permisos que la app solicita al instalar (desde shopify.app.toml):
| Permiso | Para qué |
|---|---|
read_orders | Leer datos de pedidos para la sincronización en vivo y el backfill |
read_customers | Leer perfiles de clientes para crear Contactos |
write_customers | Opcional. Se usa cuando el comerciante concede data_write para que Flowgration pueda enviar actualizaciones de etiquetas/segmentos de vuelta a los clientes de Shopify |
read_products | Espejo del catálogo de productos |
read_checkouts | Detectar checkouts abandonados |
read_inventory | Mostrar niveles de stock en la vista de productos de Flowgration |
read_fulfillments | Seguimiento del estado de envío de pedidos |
read_shipping | Mapear las direcciones de envío a los campos de dirección del Contacto |
read_locales | Establecer el idioma del Contacto a partir del locale del pedido |
read_marketing_events | Atribuir pedidos a las campañas de Flowgration |
La app no solicita write_orders, write_products ni ningún permiso financiero. Los reembolsos y las ediciones de pedidos permanecen en Shopify.
Solución de problemas
1. La app falla al instalar
- La pantalla OAuth de Shopify mostraba casillas de permisos que el comerciante desmarcó. Abre Partner Dashboard → Configuración de la app → Permisos y compara con la lista anterior.
- Vuelve a instalar con todos los permisos concedidos.
2. Los webhooks no se disparan
- Un evento app/scopes_update anterior revocó un permiso del que depende el webhook. Comprueba la columna lastScopes en la fila PluginIntegration.
- Vuelve a conceder los permisos desde /admin/apps/flowgration/grant.
- Confirma el estado de los webhooks en Shopify: Ajustes → Notificaciones → Webhooks. Los envíos fallidos son visibles allí.
3. Los pedidos muestran «cliente no encontrado»
- Los checkouts como invitado no tienen registro Customer en Shopify. Flowgration recurre a order.customer.email (o order.email) y crea un Contacto con esa dirección.
- Si ambos están ausentes, el pedido se descarta con una advertencia en PluginEventLog. Esto ocurre cuando un comerciante desactiva «requerir email en el checkout» — lo recomendamos evitar.
4. Tiendas multi-divisa
- El campo currency del payload del webhook se reenvía tal cual. La fila de Pedido guarda la divisa original.
- La capa de informes de Flowgration convierte a la divisa base de la organización usando tipos de cambio diarios de openexchangerates.org. Los informes muestran ambos valores.
- Los tipos de cambio por pedido no se guardan en el momento de escritura — si necesitas tipos puntuales, activa FX de auditoría en Ajustes → Divisas (plan Business).
5. La app tarda en crear pedidos
- Los webhooks se procesan con el patrón enqueue-then-forward: el gestor HTTP devuelve 200 en <5 s tras escribir en la cola de trabajos. Shopify nunca espera a tu CRM.
- Si el log de webhooks de Shopify muestra tiempos de respuesta elevados desde Flowgration, consulta https://status.flowgration.com.
6. Banner «La app ya no está instalada» dentro del admin de Shopify
- El token de sesión de la tienda expiró (Shopify los rota de forma agresiva). Vuelve a abrir la app desde Apps → Flowgration; App Bridge actualizará el token automáticamente.
- Si el banner persiste, desinstala y reinstala. La reinstalación es idempotente — se reutiliza la misma fila PluginIntegration.
7. Los eventos de carrito abandonado no se disparan
- Shopify solo envía checkouts/update si el cliente introdujo una dirección de email en el checkout. Los carritos de invitados sin email son invisibles para las apps.
- El umbral de 30 minutos lo aplica el worker de Flowgration en el cliente, no Shopify. Si ves eventos dispararse para carritos de menos de 30 min, es otra app de carrito abandonado.
8. Contactos duplicados tras reinstalar
- La tienda se desinstaló, se ejecutó el trabajo customers/redact y luego la app se reinstalió al día siguiente. El redact borró los emails de los Contactos → la nueva sincronización crea registros nuevos porque la deduplicación es por email.
- Usa Ajustes → Duplicados en Flowgration para fusionarlos. O reinstala dentro de la ventana de gracia de 48h de shop/redact — el trabajo de redact todavía no habrá ejecutado.
9. Plus / multi-tienda — eventos de la tienda B aparecen bajo la tienda A
- Cada tienda debe conectarse con su propia clave API. Reutilizar una clave en varias tiendas en mode=connect está soportado pero es experimental.
- La fila PluginIntegration tiene clave por (organization_id, platform, store_url), por lo que distintos dominios <shop>.myshopify.com se enrutan correctamente aunque compartan clave. Mismo dominio = misma fila.
10. La app lanza «HMAC mismatch» en cada webhook
- Shopify rotó el secreto compartido. Esto ocurre automáticamente al reinstalar la app. Flowgration regenera su copia en el siguiente callback de autenticación exitoso.
- Si persiste, rota el secreto manualmente en Partner Dashboard y haz clic en Ajustes → Actualizar secreto en la app embebida.
Privacidad y datos
Qué sale de tu tienda
- Solo los eventos indicados en Qué se sincroniza, más los campos de cliente y pedido cubiertos por los permisos concedidos.
- Sin datos de tarjeta en bruto (Shopify nunca los envía).
- Sin imágenes ni archivos de tema.
Dónde van
Frankfurt, EU (AWS eu-central-1). Fráncfort, UE (AWS eu-central-1). Los datos nunca salen de la UE en operación normal.
Retención
- Los eventos de webhook viven en PluginEventLog durante 90 días y después se agregan.
- Los datos de Contacto y Pedido persisten hasta que desinstales la app o el comerciante elimine el contacto.
- customers/redact borra los datos personales de inmediato; los análisis agregados conservan contadores anónimos.
Desinstalar
Desde Shopify
Apps → Flowgration → Desinstalar. Shopify revoca el token OAuth, dispara app/uninstalled y (tras 48h) dispara shop/redact.
Qué se limpia
- En Flowgration (lado Prisma): la fila PluginIntegration pasa a disconnected; se revoca la clave API. Los datos sincronizados se conservan hasta que llega shop/redact, momento en que se borran todos los Contactos y los datos personales relacionados originados en esta tienda.
- En Shopify (lado del servidor): se eliminan todas las suscripciones de webhooks. Los registros de clientes/pedidos del comerciante no se modifican — Flowgration nunca escribió en Shopify.
La reinstalación es idempotente: el siguiente callback OAuth actualiza la fila PluginIntegration por (organization_id, platform, store_url), conservando la configuración de mapeo si la ventana de gracia no ha expirado.