Import PrestaShop CSV XML JSON Excel : réconciliation et gestion des déclinaisons

Table des matières :

1. Choisir un canal d’import PrestaShop (CSV Back‑Office, API, module, ETL)
2. Normaliser CSV/XML/JSON/Excel : mapping, encodage et règles de réconciliation
3. Déclinaisons PrestaShop : modèle SQL, unicité des combinaisons et import sans casse
4. Importer à grande échelle : idempotence, staging SQL, transactions et performance

Choisir un canal d’import PrestaShop (CSV Back‑Office, API, module, ETL)

Sur PrestaShop 8.1/8.2 et PrestaShop 9.x (PHP 8.2+ recommandé en production), le cœur reste orienté import CSV via Paramètres avancés → Import (catalogue, déclinaisons, catégories, clients, etc.). C’est robuste pour du “one shot”, beaucoup moins pour des synchronisations régulières avec un ERP/PIM/WMS : pas de transaction globale, peu de mécanismes d’upsert explicites, et une gestion des erreurs qui s’arrête souvent au niveau “ligne X invalide” sans contexte exploitable (clé de réconciliation, règle métier, contrainte violée). Si vous avez un catalogue volumineux, l’import BO est aussi une source classique de timeouts PHP/FPM et de verrous MySQL (pics de CPU, locks sur tables de stock, ralentissements du BO).

Dès que la source n’est pas du CSV (XML/JSON/Excel), il faut accepter une réalité simple : PrestaShop n’importe pas nativement le JSON, le XML « métier » ou le XLSX. Vous allez donc soit (a) convertir vers le CSV attendu par l’importeur, soit (b) passer par une API (Webservice historique REST/XML ou API d’administration PrestaShop 9), soit (c) développer un module d’import/ETL. Pour les synchronisations industrielles (delta stock/prix, mapping attributs, gestion multi-boutique), le meilleur point de départ côté “stack PrestaShop” est souvent l’API : voir Webservice PrestaShop : activer l’API et créer une clé d’accès et, si vous êtes déjà sur PrestaShop 9, API d’administration PrestaShop 9 : OAuth, API Platform v3, endpoints CQRS.

Pour décider vite, raisonnez en cadence et en niveau d’intégrité attendu. Une grille simple (et honnête) :

Canal	Idéal pour	Points forts	Limites typiques
Import BO (CSV)	Import ponctuel / migration	Simple, “dans le core”, reproductible manuellement	Peu idempotent, erreurs peu actionnables, timeouts, création implicite d’attributs
Webservice historique	Upserts unitaires, intégration “rapide”	Contrat stable, permissions par clé, pilotable en cron	XML-centric, débit limité, complexité sur déclinaisons/images
Admin API PrestaShop 9	Intégration moderne, outillage	OAuth, approche plus “API-first”, meilleure industrialisation	Nécessite PrestaShop 9 + montée en compétence
Module/ETL custom	Imports réguliers + règles métier	Idempotence stricte, staging, règles de réconciliation, observabilité	Coût initial, maintenance, tests indispensables

• Import BO CSV : OK pour un lot ponctuel, dangereux pour du quotidien (erreurs silencieuses, états intermédiaires).
• Webservice : bon compromis pour des upserts unitaires, mais le payload est historiquement en XML et le débit est limité (latence + overhead).
• Import custom (module/ETL) : indispensable si vous devez faire de la réconciliation multi-clés + règles métier + idempotence stricte.

Cas fréquent (contexte FR) : un ERP “sort” un Excel de prix en virgule décimale (ex. 12,90) et un export stock en CSV, tandis qu’un PIM fournit un JSON produit. Dans ce cas, tenter de “tout faire” via l’import BO devient vite fragile ; l’approche la plus sûre est plutôt un pipeline : conversion/normalisation → staging → écriture via API ou module.

