Idealno.ba specifikacija za XML izvoznu datoteku

Overview

• General info
  • Definitions
  • Quick reference
• Elements specifications
  • Root element
  • Products element
  • Basic product data
  • Price & availability
  • Product category
  • Product identifiers
  • Additional product data
  • Shipping
  • Detailed product specifications
• Additional requirements
• XML file example
• Common problems and mistakes

General info

This specification defines how your product information is displayed on Idealno.ba, therefore submitting your data in the correct format is crucial for good sales results. Since the XML feed is automatically generated from your site, consult your webmaster to create or edit it.

Definitions

• Product. The actual product that your potential customers would be searching for at Idealno.ba
• Variant. A product that comes in different variations. For example, a shirt that comes in different sizes and/or colors has size/color variants
• Element A field in XML that consist of start tag, data and end tag
• Attribute Product’s characteristics

Quick reference

Elements		Common product categories
Group	Element name	Clothes & Shoes	Variant products	All other product types
Root element	<CNJExport>	R	R	R
Products element	<Item>	R	R	R
Basic product data	<ID>	R	R	R
	<name>	R	R	R
	<description>	R	R	R
	<specification>	D	D	D
	<link>	R	R	R
	<mainImage>	R	R	R
	<moreImages>	D	D	D
	<videoUrl>	O	O	O
Price & availability	<price>	R	R	R
	<regularPrice>	D	D	D
	<clubPrice>	O	O	O
	<curCode>	O	O	O
	<stockText>	O	O	O
	<stock>	R	R	R
	<inStoreAvailability>	O	O	O
	<store>	O	O	O
	<availability>	O	O	O
	<quantity>	O	O	O
Product category	<fileUnder>	R	R	R
	<cenCategoryId>	O	O	O
Product identifiers	<brand>	D	D	D
	<EAN>	R	R	R
	<CUIN>	O	O	O
	<productCode>	D	D	D
	<productModel>	D	D	D
Additional product data	<condition>	D	D	D
	<warranty>	O	O	O
	<coupon>	O	O	O
	<couponCode>	O	O	O
	<gift>	O	O	O
Shipping	<deliveryCost>	R	R	R
	<deliveryTimeMin>	D	D	D
	<deliveryTimeMax>	D	D	D
Detailed product specifications	<groupId>	R	R	D
	<attributes>	R	R	R
	<gender>	R	D	D
	<color>	R	D	D
	<size>	R	D	D
	<ageGroup>	R	D	D
	<attribute>	R	R	R
	<name>	R	R	R
	<values>	R	R	R
	<value>	R	R	R

Below, you will find full details, including more information about the minimum requirements, best practices, and examples of each element.

Elements specifications

Root element

Products element

Basic product data

Element	Format	Description
<ID>	Required Your product’s unique identifier Example 546AB-1 Syntax Max 50 characters	Use a unique value for each product. Use the product's SKU where possible Keep the ID the same when updating your data Use only valid Unicode characters. Avoid invalid characters like control, function, or private area characters Use the same ID for the same product - across countries Never change this ID Never use it for different product
<name>	Required Your product’s name Example SAMSUNG refrigerator RB37J5018SA Syntax Max 200 characters	Accurately describe your product It should contain BRAND, product type (refrigerator) and MODEL. Don’t include promotional text like "free shipping," or all capital letters … For variants: Include a distinguishing feature such as color For Clothes and shoes: Don’t include size in name
<description>	Required Your product’s descriptive description Example <p>A refrigerator with a capacity of 217 liters is best suited for use in larger households.</p> <p>Shelves and drawers in the interior are optimally positioned, and LED lighting also allows visibility even at night. </p> Syntax “No” restriction	Whole text description of your products. If you have text description of a product it must be included in feed Description must be in HTML code (without styling!) Accurately describe your product - it must contain the same data as landing page Don’t include promotional text like "free shipping," or all capital letters … Include only information about the product. Don’t include links to your store, sales information, details about competitors, other products, or accessories
<specification>	Required Your product’s specifications Example <ul>   <li>   Energy class: A +   </ li>   <li>   Volume: 217 liters   </ li>   <li>   Dimensions: 181x59x64   </ li>   <li>   Auto defrost: yes   </ li> </ ul> Syntax “No” restriction	All specifications of your products If you have specifications of a product it must be included in feed Specifications must be in HTML code (without styling!) Only accurate product specifications - it must contain the same data as landing page Don’t include promotional text like "free shipping," or all capital letters … Include only information about the product. Don’t include links to your store, sales information, details about competitors, other products, or accessories If you can’t separate specifications from text description include them both in <description> element
<link>	Required Your product’s landing page Example https://www.example.org/product-id Syntax Max 400 characters	Direct URL to your product page Start with http or https For tracking purposes (traffic, conversions) add your own UTM parameters to URLs.
<mainImage>	Required The URL of your product’s main image Example https://www.example.org/image1.jpg Syntax Max 200 characters	For image URL: Direct ULR to the main image of your product Start with http or https URL must be without spaces or accents or any special characters (for example: ć, č, đ, š, ž, ü, …) For the image: Accurately display the product you're selling It must be highest resolution you have available Use an accepted format: non-animated GIF (.gif), JPEG (.jpg/.jpeg), PNG (.png) For non-Clothes or non-Shoes products, use an image of at least 300 x 300 pixels For Clothes or shoes products, use an image of at least 600 x 600 pixels Don't scale up an image or submit a thumbnail Don't include promotional text, watermarks, or borders Don't submit a placeholder or a generic image
<moreImages>	Required (when your product has more than one image) Optional (when your product doesn’t have more than one image) The URLs of your product’s additional images - URLs are separated with comma Example https://www.example.org/image2.jpg, https://www.example.org/image3.jpg, https://www.example.org/image4.jpg Syntax Max 1000 characters	Meet the requirements for <mainImage> element
<videoUrl>	Optional The URL of your product’s video preview. Example https://www.youtube.com/watch?v=x1La2Y140Bc Syntax Max 400 characters	If you or product manufacturer have your product’s video preview, you can include it here Only URLs on www.youtube.com will be accepted

