Vous pouvez importer votre catalogue produit à l'aide d'un fichier CSV, en réutilisant un fichier existant, qu'il s'agisse d'un format Google Shopping ou d'un autre format que vous utilisez déjà.

Si vous devez créer un nouveau fichier CSV spécifiquement pour le catalogue, la description du flux de données ci-dessous précise les informations essentielles à inclure.

Le catalogue de produits fournit à votre Assistant les données nécessaires pour assister les clients dans leur recherche et répondre aux questions concernant les caractéristiques des produits. Une structuration optimale de ce fichier CSV est donc cruciale pour garantir un fonctionnement efficace.

1. Description du flux de données

1.1. Format du fichier

Le fichier CSV doit comporter une ligne d'en-tête indiquant le contenu de chaque colonne, suivie d'une ligne pour chaque produit. Les colonnes doivent lister les caractéristiques des produits telles que le Titre, la Description, le Prix, etc.

Un exemple de fichier CSV est disponible depuis ce lien. Assurez-vous d'utiliser le format CSV avec encodage UTF-8 pour éviter toute erreur lors de l'importation.

1.2. Données attendues

Les champs obligatoires :

id : Identifiant unique du produit
title : Titre
description : Description
link : URL de la page produit sur votre site

Les autres champs non obligatoires mais fortement conseillés :

item_group_id : ID de groupe (pour regrouper les variants du même produit : tailles, couleurs, matériaux, états)
availability : Disponibilité
Valeurs standards : in_stock, out_of_stock, preorder, backorder

Le système accepte également :
- Variations d'écriture : majuscules/minuscules, avec ou sans tirets/espaces (ex : in stock, IN-STOCK)
- Valeurs numériques : 0 ou négatif = rupture de stock | nombre positif = en stock
- Synonymes multilingues : yes, true, disponible = en stock | no, false, non = rupture de stock
Le système normalise automatiquement ces valeurs vers l'un des 4 statuts standards.
availability_date : Date de disponibilité
price : Prix
sale_price : Prix soldé
image_link : URL de l'image principale du produit

Nécessaire pour la fonctionnalité product discovery de votre Assistant Shopping IA
additional_image_link : URL(s) des images complémentaires du produit

Nécessaire pour la fonctionnalité product discovery de votre Assistant Shopping IA
product_types : Catégorie du produit

Exemple de valeur : Accueil > Homme > Vêtements > Chemises
gender : Genre

Valeurs supportées : male, female, unisex
brand : Marque
color : Couleur

Couleur principale listée en premier
size : Taille
material : Matière

Peut être composé d'un matériau principal et de matériaux secondaires séparés par une virgule, slash…
condition : État

Valeurs supportées : new, refurbished, used
crosssellproducts : vente additionnelle (cross selling)
compatiblewith : Compatibilité (en savoir plus)

Ces informations sont essentielles pour offrir une expérience optimale à vos visiteurs. Si elles ne sont pas correctement renseignées pour la majorité des produits, le catalogue ne pourra pas être activé ni utilisé par votre Assistant.

Le fichier CSV peut contenir des colonnes supplémentaires pour enrichir votre Assistant. Vous avez deux options :

Utiliser la fonctionnalité de mapping pour définir le contenu des colonnes supplémentaires, comme la couleur ou la taille.
Laisser notre système enregistrer ces informations comme données complémentaires. Dans ce cas, veillez à ce que le nom des colonnes soit explicite, par exemple : "Délai de fabrication" ou "Puissance de l'alimentation".

Une fois votre catalogue produit créé, utilisez l'explorateur de connaissances pour vérifier que toutes les informations fournies sont correctement intégrées dans la base de connaissance.

1.3. Mise à jour des données

Trois méthodes d'import sont disponibles pour votre fichier CSV : Fichier local, URL et SFTP. Le mode d'import choisi détermine la façon dont vos données peuvent être mises à jour.

Fichier local

Lorsque vous importez un fichier depuis votre ordinateur, la mise à jour de vos données est manuelle. Pour actualiser le catalogue, vous devez importer un nouveau fichier directement depuis votre source de connaissance.

URL

Lorsque vous importez votre fichier CSV via une URL, iAdvize re-télécharge automatiquement le fichier hébergé à cette adresse selon la fréquence que vous configurez.

Par défaut, la mise à jour est quotidienne à 03h00 (GMT+02:00, Europe/Paris).

Pour la méthode URL, vous pouvez personnaliser la fréquence de mise à jour depuis vos connaissances :

Sélectionnez la fréquence souhaitée : Quotidienne ou Hebdomadaire.
Définissez l'heure de mise à jour et le fuseau horaire.
Cliquez sur Sauvegarder en haut à droite de l'écran.

Paramétrage de la fréquence de mise à jour via URL

SFTP

La méthode SFTP (Secure File Transfer Protocol) permet à iAdvize de se connecter directement à votre serveur SFTP chaque jour pour récupérer automatiquement votre fichier catalogue. Cette méthode est adaptée lorsque vos fichiers sont hébergés sur un serveur SFTP interne.

Pour configurer l'import via SFTP, renseignez les champs suivants :

Hôte : adresse de votre serveur SFTP (ex. : sftp.monentreprise.com)
Port : port de connexion (ex. : 22)
Nom d'utilisateur : identifiant de connexion au serveur
Mot de passe : mot de passe associé à cet identifiant
Répertoire : chemin vers le dossier contenant votre fichier catalogue (ex. : / pour la racine)
Motif de nom de fichier (optionnel) : permet de cibler un fichier précis via une expression régulière (ex. : catalog_.*\.csv). Si plusieurs fichiers correspondent au motif, le fichier le plus récemment modifié est importé.
Séparateur de colonnes CSV : sélectionnez le séparateur utilisé dans votre fichier.

