DataFirefly Shopify Migrator: guia completo

Apresentação

O DataFirefly Shopify Migrator é um módulo PrestaShop 8 e 9 que exporta a totalidade de um catálogo para o Shopify, com dois modos à escolha: CSV (geração de ficheiros prontos a importar manualmente através da administração Shopify, sem chave API) ou API (push direto para uma loja Shopify ligada através da Admin REST API 2026-04).

O módulo gere oito entidades, pela ordem em que devem tipicamente ser migradas:

• Produtos: fichas completas, combinações até 3 grupos de atributos, imagens, stocks, preços sem ou com IVA, etiquetas SEO preservadas através dos metafields global title_tag/description_tag
• Coleções: categorias PrestaShop convertidas em custom collections com imagem e descrição
• Páginas CMS: páginas PrestaShop convertidas em páginas Shopify com slug e meta SEO
• Clientes: fichas de cliente + morada por defeito + estatísticas de encomendas, com a tag imported-prestashop
• Encomendas: exportação CSV apenas para consulta (o Shopify não aceita importação nativa de encomendas por CSV padrão)
• Redirecionamentos 301: tabela de correspondência URLs antigos PrestaShop → novos URLs Shopify para preservar o SEO
• Repair images e Variant images: dois jobs de reparação para recuperar as imagens que o Shopify perdeu silenciosamente durante o fetch assíncrono, e para associar cada combinação Shopify à sua imagem
• Features → Metafields: push das características de produto PrestaShop como metafields Shopify com criação automática das Metafield Definitions através de GraphQL

A arquitetura é assíncrona por jobs: cada migração cria um job na base de dados, tratado depois por lotes configuráveis através de um worker cron protegido por token. O rate limit do Shopify é respeitado automaticamente (1,8 req/s, retry 429), e um mapeamento persistente na base de dados liga os identificadores PrestaShop aos identificadores Shopify para permitir os redirecionamentos e evitar duplicados em caso de relançamento.

Pré-requisitos

• PrestaShop 8.0 a 9.x
• PHP 7.4 a 8.3
• Para o modo API: uma loja Shopify de destino (o plano Basic é suficiente), uma conta Shopify Partners ou acesso ao Shopify Dev Dashboard
• Para o modo cron: a possibilidade de agendar um URL do lado do alojamento (crontab, cron-as-a-service, ou Plesk/cPanel)
• Do lado do servidor: extensões PHP curl e iconv ativas

Instalação

1. Transfira o ZIP a partir da sua conta de cliente DataFirefly (área de Transferências da ficha de produto).
2. No back-office do PrestaShop, aceda a Módulos → Gestor de módulos → Carregar um módulo e envie o ZIP.
3. Clique em Instalar. O módulo cria três tabelas (jobs, mapeamento, registo) e um separador dedicado em Parâmetros avançados → Shopify Migrator.
4. Clique em Configurar para aceder à interface principal.

Escolher entre modo CSV e modo API

Modo CSV

O módulo gera ficheiros CSV no formato nativo esperado pelo Shopify Admin (Products Import, Customers Import, URL Redirects Import). Transfere cada ficheiro a partir do separador Jobs e importa-o depois manualmente para o Shopify.

Vantagens: nenhuma chave API a configurar, possibilidade de inspecionar e ajustar os ficheiros antes da importação, tratamento muito rápido do lado do PrestaShop.

Limites: as coleções Shopify não têm importação CSV nativa (o ficheiro gerado serve de referência), e as encomendas nunca são importáveis em CSV padrão do lado do Shopify.

Modo API

O módulo envia cada entidade diretamente para a sua loja Shopify através da API Admin REST 2026-04, com gestão do rate limit, retry automático em erro 429 e mapeamento persistente dos IDs para permitir os redirecionamentos automáticos e a idempotência dos relançamentos.

Vantagens: migração de ponta a ponta num só comando, redirecionamentos enviados diretamente, coleções criadas automaticamente com associação dos produtos, perfeito para os catálogos grandes.

Limites: exige uma app Shopify com os scopes corretos, e algumas organizações Shopify criadas depois de abril de 2025 são apenas GraphQL (o módulo continua compatível com REST para as organizações padrão).

Modo API: criar a app Shopify

Criação da app no Dev Dashboard

1. Inicie sessão no Shopify Dev Dashboard (dev.shopify.com/dashboard) com a sua conta Partners.
2. Clique em Create app, dê-lhe um nome (por exemplo “Migrator”) e confirme.
3. No ecrã de configuração, o App URL pode ficar com qualquer valor HTTPS válido. Só é usado para o OAuth, o que não se aplica ao nosso caso.