Price & availability

Element	Format	Description
<price>	Required Your product’s price Example 1230.99 Syntax Numeric	Accurate price of your product with included taxes Must be the same as price on landing page You can use dot or comma as decimal separator Use the same decimal separator in the whole feed Make sure that your landing page includes the price in the currency of the country of sale prominently, and in a place, that's straightforward to find Ensure that the product can be purchased online for the submitted price Make sure that any user in the country of sale can buy the product for the submitted price, and without paying for a membership Don't submit a price of 0 (a price of 0 is allowed, but products with price of 0 won’t be published on Idealno.ba)
<regularPrice>	Required (when product is on sale) Optional (when product is not on sale) Your product’s price before sale Example 1430.99 Syntax Numeric	Required when product is on sale Accurate price of your product with included taxes before it was on sale You can use dot or comma as decimal separator Use the same decimal separator in the whole feed
<clubPrice>	Optional Your product’s price for club members Example 1130.99 Syntax Numeric	Accurate price of your product with included taxes for club members You can use dot or comma as decimal separator Use the same decimal separator in the whole feed
<curCode>	Optional Currency code in which are prices in feed Example EUR Supported values EUR HRK RSD BAM	Only acceptable values are: EUR (Euro) HRK (Croatian kuna) RSD (Serbian dinar) BAM (Bosnia and Herzegovina convertible mark)
<stockText>	Optional Your product’s descriptive stock text Example Only 10 items in stock Syntax Max 50 characters	Accurately submit the product's stock description as you wish, and match the stock from your landing page Submit only accurate stock information Additional examples: Last item Only 10 items in stock Check ...
<stock>	Required Your product’s stock Example Out of stock Supported values in stock preorder out of stock	Accurately submit the product's stock and match the stock from your landing page Submit only accurate stock information Additional explanation of supported values: in stock (product will be shipped no later than 1 day after ordering or is available for personal pick-up) preorder (product will be shipped in 2 to 10 work days from date of order or available for personal pick-up) out of stock (product doesn’t have a known delivery date)
<inStoreAvailability>	Optional Contains elements that provide info about availability in physical (Brick and mortar) stores - available for personal pick-up. These elements are: <store> <availability> <quantity>	You must repeat this element for each store location you have.
<store>	Optional Location of your store. Example BTC Hala A, Šmartinska cesta 152, 1000 Ljubljana Syntax Max 100 characters	Accurately submit the stores location in following form: shopping center (optional) street address and number (required) post number & city (required) separate each information with a comma (,)
<availability>	Optional Is product available for personal pick-up and when Example today Supported values today tomorrow no	Accurately submit if and when product is available for pick-up in store (specified in <store> element) Submit only accurate information Additional explanation of supported values: today (customer can come into store at any time today during working hours and purchase this product OR order it online and pick it up today during working hours) tomorrow (customer can order it online and pick it up today or tomorrow during working hours) no (product isn’t available for personal pick-up) “Today” and “tomorrow” refers to working days only
<quantity>	Optional Quantity of available products in specified store location Example 10 Syntax Integer, equal or greater than 0	Accurately submit how many products is available for purchase and pick-up in store (specified in <store> element) Submit only accurate information

