Synchronisation par CSV : spécification complète

Pour la synchronisation entre les clients et Portal Hero, nous utilisons un système de fichiers CSV. Le principal fichier CSV est celui des articles (ou flux d'articles), où sont listés tous les articles publiés sur les différents portails. Ce fichier contient les articles avec leurs caractéristiques.

Fonctionnement de la synchronisation

La manière d'identifier chaque article se fait via le champ id, sur lequel nous nous baserons comme identifiant unique pour décider si un article est mis à jour ou cesse d'exister. Lorsqu'un article apparaît pour la première fois dans le flux d'articles, il est envoyé sur tous les portails sélectionnés par le client. Lorsqu'un article n'est plus présent dans le flux, il est marqué comme vendu, et lorsqu'une donnée de l'article change, il est également mis à jour sur les portails. Pour plus de détails sur la synchronisation elle-même, vous pouvez les consulter ici.

Le format général de ces fichiers CSV est le suivant :

• Champs séparés par des virgules
• L'en-tête doit être présent pour pouvoir identifier les champs
• Champs délimités par des guillemets doubles (si nécessaire ou toujours)
• Encodage du fichier UTF-8

Partage des fichiers

Nous avons deux options pour nous transmettre le fichier :

• SFTP
  Nous disposons d'un SFTP pour partager les fichiers et faciliter l'échange d'informations de manière sécurisée. Les données d'accès au SFTP (identifiant et mot de passe) seront fournies lors du processus d'onboarding.
  Les autres données de connexion communes sont les suivantes :
  • Host : sftp.portalhero.pro
  • Port : 2222
  
  De plus, le SFTP est sécurisé et restreint au niveau réseau et nous aurons besoin d'une ou plusieurs IPs pour les ajouter à notre liste d'IPs d'accès autorisées.
  À l'intérieur du SFTP, un dossier nommé upload est créé où les fichiers seront écrits : pour celui des articles, le nom du fichier sera : item_feed.csv
• url
  Le flux d'articles peut également être envoyé via une URL publique depuis laquelle le processus de Portal Hero le téléchargera à chaque exécution quotidienne du processus.
  L'URL devra être renseignée par le client lors du processus d'onboarding. Si des mesures de sécurité supplémentaires sont nécessaires, vous pouvez nous fournir n'importe quel(s) header(s) que nous ajouterons à la requête.

Format des fichiers CSV

Liste des champs, typologie des détails et exemples du fichier CSV d'articles :

* Pour les articles de voitures, les attributs suivants doivent être fournis dans le champ 'attributes' sous forme de chaîne JSON sérialisée :

Concernant le champ status qui fait référence à l'état des articles, les options sont les suivantes :

["new", "as_good_as_new", "good", "fair", "has_given_it_all"]

Attributs de la voiture

Les attributs de la voiture sont un ensemble de caractéristiques qui décrivent une voiture. Ils sont utilisés dans le flux et pour la publier sur les marketplaces.

Exemple (python) :

car_attrs = {
    "version": "1.6 TDI Toyota",
    "year": "2018",
    "horse_power": 100,
    "mileage": 12000,
    "engine": "gasoil",
    "gearbox": "manual"
}

attributes = json.dumps(car_attrs)

Attributs de la moto

Pour intégrer des motos, l'article doit inclure les informations spécifiques du véhicule. Les données techniques sont envoyées sérialisées en JSON dans le champ 'attributes', tandis que la marque et le modèle voyagent dans les champs 'brand' et 'model' du CSV.

Le champ 'external_category' doit prendre l'une des valeurs '2', 'Motos', 'Motorbikes' pour que l'article soit traité comme une moto. Cette intégration nécessite d'avoir le service ERP de motos actif sur votre compte.

Les valeurs de 'brand' et 'model' doivent correspondre exactement à celles de notre taxonomie de motos. Pour consulter les valeurs valides, nous disposons de deux endpoints publics (ils nécessitent une authentification et le service ERP de motos actif) :

• GET /motorbike_brands — renvoie la liste complète des marques disponibles, avec leur 'uid' et 'value'.
• GET /motorbike_models?brand_id={uid} — renvoie les modèles associés à la marque indiquée au moyen de 'brand_id'.

Notez que le titre de l'article est généré automatiquement à partir de la marque, du modèle, de la version (si renseignée) et de l'année, de sorte que la valeur du champ 'title' sera écrasée pour les motos.

Exemple (python) :

motorbike_attrs = {
    "year": 2020,
    "version": "modelo actual",
    "km": 5420,
    "horse_power": 47,
    "engine_capacity_cc": 400,
    "fuel_type": "gasoline",
    "license_plate": "1234 ABC"
}

attributes = json.dumps(motorbike_attrs)