Importação de Fornecedores e Dropshipping para PrestaShop 8 e 9

Apresentação

O módulo Importação de Fornecedores e Dropshipping (nome técnico dfsupplierfeed) importa e sincroniza automaticamente os catálogos dos seus fornecedores no PrestaShop 8 e 9. Gere vários fornecedores e feeds em CSV, XML e JSON, aplica as suas regras de margem, constrói as combinações, liga os produtos entre si, sincroniza o stock por cron e arbitra os EAN13 duplicados através de uma prioridade por fornecedor.

Instalação

1. No back office, vá a Módulos > Gestor de módulos e depois Carregar um módulo.
2. Selecione o ficheiro dfsupplierfeed.zip e confirme.
3. Depois de instalado, clique em Configurar.

Na instalação, o módulo cria cinco tabelas (dfsf_supplier, dfsf_feed, dfsf_rule, dfsf_product, dfsf_log) e gera um token de cron único.

Visão geral da interface

• Dashboard — contadores e aviso sobre os feeds cuja importação está em curso.
• Suppliers — fornecedores e prioridades.
• Feeds — feeds, análise, mapeamento de campos e opções.
• Margin rules — regras de cálculo dos preços de venda.
• Logs — histórico detalhado das importações.
• Settings & Cron — definições gerais, catálogos grandes, URL de cron.

Passo 1 — Criar os fornecedores

No separador Suppliers, adicione um fornecedor com o seu nome, a sua prioridade (inteiro, 1 é a mais alta e resolve os EAN13 duplicados), o estado ativo e a opção Criar o fornecedor nativo do PrestaShop, que preenche também o custo de compra em product_supplier.

Passo 2 — Criar o feed e deixar o módulo analisá-lo

No separador Feeds, crie o feed com o seu fornecedor, o tipo de fonte (URL remoto ou ficheiro local no diretório da loja) e o formato. Guarde e clique no botão lupa na linha do feed.

O módulo descarrega uma amostra e mostra o items_path detetado, a lista de todos os campos realmente presentes com valores de exemplo, e um mapeamento completo pré-preenchido editável antes de aplicar.

As colunas de fotos numeradas são agrupadas automaticamente, as colunas de tamanhos agrupados, de cor e de referências relacionadas são reconhecidas, e os nomes das colunas identificados em inglês, francês, espanhol, alemão e italiano.

Passo 3 — O mapeamento dos campos

O mapeamento é um objeto JSON que liga as colunas ou nós do feed a campos normalizados. Os 21 campos canónicos são:

name reference ean13 mpn cost quantity description description_short category manufacturer weight tax_rate image images group_reference attributes variants_stock variants_ean variants_reference variant_attribute related

Apenas reference ou ean13 é obrigatório.

Várias fontes para um mesmo campo

{
  "fields": {
    "reference": "id",
    "name": "name",
    "cost": "wholesale_price",
    "images": ["image_1", "image_2", "image_3", "image_4"]
  }
}

No campo images são importadas todas as colunas preenchidas. Em qualquer outro campo fica o primeiro valor não vazio, o que permite escrever uma cadeia de recurso.

CSV

Ligue cada campo a um cabeçalho de coluna ou a um índice de coluna a partir de 0. O delimitador é detetado automaticamente, os campos multilinha entre aspas são tratados.

{
  "fields": {
    "name": "product_name",
    "reference": "sku",
    "ean13": "ean",
    "cost": "price",
    "quantity": "stock",
    "category": "category",
    "image": "image_url"
  }
}

XML

items_path aponta para o nó repetido, a qualquer profundidade. Os caminhos dos campos são relativos a esse nó e @nome lê um atributo.

{
  "items_path": "products/product",
  "fields": {
    "reference": "@sku",
    "name": "title",
    "ean13": "ean",
    "cost": "pricing/wholesale",
    "quantity": "stock/quantity",
    "image": "images/image"
  }
}

JSON

items_path usa notação com pontos até ao array de artigos. Um segmento numérico lê uma entrada: images.0 é a primeira imagem.

