Synchroniser le catalogue et les produits par fichier

CitrusAd prend en charge trois types de formats pour la synchronisation des données produit via un fichier :

  • TSV
  • CSV
  • XML.

Cette section détaille les structures de chaque format de fichier pour les données de produits traitées dans CitrusAd.

Fichiers TSV/CSV

Le tableau ci-dessous liste les noms de colonnes et leur description pour les produits dans un fichier TSV/CSV. Dans ce tableau, nous spécifions également les colonnes obligatoires dans un fichier. Lorsqu'une colonne est obligatoire, ses valeurs doivent être fournies dans chaque ligne.

️ TSV sans guillemets

Les fichiers TSV ne peuvent pas contenir de guillemets. Lors d'une synchronisation via TSV, assurez-vous de synchroniser les fichiers sans guillemets.

Noms de colonnes et descriptions des données produit dans les fichiers TSV/CSV

Nom de la colonneObligatoire/facultatifType de donnéesDescriptionExemple
product_codeObligatoireTexteCode permettant d'identifier le produit dans votre système. Ce champ est identique aux champs gtin et item dans le cadre de la synchronisation des fichiers API et XML.F153212AN1
nameObligatoireTexteLe nom du produit.T-shirt autocollant SS - Enfants
image_urlObligatoireURLUn hyperlien vers l'image d'un produit. L'URL doit être valide.https://www.retailer.com/product/1234.jpg
inventoryObligatoireNuméroLe stock du produit. Si la valeur est de 0, aucune annonce de produit ne sera diffusée pour ce produit.1
descriptionObligatoireTexteLa description du produit.Avec son logo trèfle brodé et ses 3 bandes blanches, le short de sport est une nouveauté Adidas Originals.
KEY (as a value)Obligatoire pour les emplacements de catégories et d'affichages largesTexteSi ce type de colonne est utilisé, les détaillants doivent fournir une valeur pour .

Plusieurs colonnes peuvent présenter cette syntaxe dans un fichier TSV.
Le nom de la colonne peut être « brand » et la valeur de la cellule dans cette colonne peut être « green-fairy ». Cela se traduira par un filtre « brand:green-fairy » sur le produit.
subClassNameNécessaire pour les emplacements de vente croisée et incitativeTexteLe nom de la sous-classe/catégorie dans laquelle se trouve le produit concerné.

Les sous-classes permettent un meilleur ciblage des produits. Ainsi, un produit à base de beurre peut cibler le pain, mais il ne ciblera pas les pansements.
Fromage
xSellSubClassNameNécessaire pour les emplacements de vente croisée et incitativeTexteLes noms des sous-classes/catégories dans lesquelles le produit pertinent peut cibler des produits.Pains, pâtes à tartiner, crackers
priceFacultatifNuméroLe prix d'un produit.30,00
brandObligatoireTexteLa marque du produit.Tommy Hilfiger
typeObligatoireTexteLe type de produit.Vêtements
retailer_taxonomyRequis pour une meilleure attribution. Il ne doit pas y avoir d'espace entre > caractèresTexteVotre taxonomie personnelle du produit pour les détaillants.Hommes > Vêtements homme > Pulls
google_taxonomyRequis pour une meilleure attribution si retailer_taxonomy ne peut pas être fourniTexteLa taxonomie Google standard du produit. Vous trouverez plus d'informations ici : https://www.google.com/basepages/producttype/taxonomy.en-US.txtVêtements et accessoires > Vêtements > Hauts
global_identifierObligatoireTexteL'identifiant global du produit.08719108994761
global_identifier_typeObligatoireTexteLe type d'identifiant global.GTIN
custom_payloadFacultatif*Tableau d'octets codés en Base64Ce champ contient une charge utile personnalisée qui doit être transmise à la génération d'annonces. Le champ doit contenir un objet JSON valide sérialisé dans un tableau d'octets et encodé en Base64. L'objet JSON doit être conforme à un schéma.Voir la section sur les charges utiles personnalisées.
hfssFacultatifBooléenSert à indiquer si un produit présente une forte teneur en matières grasses, sucre ou sel. Ceci est également utilisé dans l'interface utilisateur de CitrusAd. Consultez notre documentation HFSS pour plus d'informations.true
seller_idFacultatifTexteID unique du vendeur. Cet identifiant est uniquement requis pour l'onboarding de vendeurs Marketplace. Il n'a pas besoin d'être renseigné pour la vente de produits en dehors de Marketplace.