Par défaut, la mise à jour est quotidienne à 03h00 (GMT+02:00, Europe/Paris).

Pour la méthode SFTP, vous pouvez personnaliser la fréquence de mise à jour depuis vos connaissances :

Sélectionnez la fréquence souhaitée : Quotidienne ou Hebdomadaire.
Définissez l'heure de mise à jour et le fuseau horaire.
Cliquez sur Sauvegarder en haut à droite de l'écran.

1.4. Gestion des variants de produits

Lorsqu'un produit existe en plusieurs déclinaisons (taille, couleur, matière, etc.), chaque variant doit être représenté par une ligne distincte dans le fichier CSV. Tous les variants d'un même produit sont reliés entre eux grâce au champ item_group_id, qui doit porter la même valeur pour l'ensemble du groupe.

Règles de structuration à respecter :

Chaque variant dispose d'un id unique qui l'identifie individuellement.
Tous les variants d'un même produit partagent le même item_group_id.
Le champ item_group_id doit être renseigné sur chaque ligne de variant.

Exemple :

Un jean disponible en trois couleurs est structuré comme suit dans le catalogue :

id	title	color	item_group_id
79052-BRU	Jean coupe droite – Brut	Brut	79052
79052-NOI	Jean coupe droite – Noir	Noir	79052
79052-DEL	Jean coupe droite – Délavé	Délavé	79052

Chaque variant a un id propre et tous partagent le même item_group_id : 79052.

⚠ Ne pas inclure de ligne "parent" ou "groupe" dans le catalogue.

Certains formats de catalogue incluent une ligne supplémentaire dont l'id correspond à la valeur d'item_group_id des variants, sans que cette ligne ne soit elle-même un vrai variant achetable (pas de couleur, taille, stock propres).

Ce type de ligne n'est pas conforme à la structure attendue par l'Assistant et peut provoquer des comportements indésirables :

L'Assistant peut identifier cette ligne lors de la recherche de produits, mais l'ajout au panier (Add-To-Cart) ne pourra pas fonctionner correctement, car cette ligne ne correspond à aucun variant réel.
La sélection de variants proposée au visiteur sera incorrecte ou absente.

Si votre catalogue contient ce type de ligne, supprimez-la. Seules les lignes correspondant à de vrais variants achetables doivent être présentes.

NB La fonctionnalité Add-To-Cart identifie les produits via le champ id (identifiant unique de variant) et non via le champ item_group_id. Il est donc indispensable que chaque ligne du catalogue représente un variant réel, avec un id propre et un item_group_id renseigné.

2. Création du catalogue produit avec le fichier CSV

Si une authentification est requise pour accéder à votre fichier via URL, ajoutez les informations nécessaires dans les headers.

Si votre fichier n'utilise pas le format CSV standard (virgule, point-virgule, tabulation, etc.), adaptez le séparateur de champs pour garantir une lecture correcte.

Lorsque les colonnes de votre fichier respectent des libellés standard, elles sont automatiquement reconnues et associées aux champs correspondants. Les colonnes supplémentaires non configurées dans le mapping seront ajoutées comme informations complémentaires, à condition que leur nom soit suffisamment explicite pour être interprété correctement.

Vos informations doivent être régulièrement à jour pour garantir que votre Assistant dispose toujours des informations les plus récentes sur vos produits.

NB Lors de l'import de votre fichier CSV (via URL, fichier local ou SFTP), un contrôle préliminaire est effectué sur les 10 000 premières lignes du fichier. Cela permet de détecter immédiatement les erreurs potentielles avant de lancer l'ingestion complète, ce qui rend le processus plus fluide, notamment pour les fichiers volumineux.

3. Gestion des erreurs

En cas d'erreur, un message explicatif précise les raisons du problème.

Erreurs liées au fichier CSV

Les erreurs les plus fréquentes incluent :

Séparateur incorrect : Le séparateur spécifié ne correspond pas au format du fichier.
Non-respect du format CSV : Certaines lignes ne contiennent pas le même nombre de colonnes. Chaque ligne doit avoir un nombre fixe de colonnes, même si certaines sont vides.
Encodage non conforme : Le fichier n'est pas encodé en UTF-8.
Format de champ non respecté : Le contenu d'un ou plusieurs champs ne suit pas les spécifications attendues (voir les exigences des champs du catalogue produit).

Erreurs liées à la connexion SFTP

Le tableau ci-dessous recense les messages d'erreur pouvant survenir.

Message d'erreur	Cause probable	Action corrective
`Error while retrieving file from SFTP host=… : Exhausted available authentication methods`	Le nom d'utilisateur ou le mot de passe est incorrect.	Vérifiez et corrigez les identifiants de connexion renseignés dans la configuration.
`Error while retrieving file from SFTP host=…`	Le nom de l'hôte est incorrect ou le serveur est inaccessible.	Vérifiez l'adresse de l'hôte et assurez-vous que le serveur SFTP est accessible depuis Internet.
`Error while retrieving file from SFTP host=… : No eligible files with extension csv or xml has been found on the ftp server`	Le répertoire renseigné est incorrect ou aucun fichier ne correspond au motif de nom de fichier défini.	Vérifiez le chemin du répertoire et le motif de nom de fichier. Assurez-vous qu'un fichier `.csv` ou `.xml` est bien présent dans le dossier cible.

Tips En cas d'erreur persistante sur la connexion SFTP, vérifiez que votre serveur autorise les connexions entrantes depuis les adresses IP iAdvize. Contactez votre équipe technique si nécessaire.