Product category

Element	Format	Description
<fileUnder>	Required Your product’s category tree Example Men’s Apparel & Accessories > Clothing > Outerwear > Coats & Jackets Syntax Max 400 characters	Accurate product category structure from your webstore Very important for sorting products into Idealno.ba categories Include only 1 category Include the most relevant category Include full path of the category Main category - Category - Sub category
<cenCategoryId>	Optional Category ID from our portal Example 1528 Syntax Max 10 numeric characters	Submit the Category ID from our portal, that matches your product To download the file with our categorization, please click HERE. For each product in the feed, insert the data found in column L3 motherID Products with this data will be sorted into Idealno.ba categories within 48 hours

Product identifiers

Element	Format	Description
<brand>	Required (for all products, that have brand) Optional (for products, that don’t have brand) Your product’s brand name Example Samsung Syntax Max 50 characters	Provide the brand name of the product generally recognized by consumers If you don't have a brand to provide, don't provide a value. For example, don't use N/A, Generic, No brand, or Does not exist Don't provide the Original Equipment Manufacturer (OEM) brand to indicate that your product is compatible with or a replica of the OEM brand's product
<EAN>	Required (for all new products, that have EAN assigned by the manufacturer) Optional (for products, that don’t have EAN) Your product’s EAN or Global Trade Item Number (GTIN) Example 8806088059785 Syntax Exactly 13 numeric characters	You must include EAN if it exists for your product Submit only valid EANs as defined in the official GS1 validation guide, which includes these requirements: The checksum digit is present and correct The EAN is not restricted (GS1 prefix ranges 02, 04, 2) The EAN is not a coupon (GS1 prefix ranges 98 - 99)
<CUIN>	Optional Your product’s exact match CUIN code from Idealno.ba Example CX0078266A Syntax Max 10 characters	CUIN code is Idealno.ba unique product code. You can find this code on every product page on Idealno.ba (under tab “Podatki”) Your products with CUIN code will be automatically linked to existing product on Idealno.ba within 48 hours.
<productCode>	Required (for all products from Car tires category) Optional (for all other products) Your product’s internal or suppliers code Example 516843-845 Syntax Max 20 characters	Any product code, that you have - it can be also suppliers’ product code If your product is from Car tires category you must supply your products SAP code in this field (6-digit number).
<productModel>	Optional Your product’s manufacturers code (model) Example RB37J5018SA Syntax Max 20 characters	Your product’s model Use the most specific model possible. For example, different colors of a product should have different models

Additional product data

Element	Format	Description
<condition>	Required (for all products, that are renew, refurbished, reboxed or used) Optional (for all new products) Your product’s condition Example new Syntax new renew refurbished reboxed used	Accurately submit the product's condition
<warranty>	Optional Your product’s warranty information Example 3 years Syntax Max 50 characters
<coupon>	Optional Description of what buyer gets with using <couponCode> Example Code for 10% discount on whole purchase in our store Syntax Max 75 characters
<couponCode>	Optional Coupon code that buyer needs to use to get its benefits Example KODA10CENEJE Sintaksa Max 15 characters
<gift>	Optional Gift, that buyer receives by buying this product Example T-shirt Syntax Max 150 characters

Shipping

Element	Format	Description
<deliveryCost>	Required Your product’s shipping cost Example 3.45 Syntax Numeric	Accurately submit the product's shipping cost You can use dot or comma as decimal separator Use the same decimal separator in the whole feed
<deliveryTimeMin>	Required (for all products, that have in element <stock> value in stock or preorder) Optional (for all other products) The shortest amount of time (in days) between when an order is placed for a product and when the product is delivered. Example 2 Syntax Integer, equal or greater than 0	The shortest time (in days) it takes for a product to arrive at its destination Do not include weekends For submitting a time range submit <deliveryTimeMin> in combination with <deliveryTimeMax>
<deliveryTimeMax>	Required (for all products, that have in element <stock> value in stock or preorder) Optional (for all other products) The longest amount of time (in days) between when an order is placed for a product and when the product is delivered. Example 3 Syntax Integer, equal or greater than 0	The longest time (in days) it takes for a product to arrive at its destination Do not include weekends For submitting a time range submit <deliveryTimeMin> in combination with <deliveryTimeMax>

