Price Wars II Zaawansowana konfiguracja Dokumentacja formatu SXF Wersja 3

Table of Contents

Struktura XML powstała z myślą o eksporcie produktów z platform Prestashop oraz thirtybees. Celem formatu jest odzwierciedlenie struktury produktowej używanej w w/w platformach.

Struktura XML w wersji 3

Zmiany w wersji 3:

  • ustandaryzowanie pól językowych, aby praktycznie każdy element opisowy mógł zawierać wielojęzyczność
  • zmieniona struktura przechowująca opis, opis krótki i nazwę produktu
  • Zamiana elementu <p> » <id> na atrybut elementu: `<p id="n">`
  • Zamiana elementu <c> » <id_product_attribute>
    • na atrybut elementu: <c id="n">
  • Zmiana pola quantity na stock - jak jest w głównym obiekcie produktu

Definicja typów danych

Każdy z elementów XML powinien zachować określony typ danych. Definicje typów danych i ich oznaczenia:

  • {type:#int} Liczba naturalna >= 0
  • {type:#id_reference} Identyfikator. Zalecany format: a-zA-Z0-9_-
  • {type:#char} ciąg znaków
  • {type:#ean13} 13 cyfrowy ciąg liczbowy
  • {type:#string} - ciąg znaków a-z
  • {type:#string_cdata} jak wyżej, zalecane zamknięcie w CDATA
  • {type:#vat} Wartość VAT w formie % bez znaku procent. Tj. 0 5 8 23 etc.
  • {type:#float} Wartość zmiennoprzecinkowa
  • {type:#float:n} Wartość zmiennoprzecinkowa zaokrąglona do n {type:#float:3} wartość zaokrąglna do 3 miejsc po przecinku
  • {type:#url} Adres URL
  • {type:#unit_weight} Jednostka Wagi. Domyślnie kg
  • {type:#iso_lang} Kod języka ISO 639-1 pl, en lub kod języka IETF ( IETF Language tag ) pl-PL
  • {type:#iso_currency} Kod waluty ISO 4217 (PLN, USD, GPB etc.)

Wielojęzyczność

Dla uproszczenia elementy wielojęzykowe w XML będziemy oznaczali jako {xml:#lang}. Oznacza to, że elementy tak oznaczone, zawierać mogą prosty ciąg znaków, lub zbiór elementów <lang>

Definicja

<?xml version="1.0" encoding="utf-8"?>
<root>
    <!-- Pełny obiekt językowy -->
    <obiekt_jezykowy>
        <!-- Obiekt powinien, ale nie musi zawierać tagu CDATA -->
        <lang iso="{type:#iso_lang}">{type:#string_cdata}</lang>
        <lang iso="{type:#iso_lang}">{type:#string_cdata}</lang>
        <lang iso="{type:#iso_lang}">{type:#string_cdata}</lang>
        <lang iso="{type:#iso_lang}">{type:#string_cdata}</lang>
    </obiekt_jezykowy>
    <!-- Uproszczony obiekt językowy (w przypadku tylko 1 języka) -->
    <obiekt_jezykowy>{type:#string_cdata}</obiekt_jezykowy>

</root>

Przykłady

Zakładając uproszczony przykład XML zawierającego tylko 1 element <description>

<?xml version="1.0" encoding="utf-8"?>
<root>
    <description>{xml:#lang}</description>
</root>

Oznacza to, że tak zapisany abstrakt oznacza następujące możliwe fromaty:

<?xml version="1.0" encoding="utf-8"?>
<root>
    <description>Opis produktu lorem ipsum</description>
</root>

i/lub

<?xml version="1.0" encoding="utf-8"?>
<root>
    <description>
        <lang iso="pl">opis</lang>
        <lang iso="en">description</lang>
        <lang iso="de">Beschreibung</lang>
        <lang iso="fr">la description</lang>
    </description>

</root>

Struktura Pliku XML

Definicja w formacie XML

<?xml version="1.0" encoding="utf-8"?>
    <root sxfversion="3.0" gendate="2000-01-01 00:00:00" currency="{type:#iso_currency}">
        <categories>
            <c id="{type:#id_reference}" id_parent="{type:#id_reference}">{xml:#lang}</c>
        </categories>
        <products>
            <p id="{type:#id_reference}">
                <name>{xml:#lang}</name>
                <description>{xml:#lang}</description>
                <description_short>{xml:#lang}</description_short>
                <reference>{type:#id_reference}</reference> <!-- Kod nadany przez producenta -->
                <ean13>{type:#ean13}</ean13> <!-- EAN13 -->
                <stock>{type:#int}</stock> <!-- Stan magazynowy produktu (W przypadku posiadania kombinacji, suma stanów kombinacji) -->
                <price> <!-- Ceny zakupu, z uwzględnieniem zniżek -->
                    <tax>{type:#vat}</tax> <!-- Podatek w % jako liczba --> 
                    <srp>{type:#float}</srp> <!-- Cena netto SRP / Cena bez rabatu -->
                    <price>{type:#float}</price> <!-- Cena Netto zakupu | Przykład pokazuje rabat 50% -->
                </price>
                <tags>
                    <lang iso="{type:#iso_lang}">
                        <tag>{type:#char}</tag>
                    </lang>
                </tags>
                <tags> <!-- Dla plików jednojęzykowych nie trzeba definiować <lang> -->
                    <tag>{type:#char}</tag>
                </tags>
                <weight unit="{type:#unit_weight}">{type:#float}</weight>
                <manufacturer id="{type:#id_reference}">{xml:#lang}</manufacturer>
                <cat id="{type:#id_reference}"/>
                <images> <!-- Wszystkie zdjęcia -->
                    <img id="{type:#id_reference}">{type:#url}</img>
                </images>
                <features>
                    <f>
                        <name id="{type:#id_reference}">{xml:#lang}</name>
                        <value id="{type:#id_reference}">{xml:#lang}</value>
                    </f>
                    <f>
                        <name id="{type:#id_reference}">{xml:#lang}</name>
                        <value id="{type:#id_reference}">{xml:#lang}</value>
                    </f>
                </features>
                <combinations>
                    <c id="{type:#id_reference}"> <!-- Kombinacja - może być wiele -->
                        <reference>{type:#id_reference}</reference>
                        <ean13>{type:#ean13}</ean13>
                        <price> <!-- Zawiera ostateczną cenę produktu w tej kombinacji -->
                            <srp>{type:#float}</srp> <!-- Cena netto SRP - Zalecana cena sprzedaży -->
                            <price>{type:#float}</price> <!-- Cena Netto sprzedaży - ile klient końcowy płaci za twoar -->
                        </price>
                        <default>{type:#int}</default>  <!-- 1 lub 0 . Tylko 1 atrybut może mieć wartość 1, co oznacza że jest to główny atrybut -->
                        <weight_impact>{type:#float}</weight_impact><!-- Wpływ na wagę (waga atrybutu = waga produktu + weight_impact) -->
                        <stock>{type:#int}</stock> 
                        <subname>{xml:#lang}</subname>
                        <images> <!-- Zdjęcia przypisane do konkretnej kombinacji -->
                            <img id="{type:#id_reference}">{type:#url}</img>
                        </images>
                        <attributes>
                            <a>
                                <name>{xml:#lang}</name>
                                <value>{xml:#lang}</value>
                            </a>
                        </attributes>
                    </c>
                </combinations>
            </p>
        </products>
    </root>

Opis pól

Z - pole zalecane; - nie dotyczy

Pole Wymagane Wielojęzykowe Unikalny Opis
root > Y N Y Element główny
> categories Y N Y Informacje o kategoriach
> categories > c Y N N Element opisujący jedną kategorię. Wartość to nazwa kategorii (bez pełnej ścieżki)
> categories > c:id Y - Y Unikalne ID kategorii
> categories > c:id_parent Y - Y ID kategorii nadrzędnej. 0 dla kategorii głównej
root > products Y - Y
root > products > p:id Tożsame z elementem id
root > products > p > Y - N Element produktu
> name Y Y Y
> description Z Y Y
> description_short Z Y Y
> reference Z N Y
> ean13 Z N Y
> stock Y - Y
> price Y - Y
> price > tax Y - Y
> price > srp N - Y
> price > price Y - Y
> tags N Struktura językowa tego pola posiada inną definicję językową niż reszta pól
> tags > lang Y/N Niewymagane dla plików jednojęzykowych
> tags > lang:iso Y/N Niewymagane dla plików jednojęzykowych
> tags > lang > tag Y Wymagane, może być umieszczone w tagu lang lub poza nim
> weight N - Y
> manufacturer N Y Y
> manufacturer:id N - Y
> cat Y - N Element z bez wartości - pierwszy element jest kategorią domyślną produktu
> cat:id Y - Y Atrybut z ID kategorii – root > categories > c:id
> images Z - Y Element powinien być dodawany tylko jeśli zawiera podelementy
> images img Y - N Wartośc pola do adres URL zdjęcia
> images img:id N - Y
> images img:hash N - Y Hash może być zarówno datą jak i sumą kontrolną
> features N Y Element powinien być dodawany tylko jeśli zawiera podelementy
> features > f Y - N Element zawierający informację o 1 cesze
> features > f > name Y Y Y Nazwa cechy np. Materiał
> features > f > name:id N - Y Unikalne ID cechy z systemu generującego
> features > f > value Y Y N Element można dodawać wielokrotnie, jeśli system obsługuje wiele cech
> features > f > value:id N - Y
> combinations N - Y
> combinations > c > Y - N Element kombinacji
> c:id Y - Y
> c > reference Z N Y
> c > ean13 Z N Y
> c > price N - Y Struktura obiektu price jest taka sama jak w głównym produkcie “p > price” lecz nie wymaga elementu “tax”
> c > default N - Y
> c > weight_impact N - Y
> c > stock Y - Y Wcześniej była to wartość “quantity”
> c > subname N Y Y
> c > images N - Y
> c > images > img Y - N
> c > images > img:id N - Y
> c > images > attributes N - Y
> c > images > attributes > a Y - N
> c > images > attributes > a > name Y Y Y
> c > images > attributes > a > value Y Y Y

Przykładowe Pliki XML

Wielojęzykowy plik XML

Zarówno w format wielojęzyczny jak i jednojęzyczny może zawierać elementy jedno i wielojęzykowe. 
<?xml version="1.0" encoding="utf-8"?>
    <root sxfversion="2.0" gendate="2000-01-01 00:00:00" currency="PLN">
        <categories>
            <c id="1" id_parent="0">
                <lang iso="en"><![CDATA[Haberdashery]]></lang>
                <lang iso="pl"><![CDATA[Pasmanteria]]></lang>
                <lang iso="de"><![CDATA[Kurzwaren]]></lang>
                <lang iso="de"><![CDATA[Галантерея]]></lang>
            </c>
            <c id="2" id_parent="1">
                <lang iso="en"><![CDATA[laces]]></lang>
                <lang iso="pl"><![CDATA[Sznurówki]]></lang>
                <lang iso="de"><![CDATA[Schnürsenkel]]></lang>
                <lang iso="de"><![CDATA[шнурки]]></lang>
            </c>
        </categories>
        <products>
            <p id="1">
                <name>
                    <lang iso="en"><![CDATA[Product Name]]></lang>
                    <lang iso="pl"><![CDATA[Nazwa produktu]]></lang>
                    <lang iso="de"><![CDATA[Produktname]]></lang>
                    <lang iso="de"><![CDATA[наименование товара]]></lang>
                </name>
                <description>
                    <lang iso="en"><![CDATA[Long description of a product]]></lang>
                    <lang iso="pl"><![CDATA[Długi opis produktu]]></lang>
                    <lang iso="de"><![CDATA[Lange Beschreibung eines Produkts]]></lang>
                    <lang iso="de"><![CDATA[Длинное описание продукта]]></lang>
                </description>
                <description_short>
                    <lang iso="en"><![CDATA[short description of a product]]></lang>
                    <lang iso="pl"><![CDATA[Krótki opis produktu]]></lang>
                    <lang iso="de"><![CDATA[kurze Beschreibung eines Produkts]]></lang>
                    <lang iso="ru"><![CDATA[краткое описание продукта]]></lang>
                </description_short>
                <reference>ABC_XYZ-1</reference> <!-- Kod nadany przez producenta -->
                <ean13>1234567890123</ean13> <!-- EAN13 -->
                <stock>5</stock> <!-- Stan magazynowy produktu (W przypadku posiadania kombinacji, suma stanów kombinacji) -->
                <price> <!-- Ceny zakupu, z uwzględnieniem zniżek -->
                    <tax>23</tax> <!-- Podatek w % jako liczba --> 
                    <srp>200</srp> <!-- Cena netto SRP / Cena bez rabatu -->
                    <price>160.33</price> <!-- Cena Netto zakupu | Przykład pokazuje rabat 50% -->
                </price>
                <weight unit="kg">0.25</weight>
                <manufacturer id="1">
                    <lang iso="en"><![CDATA[Manufacturer of shoelaces]]></lang>
                    <lang iso="pl"><![CDATA[Producent sznurówek]]></lang>
                    <lang iso="de"><![CDATA[Hersteller von Schnürsenkeln]]></lang>
                    <lang iso="de"><![CDATA[Производитель шнурков]]></lang>
                </manufacturer>
                <tags>
                    <lang iso="pl">
                        <tag>Czerwony</tag>
                        <tag>Wielokolorowy</tag>
                    </lang>
                    <lang iso="en">
                        <tag>Reddish</tag>
                        <tag>Red</tag>
                        <tag>Multicolor</tag>
                    </lang>
                </tags>
                <cat id="2"/>
                <images> <!-- Wszystkie zdjęcia -->
                    <img id="1" hash="2020-01-03">https://example.com/images/1.jpg</img>
                    <img id="2" hash="a8f5f167f44f4964e6c998dee827110c">https://example.com/images/2.jpg</img>
                </images>
                <features>
                    <f>
                        <name id="1">
                            <lang iso="en"><![CDATA[Length]]></lang>
                            <lang iso="pl"><![CDATA[Długość]]></lang>
                            <lang iso="de"><![CDATA[Länge]]></lang>
                            <lang iso="ru"><![CDATA[длина]]></lang>
                        </name>
                        <value id="1">
                            <lang iso="en"><![CDATA[Long]]></lang>
                            <lang iso="pl"><![CDATA[Długa]]></lang>
                            <lang iso="de"><![CDATA[Lange]]></lang>
                            <lang iso="ru"><![CDATA[Length in cm]]></lang>
                        </value>
                    </f>
                    <f>
                        <name id="2">
                            <lang iso="en"><![CDATA[Purpose]]></lang>
                            <lang iso="pl"><![CDATA[Przeznaczenie]]></lang>
                            <lang iso="de"><![CDATA[Zweck]]></lang>
                            <lang iso="ru"><![CDATA[Цель]]></lang>
                        </name>
                        <value id="3">
                            <lang iso="en"><![CDATA[party]]></lang>
                            <lang iso="pl"><![CDATA[imprezowe]]></lang>
                            <lang iso="de"><![CDATA[party]]></lang>
                            <lang iso="ru"><![CDATA[партия]]></lang>
                        </value>
                        <value id="4">
                            <lang iso="en"><![CDATA[casual]]></lang>
                            <lang iso="pl"><![CDATA[beiläufig]]></lang>
                            <lang iso="de"><![CDATA[beiläufig]]></lang>
                            <lang iso="ru"><![CDATA[повседневная]]></lang>
                        </value>
                    </f>
                    <f>
                        <name id="3">
                            <lang iso="en"><![CDATA[Length in cm]]></lang>
                            <lang iso="pl"><![CDATA[Długość w cm]]></lang>
                            <lang iso="de"><![CDATA[Länge in cm]]></lang>
                            <lang iso="ru"><![CDATA[Длина в см]]></lang>
                        </name>
                        <value id="5">15cm</value>
                    </f>
                </features>
                <combinations>
                    <c id="1">
                        <reference>XYZ_C1</reference>
                        <ean13>1231231231234</ean13>
                        <price>
                            <srp>50</srp>
                            <price>25</price>
                        </price>
                        <default>1</default>
                        <weight_impact>0.5</weight_impact>
                        <stock>5</stock> 
                        <subname>
                            <lang iso="en"><![CDATA[Sznurówki]]></lang>
                            <lang iso="pl"><![CDATA[Sznurówki]]></lang>
                            <lang iso="de"><![CDATA[Sznurówki]]></lang>
                        </subname>
                        <images> <!-- Zdjęcia przypisane do konkretnej kombinacji -->
                            <img id="2">https://example.com/images/2.jpg</img>
                        </images>
                        <attributes>
                            <a>
                                <name>
                                    <lang iso="en"><![CDATA[Color]]></lang>
                                    <lang iso="pl"><![CDATA[Kolor]]></lang>
                                    <lang iso="de"><![CDATA[Farbe]]></lang>
                                    <lang iso="ru"><![CDATA[цвет]]></lang>
                                </name>
                                <value>
                                    <lang iso="en"><![CDATA[green]]></lang>
                                    <lang iso="pl"><![CDATA[zielone]]></lang>
                                    <lang iso="de"><![CDATA[grün]]></lang>
                                    <lang iso="ru"><![CDATA[зеленый]]></lang>
                                </value>
                            </a>
                        </attributes>
                    </c>
                </combinations>
            </p>
        </products>
    </root>

Uproszczony, jednojęzykowy plik XML

<?xml version="1.0" encoding="utf-8"?>
    <root sxfversion="2.0" gendate="2000-01-01 00:00:00" currency="PLN">
        <categories>
            <c id="1" id_parent="0"><![CDATA[Pasmanteria]]></c>
            <c id="2" id_parent="1"><![CDATA[Sznurówki]]></c>
        </categories>
        <products>
            <p id="1">
                <name><![CDATA[Nazwa produktu]]></name>
                <description><![CDATA[Długi opis produktu]]></description>
                <description_short><![CDATA[Krótki opis produktu]]>
                </description_short>
                <reference>ABC_XYZ-1</reference> <!-- Kod nadany przez producenta -->
                <ean13>1234567890123</ean13> <!-- EAN13 -->
                <stock>5</stock> <!-- Stan magazynowy produktu (W przypadku posiadania kombinacji, suma stanów kombinacji) -->
                <price> <!-- Ceny zakupu, z uwzględnieniem zniżek -->
                    <tax>23</tax> <!-- Podatek w % jako liczba --> 
                    <srp>200</srp> <!-- Cena netto SRP / Cena bez rabatu -->
                    <price>160.33</price> <!-- Cena Netto zakupu | Przykład pokazuje rabat 50% -->
                </price>
                <tags>
                    <tag>Czerwony</tag>
                    <tag>Kolorowy</tag>
                </tags>
                <weight unit="kg">0.25</weight>
                <manufacturer id="1"><![CDATA[Producent sznurówek]]> </manufacturer>
                <cat id="2"/>
                <images> <!-- Wszystkie zdjęcia -->
                    <img id="1" hash="2020-01-03">https://example.com/images/1.jpg</img>
                    <img id="2" hash="a8f5f167f44f4964e6c998dee827110c">https://example.com/images/2.jpg</img>
                </images>
                <features>
                    <f>
                        <name id="1"><![CDATA[Długość]]></name>
                        <value id="1"><![CDATA[Długa]]></value>
                    </f>
                    <f>
                        <name id="2"><![CDATA[Przeznaczenie]]></name>
                        <value id="3"><![CDATA[imprezowe]]></value>
                        <value id="4"><![CDATA[beiläufig]]></value>
                    </f>
                    <f>
                        <name id="3"><![CDATA[Długość w cm]]></name>
                        <value id="5">15cm</value>
                    </f>
                </features>
                <combinations>
                    <c id="1">
                        <reference>XYZ_C1</reference>
                        <ean13>1231231231234</ean13>
                        <price>
                            <srp>50</srp>
                            <price>25</price>
                        </price>
                        <default>1</default>
                        <weight_impact>0.5</weight_impact>
                        <stock>5</stock> 
                        <subname><![CDATA[Sznurówki Zielone]]></subname>
                        <images> <!-- Zdjęcia przypisane do konkretnej kombinacji -->
                            <img id="2">https://example.com/images/2.jpg</img>
                        </images>
                        <attributes>
                            <a>
                                <name><![CDATA[Kolor]]></name>
                                <value><![CDATA[zielone]]></value>
                            </a>
                        </attributes>
                    </c>
                </combinations>
            </p>
        </products>
    </root>