Des exigences supplémentaires sont requises pour intégrer seller_ids. Consultez Marketplace SellerID pour plus d'informations.
aes-de4-ss

Voici un exemple de fichier représenté sous forme de tableau :

product_codenameimage_urlinventorydescriptionfilter:Categoryfilter:Sizefilter:Countrygroupspricebrandtyperetailer_taxonomygoogle_taxonomyglobal_identifierseller_idsubClassNamexSellSubClassName
80591101Coffret cadeau d'absinthe Green Fairy 500 mlhttps://www.retailer.com/product/1234.jpg20Ce coffret cadeau Green Fairy absinthe et cuillère est le cadeau parfait pour tout amateur d'absinthe ou de cocktails. Déposez un morceau de sucre sur la cuillère, versez l'absinthe par-dessus et dégustez ce spiritueux de manière traditionnelle !Cadeaux, Alcool, Coffrets cadeaux500 mlRépublique tchèqueCadeaux, Alcool, Coffrets cadeaux5.00Green FairyAlcoolCadeaux > Alcool > Coffrets cadeauxAliments, boissons et tabac > Boissons > Boissons alcoolisées > Liqueur et spiritueux > Absinthe85940014430797328s-dmie3-9jdaeCoffrets cadeauxLiqueur

📘

Les fichiers TSV ne peuvent pas contenir de guillemets.

Fichiers XML

CitrusAd a défini une liste de balises qui servent à décrire un document XML de produits. Le tableau ci-dessous présente les balises et leur description. La balise « item » est utilisée pour décrire un produit dans un document XML. Toutes les autres balises associées aux autres champs doivent être insérées à l'intérieur de cette balise.

Balises XMLObligatoire/facultatifDescription
itemObligatoireCes balises servent à décrire les produits. Toutes les autres balises XML d'un même produit doivent être insérées dans cette balise. Un document XML de produits doit contenir une liste de balises item. Ce champ est identique aux champs gtin et product_code dans le cadre de la synchronisation des fichiers API et TSV.
idObligatoireCode permettant d'identifier le produit dans votre système. Équivalent de product_code dans les fichiers TSV. Ce champ est identique aux champs gtin et item dans le cadre de la synchronisation des fichiers API et XML.
titleObligatoireLe nom du produit.
image_linkObligatoireUn hyperlien vers l'image d'un produit. L'URL doit être valide.
brandObligatoireLa marque du produit.
availabilityObligatoireCette balise définit le stock d'un produit. La valeur doit être un nombre.
descriptionObligatoireCette balise sert à décrire un produit.
priceFacultatifCette balise sert à définir le prix d'un produit. Si renseignée, la valeur doit être un nombre.
typeFacultatifLe type de produit.
retailer_taxonomyRequis pour une meilleure attribution. Également requis pour les intégrations de catégories.Votre taxonomie personnelle du produit pour les détaillants. par exemple Hommes > Vêtements homme > Pulls
google_taxonomyRequis pour une meilleure attribution si retailer_taxonomy ne peut pas être fourniLa taxonomie Google standard du produit. Vous trouverez plus d'informations ici : https://www.google.com/basepages/producttype/taxonomy.en-US.txt
global_identifierObligatoireL'identifiant global du produit. par exemple 08719108994761
global_identifier_typeObligatoireLe type d'identifiant global. par exemple GTIN
custom_payloadFacultatif*Ce champ contient une charge utile personnalisée qui doit être transmise à la génération d'annonces. Le champ doit contenir un objet JSON valide sérialisé dans un tableau d'octets et encodé en Base64. L'objet JSON doit être conforme à un schéma.
hfssFacultatifSert à indiquer si un produit présente une forte teneur en matières grasses, sucre ou sel. Ceci est également utilisé dans l'interface utilisateur de CitrusAd. Consultez notre documentation HFSS pour plus d'informations.
seller_idFacultatifID unique du vendeur. Cet identifiant est uniquement requis pour l'onboarding de vendeurs Marketplace. Il n'a pas besoin d'être renseigné pour la vente de produits en dehors de Marketplace.