Detailed product specifications

Element	Format	Description
<groupId>	Required (for all products, that are variants) Optional (for all other products) ID for a group of products that come in different versions (variants) Example 546AB Syntax Max 50 characters	Use a unique value for each group of variants. Use the parent SKU where possible Keep the value the same when updating your product data Use only valid Unicode characters. Avoid invalid characters like control, function, or private area characters Use an <groupId> for a set of products that differ by one or more of these elements: <color> <size> <gender> <ageGroup> Include the same elements for each product in the group. For example, if a product varies by size and color, submit <size> and <color> for every product that share the same value for <groupId> If your products differ by design attributes that aren't represented by the elements above, don't use this element
<attributes>	Required This element contains all product attributes. Each in its own <attribute> element. It also contains some predefined attributes as elements: <gender> <color> <size> <ageGroup>	Include all product attributes your product has
<gender>	Required(for all products, that are variants and products from categories Clothes and shoes) Optional(for all other products) The gender for which your product is intended. Example male Supported values unisex female male	For variants: Include with the same value for <groupId> and different values for <gender>
<color>	Required (for all products, that are variants and products from categories Clothes and shoes) Optional (for all other products) Your products color(s) Example white Syntax Max 40 characters	Don’t use a number such as 0 2 4 6 8 Don’t use characters that aren’t alphanumeric such as #fff000 Don’t use only 1 letter such as R Don’t reference the product or image such as “see image” Don't combine several color names into 1 word instead of separating them with a / such as RedPinkBlue Don’t use a value that isn’t a color such as various, variety, men's, women's, or N/A For variants: Include with the same value for <groupId> and different values for <color>
<size>	Required (for all products, that are variants and products from categories Clothes and shoes) Optional (for all other products) Your products size Example XL Syntax Max 40 characters	For variants: Include with the same value for <groupId> and different values for <size> In case of different sizes for different markets you must specify for what market submitted size is. Examples: EU 41 US 8 UK 7.5
<ageGroup>	Required (for all products, that are variants and products from categories Clothes and shoes) Optional (for all other products) The age group for which your product is intended. Example adult Supported values newborn infant toddler kids adult	Include one value per product For variants: Include with the same value for <groupId> and different values for <ageGroup> Additional explanation of supported values: newborn (Up to 3 months old) infant (Between 3-12 months old) toddler (Between 1-5 years old) kids (Between 5-13 years old) adult (Typically teens or older)
<attribute>	Required Each attribute your product has gets its own <attribute> element. It contains following elements: <name> <values>	Include all product attributes your product has Values for predefined attributes include in these elopements <gender> <color> <size> <ageGroup>
<name>	Required Name of attribute for which you will supply value Example Material Syntax Max 100 characters
<values>	Required This element contains all attributes values. Each in its own <value> element.	Include all attribute values your product has
<value>	Required Value of before specified attribute Example 100% Cotton Syntax Max 100 characters

Additional requirements

• Create XML file according to above specification. For better understanding, you can find an XML example below. An XML file with different product examples is also available for download here (or you received it as attachment in mail). Please open it in program like Notepad ++ so you will be able to see comments.
• Save your created XML file on your server and send us the URL to that file. We will connect to that URL on regular basis and use it to update the data on Idealno.ba.
• Some information is inserted into our database only once, so it is very important that you submit only correct and final data. All additional changes cause a lot of additional costs. Below, you can see which data is updated daily. All other data is inserted only once:
  • <CUIN>
  • <link>
  • <price>
  • <regularPrice>
  • <clubPrice>
  • <stockText>
  • <stock>
  • <inStoreAvailability>
  • <store>
  • <availability>
  • <quantity>
  • <cenCategoryId>
  • <deliveryCost>
  • <deliveryTimeMin>
  • <deliveryTimeMax>
  • <condition>
  • <warranty>
  • <coupon>
  • <couponCode>
  • <gift>

XML file example

