Idealno.ba specifikacija za XML izvoznu datoteku
Ovaj dokument namijenjen je programerima koji će pripremiti XML izvoz u svrhu prikaza proizvoda iz vaše web trgovine na Idealno.ba. Ako nemate svoj programerski tim molimo vas da proslijedite ove upute tvrtki čiju platformu za web trgovinu koristite.
Ako želite da vaša prisutnost na Idealno.ba bude maksimalno iskorištena, vaš XML izvoz mora sadržavati sve važne elemente navedene u ovoj specifikaciji.
Nakon potvrde ispravnosti vašeg XML izvoza, pobrinut ćemo se za prijenos vaših proizvoda iz XML izvoza na naš portal te redovito osvježavati cijene, dostupnost proizvoda i sve ostale informacije.
Optimiziran i pravilno uređen XML izvoz je ključan za uspješnost poslovanja, to je vaš prvi kontakt s našom platformom i vašim potencijalnim kupcima. Ako svoju prisutnost započnete s lošim podacima, nemojte očekivati dobre rezultate.
Overview
- General info
- Elements 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
<CNJExport>
. It is a basic requirement and is included only once. It contains all other elements.Products element
<Item>
element (XML is case sensitive - be aware of upper case “I”). It contains all information about a particular product. Include a copy of it for each variation of your product, if your product comes in different variants.Basic product data
Element | Format | Description |
<ID> |
Required Your product’s unique identifier Example 546AB-1 Syntax Max 50 characters |
|
<name> |
Required Your product’s name Example SAMSUNG refrigerator RB37J5018SA Syntax Max 200 characters |
|
<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>
Syntax “No” restriction |
|
<specification> |
Required
Your product’s specifications Example
<ul>
Syntax “No” restriction |
|
<link> |
Required
Your product’s landing page Example https://www.example.org/product-id
Syntax Max 400 characters |
|
<mainImage> |
Required
The URL of your product’s main image Example https://www.example.org/image1.jpg
Syntax Max 200 characters |
|
<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 |
|
<videoUrl> |
Optional
The URL of your product’s video preview. Example
https://www.youtube.com/watch?v=x1La2Y140Bc
Syntax Max 400 characters |
|
Price & availability
Element | Format | Description |
<price> |
Required
Your product’s price Example 1230.99
Syntax Numeric |
|
<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 |
|
<clubPrice> |
Optional
Your product’s price for club members Example 1130.99
Syntax Numeric |
|
<curCode> |
Optional
Currency code in which are prices in feed Example EUR
Supported values EUR HRK RSD BAM
|
|
<stockText> |
Optional
Your product’s descriptive stock text Example Only 10 items in stock
Syntax Max 50 characters |
|
<stock> |
Required
Your product’s stock Example Out of stock
Supported values in stock preorder out of stock
|
|
<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>
|
|
<store> |
Optional
Location of your store. Example BTC Hala A, Šmartinska cesta 152, 1000 Ljubljana
Syntax Max 100 characters |
|
<availability> |
Optional
Is product available for personal pick-up and when Example today
Supported values today tomorrow no
|
|
<quantity> |
Optional
Quantity of available products in specified store location
Example 10
Syntax Integer, equal or greater than 0 |
|
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 |
|
<cenCategoryId> |
Optional
Category ID from our portal Example 1528
Syntax Max 10 numeric characters |
|
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 |
|
<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 |
|
<CUIN> |
Optional
Your product’s exact match CUIN code from Idealno.ba Example CX0078266A
Syntax Max 10 characters |
|
<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 |
|
<productModel> |
Optional
Your product’s manufacturers code (model) Example RB37J5018SA
Syntax Max 20 characters |
|
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
|
|
<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 |
|
<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 |
|
<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 |
|
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 |
|
<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>
|
|
<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 |
|
<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 |
|
<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 |
|
<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
|
|
<attribute> |
Required Each attribute your product has gets its own <attribute> element. It contains following elements:<name> <values>
|
|
<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.
|
|
<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:
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.