Des exigences supplémentaires sont requises pour intégrer seller_ids. Consultez Marketplace SellerID pour plus d'informations.

Voici un exemple de document XML valide comportant ces balises :

<rss>
  <item>
      <id>80591011</id>
      <title>Melissa &amp; Doug Dinosaur Stamp Set, 4yrs+</title>
      <description>Imagine a rugged landscape littered with volcanoes, and full of dinosaurs roaming around</description>
      <image_link>https://www.retailer.com/productImages/image1.jpg</image_link>
      <price>&pound;9.99</price>
      <brand>Melissa &amp; Doug</price>
      <product_type>Food Cupboard</product_type>
      <availability>10</availability>
    	<hfss>true</hfss>
    </item>
    <item>
      <id>87086011</id>
      <title>Waitrose Splits Strawberry Ice Lollies</title>
      <description>Strawberry splits; Suitable for vegetarians. Strawberry splits vanilla flavoured ice cream with a fruity strawberry ice coating. Our fundamental belief is that few things in life are more important than the food you buy. Good quality is essential.</description>
			<image_link>https://www.retailer.com/productImages/image2.jpg</image_link>
      <price>&pound;1.25</price>
      <brand>Waitrose</brand>
      <product_type>Frozen Ice Cream Ice Cream Lollies</product_type>
      <availability>20</availability>
      <brand>Waitrose</brand>
      <hfss>false</hfss>
      <seller_id>432un3-sd32s-ssaar</seller_id>
    </item>
</rss>

Charges utiles personnalisées

En quoi consistent les charges utiles personnalisées ?

