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 colonne | Obligatoire/facultatif | Type de données | Description | Exemple |
---|---|---|---|---|
product_code | Obligatoire | Texte | Code 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 |
name | Obligatoire | Texte | Le nom du produit. | T-shirt autocollant SS - Enfants |
image_url | Obligatoire | URL | Un hyperlien vers l'image d'un produit. L'URL doit être valide. | https://www.retailer.com/product/1234.jpg |
inventory | Obligatoire | Numéro | Le stock du produit. Si la valeur est de 0, aucune annonce de produit ne sera diffusée pour ce produit. | 1 |
description | Obligatoire | Texte | La 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 larges | Texte | Si 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. |
subClassName | Nécessaire pour les emplacements de vente croisée et incitative | Texte | Le 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 |
xSellSubClassName | Nécessaire pour les emplacements de vente croisée et incitative | Texte | Les noms des sous-classes/catégories dans lesquelles le produit pertinent peut cibler des produits. | Pains, pâtes à tartiner, crackers |
price | Facultatif | Numéro | Le prix d'un produit. | 30,00 |
brand | Obligatoire | Texte | La marque du produit. | Tommy Hilfiger |
type | Obligatoire | Texte | Le type de produit. | Vêtements |
retailer_taxonomy | Requis pour une meilleure attribution. Il ne doit pas y avoir d'espace entre > caractères | Texte | Votre taxonomie personnelle du produit pour les détaillants. | Hommes > Vêtements homme > Pulls |
google_taxonomy | Requis pour une meilleure attribution si retailer_taxonomy ne peut pas être fourni | Texte | La taxonomie Google standard du produit. Vous trouverez plus d'informations ici : https://www.google.com/basepages/producttype/taxonomy.en-US.txt | Vêtements et accessoires > Vêtements > Hauts |
global_identifier | Obligatoire | Texte | L'identifiant global du produit. | 08719108994761 |
global_identifier_type | Obligatoire | Texte | Le type d'identifiant global. | GTIN |
custom_payload | Facultatif* | Tableau d'octets codés en Base64 | 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. | Voir la section sur les charges utiles personnalisées. |
hfss | Facultatif | Booléen | Sert à 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_id | Facultatif | Texte | ID 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_code | name | image_url | inventory | description | filter:Category | filter:Size | filter:Country | groups | price | brand | type | retailer_taxonomy | google_taxonomy | global_identifier | seller_id | subClassName | xSellSubClassName |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
80591101 | Coffret cadeau d'absinthe Green Fairy 500 ml | https://www.retailer.com/product/1234.jpg | 20 | Ce 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 cadeaux | 500 ml | République tchèque | Cadeaux, Alcool, Coffrets cadeaux | 5.00 | Green Fairy | Alcool | Cadeaux > Alcool > Coffrets cadeaux | Aliments, boissons et tabac > Boissons > Boissons alcoolisées > Liqueur et spiritueux > Absinthe | 8594001443079 | 7328s-dmie3-9jdae | Coffrets cadeaux | Liqueur |
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 XML | Obligatoire/facultatif | Description |
---|---|---|
item | Obligatoire | Ces 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. |
id | Obligatoire | Code 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. |
title | Obligatoire | Le nom du produit. |
image_link | Obligatoire | Un hyperlien vers l'image d'un produit. L'URL doit être valide. |
brand | Obligatoire | La marque du produit. |
availability | Obligatoire | Cette balise définit le stock d'un produit. La valeur doit être un nombre. |
description | Obligatoire | Cette balise sert à décrire un produit. |
price | Facultatif | Cette balise sert à définir le prix d'un produit. Si renseignée, la valeur doit être un nombre. |
type | Facultatif | Le type de produit. |
retailer_taxonomy | Requis 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_taxonomy | Requis pour une meilleure attribution si retailer_taxonomy ne peut pas être fourni | La taxonomie Google standard du produit. Vous trouverez plus d'informations ici : https://www.google.com/basepages/producttype/taxonomy.en-US.txt |
global_identifier | Obligatoire | L'identifiant global du produit. par exemple 08719108994761 |
global_identifier_type | Obligatoire | Le type d'identifiant global. par exemple GTIN |
custom_payload | Facultatif* | 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. |
hfss | Facultatif | Sert à 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_id | Facultatif | ID 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 & 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>£9.99</price>
<brand>Melissa & 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>£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<BR>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<BR>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<BR>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<BR>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.