Najlepsze rozwiązania do sprzedaży w internecie
Narzędzia dla Developerów
IdoSell

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