Les charges utiles personnalisées sont des champs qui sont transmis « tels quels », de l'ingestion du catalogue à la diffusion des annonces. Aucune transformation n'y sera appliquée. Toutefois, la validation basée sur le schéma JSON (https://json-schema.org/) est effectuée sur ces champs. La spécification de charge utile est fournie via le lien ci-dessous (notation JSON Schema) :

Dans la réponse de l'annonce de produit, la charge utile personnalisée exacte est renvoyée à l'intégrateur dans un champ nommé customPayload. Voici un exemple de charge utile valide :

{
  "id": "102013703",
  "upc": "4400000463",
  "name": "Bee Farms Honey - 14.4 Oz",
  "nutrientName": [
    "Kosher"
  ],
  "description": "Honey",
  "brand": "Bee Farms",
  "imageUrl": "https://www.retailer.com/products/1/image.png",
  "productUrl": "https://www.retailer.com/products/1/page.html",
  "aisleId": "1_22_2_3",
  "departmentName": "Breakfast ",
  "aisleName": "Breakfast spreads",
  "shelfName": "Honeu",
  "salesRank": 481,
  "details": "Made with real honey. No high fructose corn syrup. 8 g of while grain per 31 g serving. Per 8 Crackers: 130 calories; 0 g sat fat (% DV); 160 mg sodium (7% DV); 8 g total sugars. Start with: Bee farms honey grahams. Fill grahams with toasted marshmallows. Add milk chocolate squares. For full nutritional information, go to honeymaid.com. Try our other delicious flavors: Grahams made with real cinnamon. Grahams made with real chocolate. 8 g of whole grain per 31 g serving. Nutritionist recommend eating 18 g or more of whole grains throughout the day. 100% Whole Grain: 8 per serving. Eat 48 g or more of whole grains daily. WholeGrainsCouncil.org. Smartlabel. Visit us at: beefarms.com 1-809-622-4726 please have package available. Keep it Going: 100 recycled paperboard. Please recycle this carton. Minimum 35% post-consumer content. Made in Mexico.",
  "averageWeight": 0,
  "displayType": 0,
  "stores": [
    {
      "storeId": "2543",
      "price": 3.99,
      "salePrice": 0.28,
      "pricePer": 4.99,
      "unitOfMeasure": "OUNCE",
      "restrictedFlag": false,
      "sellByWeight": false,
      "promoDescription": "I",
      "promoText": "Club Price: $3.99&lt;BR&gt;SAVE up to: $1",
      "promoType": "P",
      "offerFlag": true
    },
    {
      "storeId": "2544",
      "price": 3.99,
      "salePrice": 0.28,
      "pricePer": 4.99,
      "unitOfMeasure": "OUNCE",
      "restrictedFlag": false,
      "sellByWeight": false,
      "promoDescription": "I",
      "promoText": "Club Price: $3.99&lt;BR&gt;SAVE up to: $1",
      "promoType": "P",
      "offerFlag": true
    }
  ]
}

🚧

Fichier uniquement

Veuillez noter que les charges utiles personnalisées ne sont prises en charge que lors de la synchronisation des produits via un fichier.

Charges utiles personnalisées dans la génération d'annonces

Lorsque vous renvoyez des annonces de produits, la charge utile personnalisée est transmise dans le cadre de l'annonce générée. Les charges utiles publicitaires renvoyées contiendront un champ supplémentaire customPayload qui contiendra un objet JSON respectant les mêmes spécifications que les informations fournies dans le flux.

Voici un exemple de réponse :

{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "4400000463",
            "customPayload": {
                "id": "102013703",
                "upc": "4400000463",
                "name": "Bee Farms Honey - 14.4 Oz",
                "nutrientName": [
                  "Kosher"
                ],
                "description": "Honey",
                "brand": "Bee Farms",
                "imageUrl": "https://www.retailer.com/products/1/image.png",
                "productUrl": "https://www.retailer.com/products/1/page.html",
                "aisleId": "1_22_2_3",
                "departmentName": "Breakfast ",
                "aisleName": "Breakfast spreads",
                "shelfName": "Honeu",
                "salesRank": 481,
                "details": "Made with real honey. No high fructose corn syrup. 8 g of while grain per 31 g serving. Per 8 Crackers: 130 calories; 0 g sat fat (% DV); 160 mg sodium (7% DV); 8 g total sugars. Start with: Bee farms honey grahams. Fill grahams with toasted marshmallows. Add milk chocolate squares. For full nutritional information, go to honeymaid.com. Try our other delicious flavors: Grahams made with real cinnamon. Grahams made with real chocolate. 8 g of whole grain per 31 g serving. Nutritionist recommend eating 18 g or more of whole grains throughout the day. 100% Whole Grain: 8 per serving. Eat 48 g or more of whole grains daily. WholeGrainsCouncil.org. Smartlabel. Visit us at: beefarms.com 1-809-622-4726 please have package available. Keep it Going: 100 recycled paperboard. Please recycle this carton. Minimum 35% post-consumer content. Made in Mexico.",
                "averageWeight": 0,
                "displayType": 0,
                "stores": [
                  {
                  "storeId": "2543",
                  "price": 3.99,
                  "salePrice": 0.28,
                  "pricePer": 4.99,
                  "unitOfMeasure": "OUNCE",
                  "restrictedFlag": false,
                  "sellByWeight": false,
                  "promoDescription": "I",
                  "promoText": "Club Price: $3.99&lt;BR&gt;SAVE up to: $1",
                  "promoType": "P",
                  "offerFlag": true
                  },
                  {
                  "storeId": "2544",
                  "price": 3.99,
                  "salePrice": 0.28,
                  "pricePer": 4.99,
                  "unitOfMeasure": "OUNCE",
                  "restrictedFlag": false,
                  "sellByWeight": false,
                  "promoDescription": "I",
                  "promoText": "Club Price: $3.99&lt;BR&gt;SAVE up to: $1",
                  "promoType": "P",
                  "offerFlag": true
                }
              ]
            } ,
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        }
    ],
    "banners": [],
    "products": []
}

🚧

Étant donné que les charges utiles personnalisées constituent une tâche supplémentaire pour notre service de génération d'annonces, veuillez noter que leur intégration n'est pas soumise au SLA de CitrusAd, sauf indication contraire.