{
  "items_path": "data.products",
  "fields": {
    "reference": "sku",
    "name": "name",
    "ean13": "barcode",
    "cost": "prices.cost",
    "quantity": "inventory.available",
    "image": "images.0"
  }
}

O separador Feeds contém dezasseis exemplos comentados.

Passo 4 — Definir as margens

No separador Margin rules, cada regra calcula o preço de venda sem IVA a partir do custo de compra sem IVA: percentagem, coeficiente ou adição fixa. Em seguida é aplicado um arredondamento psicológico opcional.

Âmbito e resolução

Uma regra pode visar um fornecedor, uma categoria, ambos, ou ser global. Vence a mais específica, nesta ordem: fornecedor + categoria, só fornecedor, só categoria, regra global. As regras de categoria aplicam-se também às subcategorias. Sem qualquer regra é usada a margem predefinida.

A prioridade EAN entre fontes

Quando o mesmo ean13 aparece em vários feeds, o fornecedor com melhor prioridade possui o produto, as restantes fontes são ignoradas, e se mais tarde um fornecedor com melhor prioridade trouxer esse EAN, assume automaticamente.

As combinações

São geridas duas estruturas de feed.

Uma linha por variante

Ative Construir as combinações e mapeie group_reference (idêntico para todas as variantes de um mesmo produto) e attributes (as opções, por exemplo Tamanho:M|Cor:Vermelho).

Uma linha por produto, tamanhos agrupados numa coluna

É a estrutura mais comum entre os grossistas de têxtil e lingerie:

sizes_stock : EU 70C | FR 85C:4,EU 70D | FR 85D:2,EU 75A | FR 90A:1
ean_codes   : EU 70C | FR 85C:5901741925360,EU 70D | FR 85D:5901741925377

Ative Dividir as variantes agrupadas e mapeie variants_stock, mais variants_ean e variants_reference se o feed os fornecer. O módulo divide a linha numa combinação por tamanho e associa stock, EAN e referência por etiqueta. Três definições acompanham a caixa: o nome do grupo de atributos (Taille por predefinição), o separador entre entradas (,) e o separador entre etiqueta e valor (:).

A divisão faz-se na última ocorrência do separador, pelo que uma etiqueta como EU 70C | FR 85C continua legível.

Um segundo eixo a partir de uma coluna do feed

Muitos fornecedores enviam a cor numa coluna separada enquanto os tamanhos estão agrupados. Mapeie variant_attribute para essa coluna:

{
  "fields": {
    "reference": "id",
    "name": "name",
    "cost": "wholesale_price",
    "variant_attribute": "color",
    "variants_stock": "sizes_stock",
    "variants_ean": "ean_codes"
  }
}

Cada combinação do produto ganha então um segundo eixo, sob o grupo de atributos da coluna adicional definido no feed (Couleur por predefinição). Obtém combinações de Tamanho e Cor, utilizáveis pelos filtros.

Produtos relacionados

Quando o feed lista as outras cores ou os modelos associados numa coluna de referências, marque Importar os produtos relacionados e mapeie related:

{
  "fields": {
    "reference": "id",
    "related": "other_colors"
  }
}

A coluna contém uma lista de referências de fornecedor separadas por vírgulas. As ligações são criadas como acessórios PrestaShop e aparecem no bloco de produtos relacionados do seu tema.

A resolução ocorre depois de lido todo o feed, porque uma referência aponta muitas vezes para um produto situado mais à frente no ficheiro. Três comportamentos a conhecer:

• uma referência que aponta para o próprio produto é ignorada, o que é frequente porque muitos fornecedores listam o grupo completo em cada membro;
• uma referência que aponta para um produto ausente do feed é ignorada sem contar como erro: numa exportação filtrada por categoria isto representa habitualmente um quinto das referências;
• os acessórios existentes nunca são eliminados, pelo que as ligações adicionadas à mão sobrevivem. Em contrapartida, um agrupamento alterado pelo fornecedor deixa ligações antigas no lugar.

O número de ligações criadas aparece na mensagem de fim de importação e numa coluna dedicada do registo.

O que o feed pode substituir

