MANUAL OF INTEGRATION THE SPECIFICATION OF OFFERS EXPORT FORMAT TO ONET ZAKUPY (version )

Transkrypt

1 MANUAL OF INTEGRATION THE SPECIFICATION OF OFFERS EXPORT FORMAT TO ONET ZAKUPY (version )

2 1. Methods for providing data and mapping categories The 1st method of providing data The 2nd method of providing data The third method of providing data Mapping categories Requirements Coding Special characters The order of the elements Namespace Kinds of transfers Deleting offers The description of a transfer s structure Introduction The elements of a transfer <oferty> (<offers> required) Updating (required) Namespace (required attribute) <oferta> (<offer> optional) <identifikator> (<identifier> required) <usun/> (<delete/> required in case of deleting offer) <nazwa> (<name> required in case of adding or updating the offer) <url> (required) <cena> (<price> required) <sciezka_kategorii> (<path _category> required) A category identifier (required) <id_kategorii_sklepu> <marka_producent> (<brand_producent> (required) Optional elements <produkt> (<product>) <opis> (<description>) <SOP_id skad= bdk > <kody_kreskowe>(<bar_codes>) <zdjecie> (<pictures>) <autorzy> (<authors>) <wykonawcy> (<artists>) <rezyserzy> (<directors>) <aktorzy> (<actors>) <nosniki> (<data_carriers>) < gatunek> (<genre>) <rok_wydania> (<year of edition>) < wydawnictwo> (< publishing house>) <ISBN>

3 <romiar> (<size>) <plec> (<sex>) <kolory> (<colours>) <darmowa_dostawa> (<free_delivery>) <oferta_specjalna> (<special_offer>) <promocyjna_cena> (<special price>, subordinate for <oferta_specjalna>) <kategoria_wiekowa> (<age_category>) <przedzial_wiekowy> (<age_bracket>) <prezenty_na> (<gifts_for>) <prezent_dla> (<gifts to>) <dodatkowe> (<additional>) <onetefekt> Category ascription (mapping) Mapping by using XML file with a category map Manual mapping category

4 DICTIONARY 1. Model a structural description of a product (SOP) it is a standard offer including a picture or pictures of the product, a name of the product, detailed parameters in the form of attributes, description as well as opinions about the product to which offers are ascribed by particular online shops. 2. Mapping category it is an ascription of the supplier s category (of the shop) to the category of OnetZakupy see point 1.4 Mapping category and point 4. Category ascription (mapping). 3. Leaf node the category which does not have any subcategories. 4.<id_kategorii_pm> - a category identifier the leaf node of OnetZkupy service (in XML to substitute for the category identifier of Marketplace Platform). 4

5 1. Methods for providing data and mapping categories. Partner has 3 methods of providing data at their disposal The 1st method of providing data passive method. It is displaying an XML file with data to import (using the format described by Onet that is explained in the next part of the document) on the shop s webpage or on the shop s FTP server. You need to define an address to download the file in the shop s control panel and then you have a possibility to define the cycle in which Onet will download the file. You can place more that one XML file in the archive. The archive cannot contain any directories. It has to be single zipped file. Please remember to pack the file in the zip format The 2nd method of providing data active method. It is placing an XML file (using the format described by Onet that is explained in the next part of the document) through the control panel (zipped or not, limitation as described above). Note: The maximum size of sent file while using this method is 25MB. You can place more that one xml file in the archive. The archive cannot contain any directories. It has to be single zipped file. Please remember to pack the file in the zip format The third method of providing data it is adding each offer through the interface of the shop s control panel administration. In this case mapping is not required categories are chosen from the list Mapping categories The 1st and the 2nd method require from the shop creating the map of the shop s category in OnetZakupy category service. What does it mean? For example the shop has offers in the category (the shopping one). RTV,AGD>TVs>LCD>29; with the category identifier at the shop=5 RTV,AGD>TVs>LCD>32; with the category identifier at the shop=10 RTV,AGD>TVs>LCD>42; with the category identifier at the shop=13 And in the shopping service there is a leaf node category (the category which hasn t got any subcategories) ->Catalogue->RTV->TVs->LCD; with the category identifier 2170 In order to import the shop s offers from its category, you need to indicate to which shopping category they should go in the shopping service. In the control panel you indicate that shopping categories with 5, 10 and 13 identifier are the equivalent of shopping service category with 2170 identifier. You can also send us an XML file containing a mapping category. For more information see 4. Category ascription (mapping). 2. Requirements 2.1. Coding Required encoding in transfers is UTF-8. <?xml version="1.0" encoding="utf-8"?> 2.2. Special characters Some of the characters in the XML format have special meaning. In order to use them you need to enter them by using their substitutes. Please see the following table. 5

6 character substitude < < > > & & " &apos; Examples: <marka_producent>johnson&johnson</marka_producent>-wrong <marka_producent>johnson&johnson</marka_producent> 2.3. The order of the elements The order provided in the XSD template needs to be preserved (see 5. Scheme). Additionally, you do not need to provide the elements of a description for deleted offers. (see 3.1 Deleting offers) 2.4. Namespace The required namespace for transfer is: You need to define it as an attribute of an offer s element in the following way. <oferty aktualizacja="t"xmlns=" NOTE: Namespace should not be omitted. The transfer having not defined or wrong namespace will be completely rejected as an error. 3. Kinds of transfers We distinguish two kinds of transfers. Overall a shop s offer is completely deleted and replaced by the offers from the transfer. If the offer is not provided in the overall transfer, it will mean deleting all shop s offers from our database. This solution allows e.g for an easy exchange of the whole offer. Diverse (updated) a shop s offer is updated using the offers from the transfer. New offers are added, existing ones updated, offers meant for deleting deleted. This kind of a transfer let us limit the amount of data sent from the shop exclusively to new records (adding new offers), updating already existing ones or deleting those out of data ones by using the element <usun/>. An updating attribute of the element <oferta> decides about the kind of a transfer. If the value of this attribute is on N, we will obtain an overall transfer, if it is on T it will be a diverse transfer Deleting offers An offer can be deleted by providing its identifier in the shop and the tag <usun/>: 6

7 <oferta> <usun/> </oferta> Advice: When using an overall transfer there is no need to use the element <usun/> because all offers not placed in the transfer will be automatically deleted. Note: After providing the element <usun/>, you cannot give any other elements such as <nazwa> (name), <url>, <cena> (price) or white characters. It is also advised to use the form of recording from the example below (empty tag). There cannot be any content inside the element usun ( e.g. the sign of the line end). The example of the wrong usage: <oferta id="938498"> <usun> </usun> </oferta> 3.2. The description of a transfer s structure Introduction The elements of a transfer can be divided into required and optional. Required elements essential data, without which a transfer will be rejected. Note: Every required element (with the exception for <marka_producenta> - <brand_producent>) should have some value. The lack of value in the required element will result in the rejection of a record as wrong. Optional elements not required; however, they are extremely important because they allow for the full offer s presentation. What will you gain by entering as many optional data as it is possible. better ascription of your offers to SOPs (the productive patterns), which additionally involves comparison of price and products technical parameters makes finding the products quicker better opportunities to use offers in the shopping editorial places in the future the use of OnetZakupy additional functionalities such as events site, gift site, newsletters and others. Not completing the information in the optional elements will result in not displaying shop s offer in the gift site, event site or in the newsletters. If a provider does not have the information which describes an optional element, then you should not place this element in the description of a single offer. There are some elements that have subordinate elements. You should not place subordinate elements on your own, whereas you can do it only inside the superior element. You can see the hierarchy of elements in point 5. Sheme The elements of a transfer <oferty> (<offers> required) Every transfer must include the element of <oferty>. This element is an overall one and includes all offers in the transfer. It also has two attributes the kind of updating and the definition of a namespace. 7

8 <oferty aktualizacja="t" xmlns=" Updating (required) This attribute indicates the kind of a transfer (see point 3. Kinds of a transfer) If the value of this attribute is on N, we will obtain an overall transfer, if it is on T it will be a diverse transfer. Advice: An overall updating allows for a convenient exchange of the whole offer. The existing provider s database of offers is deleted and replaced by the offers from the transfer. However, a diverse updating allows to reduce the amount of data sent through the shop exclusively to new records ( adding new offers), to update existing ones as well as to delete out of date ones by using the element <usun/>. The acceptable value: tak (yes), nie (no), TAK (yes), NIE (no), T, N, Y, Tak (yes), Nie (no), t, n Namespace (required attribute) A namespace is established as in the point 2.4 Namespace. The transfer without a namespace or with a changed namespace will be treated as wrong <oferta> (<offer> optional) This is an element that includes a single offer description or an order to delete it. If we choose the option to delete, we do not provide any elements except from the identifier (see 3.1 Deleting offers). NOTE: If you do not provide any element of <oferta> while using an overall transfer, it will mean deleting the whole offer database <identifikator> (<identifier> required) An offer needs to include the unique identifier that explicitly identifies the following offer in the shop database. You should also use this identifier later on while updating or deleting the offer. The identifier is set by the shop. <oferta> <identyfikator>1abf345c2456aaaff9abc24a-444</identyfikator> <! tutaj dalsze elementy opisu oferty --> </oferta> <usun/> (<delete/> required in case of deleting offer) If you are going to delete an offer, you should enter the element <usun> in this place (see 3.1 Deleting offers). After it, the element <oferta> will be closed. <oferta> <identyfikator> aaa ##@@</identyfikator> <usun/> </oferta> Note: this element is replaceable with the element <nazwa> (<name>) <nazwa> (<name> required in case of adding or updating the offer) 8

9 This element includes the name of an offer from your shop. The minimum length of the name is 1 character, and the maximum length is 100 characters. In the name field there should be exclusively the real name of a product (the short one e.g Canon ixus or more extended e.g a gold ring with a ruby and five diamonds. There should not be any slogans e.g Buy with us, any information about costs, the time of a delivery or guarantee. <nazwa><![cdata[coolpix L15]]></nazwa> <url> (required) An URL element includes the direct URL of an offer in your shop (full path containing After clicking on it, a customer should be transferred to this site. <url> <cena> (<price> required) A price should be in Polish zloty. The appropriate decimal division is a full stop. One or two decimal places are acceptable. The thousand decimal should not be used. Note: A price should be larger than 0. Entering 0 price is treated as an error. Examples: <cena>123.00</cena> <cena>123</cena> <cena>123.5</cena> <!--wrong:--> <cena>1 023</cena> <cena>1,023.00</cena> <cena>123,5</cena> <cena>1023</cena> <sciezka_kategorii> (<path _category> required) This element includes a category path, in which there is a product of your shop e.g RTV > TV > PLAZMA. 42. Entering your whole category path allows for a ascription to the category of OnetZakupy service. After providing value in this element, your category will be presented by the value given in the mapping interface/category ascription what makes the mapping process much easier. <sciezka_kategorii>rtv > Telewizory > Plazma > 42"</sciezka_kategorii> A category identifier (required) In this field we enter the category of a particular product. There are two possibilities: provide a category identifier used by an offer in the shop <id_kategorii_sklep>. It will require ascribing appropriate category of OnetZakupy service to this identifier in the administrator s panel (see point 4. Ascription (mapping ) category). provide an id of the category - leaf of OnetZakupy service where an offer is placed- <id_kategorii_pm>. This solution does not require mapping. 9

10 Advice: Please feel encourage to use a category identifier of our service. It will speed up the process of transferring offers by omitting mapping procedures. A category tree with category identifiers and a leaf node can be found in the administration panel. Note: The following elements <id_kategorii_pm> and <id _kategorii_sklepu> should not be used together in a single offer description because it will result in the rejection of the record as wrong while validation <id_kategorii_sklepu> Here we should provide the identifier of a shop s category in which an offer is. <id_kategorii_sklepu>2345aaa-333</id_kategorii_sklepu> Or <id_kategorii_pm> Here we should provide the category a leaf node of the OnetZakupy service. <id_kategorii_pm>4962</id_kategorii_pm> NOTE: You can ascribe offers exclusively to the category a leaf node of OnetZakupy service. The identifier of a pm category is the integer number larger than <marka_producent> (<brand_producent> (required) In case when it is not possible to provide a brand, please provide a producer. If none of this information cannot be completed, you need to place this element as empty. Except from the element <usun/>, it is the only element that allow to enter empty value. Examples: <marka_producent>vizir</marka_producent> Or <marka_producent>henkel</marka_producent> Or in case when it is not possible to provide required information <marka_producent></marka_producent> Optional elements Optional elements not required; however, they are extremely important because they allow for the full offer s presentation. What will you gain by entering as many optional data as it is possible. better ascription of your offers to SOPs (the productive patterns), which additionally involves comparison of price and products technical parameters makes finding the products quicker better opportunities to use offers in the shopping editorial places in the future the use of OnetZakupy additional functionalities such as events site, gift site, newsletters and others. Not completing the information in the optional elements will result in not displaying shop s offer in the gift site, event site or in the newsletters. 10

11 If a provider does not have the information which describes an optional element, then you should not place this element in the description of a single offer. NOTE: If an optional element includes subordinate elements then providing a subordinate element is only required when a superior element is used. Advice: If a provider does not have information which describes an optional element, you should not place this element in a single offer description <produkt> (<product>) The type of a product (N - new, U - used) <produkt>n</produkt> <opis> (<description>) The description of a product may include only pure text. The minimum length is 5 characters. It cannot include any HTML tags as well as any references to javascript sources. <opis><![cdata[ Here the description of a produkt in CDATA that will not be parsed as XML ]]></opis> <SOP_id skad= bdk > An identifier of a structural product description (SPD a product pattern). Providing this element means that an offer is ascribed to a SPD with a given identifier. In the attribute skad it is required to provide from which SPD provider the identifier comes from. In this case, you can enter BDK identifier. <SOP_id skad="bdk"> /55</sop_id> <kody_kreskowe>(<bar_codes>) This is an element including all your EAN codes describing given offer. They appear together with the subordinate element <kod>. <kod> (<code> subordinate, required at least one) The subordinate element for <kody kreskowe>. If the optional element <kody kreskowe> is used, you should provide at least one EAN code using the element <kod>. <kody_kreskowe> <kod> </kod> <kod> </kod> </kody_kreskowe> <zdjecie> (<pictures>) The element <zdjecie> includes an absolute URL address of the product s picture (full access path with Only gif and jpg formats are accepted. 11

12 You should provide addresses to pictures in the maximum resolution available on the site but not larger that 1280 x 1024 px (e.g. the pictures which are displayed after clicking on the button enlarge picture ). Our scanning system will ensure the right presentation of the pictures and enable larger flexibility while presenting a product. The pictures size should not be larger than 1MB. You are asked not to add any pictures miniature. The picture will be automatically downloaded by our system. If it fails after 3 trials (between 15 seconds of time interval), an offer will be recognized as not completed and rejected. NOTE: Please do not provide addresses to the miniatures! It may cause a picture s distortion in case of enlarging it. <zdjecie> <autorzy> (<authors>) This is an element that allows to enter an author or authors of a given book. You should provide at least one author by using the subordinate element <autor> <autorzy> <autor>adam Mickiewicz</autor> <autor>juliusz Słowacki</autor> </autorzy> Or <autorzy> <autor>juliusz Słowacki</autor> </autorzy> <wykonawcy> (<artists>) An artist of given song or music album. You should provide at least one artist by using the subordinate element <wykonawcy> <wykonawcy> <wykonawca>feel</wykonawca> </wykonawcy> <rezyserzy> (<directors>) A director or directors of a film. You should provide at least one director by using the subordinate element <rezyser> <rezyserzy> <rezyser>steven Spielberg</rezyser> </rezyserzy> 12

13 <aktorzy> (<actors>) These are actors who play in a film. You should provide at least one actor by using the subordinate element <aktor> <aktorzy> <aktor>cezary Pazura</aktor> </aktorzy> <nosniki> (<data_carriers>) These are data carriers used for storing a product. You should provide no more than two carriers using the subordinate element <nosnik>. Available value is : DVD, CD, MD, MHC, VHS, VCD, UMD and other. <nosniki> <nosnik>dvd</nosnik> </nosniki> < gatunek> (<genre>) This is a book or music genre. <gatunek>ambient</gatunek> Or <gatunek>thriller</gatunek> <rok_wydania> (<year of edition>) This is a year of a book s edition. <rok_wydania>98</rok_wydania> Either 98 or 1998 record is acceptable < wydawnictwo> (< publishing house>) A publishing house the name of the institutions that publish books, newspapers or magazines. <wydawnictwo>helion</wydawnictwo> <ISBN> ISBN unique 13 digital identifier for books <ISBN> </ISBN> 13

14 <romiar> (<size>) The size of clothes and shoes. The maximum length is 15 signs. <rozmiar>xl</rozmiar> <rozmiar>38</rozmiar> <rozmiar>52</rozmiar> <rozmiar>80c</rozmiar> <rozmiar>42/176</rozmiar> <rozmiar>27,5</rozmiar> <rozmiar>116</rozmiar> <plec> (<sex>) The available value is: K for woman, M for man, U for unisex. <plec>m</plec> <kolory> (<colours>) You should provide at least one colour using the subordinate element <kolor>. <kolory> <kolor>bahama yellow palony</kolor> <kolor>czerwony</kolor> </kolory> <darmowa_dostawa> (<free_delivery>) Free delivery means that a customer ordering this product will not cover the cost of a delivery. Available value: tak, nie, TAK, NIE, T, N, Y, Tak, Nie, t, n <darmowa_dostawa>n</darmowa_dostawa> <oferta_specjalna> (<special_offer>) It describes whether a product is on special offer (attribute type : P promotion, W sales). In case of placing this element, we need to provide special price or discount percentage. It is a superior element for the following elements <promocyjna_cena> (special_price) or <znizka> (discount). Type = P or W (required element) It determines the type of a special offer (promotion or discount). Depending on a given attribute type, we need to provide a special price or discount percentage <promocyjna_cena> (<special price>, subordinate for <oferta_specjalna>) The same rules apply as in case of the element <cena> (required) <znizka> (<discount> subordinate for <oferta_specjalna>) Discount percentage. You should not provide % character. The same rules apply as in case of the element <cena> (required) 14

15 <oferta_specjalna typ="p"> <promocyjna_cena>15.45</promocyjna_cena> </oferta_specjalna> Or <oferta_specjalna typ="w"> <znizka>23.5</znizka> </oferta_specjalna> <kategoria_wiekowa> (<age_category>) This is the age category to which a product refers: a child, teenagers, adults. Available value: dzieci, mlodziez, dorosli. <kategoria_wiekowa>dzieci</kategoria_wiekowa> <przedzial_wiekowy> (<age_bracket>) This is the age bracket to which a product refers. There is a possibility of placing up to two value from the list using the subordinate element <wiek> The list of value: 0-3, 4-7, 8-10, 11-15, 16-20, 21-30, 31-50, powyzej 50, 18+ <przedzial_wiekowy> <wiek>0-3</wiek> <wiek>4-7</wiek> <przedzial_wiekowy> <prezenty_na> (<gifts_for>) A product can be a gift for the following occasions or holidays. There is a possibility of placing up to three value from the list using the subordinate element <gift_for> Urodziny (Birthdays) Imieniny (Names day) Narodziny dziecka (The birth of a child) Chrzest (Christening) Komunia (Holy Communion) Slub (Wedding) Walentynk (Valentine Days) Gwiazdka (Christmas) Wieczor kawalerski (Stag party) Wieczor panienski (Hen party) Zgoda (Reconciliation) Podzkeikowanie (Thanks) Zarty (Joke) Osiemnastka (Eighteenth birthday) <prezenty_na> <prezent_na>zarty</prezent_na> <prezent_na>osiemnastka</prezent_na> <prezent_na>wieczor kawalerski</prezent_na> </prezenty_na> Note: The value of the element <prezenty_na> need to be submitted exactly as in the example above. 15

16 <prezent_dla> (<gifts to>) A product can be a gift to (see the list below). There is a possibility of placing up to three value from the list using the subordinate element <prezent_dla>. The list of values: niej (for her) niego (for him) pary (for a couple) dziecka (for a child) nastolatka (for a teenager) mamy (for a mum) taty (for a dad) babci (for a grandmother) dzadka (for a grandfather) pani domu (for a housewife) dzialkowicza (for a allotment holder) majsterkowicza (for a do-it-yourselfer) kolekcjonera (for a collector) gadzeciarza (for a gadget collector) aktywnych (for active people) domatorow (for stay-at-home people) <prezenty_dla> <prezent_dla>niej</prezent_dla> <prezent_dla>nastolatka</prezent_dla> </prezenty_dla> <dodatkowe> (<additional>) <dodatkowe> <onetefekt /> </dodatkowe> <onetefekt> Onet.pl decided to meet advertiser s needs and is offering of a new product based on a pay per an effect. Thanks to an unique technology which Onet uses, you are able to advertise your products not only in the shopping service but on the whole Onet portal just paying for transferred users, clicks or for the percent from sales. Onet.pl allows some latitude in creating marketing activities in terms of place, time or amount of edited advertisements. If you are going to use onetefekt, it is necessary to attached the following information. Note! It is important that <dodatkowe> tags need to be in the last place among all <oferta> tags. 4. Category ascription (mapping). Mapping category is an ascription of a shop s category to the service s category. If you introduce <id_kategoria_sklep> using a shop category in the XML file containing a transfer, then carrying out mapping is necessary to let offers be displayed in OnetZakupy service. Mapping can be done in two ways: 16

17 4.1. Mapping by using XML file with a category map In order to prepare an XML file with a map of shop s category you need to download an XML file with OnetZakupy categories (the file includes identifiers of all transfer s categories leaf nodes) and a model XML file showing how to do the mapping. Following the pattern you need to make a proper XML file, including all categories in which a shop is going to place offers. <kategoria> <sciezka_kategorii>agd > Do zabudowy > Ekspresy do kawy</sciezka_kategorii> <id_kategorii_sklepu>1</id_kategorii_sklepu> <id_kategorii_pm>2786</id_kategorii_pm> </kategoria> Such a file should be uploaded in a shop s administration panel (map category tab). Every time an offer is exported, it will be automatically ascribed to the proper category of OnetZakupy in accordance with the previous uploaded map Manual mapping category In order to map manually, you need to make an offer s transfer in which you introduce yourself with shop categories. All offers from this transfer will be rejected, however, all shop category from this transfer will be uploaded and displayed under the tab for mapping in the shop panel. Thanks to it, it will be possible to ascribe them manually to the service category. After doing it, you need to export a file with an offer again (that is, again download the same XML file with offers). These offers will be automatically ascribed in accordance with finished mapping and then appear in OnetZakupy service. Finished mapping will be working also in the next transfers. Note: In case of new categories (not mapped yet) the offers included in them are rejected. Every new shop category requires mapping and rejected offers need to be exported again. 17