Internet Offer Format (IOF): jak czytać strukturę pliku full.xml

Internet Offer Format for Shops (IOF) to format wymiany danych o ofercie sklepu, a plik full.xml przekazuje szczegółowe informacje o produktach w implementacji, która go udostępnia. Dokumentacja IdoSell określa full.xml jako podstawowy plik oferty z opisami, zdjęciami, atrybutami, załącznikami, grupami produktów oraz składnikami zestawów i kolekcji.

W dokumentacji IdoSell produkt może mieć cenę w węźle ``, a rozmiar może mieć osobną cenę w ``. Węzeł wariantu może zawierać informacje o stanie. Dokumentacja opisuje też cenę netto jako wymaganą wartość w atrybucie `net` oraz cenę brutto jako opcjonalny atrybut `gross`; nie potwierdza cen przypisanych do grup klientów w full.xml. Te informacje zweryfikowaliśmy 16.10.2026 w dokumentacji struktury pliku full.xml IdoSell.

Nie zakładaj, że każdy plik IOF zawiera te same pola ani że każda implementacja obsługuje identyczny zestaw plików. Sprawdź wersję specyfikacji i dokumentację producenta eksportu, a także ustal, czy źródło publikuje osobny plik aktualizacji przyrostowych. Pełny eksport i aktualizacje przyrostowe mają różne konsekwencje dla synchronizacji.

Jeżeli dane katalogowe mają wspierać rozwój widoczności produktów, pozycjonowanie SEO może objąć pracę nad kategoriami i ofertą. Warto też poznać dane strukturalne Schema.org, które opisują treść strony wyszukiwarkom.

Dokument XML składa się z elementów ułożonych hierarchicznie, a jego element główny obejmuje dane oferty i rekordy produktów. Dokładne nazwy elementów trzeba odczytać z pliku oraz dokumentacji zgodnej z jego wersją.

XML to format znaczników, w którym element może zawierać tekst, atrybuty i elementy potomne. Deklaracja XML może określać wersję oraz kodowanie. Poniższy przykład jest uproszczony i nie stanowi schematu IOF:

<?xml version="1.0" encoding="UTF-8"?>
<offer>
  <products>
    <product id="SKU-001">
      <name>Przykładowy produkt</name>
    </product>
  </products>
</offer>

Nazwy `offer`, `products` i `product` w przykładzie są poglądowe. Nie kopiuj ich do integracji bez potwierdzenia w specyfikacji danego eksportu. Przestrzeń nazw XML, czyli namespace, kwalifikuje nazwy elementów do określonego słownika; jeśli parser nie odnajduje elementu, sprawdź namespace, wielkość liter i położenie elementu w hierarchii.

Kodowanie określa sposób zapisu znaków. Gdy deklaracja wskazuje UTF-8, a plik zapisano w innym kodowaniu, polskie znaki mogą zostać uszkodzone albo parser może przerwać odczyt. Porównaj deklarację z faktycznym kodowaniem pliku przed modyfikacją danych.

Pola oferty opisują produkt, jego ceny, warianty, dostępność i treści, ale ich wymagalność zależy od specyfikacji oraz odbiorcy importu. Tabela rozróżnia przykładowe węzły udokumentowane przez IdoSell od ogólnych pojęć, których nazwa może być inna w innym eksporcie.

W przypadku pliku IdoSell dokumentacja podaje również, że atrybut `gross` przy węźle ceny jest opcjonalny, a `net` wymagany. Tabela nie ustanawia wymagań dla innych dostawców IOF; przed mapowaniem potwierdź je w dokumentacji własnego źródła i importera.

Stabilny identyfikator pozwala importerowi rozpoznać, że kolejny rekord aktualizuje istniejący produkt lub wariant. Zmiana klucza może spowodować utworzenie duplikatu zamiast aktualizacji.

Ustal, czy identyfikatorem produktu jest trwałe ID źródłowe, SKU czy inny klucz. Nazwa produktu może się zmienić, więc nie powinna zastępować stabilnego identyfikatora, jeśli importer używa go do aktualizacji. Wariant rozmiaru lub koloru powinien mieć jednoznaczne powiązanie z produktem nadrzędnym zgodnie z modelem odbiorcy.

W dokumentacji IOF IdoSell rozmiar ma własne atrybuty identyfikujące, a węzeł stanu może być powiązany z identyfikatorem stanu. Specyfikacja opisuje też powiązania z innymi plikami danych, takimi jak kategorie, producenci i jednostki. Przed integracją sprawdź, czy identyfikatory w plikach pomocniczych odpowiadają identyfikatorom użytym w full.xml.

Przetestuj trzy przypadki: nowy produkt, aktualizację ceny lub stanu istniejącego wariantu oraz brak wariantu w kolejnym eksporcie. Brak rekordu nie musi oznaczać polecenia usunięcia go z systemu docelowego.

Perspektywa KC Mobile: w integracjach katalogów ryzyko duplikatów często pojawia się po zmianie klucza, która nie zatrzymuje importu. Zalecamy monitorować listę nowych rekordów po synchronizacji i porównywać ją z zaplanowanymi nowościami.