Configuração dos scopes

Em Configuration → Admin API integration → Configure access scopes, ative os seguintes 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 (apenas se usar a entidade Features → Metafields)

Clique em Save.

Instalação na loja de destino

1. Em Distribution, escolha Custom distribution e adicione a sua loja Shopify de destino.
2. Clique na ligação de instalação gerada, que abre o ecrã de consentimento do merchant do lado do Shopify Admin.
3. Confirme a instalação: obtém o ecrã final da app.

Obtenção do Client ID e do Client Secret

Em Settings → Credentials da app, copie o Client ID e clique depois no ícone de olho ao lado de Secret para o revelar e copiar.

Modo API: configuração das credenciais

No separador Settings do módulo, escolha o modo Shopify Admin REST API e preencha:

• Shopify store domain: quer o nome curto (my-store), quer o domínio completo (my-store.myshopify.com).
• API version: por defeito 2026-04, a versão estável atual.
• Authentication method: há duas opções possíveis:

Método 1: Admin access token

Para os raros casos em que já dispõe de um token Admin API válido (custom app legacy ou token obtido manualmente através de OAuth). Cole o token no campo dedicado e guarde.

Método 2: Client Credentials Grant (recomendado)

O módulo troca o seu Client ID + Client Secret por um Admin API access token através do fluxo OAuth Client Credentials Grant. O token é colocado em cache (24 h) e renovado automaticamente menos de 5 minutos antes da sua expiração. Nenhuma intervenção manual durante a migração.

Preencha os dois campos e guarde. Clique em Test connection: o módulo mostra o nome da sua loja Shopify e o tempo restante antes da expiração do token.

Migração dos produtos

A exportação de produtos é a mais complexa. Gere os produtos, as combinações (até 3 grupos de atributos, como o Shopify autoriza), as imagens (URL absoluto a partir do seu PrestaShop), os stocks, os preços, os fabricantes usados como vendor, as categorias convertidas em tags e type, as etiquetas SEO preservadas através dos metafields global.title_tag e global.description_tag.

Lançar o job

1. Em Run a migration, selecione o cartão Products.
2. Clique em Create export job. O job aparece na lista do separador Jobs com o estado pending.
3. Se configurou o cron, o worker assume-o no minuto seguinte. Caso contrário, clique no botão Run now para o fazer avançar de forma síncrona (limitado pelo timeout PHP, cerca de 30 segundos).

Acompanhamento do progresso

O separador Jobs atualiza-se automaticamente a cada 10 segundos. Cada linha mostra o estado (pending/running/done/failed/cancelled), a percentagem de progresso, o número de sucessos e de erros, e um botão de registos expansível que mostra as 30 últimas linhas do registo.

Caso do modo CSV

O ficheiro job_X_products.csv é gerado no formato Shopify Products Import. Transfira-o a partir da lista de jobs e, no Shopify Admin, aceda a Products → Import e envie o ficheiro. O Shopify trata depois o processamento do seu lado, com uma notificação por e-mail no fim.

Migração das coleções

As categorias PrestaShop (excluindo a raiz e a categoria ID 1) tornam-se custom collections Shopify, com o seu título, descrição, imagem, etiquetas SEO e o slug limpo. Em modo API, os produtos já migrados são automaticamente associados a cada coleção através do endpoint /collects.json.

Migração das páginas CMS

As páginas PrestaShop ativas são exportadas como páginas Shopify com o seu título, conteúdo HTML (os URLs de imagens relativos são automaticamente resolvidos em URLs absolutos para o seu domínio PrestaShop), slug e etiquetas SEO.

Migração dos clientes

Para cada cliente ativo e não eliminado, o módulo exporta o nome, o e-mail, a morada por defeito, o total gasto, o número de encomendas válidas e o opt-in da newsletter. Cada cliente recebe a tag imported-prestashop para facilitar a filtragem posterior.

Migração das encomendas (apenas CSV)

A exportação de encomendas é apenas para consulta: o Shopify não propõe importação nativa de encomendas por CSV padrão. O ficheiro gerado contém todas as informações úteis para arquivo ou análise: referência, data, estado, cliente, moradas de faturação e de entrega, moeda, totais sem e com IVA, transportadora, seguimento, e uma linha por produto comprado.

Pode filtrar por intervalo de datas no formulário de criação do job (campos Orders from e Orders to).