Si vous avez déjà une brique d’orchestration (n8n, cron, CI), vous pouvez industrialiser un pipeline “fichier → normalisation → API”. Pour l’aspect intégration SI (ERP/WMS/TMS, webhooks, fichiers, API), le cadre de réflexion est proche de Portail client : intégration ERP/WMS/TMS via API, fichiers et webhooks.

Normaliser CSV/XML/JSON/Excel : mapping, encodage et règles de réconciliation

La partie la plus coûteuse n’est presque jamais “l’import PrestaShop” : c’est la normalisation et la réconciliation. Réconcilier, ici, veut dire “déterminer sans ambiguïté quel enregistrement source correspond à quel objet PrestaShop” (produit, déclinaison, image, stock), et ce de manière stable dans le temps. Sans identifiant stable, vous finirez par du dédoublonnage manuel et des combinaisons incohérentes.

Commencez par choisir une clé canonique par niveau :

• Produit : reference (SKU) ou EAN13 si fiable, idéalement une clé interne PIM (mais il faudra la stocker quelque part, souvent dans reference ou dans un champ personnalisé).
• Déclinaison : un identifiant variante (“SKU variante”), ou une concaténation stable (ex. SKU-PARENT|COLOR=Noir|SIZE=M).
• Fournisseur : supplier_reference si vous consolidez plusieurs flux.

En pratique, si vous avez déjà des SKU variantes (souvent le cas avec des ERP), exploitez-les : PrestaShop permet aussi une reference au niveau déclinaison. C’est l’un des leviers les plus efficaces pour rendre l’import de déclinaisons réconciliable et donc rejouable.

Ensuite, imposez des règles de typage et d’encodage. Excel “répare” des données (arrondis, dates, zéros non significatifs) et c’est souvent une cause directe de réconciliation ratée. Exportez en CSV UTF‑8, délimiteur explicite (souvent ; en FR), séparateur décimal cohérent, et interdisez les cellules “numériques” pour des identifiants (EAN, SKU).

Pièges très concrets (et très courants) côté Excel/CSV :

• EAN/SKU transformés : 0012345 devient 12345 ; un EAN peut passer en notation scientifique (3,56012E+12).
• Encodage : accents cassés si le CSV est en ISO-8859-1/Windows-1252 au lieu d’UTF‑8.
• Séparateurs : prix 12,90 interprété comme 1290 si vous parsez avec un mauvais séparateur décimal.
• Espaces invisibles : Noir vs Noir (espace final) → double création d’attribut.

Si vous êtes plusieurs à manipuler le fichier, mettez une validation automatisée (script, job CI, étape n8n) qui refuse par exemple :

• colonnes manquantes / colonnes renommées ;
• SKU vide ou doublonné dans un même lot ;
• EAN non conforme (13 chiffres attendus pour l’EAN‑13, avec contrôle de longueur au minimum) ;
• prix négatif, prix à 0 non autorisé, devise incohérente ;
• attribut de variante vide (ex. taille manquante) ;
• catégorie inconnue (si vous faites du mapping catégories).

Dans l’import PrestaShop, ce qui tue la qualité, ce sont les décisions implicites. Exemple concret : la couleur “Noir” vs “noir” vs “BLACK” finit par créer plusieurs attributs distincts si vous n’appliquez pas une table de correspondance (“dictionary”). Même combat pour les tailles (“M” vs “Medium”). Une approche pragmatique est d’implémenter un mapping source → PrestaShop versionné, stocké dans Git (ou au minimum dans une table dédiée).

Un exemple minimal de “dictionary” (à adapter à votre métier), utile quand vous convertissez XML/JSON/Excel vers un CSV d’import :

Valeur source	Groupe	Valeur cible PrestaShop	Remarques
BLACK, Noir, noir	Couleur	Noir	trim() + normalisation casse
M, Medium	Taille	M	éviter de créer “Medium” en plus
TU, Unique	Taille	Taille unique	utile pour filtrage

