Dokumentacja pliku w standardzie TrisoSHOP XML

Poniżej przedstawiamy opis struktury pliku XML wykorzystywany w komunikacji pomiędzy systemami zewnętrznymi. O ile w poniższym dokumencie mowa o strukturze pliku opartym na tagach, omawiane rozwiązanie i nazewnictwo pól mają zastosowanie także do pozostałych kanałów komunikacji, np. opartej o TrisoSHOP API i strukturze JSON.

Ostatnie zmiany:

30.11.2024	Dodano pole "desc_safety" Dodano pole "safety_attachments" Dodano dane producentów i podmiotów odpowiedzialnych (GPSR)

Główna struktura pliku

Produkty w standardzie TrisoSHOP XML zawarte są w głównym tagu <products> zawierającym wiele wystąpień tagu <product>.

Opis pól jakie może zawierać pojedynczy produkt jest dostępny w tabeli poniżej, przykład:

<product>
<id>100</id>
<name>Nazwa produktu</name>
</product>

Wersja standardowa

Plik XML w wersji standardowej zawiera poniższe pola

Nazwa pola	Opis	Zakres danych
<id>	Unikalny identyfikator produktu	int
<name>	Nazwa produktu	string (1-200)
<symbol>	Unikalny kod produktu (SKU)	string (0-50)
<ean>	Kod EAN	string (0-18)
<producer>	Nazwa producenta	string (0-100)
<producer_code>	Kod producenta	string (0-50)
<category>	Pełna ścieżka kategorii, separator " > " Np. Kategoria > Podkategoria	string (0 - 500) Pojedyncza kategoria max 100 znaków
<weight>	Waga produktu	float (0.000 - 999999999.999)
<store>	Całkowity stan magazynowy	float (-999999999999.999 - 999999999999.999)
<status>	Status opisowy produktu	string (1 - 100)
<unit>	Jednostka magazynowa	string (1 - 32)
<price_net>	Cena netto produktu	float (0.00 - 99999999.99)
<vat>	Stawka VAT	string (1-15)
<desc_short>	Krótki opis produktu	string (0 - 500)
<desc_long>	Pełny opis produktu (html)	string
<desc_safety>	Informacje na temat bezpieczeństwa produktu	string (0 - 10000)
<gallery>	Galeria produktu, zawiera listę tagów <image> z adresem zdjęcia, przykład: <gallery> <image>https://mojsklep.pl/image1.jpg</image> <image>https://mojsklep.pl/image2.jpg</image> </gallery> Pierwsze zdjęcie z listy zostanie ustawione jako zdjęcie główne	array
<safety_attachments>	Załączniki dotyczące bezpiecznego użytkowania, zawierają listę tagów <attachment> z linkami do pobrania, przykład: <safety_attachments> <attachment>https://mojsklep.pl/certyfikat.php</attachment> <attachment>https://mojsklep.pl/instrukcja.pdf</attachment> </safety_attachments>	array
<dictionaries>	Cechy produktu, opis poniżej	array
<variants>	Warianty produktu, opis poniżej	array

Pole <dictionaries>

Pole zawiera szczegółowe informacje na temat cech produktu. Składa się z wielu wystąpień pola <dictionary>.

Nazwa pola	Opis	Zakres danych
<dictionary>	Zawiera szczegółowe informacje na temat pojedynczej cechy (opisane poniżej) <dictionary> <name>Kolor</name> <words>...</words> </dictionary>
<name>	Nazwa cechy	string (1 - 100)
<kind>	Rodzaj cechy: 1, 2 lub 3 - standardowa cecha do wyszukiwania 4 - cecha opisowa (brak wyszukiwania) 5 - cecha liczbowa (wyszukiwanie po zakresie od-do) Pola 1, 2 i 3 określają wyłącznie sposób zapisywania cechy przez administratora. Wybór tego typu nie wpływa w żaden sposób na zachowanie wyszukiwarki w sklepie. 1 - możliwość określenia zawsze tylko jednej cechy 2 - możliwość wybrania wielu cech z listy 3 - możliwość zaznaczenia wielu cech za pomocą pola checkbox	int (1 - 5)
<words>	Lista wartości zawartych w tagach <word>, przykład: <words> <word>czerwony</word> <word>czarny</word> </words>	array
<word>	Pojedyncza wartość cechy	standardowa (kind: 1-3): string (1 - 100) opisowa (kind: 4): string (1 - 500) liczbowa (kind: 5): float (- 999999999999.999 - 999999999999.999)

Pole <variants>

Pole zawiera szczegółowe informacje na temat wariantów produktu. Składa się z wielu wystąpień pola <variant>.

Nazwa pola	Opis	Zakres danych
<variant>	Zawiera szczegółowe informacja na temat pojedynczego wariantu (opisane poniżej) <variant> <id>100</id> <items>...</items> </variant>
<id>	Unikalny identyfikator wariantu	int
<symbol>	Unikalny kod wariantu (SKU)	string (0-50)
<ean>	Kod EAN	string (0-18)
<weight>	Waga wariantu	float (0.000 - 999999999.999)
<store>	Całkowity stan magazynowy	float (-999999999999.999 - 999999999999.999)
<price_net>	Cena netto wariantu	float (0.00 - 99999999.99)
<vat>	Stawka VAT	string (1-15)
<items>	Tablica zawierająca elementy składowe wariantu <items> <item>...</item> <item>...</item> </items>	array
<item>	Pojedynczy element składowy wariantu <item> <name>Kolor</name> <value>Biały</value> </item>
<name>	Nazwa elementu składowego, np. "Kolor"	string (1-100)
<value>	Wartość elementu składowego, np. "Czerwony"	string (1-100)

