Struktura i jej opis
Plik full.xml jest pierwszym podstawowym plikiem oferty IOF zawierającym podstawowe informacje o towarach np. opisy, zdjęcia, atrybuty, załączniki czy grupy towarów bądź składowe zestawów i kolekcji.
Szczegółowe informacje na temat domyślnego języka oferty (wymagany atrybut @language) oraz waluty oferowanych towarów (wymagany atrybut @currency zgodny z normą ISO-4217) znajdują się w węźle <products>.
W węźle <products> umieszczony jest również węzeł <product> zawierający wszystkie szczegóły pojedynczego produktu: nazwę, opis, kategorię, producenta, jednostkę miary, rozmiary, serię, gwarancję, parametry, cenę wywoławczą, cenę przekreśloną, sugerowaną cenę detaliczną, adres URL, zdjecia i ikony, jak również składowe w przypadku zestawów i kolekcji.
Każdy produkt (węzeł <product>) posiada unikalny identyfikator (wymagany atrybut @id) oraz stawkę VAT (opcjonalny atrybut @vat)
Ceny
Wszystkie zwracane w pliku ceny:
- cena towaru zawarta w węźle <product><price>,
- sugerowana cena towaru zawarta w węźle <product><srp>,
- przekreślona cena detaliczna towaru zawarta w węźle <product><strikethrough_retail_price>,
- przekreślona cena hurtowa towaru zawarta w węźle <product><strikethrough_wholesale_price>,
- cena rozmiaru zawarta w węźle <product><sizes><size><price>,
- sugerowana cena rozmiaru zawarta w węźle <product><sizes><size><srp>,
- przekreślona cena detaliczna rozmiaru zawarta w węźle <product><sizes><size><strikethrough_retail_price>,
- przekreślona cena hurtowa rozmiaru zawarta w węźle <product><sizes><size><strikethrough_wholesale_price>.
są automatycznie przeliczane na walutę klienta docelowego (atrybut @currency zgodny z normą ISO-4217 w węźle <products> ), ale bez uwzględnienia rabatów przypisanych do jego konta w serwisie dostawcy (informacje o tych cenach pomniejszonych o rabat klienta zwracane są w pliku light.xml i mają najwyższy priorytet).
Węzeł każdej ceny zawiera informacje o wartości brutto (opcjonalny atrybut @gross) oraz o wartości netto (wymagany atrybut @net).
Wycinek części struktury XML prezentujący węzły cen towaru i jego rozmiarów:
Rozmiary
Każdy dostępny w pliku rozmiar (węzeł <size>) opisywany jest przez następujące atrybuty:
Atrybuty wymagane:
- @id – identyfikator rozmiaru,
- @code – unikalny kod IAI produktu np. 1454-03.
Atrybuty opcjonalne:
- @panel_name - unikalna nazwa rozmiaru,
- @name - nazwa rozmiaru wyświetlana w sklepie (nie musi być unikalna),
- @code_producer – kod producenta,
- @iaiext:code_external - kod zew. systemu (atrybut rozszerzenia IOF Extensions),
- @weight – waga produktu w opakowaniu podana w gramach,
- @iaiext:weight_net - waga produktu bez opakowania podana w gramach (atrybut rozszerzenia IOF Extensions).
Wycinek części struktury XML prezentujący węzły rozmiarów:
Nazwa, opisy i zdjęcia
Nazwa towaru oraz jego opisy umieszczone są w węźle <description>. Każdy z jego elementów może być zdefiniowany w wielu językach (opcjonalny atrybut @xml:lang).
Zdjęcia oraz ikony umieszczone są w węźle <images>. Każde zdjęcie lub ikony mogą być opisane za pomocą opcjonalnych atrybutów:
- daty ostatniej modyfikacji w formacie YYYY-MM-DD hh:mm:ss (atrybut @changed),
- klucza md5 (atrybut @hash),
- szerokości obrazu w pikselach (atrybut @width),
- wysokości obrazu w pikselach (atrybut @height).
Wycinek części struktury XML prezentujący węzły nazwy, opisów, zdjęć i ikon:
Załączniki do towarów
Rodzaje plików, które są załącznikami do towarów, powinny być opisane zgodnie z formatem MIME. Możesz także określić ograniczenia pobierania pobrań, ustawiając liczbę dni, przez które plik może zostać pobrany (limitation@days) lub liczbę pobrań (limitation@downloads).
Wycinek części struktury XML prezentujący węzły załączników w towarach zwykłych i wirtualnych:
Towary w grupie
Jeśli chcesz zgrupować oferowane towary postępuj zgodnie z poniższymi zasadami:
- każdy towar - zarówno pogrupowany, jak i niezgrupowany - znajduje się na tym samym poziomie w węźle <products><product>,
- każdy towar z danej grupy powinien zawierać węzeł <group> wraz atrybutami @id, @first_product_id, @iaiext:first_product_code_external oraz @iaiext:first_product_code_producer które identyfikują grupę produktów i jednocześnie identyfikują główny produkt w tej grupie. Wartości atrybutów @id, @first_product_id, @iaiext:first_product_code_external oraz @iaiext:first_product_code_producer powinny być takie same we wszystkich towarach danej grupy,
- węzeł <group> identyfikujący daną grupę powinien mieć co najmniej jeden wspólny parametr w każdym produkcie - w postaci węzła <group_by_parameter> z unikalnym identyfikatorem parametru (wymagany atrybut @id) oraz jego nazwą (opcjonalny węzeł <name>),
- węzeł <group_by_parameter> powinien mieć co najmniej jedną wartość parametru, która odróżnia zgrupowane towary - w postaci węzła <product_value> z unikalnym identyfikatorem wartości parametru (wymagany atrybut @id) oraz jej nazwą (opcjonalny węzeł <name>),
- nie ma żadnych ograniczeń co do ilości grupujących parametrów oraz ich wartości,
- nazwa towarów w grupie budowana jest z wszystkich wartości węzłów <product_value> np. dla informacji jak w poniższym przykładzie (nazwa produktu w grupie to skóra \ sportowe \ sznurowadła, a pełna nazwa produktu to Buty Adizero Feather 2 - skóra \ sportowe \ sznurowadła):
Wycinek części struktury XML prezentujący węzły grupy dla pojedynczego towaru z grupy:
Zestawy i kolekcje
Jeśli chcesz zwrócić w ofercie również kolekcje oraz zestawy postępuj zgodnie z poniższymi zasadami:
- każdy towar - zarówno kolekcja, jak i zestaw - znajduje się na tym samym poziomie w węźle <products><product>,
- każdy towar będący składową kolekcji, bądź zestawu powinien zawierać węzeł <bundled> wraz węzłami <product> zawierającymi informację o identyfikatorze (atrybut @id), dostępnej ilości (atrybut @quantity) oraz sposobie prezentacji rozmiarów i wariantów (atrybut @type),
- atrybut @type może przyjmować następujące wartości:
- client_chooses_defined_size - (klient może wybrać jeden ze zdefiniowanych rozmiarów prezentowanych w postaci selektora umożliwiającego wybór tylko jednego z nich),
- client_chooses_defined_size_as_separate_items - (klient widzi każdy rozmiar zwrócony jako osobny produkt składowy),
- client_chooses_size - (klient może wybrać jeden dowolny rozmiar),
- client_chooses_variant - (klient może wybrać jeden dowolny rozmiar w dowolnym wariancie).
- węzeł <bundled><product> może dodatkowo zawierać węzeł <sizes> opisujący rozmiary przypisane do produktu składowego w postaci węzła <size> wraz z identyfikatorem rozmiaru (atrybut @id) jego nazwą odpowiadającą panelowej unikalnej nazwie rozmiaru (atrybut @name) oraz kodem IAI (atrybut @iaiext:code), kodem producenta (atrybut @iaiext:code_producer) i kodem zewnętrznego systemu (atrybut @iaiext:code_external).
Wycinek części struktury XML prezentujący węzły składowych dla zestawu i kolekcji:
Changelog:
IOF 3.0
- w węźle <offer> dodaliśmy opcjonalny atrybut @generated_by pozwalający na zwrócenie informacji o platformie z której dana oferta została wygenerowana,
- w węźle <offer><products><product> dodaliśmy atrybut @type zwracający informacje o typie oferowanego towaru (regular, packaging, virtual, bundle, collection, service),
- zmieniliśmy nazwa węzeła iaiext:category_iai na category_idosell, a sam węzeł stał się podstawowy węzłem oferty zwracanym bez przedrostka iaiext:,
- w węźle <card> dodaliśmy atrybut @url_mobile, który do tej pory obsługiwany był przez rozszerzenie IOF Extensions,
- w węźle <product>:
- obok istniejącego już węzła <strikethrough_retail_price> zwracającego informację o bazowej przekreślonej cenie detalicznej dodaliśmy również węzeł <strikethrough_wholesale_price> zwracający informację o bazowej przekreślonej cenie hurtowej
- dodaliśmy węzeł <bundled> zwracający węzły <product> zawierające informacje o towarach składowych zestawów i kolekcji, sposobu prezentacji ich rozmiarów oraz oferowanej ilości.
- w węźle <product><sizes><size>:
- zmieniliśmy nazwę atrybutu zwracającego unikalną nazwę rozmiaru z @text_id na @panel_name,
- obok istniejącego już węzła <strikethrough_retail_price> zwracającego informację o przekreślonej cenie detalicznej dla danego rozmiaru dodaliśmy również węzeł <strikethrough_wholesale_price> zwracający informację o przekreślonej cenie hurtowej dla danego rozmiaru
- zmieniliśmy, aby atrybuty @iaiext:location_id oraz @iaiext:location_text_id obsługiwane do tej pory przez rozszerzenie IOF Extensions stały się podstawowymi atrybutami węzła <stock> zwracanymi bez przedrostka iaiext:.
- zmieniliśmy nazwę atrybutu @date_changed zwracanego w we wszystkich węzłach w węźle <product><images> na atrybut @changed,
- zmieniliśmy, aby obsługiwane do tej pory przez rozszerzenie IOF Extensions atrybuty @iaiext:distinction, @iaiext:group_distinction, @iaiext:hide, @iaiext:auction_template_hide, @iaiext:context_id stały się podstawowymi atrybutami węzłów <parameter> oraz <value> zwracanymi bez przedrostka iaiext:,
- zmieniliśmy, aby w węźle <group> obsługiwany do tej pory przez rozszerzenie IOF Extensions atrybut @iaiext:first_product_id stał się podstawowym atrybutem węzła zwracanym przez przedrostka iaiext:.
- w węźle <attachments><file>:
- dodaliśmy nowy atrybut @version zwracający informację o wersji danego załącznika (demo lub full),
- zmieniliśmy, aby obsługiwane do tej pory przez rozszerzenie IOF Extensions atrybuty @iaiext:enable, @iaiext:attachment_file_type, @iaiext:download_log, @iaiext:attachment_file_extension stały się podstawowymi atrybutami węzła zwracanymi bez przedrostka iaiext:.
Przykładowa struktura pliku XML:
Zależności między danymi:
- product.category@id jest ściśle powiązany z categories.category@id w pliku categories.xml,
- product.producer@id jest ściśle powiązany z producers.producer@id w pliku producers.xml,
- product.unit@id jest ściśle powiązany z units.unit@id w pliku units.xml,
- product.series@id jest ściśle powiązany z series.series@id w pliku series.xml,
- product.warranty@id jest ściśle powiązany z warranties.warranty@id w pliku warranties.xml,
- product.sizes.size@id jest ściśle powiązany z sizes.group.size@id w pliku sizes.xml,
- product.sizes.size.stock@id jest ściśle powiązany z stocks.stock@id w pliku stocks.xml,
- product.parameters.parameter@id jest ściśle powiązany z parameters.parameter@id w pliku parameters.xml,
- product.parameters.parameter@id z atrybutem @type = "parameter" jest ściśle powiązany z parameters.parameter@id w pliku parameters.xml,
- product.parameters.parameter.@id z atrybutem @type = "section" jest ściśle powiązany z parameters.sections.section@id w pliku parameters.xml,
- product.parameters.parameter.value@id jest ściśle powiązany z parameters.values.value@id w pliku parameters.xml,
- products.product.group.group_by_parameter@id jest ściśle powiązany z products.product.parameters.parameter@id oraz z parameters.parameters.parameter@id w pliku parameters.xml,
- products.product.group.group_by_parameter.product_value@id jest ściśle powiązany z products.product.parameters.parameter.value@id oraz z parameters.parameters.parameter@id w pliku parameters.xml.
Pliki do pobrania
- Pobierz przykład pliku XML full
- Pobierz walidator schematu XSD full