Pour un flux XML/JSON, validez avec un schéma (XSD/JSON Schema) avant conversion vers CSV : vous obtenez des erreurs structurées (champ manquant, type invalide), au lieu d’un import BO qui échoue en plein milieu sans “pourquoi” exploitable. Et surtout, vous séparez deux sujets : qualité des données (amont) vs écriture dans PrestaShop (aval).

Enfin, formalisez vos règles de réconciliation (c’est ce qui évite les surprises au 3ᵉ import) :

• Si un SKU existe déjà : mise à jour (ne pas recréer).
• Si un SKU n’existe plus dans la source : désactivation (plutôt que suppression), éventuellement après un délai.
• Si une variante change de libellé attribut (ex. “Noir” → “Noir profond”) : update dictionnaire (ne pas créer une nouvelle valeur).
• Si un produit passe de “sans déclinaisons” à “avec déclinaisons” : décider explicitement comment gérer stock/prix du parent vs des variantes.

Déclinaisons PrestaShop : modèle SQL, unicité des combinaisons et import sans casse

Dans PrestaShop, une “déclinaison” (combinaison) n’est pas un simple champ : c’est un ensemble de lignes dans plusieurs tables. Sur PrestaShop 8/9 (schéma proche), le noyau logique est :

• ps_product : produit parent.
• ps_product_attribute : la combinaison (une ligne = une déclinaison).
• ps_product_attribute_combination : table de jointure entre une combinaison et les attributs.
• ps_attribute / ps_attribute_group (+ tables _lang) : dictionnaire des attributs (Couleur, Taille…).
• ps_stock_available : stock (produit ou combinaison), dépend du paramètre “stock avancé”, du multi-boutique et des packs.

Ce modèle implique une règle d’or : une combinaison = un set d’attributs. Si vous importez deux fois la même combinaison (même parent + mêmes attributs), vous pouvez créer des doublons, surtout si votre pipeline n’a pas de clé de réconciliation côté combinaison.

Deux approches “anti-doublons” qui fonctionnent bien en production :

• Clé variante stable : imposer une reference unique par déclinaison (ex. TSHIRT-001-BLK-M) et s’en servir comme identifiant de réconciliation côté import (API ou module).
• Signature canonique d’attributs : construire une signature déterministe, indépendante de l’ordre (ex. trier les attributs, puis concaténer id_attribute ou valeurs normalisées). Utile si vous n’avez pas de SKU variante en amont, mais plus fragile (car dépend du dictionnaire).

Côté BO, l’import CSV des déclinaisons ne vous protège pas réellement contre toutes les collisions (notamment quand des attributs sont créés “à la volée”). C’est la raison pour laquelle beaucoup d’équipes finissent par importer d’abord le dictionnaire (groupes/valeurs), puis les produits, puis les déclinaisons.

Un autre piège structurel : la combinaison par défaut. PrestaShop attend qu’un produit avec déclinaisons ait une combinaison par défaut cohérente, sinon vous obtenez des fiches produit instables (prix affiché, images, stock) et des comportements erratiques au checkout. Lors de l’import, définissez explicitement la déclinaison par défaut (ou appliquez une règle déterministe : “celle avec stock > 0”, ou “la plus vendue”, ou “la moins chère” selon votre politique). Si vous laissez le core décider, vous aurez des changements de défaut non maîtrisés au gré des réimports.

Un contrôle simple (et très utile) après un import massif : identifier les produits “à déclinaisons” sans déclinaison par défaut correctement définie. Selon la version et le contexte multi-boutique, l’information peut être portée par un cache côté produit et/ou des champs “default”. L’idée opérationnelle reste la même : un produit avec combinaisons doit pouvoir désigner une combinaison par défaut stable.

Enfin, n’oubliez pas l’impact front/SEO. Les déclinaisons influencent l’UX (sélecteurs d’attributs, disponibilité) et parfois l’indexation si vous exposez des URLs paramétrées. Pour l’affichage et la logique “variantes en listing”, il existe des approches spécifiques (et des modules) : voir Module PrestaShop attributs : afficher les déclinaisons en liste produits. Et si votre import modifie titres, images ou données structurées, lisez aussi SEO PrestaShop : optimiser fiches produits, schema.org et images WebP.