Dane producentów i podmiotów odpowiedzialnych (GPSR)

Z uwagi na nowe przepisy GPSR obowiązujące w Unii Europejskiej, obowiązkowe jest wprowadzenie dodatkowych informacji o produktach, takich jak szczegóły kontaktowe producentów oraz informacje na temat podmiotów odpowiedzialnych za wprowadzenie produktów, jeśli są one importowane spoza Unii Europejskiej.

W celu dostosowania się do wymogów, pliki XML w strukturze standardowej mogą zawierać dwie dodatkowe ścieżki <producers> oraz <responsibles> zawierające szczegółowe informacje na temat producentów oraz podmiotów odpowiedzialnych.

Ścieżki znajdą się bezpośrednio w <products> przed wystąpieniem pierwszego tagu opisującego produkt <product>, przykład:

Pole <producers>

Pole zawiera szczegółowe informacje na temat producentów. Składa się z wielu wystąpień pola <producer>.

Nazwa pola	Opis	Zakres danych
<producer>	Zawiera szczegółowe informacje na temat pojedynczego producenta (opisane poniżej) <producer> <id>12</id> <name>Microsoft</name> </producer>
<id>	Unikalny identyfikator producenta Zgodny z <producer_id> przy danych produktu	int
<name>	Nazwa producenta	string (1 - 100)
<street>	Ulica i numer domu	string (0 - 200)
<post_code>	Kod pocztowy	string (0 - 20)
<city>	Miejscowość	string (0 - 100)
<country_code>	Kod kraju	string (0 - 2)
<email>	Adres e-mail	string (0 - 100)
<phone>	Numer telefonu	string (0 - 50)

Pole <responsibles>

Pole zawiera szczegółowe informacje na temat podmiotów odpowiedzialnych za zgodność z przepisami. Składa się z wielu wystąpień pola <responsible>.

Nazwa pola	Opis	Zakres danych
<responsible>	Zawiera szczegółowe informacje na temat pojedynczego podmiotu (opisane poniżej) <responsible> <id>12</id> <name>Adam Kwiatkowski</name> </responsible>
<id>	Unikalny identyfikator podmiotu Zgodny z <responsible_id> przy danych produktu	int
<name>	Imię nazwisko / Nazwa podmiotu	string (1 - 100)
<street>	Ulica i numer domu	string (1 - 200)
<post_code>	Kod pocztowy	string (1 - 20)
<city>	Miejscowość	string (1 - 100)
<country_code>	Kod kraju	string (2)
<email>	Adres e-mail	string (1 - 100)
<phone>	Numer telefonu	string (0 - 50)

Przykładowa struktura pliku

<products date="2024-11-29 16:44" lang="pl" currency="PLN">
<producers>
    <producer>
        <id>226</id>
        <name>ABDANK EU</name>
        <street>ul. Testowa 11</street>
        <post_code>11-111</post_code>
        <city>Testowo</city>
        <country_code>CN</country_code>
        <email>serwis@abdank.com</email>
        <phone>123456789</phone>
    </producer>
</producers>
<responsibles>
    <responsible>
        <id>1</id>
        <name>Adam Kwiatkowski</name>
        <street>ul. Testowa 11</street>
        <post_code>11-111</post_code>
        <city>Testowo</city>
        <country_code>CN</country_code>
        <email>serwis@kwiatkowski.com</email>
        <phone>123456789</phone>
    </responsible>
</responsibles>
<product>
    <id>1</id>
    <name>HP ProBook 650 G5</name>
    <symbol>HP-650</symbol>
    <ean>1234567890</ean>
    <producer>ABDANK EU</producer>
    <producer_code>HP-650-G5</producer_code>
    <producer_id>226</producer_id>
    <responsible_id>1</responsible_id>
    <category>Laptopy i tablety > Laptopy > HP</category>
    <weight>1.500</weight>
    <store>758</store>
    <status>dostępny</status>
    <unit>szt.</unit>
    <price_net>4308.94</price_net>
    <vat>23%</vat>
    <desc_short>...</desc_short>
    <desc_long><p>...</p></desc_long>
    <desc_safety>Używać bezpiecznie</desc_safety>
    <dictionaries>
        <dictionary>
            <name>Cechy dodatkowe</name>
            <kind>4</kind>
            <words>
                <word>Długi opis tekstowy</word>
            </words>
        </dictionary>
        <dictionary>
            <name>Funkcjonalność</name>
            <kind>2</kind>
            <words>
                <word>ochrona całego urządzenia</word>
              <word>ochrona tyłu i boków</word>
            </words>
        </dictionary>
    </dictionaries>
    <variants>
        <variant>
            <id>21</id>
            <symbol>HP-650/1</symbol>
            <ean>1234567890</ean>
            <producer_code>HP-650-G5/1</producer_code>
          <weight>1.500</weight>
          <store>159</store>
        <status>dostępny</status>
        <price_net>0</price_net>
          <vat>23%</vat>
        <items>
              <item>
                  <name>Ilość pamięci RAM</name>
                <value>16 GB</value>
      </item>
        <item>
              <name>Pojemność dysku</name>
              <value>256 GB SSD</value>
          </item>
</items>
</variant>
    </variants>
</product>
</products>