Cinco caixas por feed decidem que campos são sincronizados: preços, stock, nome, descrições, imagens. Por predefinição só preços e stock estão marcados.

Produtos retirados do catálogo do fornecedor

Cada feed escolhe o seu comportamento: não mexer, colocar o stock a zero, desativar ou ambos. A ação aplica-se no fim de uma importação completa concluída e apenas aos produtos desse feed.

Categorias e moedas

O campo category aceita um nome simples ou um caminho completo, por exemplo Início > Escritório > Cadeiras. O separador é configurável por feed e a opção Criar as categorias em falta cria os níveis ausentes.

Se o fornecedor fatura noutra moeda, selecione-a no feed: os custos são convertidos para a moeda predefinida da loja.

Catálogos grandes

Os feeds são lidos em streaming: a memória usada não depende do tamanho do ficheiro. O processamento é dividido em lotes retomáveis. Duas definições: ponto de retoma a cada N artigos (2000 por predefinição) e orçamento de tempo por passagem (120 s).

Lançar uma importação manualmente

• Importação completa (ícone de reprodução) — atualiza os produtos ligados e cria os que faltam se o feed o permitir.
• Sincronização de stock (ícone de atualizar) — atualiza apenas preços e quantidades dos produtos já ligados.

A partir do back office uma passagem está limitada a 45 segundos.

Automatizar com o cron

# Sincronização de stock a cada hora
0 * * * * curl -sL "https://asualoja.tld/index.php?fc=module&module=dfsupplierfeed&controller=cron&token=O_SEU_TOKEN&mode=stock" > /dev/null

# Importação completa todas as noites
30 3 * * * curl -sL "https://asualoja.tld/index.php?fc=module&module=dfsupplierfeed&controller=cron&token=O_SEU_TOKEN&mode=full" > /dev/null

Parâmetros opcionais: &id_feed=N e &budget=600.

Definições gerais

• Produtos criados ativos de imediato — desativado por predefinição.
• Desativar os produtos esgotados no fornecedor, com reativação quando o stock regressa.
• Margem predefinida quando nenhuma regra corresponde.
• Retenção dos registos e purga automática.
• Ao desinstalar — eliminar os dados ou conservar tudo.
• Limpar a cache dos feeds e os cursores no painel de manutenção.

Acompanhamento e registos

O separador Logs lista cada execução: feed, modo, artigos processados, criados, atualizados, ignorados, com erro, desaparecidos, ligações entre produtos criadas, indicador de conclusão com o ponto de retoma, tempo de execução e detalhe dos primeiros erros.

Resolução de problemas

“Malformed CSV row: 23 columns instead of 22”

A linha contém um separador ou aspas não protegidos num campo de texto. É rejeitada.

“Feed file not found or outside shop directory”

Para uma fonte de ficheiro, o caminho deve apontar para um ficheiro legível dentro do diretório da loja.

A análise não encontra artigos

Indique items_path manualmente no mapeamento e volte a lançar a análise.

Os produtos são criados mas não aparecem na loja

É o comportamento predefinido: os produtos criados ficam desativados.

As combinações não são criadas

Verifique se a caixa correspondente está marcada, se os campos necessários estão mapeados e se os separadores correspondem ao ficheiro.

O meu catálogo duplicou depois de ativar a divisão

A importação foi lançada antes de marcar a caixa. Elimine os produtos criados por esse feed, limpe os cursores e volte a lançar.

Poucas ou nenhumas ligações de produtos relacionados

As ligações só são resolvidas no fim de uma importação completa concluída: num feed grande processado em várias passagens, aparecem na última. Verifique também se as referências da coluna correspondem ao campo mapeado em reference.

Os preços parecem demasiado altos ou baixos

Verifique os custos com IVA, a moeda, que regra de margem se aplica e se o campo mapeado em cost é um custo de compra.

A importação nunca termina

É normal num feed muito grande: avança por passagens.

Compatibilidade

• PrestaShop 8.0 a 9.x, PHP 7.4 a 8.3.
• Sem override do núcleo do PrestaShop.
• Multiloja: os produtos criados são associados às lojas do contexto.
• Interface traduzida para inglês e francês.