Importer à grande échelle : idempotence, staging SQL, transactions et performance

L’objectif d’un import “sérieux” n’est pas de passer une fois, mais de pouvoir rejouer sans casse. C’est la définition opérationnelle de l’idempotence : rejouer un flux identique doit aboutir au même état. Avec PrestaShop, l’import BO n’est pas idempotent par design (créations implicites, mises à jour partielles, dépendances non explicites).

La solution classique en environnement pro est de construire une phase staging : vous chargez d’abord vos données normalisées dans une table stg_* (ou une base temporaire), puis vous faites des opérations SQL/API contrôlées (upsert, désactivation de produits absents, mise à jour conditionnelle des prix/stock).

Un pattern simple et efficace :

1. Charger stg_products, stg_variants, stg_prices, stg_stock (avec un import_id horodaté).
2. Valider (contraintes : SKU non nul, attributs connus, prix cohérents, unicité des clés).
3. Réconcilier : établir des correspondances sku → id_product et sku_variante → id_product_attribute (dans des tables de mapping).
4. Écrire : appliquer mises à jour et créations dans PrestaShop via API/module (ou SQL si vous maîtrisez parfaitement les impacts).
5. Conclure : marquer les lignes traitées, produire un rapport (créés, mis à jour, ignorés, erreurs).

Sur MySQL/MariaDB, vous voulez aussi tirer parti des transactions là où c’est possible (au moins par lots), et vous appuyer sur le fait qu’InnoDB gère les transactions et les verrous au niveau ligne. Attention : PrestaShop lui-même n’encapsule pas “un import complet” dans une transaction unique, et il y a des effets de bord (écriture d’images, recalculs, hooks). Mais pour vos propres étapes de staging (merge de dictionnaire attributs, tables de mapping), vous pouvez sécuriser fortement l’intégrité.

Quelques bonnes pratiques “gros volume” (déclinaisons, stock, prix) :

• Batcher : préférez 500–2 000 lignes par lot (à ajuster), plutôt qu’un seul méga import.
• Éviter les recalculs permanents : si vous mettez à jour des milliers de produits, planifiez la réindexation (recherche, prix spécifiques) une fois, après.
• Stabiliser l’instantané : faites vos imports sur un créneau calme, voire avec boutique en maintenance si l’écart de prix/stock ne doit jamais être visible “à moitié”.
• Observer : si vous ne mesurez pas, vous ne corrigerez pas (temps par lot, erreurs par type, requêtes lentes, mémoire).

Côté performance, la stratégie change avec la taille du catalogue. Au-delà de quelques dizaines de milliers de déclinaisons, l’import devient un problème de DB + cache + index. Activez et surveillez le slow query log pendant les imports, parce que les réconciliations naïves finissent en scans sur ps_product_attribute_combination. Référence utile : Requêtes MySQL lentes PrestaShop : activer slow query log. Et si vous êtes dans une configuration “gros catalogue”, travaillez votre infra (Redis, OPcache, workers PHP, index DB) : PrestaShop performance : optimiser gros catalogues et Core Web Vitals.

Un détail “terrain” : si vous restez sur l’import BO, les limites max_execution_time, memory_limit, et les timeouts proxy/CDN peuvent vous piéger. L’approche la plus stable consiste à exécuter la partie lourde hors navigateur (ETL, scripts, jobs) et à utiliser le BO surtout pour contrôler, pas pour traiter 100% du volume.

Pipeline pratique : Excel/JSON/XML → normalisation → import + contrôles post‑import

Un pipeline efficace découpe le problème en étapes testables. Exemple réaliste : vous recevez un XLSX (tarif + stock) et un JSON (catalogue enrichi).

Étape 1 : convertir vers un format de travail stable (CSV UTF‑8) en neutralisant les “bizarreries Excel”. Avec Python/pandas (hors PrestaShop), on fait typiquement :

import pandas as pd

