DataFirefly Shopify Migrator — Guía completa

Presentación

DataFirefly Shopify Migrator es un módulo PrestaShop 8 y 9 que exporta el catálogo completo hacia Shopify, con dos modos a elegir: CSV (generación de archivos listos para importar manualmente desde el admin de Shopify, sin clave API) o API (push directo hacia una tienda Shopify conectada vía la Admin REST API 2026-04).

El módulo gestiona ocho entidades, en el orden en el que típicamente deben migrarse:

• Productos — fichas completas, variantes hasta 3 grupos de atributos, imágenes, stocks, precios sin o con IVA, meta SEO preservados vía metafields global title_tag/description_tag
• Colecciones — categorías PrestaShop convertidas en custom collections con imagen y descripción
• Páginas CMS — páginas PrestaShop convertidas en páginas Shopify con slug y meta SEO
• Clientes — fichas cliente + dirección por defecto + estadísticas de pedidos, etiquetados imported-prestashop
• Pedidos — exportación CSV consultiva únicamente (Shopify no acepta import nativo de pedidos vía CSV estándar)
• Redirecciones 301 — tabla de correspondencia de URLs antiguas PrestaShop hacia nuevas URLs Shopify para preservar el posicionamiento
• Repair images y Variant images — dos jobs de reparación para recuperar las imágenes que Shopify perdió silenciosamente durante el fetch asíncrono, y para vincular cada variante Shopify a su imagen
• Features → Metafields — push de las características de productos PrestaShop como metafields Shopify con creación automática de Metafield Definitions vía GraphQL

La arquitectura es asíncrona por jobs: cada migración crea un job en base de datos, que luego es procesado por lotes configurables vía un worker cron protegido por token. El rate limit de Shopify se respeta automáticamente (1,8 req/s, retry 429), y un mapeo persistente en base de datos vincula los identificadores PrestaShop con los identificadores Shopify para permitir las redirecciones y evitar duplicados en relances.

Requisitos

• PrestaShop 8.0 a 9.x
• PHP 7.4 a 8.3
• Para modo API: una tienda Shopify destino (el plan Basic basta), una cuenta Shopify Partners o acceso al Shopify Dev Dashboard
• Para modo cron: capacidad de planificar una URL en el hosting (crontab, cron-as-a-service, o Plesk/cPanel)
• Del lado servidor: extensiones PHP curl e iconv activadas

Instalación

1. Descargue el ZIP desde su cuenta de cliente DataFirefly (sección Descargas de la ficha de producto).
2. En el back-office PrestaShop, vaya a Módulos → Gestor de módulos → Subir un módulo, suelte el ZIP.
3. Haga clic en Instalar. El módulo crea tres tablas (jobs, mapping, log) y una pestaña dedicada en Parámetros avanzados → Shopify Migrator.
4. Haga clic en Configurar para acceder a la interfaz principal.

Elegir entre modo CSV y modo API

Modo CSV

El módulo genera archivos CSV en el formato nativo esperado por Shopify Admin (Products Import, Customers Import, URL Redirects Import). Descarga cada archivo desde la pestaña Jobs y lo importa manualmente en Shopify.

Ventajas: ninguna clave API que configurar, posibilidad de inspeccionar y ajustar los archivos antes del import, procesamiento muy rápido del lado PrestaShop.

Limitaciones: las colecciones Shopify no tienen import CSV nativo (el archivo generado sirve de referencia), y los pedidos nunca son importables en CSV estándar del lado Shopify.

Modo API

El módulo envía cada entidad directamente a su tienda Shopify vía la Admin REST API 2026-04, con gestión del rate limit, retry automático en error 429, y mapeo persistente de IDs para permitir las redirecciones automáticas y la idempotencia de los relances.

Ventajas: migración de extremo a extremo en un comando, redirecciones empujadas directamente, colecciones creadas automáticamente con enlace de productos, perfecto para grandes catálogos.

Limitaciones: requiere una app Shopify con los scopes correctos, y algunas organizaciones Shopify creadas después de abril 2025 son GraphQL-only (el módulo sigue siendo compatible REST para las organizaciones estándar).

Modo API: crear la app Shopify

Creación de la app en el Dev Dashboard

1. Conéctese al Shopify Dev Dashboard (dev.shopify.com/dashboard) con su cuenta Partners.
2. Haga clic en Create app, póngale un nombre (por ejemplo «Migrator»), y confirme.
3. En la pantalla de configuración, el App URL puede dejarse en cualquier valor HTTPS válido. Solo se usa para OAuth, lo que no concierne nuestro caso.