Para os utilizadores do Shopify Plus, ferramentas de terceiros como o Matrixify aceitam este formato como entrada para efetuar uma verdadeira reimportação.

Migração dos redirecionamentos 301

É o ponto-chave para preservar o seu SEO no dia da mudança de domínio. O módulo lê a tabela de mapeamento construída pelas exportações anteriores (produtos, coleções, páginas) e gera um CSV de duas colunas no formato nativo Shopify URL Redirects, com os URLs antigos PrestaShop na primeira coluna e os novos URLs Shopify na segunda.

Em modo API, o módulo envia diretamente cada redirecionamento através de POST /redirects.json. Em modo CSV, importe o ficheiro no Shopify Admin através de Online Store → Navigation → URL Redirects → Import.

Filtros de exclusão (v1.1)

Dois filtros opcionais permitem excluir produtos da exportação, configuráveis em Settings → Product filters (exclusions).

Excluir categorias

Campo de texto com uma lista de IDs de categorias PrestaShop separados por vírgulas. Um produto que pertença a pelo menos uma dessas categorias é excluído da exportação Products. As próprias categorias continuam a ser migradas pela entidade Collections (útil se uma categoria técnica não se destina a ser apresentada mas pode conter produtos).

Excluir prefixos de referência

Campo de texto com uma lista de prefixos separados por vírgulas. Qualquer produto cuja referência comece por um desses prefixos é excluído. Útil para não migrar produtos internos (NV para não vendáveis, INT para uso interno, OBSOLETO- para as gamas descontinuadas, etc.). Os prefixos não distinguem maiúsculas de minúsculas.

Reparação das imagens (v1.3)

O Shopify transfere as imagens de forma assíncrona depois da criação de um produto: faz o fetch do URL que forneceu e, se isso falhar silenciosamente (timeout, URL bloqueado, ficheiro demasiado grande, formato recusado), não devolve nenhum erro. O produto é criado com “success” do lado da API mas sem imagem.

A entidade Repair images repara esses casos. Para cada produto do mapeamento:

1. GET /products/{shopify_id}/images.json para contar as imagens atuais do lado do Shopify.
2. Leitura das imagens correspondentes no PrestaShop.
3. Se o Shopify já tiver tantas imagens como o PS → o produto é saltado.
4. Caso contrário: eliminação das imagens Shopify parciais, e depois upload de cada imagem PS através de base64 attachment (modo síncrono, o Shopify confirma a criação imediatamente), com recurso ao URL para os ficheiros com mais de 3 MB.

Modo API obrigatório. Idempotente: pode relançar o job tantas vezes quantas forem necessárias.

Variant images (v1.4)

Uma vez as imagens principais no sítio, falta associar cada combinação Shopify à sua imagem correspondente. A entidade Variant images encarrega-se disso: para cada produto do mapeamento, consulta a lista de variantes e de imagens Shopify e cruza-a depois com as relações product_attribute_image do PrestaShop.

A correspondência variante PS → variante Shopify usa primeiro o SKU (referência da combinação), com recurso ao tuplo de opções (option1/option2/option3 em minúsculas) se a referência estiver vazia.

A correspondência imagem PS → imagem Shopify é feita por alinhamento de posição: a N-ésima imagem PS corresponde à N-ésima imagem Shopify. Isto é válido enquanto não tiver reorganizado manualmente as imagens na administração Shopify.

Idempotente: uma variante já com o image_id correto é saltada (registada como already_ok). O registo conta por produto: assigned / already_ok / missing_image / missing_variant.

Features → Metafields (v1.5)

As características de produto PrestaShop (Catálogo → Atributos e Características → Características) são enviadas como metafields Shopify sob o namespace custom, com criação automática das Metafield Definitions para que sejam editáveis a partir da administração Shopify.

Fase A: criação das Definitions (primeiro lote)

No primeiro lote do job, o módulo lista todas as características distintas da loja e cria para cada uma uma Metafield Definition através da mutação GraphQL metafieldDefinitionCreate. As definitions já existentes (código TAKEN ou DUPLICATE_KEY) são silenciosamente ignoradas.

Fase B: push dos valores (cada lote)

Para cada produto do mapeamento, o módulo lista os metafields custom.* existentes e, para cada característica PS, efetua um upsert: PUT se a chave existir com um valor diferente, POST se a chave não existir. Os valores já idênticos são saltados.

Conversão nome → chave