df = pd.read_excel("catalogue.xlsx", dtype={"sku": "string", "ean": "string"})
df["sku"] = df["sku"].str.strip()
df.to_csv("catalogue.normalise.csv", sep=";", index=False, encoding="utf-8")

Si vous manipulez des prix FR (virgule), l’objectif est de choisir une convention dans votre pipeline (souvent “point” côté ETL), puis de produire un CSV d’import cohérent. Le plus important : ne jamais laisser un tableur décider à votre place.

Étape 2 : appliquer une table de correspondance attributs (ex. BLACK → Noir, XL → XL) et produire un fichier “combinaisons” explicitant parent, attributs et identifiant variante. Là, vous évitez une erreur fréquente : importer des déclinaisons en espérant que PrestaShop “devine” les groupes/valeurs. Il ne devine rien : il crée, et vous vous retrouvez avec un dictionnaire sale.

À ce stade, ajoutez un contrôle “métier” très rentable : vérifier que chaque ligne variante a exactement les attributs attendus. Exemple : si votre gamme impose Couleur + Taille, refusez les variantes avec seulement Couleur (sinon vous créez des combinaisons “incomplètes” qui perturbent l’expérience d’achat).

Étape 3 : choisir la mécanique d’écriture. Si vous restez en CSV BO, faites-le sur un environnement de staging, avec sauvegarde DB, et évitez les imports en journée. Si vous passez par API, vous pouvez piloter du upsert au niveau produit/combinaison en réconciliant sur reference.

• Webservice (historique) : pratique mais XML-centric. Pour les prérequis (clé, permissions, endpoints), voir le guide activer le Webservice PrestaShop et générer une clé
• PrestaShop 9 Admin API : plus moderne (OAuth, endpoints CQRS). Si vous êtes en 9.x, c’est généralement la voie la plus propre pour industrialiser : API d’administration PrestaShop 9

Après import, ne “faites pas confiance” à l’interface. Ajoutez des contrôles objectifs (idéalement automatisés) :

1. Stock : vérifier ps_stock_available cohérent produit/combinaison, et que la déclinaison par défaut a un stock attendu. En multi-boutique, pensez à valider par id_shop (un stock juste sur une boutique peut être faux sur une autre).
2. Prix : vérifier l’absence de prix à 0 involontaire, d’écarts HT/TTC (TVA), et de règles spécifiques (prix spécifiques, remises catalogues). En contexte FR, un mauvais mapping de taxe (20%, 10%, 5,5%…) se voit souvent après coup : mieux vaut détecter les anomalies par tranche (ex. “trop de produits à 0%” ou “prix TTC incohérents”).
3. Déclinaisons : vérifier doublons de combinaisons (mêmes attributs) et existence d’une combinaison par défaut stable.
4. Recherche : si vous modifiez massivement des noms/références, réindexez et testez la pertinence. Vous pouvez vous appuyer sur l’analyse du moteur interne (structure SQL, index) : Index de recherche PrestaShop : fonctionnement, tables SQL et pondérations.

Enfin, outillez la détection d’erreurs : un import massif déclenche souvent des notices PHP, des erreurs SQL, ou des problèmes de mémoire. En production, vous voulez une visibilité centralisée (logs PHP-FPM, MySQL, JS) et des alertes : PrestaShop monitoring d’erreurs : logs PHP, MySQL, JavaScript et alertes e-mail.

Et si vous devez nettoyer après des imports ratés (images orphelines, tables gonflées, fichiers temporaires), le sujet est directement adjacent à MedCleanMyShop PrestaShop : nettoyage base de données et fichiers automatisé.

Un dernier conseil opérationnel : conservez systématiquement (1) le fichier source, (2) le fichier normalisé, (3) le rapport d’import (créés/mis à jour/erreurs) avec un identifiant d’exécution. Quand un écart est signalé (“le stock a disparu”, “les tailles ont doublonné”), vous pourrez remonter quelle transformation l’a introduit — et corriger sans tâtonner.