<?xml version="1.0" encoding="UTF-8"?>
<CNJExport>
<Item>
<ID><![CDATA[DM1054]]></ID>
<name><![CDATA[SAMSUNG refrigerator RB37J5018SA]]></name>
<description><![CDATA[<p>A refrigerator with a capacity of 217 liters is best suited for use in larger households.</p><p>Shelves and drawers in the interior are optimally positioned, and LED lighting also allows visibility even at night.</p>]]></description>
<specifications><![CDATA[<ul><li>Energy class: A +</ li><li>Volume: 217 liters</ li><li>Dimensions: 181x59x64 </ li><li>Auto defrost: yes</li></ul>]]></specifications>
<link><![CDATA[https://www.example.org/product/RB37J5018SA/]]></link>
<mainImage><![CDATA[https://www.example.org/image01.jpg]]></mainImage>
<moreImages><![CDATA[https://www.example.org/image02.jpg,https://www.example.org/image03.jpg]]></moreImages>
<videoUrl><![CDATA[https://www.youtube.com/watch?v=x1La2Y140Bc]]> </videoUrl>
<price>659,90</price>
<regularPrice>699,90</regularPrice>
<clubPrice>620,90 </clubPrice>
<curCode>EUR</curCode>
<stockText><![CDATA[only 10 left]]></stockText>
<stock>preorder</stock>
<inStoreAvailability>
   <store><![CDATA[BTC hala A, Šmartinska cesta 152, 1000 Ljubljana]]></store>
   <availability>today</availability>
   <quantity>2</quantity>
</inStoreAvailability>
<inStoreAvailability>
   <store><![CDATA[Tržaška cesta 87, 2000 Maribor]]></store>
   <availability>today</availability>
   <quantity>3</quantity>
</inStoreAvailability>
<inStoreAvailability>
   <store><![CDATA[Ankaranska cesta 3, 6000 Koper]]></store>
   <availability>tomorrow</availability>
   <quantity>1</quantity>
</inStoreAvailability>
<inStoreAvailability>
   <store><![CDATA[Ulica Mirka Vadnova 7, 4000 Kranj]]></store>
   <availability>no</availability>
   <quantity>0</quantity>
</inStoreAvailability>
<fileUnder><![CDATA[Home & Garden - Home Appliances - Refrigerators]]></fileUnder>
<cenCategoryId>221</cenCategoryId>
<brand><![CDATA[SAMSUNG]]> </brand>
<EAN><![CDATA[8806088059785]]></EAN>
<CUIN><![CDATA[CX0078266A]]></CUIN>
<productCode><![CDATA[516843-845]]></productCode>
<productModel><![CDATA[RB37J5018SA]]></productModel>
<condition><![CDATA[new]]></condition>
<warranty><![CDATA[5 years]]></warranty>
<coupon><![CDATA[Code for 10% discount on whole purchase in our store]]></coupon>
<couponCode><![CDATA[KODA10CENEJE]]></couponCode>
<gift></gift>
<deliveryCost>3,40</deliveryCost>
<deliveryTimeMin>2</deliveryTimeMin>
<deliveryTimeMax>7</deliveryTimeMax>
<groupId></groupId>
<attributes>
  <gender></gender>
  <color><![CDATA[white]]></color>
  <size></size>
  <ageGroup></ageGroup>
  <attribute>
     <name><![CDATA[Energy class]]></name>
     <values>
      <value><![CDATA[A+]]></value>
     </values>
   </attribute>
   <attribute>
     <name>![CDATA[Volume]]</name>
     <values>
      <value>![CDATA[217 l]</value>
     </values>
   </attribute>
   <attribute>
     <name>![CDATA[Technologies]]</name>
     <values>
      <value>![CDATA[Twin Cooling Plus]]</value>
      <value>![CDATA[Space Max]]</value>
      <value>![CDATA[Fresh Zone]]</value>
     </values>
   </attribute>
</attributes>
</Item>
</CNJExport>


Common problems and mistakes

• In text elements (<name>, <description> …) use CDATA (as in example above). XML file must be valid and well formed. You can check here if your XML is valid:
  • https://www.w3schools.com/xml/xml_validator.asp or
  • https://www.xmlvalidation.com/ or
  • save the XML file to your computer and open it in your web browser (we have best experience with Firefox).
• Set the first line in XML correctly <?xml version="1.0" encoding="UTF-8"?>. The vast majority of encoding errors happen because of an improper setting of this value. Encoding doesn’t need to be “UTF-8” it can be also “windows-1250” or any other encoding. It is important that the encoding being used is the same as it is declared in the first line of the feed.
• All tags are case sensitive.
• Whenever you will be changing web store platform/system, please pay attention that product IDs don’t change. Please contact us before any changes, so we can provide necessary information or support, and prepare you for a smooth transition to new IDs.
• Please form <fileUnder> very carefully. This information is key for sorting products into Idealno.ba categories.
• <EAN>, <productCode> and <productModel> are elements we use for connecting products and offers, so make sure you fill this elements with codes from your product database.

If you have any questions regarding this XML feed specifications, we will gladly answer them. Contact us at urednik@ceneje.si.