O nome da característica PrestaShop é convertido em chave de metafield Shopify por transliteração ASCII, passagem a minúsculas, substituição dos caracteres não alfanuméricos por underscores e truncatura a 30 caracteres. Exemplos:

• Material principal passa a material_principal
• Peso (kg) passa a peso_kg
• Cor passa a cor

Worker cron

O módulo expõe um endpoint front-office protegido por token que trata um job por tick, à razão de 20 lotes por tick. O URL completo com token é apresentado no separador Run a migration, com um botão de cópia.

Exemplo de entrada crontab para um tick por minuto:

* * * * * curl -s "https://o-seu-prestashop.pt/index.php?fc=module&module=dfshopifymigrator&controller=cron&token=O_SEU_TOKEN" > /dev/null

Sem cron configurado, pode sempre fazer avançar um job à mão com o botão Run now da lista de jobs (progresso síncrono, limitado pelo timeout PHP do back-office, cerca de 30 segundos).

Ordem recomendada dos jobs

Para uma migração completa sem surpresas, lance os jobs por esta ordem:

1. Products: cria o mapeamento PS→Shopify para os produtos, usado por todas as etapas seguintes.
2. Collections: cria o mapeamento para as categorias e associa automaticamente os produtos.
3. Pages: cria o mapeamento para as páginas CMS.
4. Customers: independente do resto.
5. Orders: CSV apenas para consulta, lançamento ao seu ritmo.
6. Repair images (se necessário): repara as imagens perdidas durante o fetch assíncrono do Shopify.
7. Variant images: reassocia cada combinação à sua imagem.
8. Features → Metafields: envia as características de produto como metafields visíveis.
9. Redirects: em último lugar, consome todo o mapeamento construído acima.

Limitações conhecidas (v1)

• Só é exportado um idioma por migração (o idioma selecionado em Settings). A v2 acrescentará o mapeamento dos idiomas PrestaShop para Shopify Markets e Translate & Adapt.
• As encomendas são exportadas apenas em formato CSV para consulta.
• As palavras-passe dos clientes não são migradas.
• As combinações estão limitadas a 3 grupos de atributos (limite Shopify Option1/Option2/Option3).
• As imagens são servidas a partir do URL público do seu PrestaShop: mantenha o seu PS online durante a importação Shopify e, no mínimo, durante o eventual job Repair images.

Resolução de problemas

Shopify API error: Not Found

Verifique em primeiro lugar o campo API version em Settings: deve ser 2026-04 (as versões antigas como 2024-10 foram retiradas). Verifique também que a sua app está instalada na loja de destino em Distribution.

Shopify API error: Invalid API key or access token

O token expirou (CCG: validade de 24 h, renovado automaticamente) ou a app foi desinstalada. Clique em Test connection para forçar uma renovação do token CCG. Se o erro persistir, aceda a Shopify Admin → Apps and sales channels e verifique que a app Migrator está na lista das aplicações instaladas.

This action requires merchant approval for write_X scope

Modificou os scopes depois da instalação inicial da app e o merchant não teve oportunidade de os aprovar. Desinstale a app no Shopify Admin e reinstale-a através da ligação de Distribution do Dev Dashboard. O ecrã de consentimento do merchant aparecerá de novo com os novos scopes.

shop_not_permitted na troca CCG

A sua loja Shopify não está na mesma organization que a sua app Dev Dashboard. Ou associa a loja à sua organization Partners, ou usa um token Admin obtido manualmente (Authorization Code Grant OAuth, fora do âmbito do módulo).

Cardinality violation: Subquery returns more than 1 row

Bug corrigido na v1.2.1. Atualize para a última versão do módulo.

Muitas fichas Shopify chegaram sem imagem

É o comportamento documentado do Shopify para as imagens enviadas por URL. Lance o job Repair images em modo API: deteta as fichas com menos imagens do que o PS e republica tudo em base64 (modo síncrono, garante a chegada).

Muitos “missing_variant” nos registos de Variant images

O SKU da combinação Shopify não corresponde à referência do product_attribute PrestaShop, e o recurso ao tuplo de opções também não encontrou correspondência. Verifique que as suas combinações PS têm referências preenchidas, ou contacte o suporte DataFirefly para um ajuste personalizado da correspondência.

Recursos

• Ficha de produto DataFirefly Shopify Migrator (transferências, compra, licença)
• Documentação oficial Shopify Admin REST API: shopify.dev/docs/api/admin-rest
• Documentação Shopify Client Credentials Grant: shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant
• Suporte DataFirefly: hello@datafirefly.com