# DataFirefly Shopify Migrator: guia completo

> O guia completo do módulo DataFirefly Shopify Migrator: instalação, escolha entre modo CSV e modo API, criação da app Shopify com Client Credentials Grant, migração entidade a entidade, ferramentas de reparação das imagens e das variantes, push das características em metafields, filtros de exclusão, worker cron assíncrono e resolução dos casos correntes.

- Página: <https://www.datafirefly.com/pt/documentation/dfshopifymigrator/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfshopifymigrator/index.md), [en](https://www.datafirefly.com/en/documentation/dfshopifymigrator/index.md), [es](https://www.datafirefly.com/es/documentation/dfshopifymigrator/index.md), [de](https://www.datafirefly.com/de/documentation/dfshopifymigrator/index.md), [it](https://www.datafirefly.com/it/documentation/dfshopifymigrator/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfshopifymigrator/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfshopifymigrator/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## 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.

**Primeiro reflexo:** comece em modo CSV para testar sem risco. Não é necessária nenhuma chave API e pode inspecionar os ficheiros gerados antes de os importar para o Shopify.

## 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

**Importante:** desde 1 de janeiro de 2026, o antigo fluxo "Settings → Apps → Develop apps" foi descontinuado. Tem de passar pelo Shopify Dev Dashboard. Os tokens já não são apresentados diretamente na administração Shopify: é preciso trocá-los através do Client Credentials Grant (CCG).

### 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.

**Se modificar os scopes depois da instalação,** o merchant não terá aprovado os novos. Desinstale e reinstale a app para atualizar o consentimento, caso contrário obterá _This action requires merchant approval for scope_name_ nas chamadas em causa.

### 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.

**O App Automation Token não é um Admin API token.** Serve apenas para autenticar o Shopify CLI nas implementações CI/CD. Não use o botão "Create token" desta secção para configurar o módulo.

## 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.

**Limite do CCG:** a sua loja Shopify e a sua app Dev Dashboard têm de pertencer à mesma Shopify organization. Numa loja paga fora da organização, o Shopify devolve `shop_not_permitted`. Nesse caso, ou associa a loja à sua organização Partners, ou obtém manualmente um token através do Authorization Code Grant OAuth (fora do âmbito do módulo).

## 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`.

**Ordem importante:** em modo API, migre os produtos antes das coleções, caso contrário o mapeamento dos IDs Shopify ainda não está disponível e os produtos não poderão ser associados.

## 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.

**As palavras-passe não são migradas,** por segurança. O Shopify enviará um convite de redefinição a cada um dos seus clientes no seu primeiro envio comercial.

## 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_.

**Os redirecionamentos devem ser migrados em último lugar,** depois dos produtos, coleções e páginas CMS. Consomem a tabela de mapeamento construída por esses três jobs anteriores.

## 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.

**Snapshot no momento do job:** os filtros são guardados em configuração persistente mas fixados no momento da criação do job (snapshot nos params). Modificar os filtros não altera um job já em curso.

## 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`

**Scope necessário:** sem `write_metaobject_definitions` na app Shopify, a Fase A falha. A Fase B funciona na mesma, mas os metafields não ficam visíveis de forma editável na UI de administração Shopify. Para os acrescentar sem reinstalar a app, adicione o scope em Configuration, guarde, e depois desinstale/reinstale a app para atualizar o consentimento do merchant.

## 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