Configuración de scopes

En Configuration → Admin API integration → Configure access scopes, active los siguientes scopes:

• read_products, write_products
• read_customers, write_customers
• read_content, write_content
• read_inventory, write_inventory
• read_online_store_pages, write_online_store_pages
• read_online_store_navigation, write_online_store_navigation
• write_metaobject_definitions (únicamente si utiliza la entidad Features → Metafields)

Haga clic en Save.

Instalación en la tienda destino

1. En Distribution, elija Custom distribution y añada su tienda Shopify destino.
2. Haga clic en el enlace de instalación generado, que abre la pantalla de consentimiento merchant del lado Shopify Admin.
3. Valide la instalación: obtiene la pantalla final de la app.

Recuperación del Client ID y del Client Secret

En Settings → Credentials de la app, copie el Client ID, luego haga clic en el icono de ojo al lado de Secret para revelarlo y copiarlo.

Modo API: configuración de las credenciales

En la pestaña Settings del módulo, elija el modo Shopify Admin REST API, luego rellene:

• Shopify store domain — el nombre corto (my-store) o el dominio completo (my-store.myshopify.com).
• API version — por defecto 2026-04, la versión estable actual.
• Authentication method — dos opciones disponibles:

Método 1: Admin access token

Para los casos raros en los que ya dispone de un token Admin API válido (custom app legacy o token obtenido manualmente vía OAuth). Pegue el token en el campo dedicado y guarde.

Método 2: Client Credentials Grant (recomendado)

El módulo intercambia su Client ID + Client Secret por un Admin API access token vía el flow OAuth Client Credentials Grant. El token se cachea (24 h), automáticamente renovado menos de 5 minutos antes de su expiración. Ninguna intervención manual durante la migración.

Rellene los dos campos y guarde. Haga clic en Test connection: el módulo muestra el nombre de su tienda Shopify y el tiempo restante antes de la expiración del token.

Migración de productos

La exportación de productos es la más compleja. Gestiona los productos, las variantes (hasta 3 grupos de atributos como Shopify autoriza), las imágenes (URL absoluta desde su PrestaShop), los stocks, los precios, los fabricantes utilizados como vendor, las categorías convertidas en tags y type, las meta SEO preservadas vía los metafields global.title_tag y global.description_tag.

Lanzar el job

1. En Run a migration, seleccione la tarjeta Products.
2. Haga clic en Create export job. El job aparece en la lista de la pestaña Jobs con el estado pending.
3. Si ha configurado el cron, el worker lo toma a cargo en el minuto siguiente. Sino haga clic en el botón Run now para hacerlo avanzar síncronamente (limitado por el timeout PHP, alrededor de 30 segundos).

Seguimiento del progreso

La pestaña Jobs se auto-actualiza cada 10 segundos. Cada línea muestra el estado (pending/running/done/failed/cancelled), el porcentaje de avance, el número de éxitos y errores, y un botón de logs desplegable que muestra las 30 últimas líneas del registro.

Caso del modo CSV

El archivo job_X_products.csv se genera en el formato Shopify Products Import. Descárguelo desde la lista de jobs, luego en Shopify Admin vaya a Products → Import y suelte el archivo. Shopify gestiona luego el procesamiento de su lado, con una notificación por email al final.

Migración de colecciones

Las categorías PrestaShop (excepto raíz y excepto la categoría ID 1) se convierten en custom collections Shopify, con su título, descripción, imagen, meta SEO y slug limpio. En modo API, los productos ya migrados se vinculan automáticamente a cada colección vía el endpoint /collects.json.

Migración de páginas CMS

Las páginas PrestaShop activas se exportan en páginas Shopify con su título, contenido HTML (las URLs de imágenes relativas se resuelven automáticamente en URL absolutas hacia su dominio PrestaShop), slug y meta SEO.

Migración de clientes

Para cada cliente activo y no eliminado, el módulo exporta el nombre, el email, la dirección por defecto, el total gastado, el número de pedidos válidos, y el opt-in newsletter. Cada cliente recibe el tag imported-prestashop para facilitar el filtrado posterior.

Migración de pedidos (CSV únicamente)

La exportación de pedidos es consultiva: Shopify no propone import nativo de pedidos vía CSV estándar. El archivo generado contiene toda la información útil para archivo o análisis: referencia, fecha, estado, cliente, direcciones de facturación y envío, divisa, totales sin y con IVA, transportista, seguimiento, y una línea por producto comprado.

