Passer au contenu principal

​
1. Introduction

Cette documentation décrit comment structurer vos fichiers de données — produits, commandes, retours et données associées — dans notre environnement SFTP une fois votre espace dédié provisionné. Si vous exploitez plusieurs boutiques, ou disposez de plusieurs environnements (prod, preprod, etc.), veuillez créer un sous-dossier séparé pour chacun (il peut également s’agir de marques différentes, de pays différents, etc.).

​
Exemple de structure de répertoire

/root_space
    /shop_fr
    /shop_en
    /shop_it

​
2. Calendrier de transmission des données

Les fichiers de données doivent idéalement être transmis quotidiennement entre :
  • 02h00
  • 05h00
Ce créneau garantit un traitement et une ingestion des données optimaux.

​
3. Normes d’organisation des fichiers

Dans chaque répertoire de boutique, veuillez créer les dossiers suivants :
  • products
  • orders
  • returns
  • return_reasons (optionnel)
  • misc (optionnel)
Remarques :
  • Le dossier return_reasons est utilisé pour les fichiers d’export contenant des données de retour supplémentaires telles que les raisons fournies par les clients. Ces exports sont optionnels.
  • Le dossier misc peut contenir des fichiers divers. Si vous souhaitez utiliser ce dossier, veuillez en discuter la hiérarchie et la structure avec nous au préalable afin d’assurer la compatibilité.
Chaque export doit être placé dans le dossier approprié et horodaté avec un nom de fichier incluant un timestamp.

​
Exemple de format de nom de fichier

products_2025-01-15T02-00-00.csv

​
4. Exigences relatives au contenu des exports

Une spécification détaillée des champs attendus, des formats et des contraintes pour chaque type de jeu de données est disponible dans la documentation Transferts de données : Modèle. Exigences clés pour les exports du catalogue produits :
  • Exporter toutes les variantes de produits, y compris les articles en rupture de stock
  • Inclure un champ date de dernière modification pour le traitement incrémental
  • Maintenir des informations complètes sur les variantes pour permettre une analyse correcte des tailles
  • Ajouter optionnellement un drapeau de désactivation pour le contrôle de la présence Kleep
Veuillez vous référer au modèle pour des définitions de champs complètes et des exemples.

​
5. Gestion des données répétées entre les exports

Des enregistrements peuvent légitimement apparaître dans plusieurs exports quotidiens. Par exemple, un retour donné peut être inclus plusieurs fois dans différents fichiers. Notre système d’ingestion gère automatiquement la déduplication et traite uniquement la version la plus récente de chaque enregistrement.

​
6. Directives sur le format des données

Tous les exports doivent être fournis au format CSV. Les fichiers Excel (.xlsx) sont déconseillés car ils introduisent des incohérences de formatage et peuvent compliquer les workflows d’ingestion automatisée.
  • Date/heure : Utilisez le format ISO 8601 : YYYY-MM-DDTHH:MM:SSZ, exemple : 2025-01-15T14:30:00Z
  • Encodage : Encodage UTF-8 pour tous les champs texte, échapper correctement les caractères spéciaux en CSV
  • Valeurs booléennes : Utilisez true/false (minuscules) ou True/False
  • Valeurs décimales : Utilisez le point (.) comme séparateur décimal. Exemple : 129.99 et non 129,99
  • Valeurs nulles : Chaîne vide pour les champs texte optionnels manquants en CSV, utiliser null en JSON

​
Convention de nommage des fichiers

Comme spécifié dans la documentation de la structure des données SFTP, utilisez le format suivant : 
{data_type}_{timestamp}.csv
Exemples :
  • products_2025-01-15T02-00-00.csv
  • orders_2025-01-15T02-00-00.csv
  • returns_2025-01-15T02-00-00.csv

​
7. Export des données historiques

Si vous devez fournir des données historiques (c’est-à-dire des données ne faisant pas partie des exports quotidiens), vous pouvez exporter jusqu’à un an de données historiques pour tous les types de données, notamment :
  • Produits
  • Commandes
  • Retours
Les jeux de données historiques peuvent être transmis via le SFTP ou, si c’est plus pratique, via un autre medium convenu.

​
Exemple d’une structure SFTP complète

/root_space
    /shop_fr
        /products
            products_2025-01-15T02-00-00.csv
            products_2025-01-16T02-00-00.csv
        /orders
            orders_2025-01-15T02-00-00.csv
            orders_2025-01-16T02-00-00.csv
        /returns
            returns_2025-01-15T02-00-00.csv
            returns_2025-01-16T02-00-00.csv
        /return_reasons
            return_reasons_2025-01-15T02-00-00.csv  (optionnel)
        /misc
            (optionnel, veuillez en discuter la hiérarchie avec nous)

    /shop_en
        /products
        /orders
        /returns
        /return_reasons
        /misc

    /shop_it
        /products
        /orders
        /returns
        /return_reasons
        /misc