Ceneje.si specifikacija za XML izvozno datoteko
Ta dokument je namenjen programerjem, ki bodo pripravili XML izvoz za objavo izdelkov vaše spletne trgovine na Ceneje.si. V primeru, da nimate svoje programerske ekipe, ta navodila posredujte podjetju, čigar platformo uporabljate za svojo spletno trgovino.
Če želite, da je vaša prisotnost na Ceneje.si čimbolj učinkovita, zagotovite, da bo vaš XML izvoz vseboval vse pomembne elemente te XML specifikacije.
Po potrditvi ustreznosti vašega XML izvoza bomo poskrbeli za prenos vaših izdelkov iz XML izvoza na naš portal in kasneje redno posodabljali cene, razpoložljivost in druge informacije.
Optimiziran in pravilno narejen XML izvoz je ključen za uspešnost sodelovanja, saj gre za vaš prvi stik z našim portalom in vašimi potencialnimi strankami. Če svojo prisotnost začnete s slabimi podatki, ne gre pričakovati dobrih rezultatov.
Pregled
Splošne informacije
Specifikacija pred vami definira prikazovanje informacij na Ceneje.si. Oblikovanje dokumenta po spodnjih navodilih je ključnega pomena za dobre prodajne rezultate. Za pripravo XML izvoza se posvetujte s svojim skrbnikom spletne strani, saj se izvoz avtomatsko generira na vaših spletnih strežnikih.DEFINICIJE
- Izdelek. Dejanski izdelek, ki ga bodo vaše potencialne stranke iskale na Ceneje.si
- Različica. Izdelek, ki obstaja v večih različicah. Na primer majica, ki obstaja v različnih barvah in/ali velikostih, ima barvne/velikostne različice.
- Element. Polje v XML, sestavljeno iz začetne značke, podatkov in zaključne značke.
- Atribut. Lastnost izdelka
HITRA REFERENCA
Elementi | Kategorije izdelkov | |||
Skupina | Ime elementa | Oblačila in obutev | Različice izdelka | Ostale skupine izdelkov |
Korenski element | <CNJExport> |
R | R | R |
Element izdelka | <Item> |
R | R | R |
Osnovne informacije o izdelku | <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 | |
Cena in dobavljivost | <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 | |
Kategorija izdelka | <fileUnder> |
R | R | R |
<cenCategoryId> |
O | O | O | |
Identifikatorji izdelka | <brand> |
D | D | D |
<EAN> |
R | R | R | |
<CUIN> |
O | O | O | |
<productCode> |
D | D | D | |
<productModel> |
D | D | D | |
Dodatne informacije o izdelku | <condition> |
D | D | D |
<warranty> |
O | O | O | |
<coupon> |
O | O | O | |
<couponCode> |
O | O | O | |
<gift> |
O | O | O | |
Dostava | <deliveryCost> |
R | R | R |
<deliveryTimeMin> |
D | D | D | |
<deliveryTimeMax> |
D | D | D | |
Podrobne specifikacije izdelka | <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 |
Spodaj najdete več podrobnosti, ki vključujejo informacije o minimalnih zahtevah in najboljših praksah ter primere za vsak element.
Specifikacije elementov
KORENSKI ELEMENT
<CNJExport>
. Gre za obvezen element, ki je vključen le enkrat in vsebuje vse ostale elemente..ELEMENT IZDELKA
<Item>
elementa (XML je občutljiv na velike in male črke, zato bodite pozorni na veliko začetnico “I”). Ta element vsebuje vse informacije o določenem izdelku. V primeru, da vaš izdelek obstaja v več različicah, vključite <Item>
element za vsako različico izdelka.OSNOVNE INFORMACIJE O IZDELKU
Element | Oblika | Opis |
<ID> |
Obvezno / Required Edinstven identifikator izdelka Primer 546AB-1 Sintaksa Max 50 znakov |
|
<name> |
Obvezno / Required Ime vašega izdelka Primer SAMSUNG hladilnik z zamrzovalnikom RB37J5018SA Sintaksa Max 200 znakov |
|
<description> |
Obvezno / Required Opisni opis vašega izdelka Primer
<p>Prostostoječ hladilnik z zamrzovalnikom ima 267 L prostornine hladilnega in 98 L prostornine zamrzovalnega dela.</p>
Sintaksa ”Brez” omejitev |
|
<specification> |
Obvezno / Required
Specifikacije vašega izdelka Primer
<ul>
Sintaksa “Brez” omejitev |
|
<link> |
Obvezno / Required
Pristajalna stran vašega izdelka Primer https://www.example.org/product-id
Sintaksa Max 400 znakov |
|
<mainImage> |
Obvezno / Required
URL slike, ki najbolje predstavlja vaš izdelek Primer https://www.example.org/image1.jpg
Sintaksa Max 200 znakov |
|
<moreImages> |
Obvezno / Required (ko ima vaš izdelek več kot eno sliko)
Priporočeno / Optional (ko ima vaš izdelek le eno sliko) URL-ji dodatnih slik vašega izdelka. URL-ji so med seboj ločeni z vejico. Primer
https://www.example.org/image2.jpg,
https://www.example.org/image3.jpg,
https://www.example.org/image4.jpg
Sintaksa Max 1000 znakov |
|
<videoUrl> |
Priporočeno / Optional
URL povezava do videoposnetka vašega izdelka. Primer
https://www.youtube.com/watch?v=x1La2Y140Bc
Sintaksa Max 400 znakov |
|
CENA IN RAZPOLOŽLJIVOST
Element | Oblika | Opis |
<price> |
Obvezno / Required
Cena vašega izdelka Primer 1230.99
Sintaksa Številčna vrednost |
|
<regularPrice> |
Obvezno / Required (ko je izdelek znižan)
Priporočeno / Optional (ko izdelek ni znižan) Cena izdelka pred znižanjem Primer 1430.99
Sintaksa Številčna vrednost |
|
<clubPrice> |
Priporočeno / Optional
Cena vašega izdelka za člane Primer 1130.99
Sintaksa Številčna vrednost |
|
<curCode> |
Priporočeno / Optional
Valuta cen v izvozu Primer EUR
Dovoljene vrednosti EUR HRK RSD BAM
|
|
<stockText> |
Priporočeno / Optional
Opisna vrednost zaloge izdelka Primer Samo 10 izdelkov na zalogi
Sintaksa Max 50 znakov |
|
<stock> |
Obvezno / Required
Zaloga vašega izdelka Primer out of stock
Dovoljene vrednosti in stock preorder out of stock
|
|
<inStoreAvailability> |
Priporočeno / Optional
Vsebuje elemente z informacijami o razpoložljivosti v fizičnih poslovalnicah – dostopno za osebni prevzem Ti elementi so: <store> <availability> <quantity>
|
|
<store> |
Priporočeno / Optional
Lokacija vaše trgovine Primer BTC Hala A, Šmartinska cesta 152, 1000 Ljubljana
Sintaksa Max 100 znakov |
|
<availability> |
Priporočeno / Optional
Ali je izdelek na voljo za osebni prevzem in kdaj Primer today
Dovoljene vrednosti today tomorrow no
|
|
<quantity> |
Priporočeno / Optional
Količina izdelkov, ki so na voljo v določeni poslovalnici
Primer 10
Sintaksa Celo število, večje ali enako 0 |
|
KATEGORIJA IZDELKA
Element | Oblika | Opis |
<fileUnder> |
Obvezno / Required
Celotna kategorizacija vašega izdelka Primer
Moška oblačila in dodatki > Oblačila > Plašči in jakne
Sintaksa Max 400 znakov |
|
<cenCategoryId> |
Priporočeno / Optional
ID kategorije z našega portala Primer 1528
Sintaksa Max 10 številskih znakov |
|
IDENTIFIKATORJI IZDELKA
Element | Oblika | Opis |
<brand> |
Obvezno / Required (za vse izdelke z znamko)
Priporočeno / Optional (za izdelke brez znamke) Ime znamke vašega izdelka Primer Samsung
Sintaksa Max 50 znakov |
|
<EAN> |
Obvezno / Required (za vse nove izdelke s predpisanimi EAN kodami s strani proizvajalca)
Priporočeno / Optional (za vse izdelke brez EAN kode) EAN ali GTIN (Global Trade Item Number) koda vašega izdelka Primer 8806088059785
Sintaksa Natančno 13 številskih znakov |
|
<CUIN> |
Priporočeno / Optional
CUIN koda izdelka s Ceneje.si, ki se natančno ujema z vašim izdelkom Primer CX0078266A
Sintaksa Max 10 znakov |
|
<productCode> |
Obvezno / Required (za vse izdelke iz kategorij pnevmatik)
Priporočeno / Optional (za vse ostale izdelke) Interna ali dobaviteljeva koda vašega izdelka Primer 516843-845
Sintaksa Max 20 znakov |
|
<productModel> |
Priporočeno / Optional
Your product’s manufacturers code (model) Primer RB37J5018SA
Sintaksa Max 20 characters |
|
DODATNE INFORMACIJE O IZDELKU
Element | Oblika | Opis |
<condition> |
Obvezno / Required (za vse izdelke, ki niso novi in imajo status renew, refurbished, reboxed ali so rabljeni)
Priporočeno / Optional (za vse nove izdelke) Stanje vašega izdelka Primer new
Sintaksa new renew refurbished reboxed used
|
|
<warranty> |
Priporočeno / Optional
Informacije o garanciji vašega izdelka Primer 3 leta
Sintaksa Max 50 znakov |
|
<coupon> |
Priporočeno / Optional
Opisno, kaj kupec dobi z uporabo kode zapisane v <couponCode>
Primer
Koda za 10% popusta na celoten nakup v
naši trgovini
Sintaksa Max 75 znakov |
|
<couponCode> |
Priporočeno / Optional
Koda kupona, ki jo mora kupec uporabiti, da lahko koristi ugodnosti, ki jih ponuja Primer KODA10CENEJE
Sintaksa Max 15 znakov |
|
<gift> |
Priporočeno / Optional
Darilo, ki ga kupec prejme ob nakupu tega izdelka Primer majica
Sintaksa Max 150 znakov |
DOSTAVA
Element | Oblika | Opis |
<deliveryCost> |
Obvezno / Required
Cena dostave vašega izdelka Primer 3.45
Sintaksa Številčna vrednost |
|
<deliveryTimeMin> |
Obvezno / Required (za vse elemente, ki imajo v elementu <stock> vrednost in stock ali preorder)
Priporočeno / Optional (za vse ostale izdelke) Najkrajši čas (v dnevih) od naročila do dostave izdelka. Primer 2
Sintaksa Celo število, večje ali enako 0 |
|
<deliveryTimeMax> |
Obvezno / Required (za vse elemente, ki imajo v elementu <stock> vrednost na in stock ali preorder)
Priporočeno / Optional (za vse ostale izdelke) Najkrajši čas (v dnevih) od naročila do dostave izdelka. Primer 3
Sintaksa Celo število, večje ali enako 0 |
|
PODROBNE SPECIFIKACIJE IZDELKA
Element | Oblika | Opis |
<groupId> |
Obvezno / Required (za vse izdelke, ki so različice)
Priporočeno / Optional (za vse ostale izdelke) ID za skupino izdelkov, ki obstajajo v različnih različicah Primer 546AB
Sintaksa Max 50 znakov |
|
<attributes> |
Obvezno / Required
Ta element vsebuje vse atribute izdelka, vsakega v svojem <attribute>
elementu. Vključuje tudi nekaj vnaprej definiranih atributov v obliki elementov: <gender> <color> <size> <ageGroup>
|
|
<gender> |
Obvezno / Required(za vse izdelke, ki so različice in za izdelke iz kategorij oblačil in obutve) Priporočeno / Optional(za vse ostale izdelke) Spol, kateremu je namenjen izdelek. Primer male Supported values unisex female male |
|
<color> |
Obvezno / Required (za vse izdelke, ki so različice in za izdelke iz kategorij oblačil in obutve) Priporočeno / Optional (za vse ostale izdelke) Barve vašega izdelka Primer bela Sintaksa Max 40 znakov |
|
<size> |
Obvezno / Required (za vse izdelke, ki so različice in za izdelke iz kategorij oblačil in obutve) Priporočeno / Optional (za vse ostale izdelke) Velikost vašega izdelka Primer XL EU 42 Sintaksa Max 40 znakov |
|
<ageGroup> |
Obvezno / Required (za vse izdelke, ki so različice in za izdelke iz kategorij oblačil in obutve) Priporočeno / Optional (za vse ostale izdelke) Starostna skupina, kateri je namenjen izdelek Primer adult Supported values newborn infant toddler kids adult
|
|
<attribute> |
Obvezno / Required Vsak atribut vašega izdelka spada v ločen <attribute> element. Ta vsebuje sledeča elementa:<name> <values>
|
|
<name> |
Obvezno / Required Ime atributa, katerega vrednost boste vključili Primer Material Sintaksa Max 100 znakov |
|
<values> |
Obvezno / Required Ta element vsebuje vse vrednosti za ta atribut. Vsakega vključite v svojem <value> element.
|
|
<value> |
Obvezno / Required Vrednost prej določenega atributa Primer 100% bombaž Sintaksa Max 100 znakov |
Dodatne zahteve
- XML izvoz oblikujte po zgornjih navodilih. Za boljše razumevanje je spodaj priložen primer XML izvoza. Dodatno XML datoteko z različnimi primeri izdelkov lahko prenesete tukaj (ali pa ste jo prejeli na elektronki naslov kot priponko). Datoteko odprite v primernem programu (priporočamo Notepad++), saj vključuje tudi komentarje.
- XML datoteko shranite na svojem strežniku in nam pošljite URL povezavo do nje. Do tega URL-ja bomo redno dostopali z namenom posodabljanja vaših podatkov o izdelkih na Ceneje.si.
- Nekatere informacije se v našo bazo prenesejo samo enkrat, zato je za te podatke še posebej pomembno, da že na začetku vključite le pravilne in končne informacije. Dodatne spremembe teh podatkov prinesejo dodatne stroške. Dnevno posodabljamo le spodnje podatke:
Primer XML datoteke
<?xml version="1.0" encoding="UTF-8"?>
<CNJExport>
<Item>
<ID><![CDATA[DM1054]]></ID>
<name><![CDATA[SAMSUNG refrigerator RB37J5018SA]]></name>
<description><![CDATA[<p>Prostostoječ hladilnik z zamrzovalnikom ima 267 L prostornine hladilnega in 98 L prostornine zamrzovalnega dela.</p><p>Police in predali v notranjosti so optimalno razporejeni, LED osvetljava pa omogoča vidljivost tudi ponoči.</p>]]></description>
<specifications><![CDATA[<ul><li>Energijski razred: A +</ li><li>Volumen: 217 liters</ li><li>Dimenzije: 181x59x64 </ li><li>Program Auto defrost: da</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[samo še 10 kosov]]>></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 & Dom & Vrt- Bela tehnika - Hladilniki]]></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 let]]></warranty>
<coupon><![CDATA[Koda za 10% popusta na celoten nakup v naši trgovini]]></coupon>
<couponCode><![CDATA[KODA10CENEJE]]></couponCode>
<gift></gift>
<deliveryCost>3,40</deliveryCost>
<deliveryTimeMin>2</deliveryTimeMin>
<deliveryTimeMax>7</deliveryTimeMax>
<groupId></groupId>
<attributes>
<gender></gender>
<color><![CDATA[bel]]></color>
<size></size>
<ageGroup></ageGroup>
<attribute>
<name><![CDATA[Energijski razred]]></name>
<values>
<value><![CDATA[A+]]></value>
</values>
</attribute>
<attribute>
<name><![CDATA[Prostornina]]</name>
<values>
<value><![CDATA[217 l]></value>
</values>
</attribute>
<attribute>
<name><![CDATA[Tehnologije]]></name>
<values>
<value><![CDATA[Twin Cooling Plus]]></value>
<value><![CDATA[Space Max]]></value>
<value><![CDATA[Fresh Zone]]></value>
</values>
</attribute>
</attributes>
</Item>
</CNJExport>
Pogoste težave in napake
-
V elementih z besedilom (
<name>
,<description>
…) uporabite CDATA (kot v zgornjem primeru). XML datoteka mora biti veljavna in pravilno oblikovana. Veljavnost XML datoteke lahko preverite tu:- https://www.w3schools.com/xml/xml_validator.asp
- https://www.xmlvalidation.com/
- ali pa si XML datoteko shranite na računalnik in jo odprete v spletnem brskalniku (najboljše izkušnje imamo z brskalnikom Firefox)
-
Prva vrstica v XML datoteki mora biti pravilno nastavljena:
<?xml version="1.0" encoding="UTF-8"?>
. Večina encoding težav se zgodi zaradi napačne nastavitve te vrednosti. Vrednost je lahko “UTF-8”, “windows-1250” ali kakršnokoli drugo kodiranje. Pomembno je, da je kodiranje, uporabljeno v dokumentu, enako tistemu, ki je deklariran v prvi vrstici dokumenta. - Vse značke so občutljive na velike/male črke in se morajo popolnoma ujemati s predpisanimi.
- V primeru, da boste menjali platformo ali sistem vaše spletne trgovine, bodite pozorni, da ID-ji izdelkov ostanejo isti. Pred spremembami nas prosim kontaktirajte – z veseljem vam pomagamo z dodatnimi informacijami in podporo ter vam pomagamo ob prehodu na nove ID-je.
- Posebno pozornost namenite oblikovanju
<fileUnder>
. Ta informacija je ključna za umeščanje vaših izdelkov znotraj kategorij na Ceneje.si. -
Za povezovanje izdelkov in ponudb se uporablja elemente
<EAN>
,<productCode>
in<productModel>
, zato se tu še posebej prepričajte, da nam posredujete pravilne in kvalitetne podatke iz svoje baze izdelkov.
Za kakršnakoli vprašanja glede priprave XML izvoza in teh navodil smo vam vedno na voljo. Pišite nam na urednik@ceneje.si in z veseljem vam bomo pomagali.