Puede filtrar por rango de fechas en el formulario de creación del job (campos Orders from y Orders to).

Para los usuarios Shopify Plus, herramientas de terceros como Matrixify aceptan este formato como entrada para efectuar una verdadera reimportación.

Migración de redirecciones 301

Es el punto clave para preservar su posicionamiento el día del cambio de dominio. El módulo lee la tabla de mapeo construida por las exportaciones previas (productos, colecciones, páginas) y genera un CSV de dos columnas en el formato nativo Shopify URL Redirects, con las antiguas URLs PrestaShop en la primera columna y las nuevas URLs Shopify en la segunda.

En modo API, el módulo empuja directamente cada redirección vía POST /redirects.json. En modo CSV, importe el archivo en Shopify Admin vía Online Store → Navigation → URL Redirects → Import.

Filtros de exclusión (v1.1)

Dos filtros opcionales permiten excluir productos de la exportación, configurables en Settings → Product filters (exclusions).

Excluir categorías

Campo texto con una lista de IDs de categorías PrestaShop separados por comas. Un producto que pertenezca al menos a una de estas categorías queda excluido de la exportación Products. Las categorías en sí siguen migradas por la entidad Collections (útil si una categoría técnica no debe mostrarse pero puede contener productos).

Excluir prefijos de referencia

Campo texto con una lista de prefijos separados por comas. Cualquier producto cuya referencia comience por uno de estos prefijos queda excluido. Útil para no migrar productos internos (NS para no vendibles, HB para fuera de negocio, OBSOLETE- para gamas descatalogadas, etc.). Los prefijos son insensibles a mayúsculas/minúsculas.

Reparación de imágenes (v1.3)

Shopify descarga las imágenes de forma asíncrona después de la creación de un producto: hace fetch de la URL que ha proporcionado, y si falla silenciosamente (timeout, URL bloqueada, archivo demasiado grande, formato rechazado), no devuelve ningún error. El producto se crea «success» del lado API pero sin imagen.

La entidad Repair images repara estos casos. Para cada producto del mapeo:

1. GET /products/{shopify_id}/images.json para contar las imágenes actuales del lado Shopify.
2. Lectura de las imágenes correspondientes en PrestaShop.
3. Si Shopify ya tiene tantas imágenes como PS → el producto se omite.
4. Sino: eliminación de las imágenes Shopify parciales, luego subida de cada imagen PS vía base64 attachment (modo síncrono, Shopify confirma la creación inmediatamente), con fallback URL para los archivos de más de 3 MB.

Modo API obligatorio. Idempotente: puede relanzar el job tantas veces como sea necesario.

Variant images (v1.4)

Una vez las imágenes principales en su lugar, queda asociar cada variante Shopify a su imagen correspondiente. La entidad Variant images se encarga de ello: para cada producto del mapeo, interroga la lista de variantes e imágenes Shopify, luego cruza con las relaciones product_attribute_image de PrestaShop.

La correspondencia variante PS → variante Shopify utiliza primero el SKU (referencia de la variante), con un fallback por tupla de opciones (option1/option2/option3 en minúsculas) si la referencia está vacía.

La correspondencia imagen PS → imagen Shopify se hace por alineación de posición: la N-ésima imagen PS corresponde a la N-ésima imagen Shopify. Vale mientras no haya reorganizado manualmente las imágenes en el admin Shopify.

Idempotente: una variante ya en el image_id correcto se omite (registrado already_ok). El registro cuenta por producto: assigned / already_ok / missing_image / missing_variant.

Features → Metafields (v1.5)

Las características de productos PrestaShop (Catálogo → Atributos y Características → Características) se empujan como metafields Shopify bajo el namespace custom, con creación automática de las Metafield Definitions para que sean editables desde el admin Shopify.

Fase A: creación de las Definitions (primer lote)

En el primer batch del job, el módulo lista todas las features distintas del shop y crea para cada una una Metafield Definition vía la mutación GraphQL metafieldDefinitionCreate. Las definitions ya existentes (código TAKEN o DUPLICATE_KEY) se ignoran silenciosamente.

Fase B: push de los valores (cada batch)

Para cada producto del mapeo, el módulo lista los metafields custom.* existentes, luego para cada feature PS efectúa un upsert: PUT si la clave existe con un valor distinto, POST si la clave no existe. Los valores ya idénticos se omiten.

Conversión nombre → clave

El nombre de la feature PrestaShop se convierte en clave metafield Shopify por transliteración ASCII, paso a minúsculas, reemplazo de caracteres no alfanuméricos por underscores, truncamiento a 30 caracteres. Ejemplos:

• Materia principal se convierte en materia_principal
• Peso (kg) se convierte en peso_kg
• Color se convierte en color

Worker cron

El módulo expone un endpoint front protegido por token que procesa un job por tick, a razón de 20 lotes por tick. La URL completa con token se muestra en la pestaña Run a migration, con un botón de copia.

Ejemplo de entrada crontab para un tick por minuto:

* * * * * curl -s "https://su-prestashop.com/index.php?fc=module&module=dfshopifymigrator&controller=cron&token=SU_TOKEN" > /dev/null

Sin cron configurado, siempre puede hacer avanzar un job manualmente con el botón Run now de la lista de jobs (avance síncrono, limitado por el timeout PHP del back-office, alrededor de 30 segundos).

Orden recomendado de los jobs

Para una migración completa sin sorpresas, lance los jobs en este orden:

1. Products — crea el mapeo PS→Shopify para los productos, utilizado por todas las etapas siguientes.
2. Collections — crea el mapeo para las categorías y vincula automáticamente los productos.
3. Pages — crea el mapeo para las páginas CMS.
4. Customers — independiente del resto.
5. Orders — CSV consultivo únicamente, lanzamiento a su ritmo.
6. Repair images (si es necesario) — repara las imágenes perdidas durante el fetch asíncrono Shopify.
7. Variant images — reasocia cada variante a su imagen.
8. Features → Metafields — empuja las características de productos como metafields visibles.
9. Redirects — en último lugar, consume todo el mapeo construido arriba.

Limitaciones conocidas (v1)

• Una sola lengua se exporta por migración (la lengua seleccionada en Settings). La v2 añadirá el mapeo de las lenguas PrestaShop hacia Shopify Markets y Translate & Adapt.
• Los pedidos se exportan en formato CSV consultivo únicamente.
• Las contraseñas de los clientes no se migran.
• Las variantes están limitadas a 3 grupos de atributos (límite Shopify Option1/Option2/Option3).
• Las imágenes se sirven desde la URL pública de su PrestaShop: mantenga su PS en línea durante el import Shopify, y como mínimo durante el eventual job Repair images.

Resolución de problemas

Shopify API error: Not Found

Compruebe en prioridad el campo API version en Settings: debe ser 2026-04 (las versiones antiguas como 2024-10 están retiradas). Compruebe también que su app está bien instalada en la tienda destino en Distribution.

Shopify API error: Invalid API key or access token

El token ha expirado (CCG: duración de vida 24 h, refrescado automáticamente) o la app ha sido desinstalada. Haga clic en Test connection para forzar una renovación del token CCG. Si el error persiste, vaya a Shopify Admin → Apps and sales channels y compruebe que la app Migrator está en la lista de aplicaciones instaladas.

This action requires merchant approval for write_X scope

Ha modificado los scopes después de la instalación inicial de la app, el merchant no ha tenido ocasión de aprobarlos. Desinstale la app en Shopify Admin luego reinstálela vía el enlace de Distribution del Dev Dashboard. La pantalla de consentimiento merchant aparecerá de nuevo con los nuevos scopes.

shop_not_permitted durante el intercambio CCG

Su tienda Shopify no está en la misma organization que su app Dev Dashboard. Sea vincule la tienda a su organization Partners, sea utilice un token Admin obtenido manualmente (Authorization Code Grant OAuth, fuera del perímetro del módulo).

Cardinality violation: Subquery returns more than 1 row

Bug corregido en v1.2.1. Actualice a la última versión del módulo.

Muchas fichas Shopify han llegado sin imagen

Es el comportamiento Shopify documentado para las imágenes push vía URL. Lance el job Repair images en modo API: detecta las fichas con menos imágenes que PS y republica todo en base64 (modo síncrono, garantiza la llegada).

Muchos «missing_variant» en los registros de Variant images

El SKU de la variante Shopify no corresponde a la referencia del product_attribute PrestaShop, y el fallback por tupla de opciones no ha hecho match tampoco. Compruebe que sus variantes PS tienen las referencias rellenas, o contacte el soporte DataFirefly para un ajuste personalizado del matching.

Recursos

• Ficha de producto DataFirefly Shopify Migrator (descargas, compra, licencia)
• Documentación oficial Shopify Admin REST API: shopify.dev/docs/api/admin-rest
• Documentación Shopify Client Credentials Grant: shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant
• Soporte DataFirefly: hello@datafirefly.com