CitrusAd admite tres tipos de formato para la sincronización de datos de productos a través de archivos:
- TSV
- CSV
- XML.
Esta sección describe las estructuras de cada formato de archivo para los datos de productos que procesamos en CitrusAd.
Archivos TSV/CSV
La siguiente tabla ilustra los nombres de columna y la descripción de columna para los productos en un archivo TSV/CSV. En esta tabla, también especificamos las columnas obligatorias que deben proporcionarse en un archivo. Cuando se requiere una columna, todos los valores de la misma deben proporcionarse en sus filas.
TSV sin comillas
Los archivos TSV no pueden estar entre comillas. Al sincronizar a través de TSV, deben sincronizarse los archivos sin comillas.
Nombres de columna y descripciones de datos de productos en archivos TSV/CSV
| Nombre de la columna | Obligatorio/opcional | Tipo de datos | Descripción | Ejemplo |
|---|---|---|---|---|
product_code | Obligatorio | Texto | Un código para identificar el producto en su sistema. Este campo es idéntico a los campos GTIN y de artículo en la sincronización de archivos API y XML. | F153212AN1 |
name | Obligatorio | Texto | El nombre del producto. | Camiseta SS con pegatina - Niños |
image_url | Obligatorio | URL | Un hipervínculo a la imagen de un producto. Debe ser una URL válida. | https://www.retailer.com/product/1234.jpg |
inventory | Obligatorio | Número | El inventario del producto. Si el valor es 0, no se distribuirán anuncios de productos para este producto. | 1 |
description | Obligatorio | Texto | La descripción del producto. | Con tréboles bordados y 3 rayas perfiladas en blanco a contraste, los pantalones cortos Sport Sweat son una novedad de Adidas Originals. |
KEY (as a value) | Obligatorio para ubicaciones de categorías y visualizaciones amplias | Texto | Si se utiliza este tipo de columna, los minoristas deben proporcionar un valor para . Puede tener varias columnas con esta sintaxis en un archivo TSV. | El nombre de la columna puede ser "marca" y el valor de la celda en la columna puede ser "hada-verde". Esto generará el filtro "marca:hada-verde" en el producto. |
subClassName | Obligatorio para ubicaciones de ventas cruzadas/mejoradas | Texto | El nombre de la subclase/categoría en la que se encuentra el producto correspondiente. Las subclases permiten una mejor orientación del producto, por ejemplo, una mantequilla puede orientarse al pan, pero no a las tiritas. | Queso |
xSellSubClassName | Obligatorio para ubicaciones de ventas cruzadas/mejoradas | Texto | Los nombres de las subclases/categorías a las que el producto en cuestión puede dirigirse. | Pan, rebanadas, galletitas |
price | Opcional | Número | El precio de un producto. | 30,00 |
brand | Obligatorio | Texto | La marca del producto. | Tommy Hilfiger |
type | Obligatorio | Texto | El tipo de producto. | Ropa |
retailer_taxonomy | Obligatorio para una atribución mejorada. No debe tener espacios entre > los caracteres | Texto | Su taxonomía individual de minorista del producto. | Hombres > Ropa para hombre > Suéteres |
google_taxonomy | Obligatorio para una atribución mejorada si retailer_taxonomy no se puede proporcionar | Texto | Taxonomía estándar de Google del producto. Puede encontrar más información aquí: https://www.google.com/basepages/producttype/taxonomy.en-US.txt | Ropa y accesorios > Ropa > Tops |
global_identifier | Obligatorio | Texto | El identificador mundial para el producto. | 08719108994761 |
global_identifier_type | Obligatorio | Texto | El tipo de identificador mundial. | GTIN |
custom_payload | Opcional* | Matriz de bytes codificada en Base64 | Este campo contiene una carga personalizada que debe enrutarse a través de la generación de anuncios. El campo debe contener un objeto JSON válido serializado en una matriz de bytes y codificado en Base64. El objeto JSON debe ajustarse a un esquema. | Consulte la sección de cargas personalizadas. |
hfss | Opcional | Booleano | Se utiliza para indicar si un producto es HFSS o no. Esto también se usa en la interfaz de usuario de CitrusAD. Consulte nuestra Documentación de HFSS para obtener más información. | verdadero |
seller_id | Opcional | Texto | El identificador único del vendedor. Solo es necesario si se incorporan vendedores del mercado web. Puede dejarse en blanco para productos que no son del mercado web. Existen requisitos adicionales para integrar seller_ids, consulte Marketplace sellerId para obtener más información. | aes-de4-ss |
A continuación se muestra un archivo de ejemplo en forma de tabla:
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 | Paquete de regalo Absenta Hada Verde de 500 ml | https://www.retailer.com/product/1234.jpg | 20 | Este paquete de regalo Absenta Hada Verde y Cuchara es el regalo perfecto para cualquier amante de la absenta o de los cócteles. ¡Ponga un terrón de azúcar en la cuchara y vierta la absenta para beber este licor a la manera más auténtica! | Regalos, Alcohol, Paquetes de regalo | 500 ml | República Checa | Regalos, Alcohol, Paquetes de regalo | 5.00 | Hada Verde | Alcohol | Regalos > Alcohol > Paquetes de regalo | Alimentos, bebidas y tabaco > Bebidas > Bebidas alcohólicas > Licor y bebidas espirituosas > Absenta | 8594001443079 | 7328s-dmie3-9jdae | Paquetes de regalo | Licor |
Los archivos TSV no pueden estar en formato de comillas.
Archivos XML
CitrusAd ha definido una lista de etiquetas que se utilizan para describir un documento XML para los productos. La siguiente tabla muestra las etiquetas y sus descripciones. La etiqueta "artículo" se utiliza para describir un producto en un documento XML. El resto de etiquetas para los otros campos debe escribirse dentro de esta etiqueta.
| Etiquetas XML | Obligatorio/opcional | Descripción |
|---|---|---|
item | Obligatorio | Esta etiqueta se utiliza para describir un producto. El resto de etiquetas XML de un producto debe estar dentro de esta etiqueta. Un documento XML para productos debe contener una lista de etiquetas de artículo. Este campo es idéntico a los campos GTIN y product_code en la sincronización de archivos API y TSV. |
id | Obligatorio | Un código para identificar el producto en su sistema. Equivalente a product_code en archivos TSV. Este campo es idéntico a los campos GTIN y de artículo en la sincronización de archivos API y XML. |
title | Obligatorio | El nombre del producto. |
image_link | Obligatorio | Un hipervínculo a la imagen de un producto. Debe ser una URL válida. |
brand | Obligatorio | La marca del producto. |
availability | Obligatorio | Esta etiqueta sirve para describir el inventario de un producto. El valor debe ser un número. |
description | Obligatorio | Esta etiqueta sirve para describir un producto. |
price | Opcional | Esta etiqueta sirve para describir el precio de un producto. Si se indica el valor dentro de la etiqueta, este debe ser un número. |
type | Opcional | El tipo de producto. |
retailer_taxonomy | Obligatorio para una atribución mejorada. También es necesario para las integraciones de categorías. | Su taxonomía individual de minorista del producto. Por ejemplo, Hombres > Ropa para hombre > Suéteres |
google_taxonomy | Obligatorio para una atribución mejorada si retailer_taxonomy no se puede proporcionar | Taxonomía estándar de Google del producto. Puede encontrar más información aquí: https://www.google.com/basepages/producttype/taxonomy.en-US.txt |
global_identifier | Obligatorio | El identificador mundial para el producto. P. ej. 08719108994761 |
global_identifier_type | Obligatorio | El tipo de identificador mundial. Por ejemplo, GTIN |
custom_payload | Opcional* | Este campo contiene una carga personalizada que debe enrutarse a través de la generación de anuncios. El campo debe contener un objeto JSON válido serializado en una matriz de bytes y codificado en Base64. El objeto JSON debe ajustarse a un esquema. |
hfss | Opcional | Se utiliza para indicar si un producto es HFSS o no. Esto también se usa en la interfaz de usuario de CitrusAD. Consulte nuestra Documentación de HFSS para obtener más información. |
seller_id | Opcional | El identificador único del vendedor. Solo es necesario si se incorporan vendedores del mercado web. Puede dejarse en blanco para productos que no son del mercado web. Existen requisitos adicionales para integrar seller_ids, consulte Marketplace sellerId para obtener más información. |
A continuación se describe un ejemplo de documento XML válido con etiquetas:
<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>
Cargas personalizadas
¿Qué son las cargas personalizadas?
Las cargas personalizadas son campos que se encauzan "tal cual", desde la incorporación del catálogo hasta la publicación de anuncios. No se aplicarán transformaciones al campo. Sin embargo, la validación basada en el esquema JSON (https://json-schema.org/) se realiza en el campo. La especificación de carga se proporciona a través del siguiente enlace (notación de esquema JSON):
En la respuesta de anuncio del producto, la carga personalizada exacta se devuelve al integrador en un campo llamado customPayload. A continuación se proporciona un ejemplo de carga válida:
{
"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
}
]
}
Solo archivo
Tenga en cuenta que las cargas personalizadas solo se admiten al sincronizar productos a través de archivos.
Cargas personalizadas en la generación de anuncios
Al devolver anuncios de productos, la carga personalizada se realiza como parte del anuncio generado. Las cargas de anuncios devueltos contendrán un campo adicional customPayload que incluirá un objeto JSON que cumple con la misma especificación que la información proporcionada en el muro.
Una respuesta de ejemplo puede ser:
{
"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": []
}
Como las cargas personalizadas son cargas de trabajo adicionales para nuestro servicio de generación de anuncios, tenga en cuenta que las integraciones de cargas personalizadas no están sujetas al SLA de CitrusAd, a menos que se especifique lo contrario.