Poprawność full.xml sprawdzisz przez kontrolę składni XML, kodowania, walidację XSD i porównanie rekordów z katalogiem źródłowym. XSD to schemat definiujący dozwolone elementy, atrybuty i typy wartości dla określonego formatu.

Wykonaj kontrole w tej kolejności:
1. Pobierz plik z adresu źródła i zachowaj kopię wraz z datą pobrania.
2. Sprawdź, czy plik jest kompletny, a deklaracja kodowania odpowiada faktycznemu zapisowi.
3. Otwórz plik parserem XML. Usuń błędy składni, takie jak niedomknięty element, nieprawidłowe zagnieżdżenie lub nieescapowany znak specjalny.
4. Jeśli dostawca udostępnia XSD dla używanej wersji, zwaliduj plik względem tego schematu.
5. Porównaj rekordy z katalogiem źródłowym: identyfikator, nazwę, cenę, walutę, stan, wariant i adres zdjęcia.
6. Porównaj liczbę rekordów z informacją o eksporcie, uwzględniając filtry i wykluczenia.

Walidacja XSD potwierdza zgodność struktury z konkretnym schematem, ale nie potwierdza, że kategoria istnieje w sklepie, zdjęcie jest dostępne albo cena pasuje do reguł handlowych. IdoSell udostępnia na stronie dokumentacji przykładowy plik full oraz walidator XSD; użyj wersji odpowiadającej eksportowi. Gdy inny dostawca nie publikuje schematu, testuj próbkę zgodnie z jego dokumentacją.

Błąd składni XML może zatrzymać odczyt całego dokumentu, a błąd mapowania lub reguły biznesowej może dotyczyć wybranych rekordów albo prowadzić do zapisu nieprawidłowych danych. Komunikat importera i identyfikator rekordu pomagają ustalić warstwę problemu.

Tabela odpowiada na pytanie, od jakiego testu zacząć przy typowych objawach importu. Nazwy komunikatów zależą od użytego parsera i systemu odbierającego.

Jeśli ten sam błąd parsera obejmuje cały dokument, sprawdź plik źródłowy i jego składnię. Jeśli importer odrzuca wybrane warianty lub kategorie, porównaj ich wartości z mapowaniem i konfiguracją systemu docelowego.

Zapisuj pełny komunikat, ID rekordu, wersję pliku i czas importu. Ogólny status "import nieudany" nie wyjaśnia, czy przyczyna leży w eksporcie, mapowaniu czy regułach biznesowych.

Bezpieczne mapowanie IOF zaczyna się od próbki w środowisku testowym i decyzji, który system zarządza ceną, stanem oraz opisem. Import całego katalogu bez próby może nadpisać ręczne zmiany albo utworzyć duplikaty.

Dla każdej grupy pól ustal źródło prawdy i zachowanie aktualizacji. ERP może zarządzać ceną i dostępnością, a sklep opisem marketingowym. Zapisz, czy import nadpisuje ręczne zmiany, pomija puste pola, aktualizuje tylko zmienione rekordy i jak traktuje produkty nieobecne w eksporcie.

W środowisku testowym zaimportuj produkt prosty, wariantowy, rekord bez zdjęcia i opis z polskimi znakami. Zapisz rekordy dodane, zmienione i odrzucone, a po teście porównaj liczbę produktów oraz ceny i stany z raportem eksportu.

Jeśli uporządkowany katalog ma wspierać widoczność w wyszukiwarce, pozycjonowanie SEO dla sklepu może objąć rozwój widoczności kategorii i produktów. Zasady synchronizacji, mapowanie oraz operacje na danych powinien zatwierdzić właściciel integracji.

Przed integracją potwierdź wersję IOF, schemat, częstotliwość eksportu i właściciela każdego pola. Plik poprawny składniowo nadal może zawierać błędne ceny, stany lub identyfikatory dla systemu docelowego.

Lista kontrolna do uzgodnienia przez sklep, dostawcę pliku i wykonawcę integracji:
- Wersja specyfikacji i zgodny plik XSD, jeśli dostawca go udostępnia.
- Kodowanie, kompresja, lokalizacja pliku i sposób uwierzytelnienia.
- Częstotliwość eksportu, rozmiar pliku i zachowanie po błędzie pobrania.
- Źródło prawdy dla identyfikatorów, SKU, cen, walut, stanów, opisów i zdjęć.
- Zasady wariantów, aktualizacji przyrostowych, usunięć i pustych wartości.
- Zachowanie importera wobec ręcznych zmian i ponownego importu tego samego pliku.
- Odpowiedzialność za błędy eksportu, mapowania i katalogu docelowego.

Zapisz uzgodnienia wraz z przykładowym rekordem wejściowym i oczekiwanym wynikiem importu. Przy rozwijaniu widoczności treści możesz także sprawdzić, jak Schema.org wpływa na widoczność w AI oraz jak działają AI Overviews a pozycje w Google.

• Co to są dane strukturalne? Definicja, przykłady i zastosowanie
• Google nie pokazuje featured snippets? Sprawdź przyczyny i napraw problem
• Marketing lokalny zgodnie z umową: jak sprawdzić zakres i rozliczenie
• Google Web Stories: czym są, jak je tworzyć i sprawdzić przed publikacją