Informacje ogólne

Opisane w tym dokumencie API (Application Programming Interface) służy do importu katalogu produktów z Hurtowni i przeznaczone jest dla odbiorców hurtowych. API dostępne jest pod adresem
http://adres-hurtowni.pl/importapi.php
Aby go użyć, należy powyższy URL wywołać poleceniem http GET dodając opisane niżej parametry. W odpowiedzi uzyskuje się dokument xml zawierający żądane dane lub komunikat błędu.

Parametry wywołania

Każde polecenie pobrania danych przez API wymaga autoryzacji i musi zaczynac się od
http://adres-hurtowni.pl/importapi.php?u=usr&h=pas&w=1&z=[...]
gdzie usr i pas są identyfikatorem użytkownika i hasłem uzyskanym podczas aktywacji usługi. Parametr 'w' oznacza nr wersji API i obecnie jest równy 1. Parametr 'z' określa jaki zasób ma zostać zwrócony. Dalej mogą wystąpić kolejne parametry zależne od wartości 'z'.

Wyjątkiem jest polecenie pobrania zdjęcia, które ma postać

http://adres-hurtowni.pl/importapi.php?zdj=id_zdjecia

i w odpowiedzi zwracany jest plik graficzny lub w przypadku braku zdjęcia o podanym identyfikatorze błąd http 404.

Każda odpowiedź xml w głównym elemencie (root) zawiera atrybut 'wersja' określający aktualny numer wersji api. Wraz z rozwojem API numer ten będzie się zwiększał. W opisanym niżej rekordzie stanu atrybut 'wersja_wymagana' określa jaką minimalną wersję API musi obsługiwać program importujący, aby zachować kompatybilność z aktualną wersją API.

Odczyt stanu

Aby uzyskać informacje o aktualnym stanie danych możliwych do importu należy użyć parametru z=stan. Informuje on o tym czy import jest dostępny i zawiera sumaryczne infomacje o danych. Postać polecenia:
http://adres-hurtowni.pl/importapi.php?u=usr&h=pas&w=1&z=stan
Przykładowa odpowiedź: [+-]

Specyfikacja xsd:[+-]

Pobranie danych słownikowych

Dane słownikowe uzyskuje się podając parametr z=slo. Zawierają rozwinięcie danych, które w produkcie zapisane są jako kod liczbowy i obejmują strukturę kategorii, nazwy producentów i nazwa stanów dostępności.

Struktura kategorii zawiera tylko te kategorie, które aktualnie są dostępne do importu

Postać polecenia:
http://adres-hurtowni.pl/importapi.php?u=usr&h=pas&w=1&z=slo

Specyfikacja xsd:[+-]

Pobranie kategorii dwóch poziomów

Uzyskuje się je podając parametr z=kat2p. Jest to uproszczona lista kategorii ograniczona do pierwszych dwóch poziomów. Jej przeznaczeniem jest umożliwienie definiowania filtrów w programie importującym dane.

Podobnie jak w danych słownikowych, struktura kategorii zawiera tylko te kategorie, które aktualnie są dostępne do importu.

Postać polecenia:
http://adres-hurtowni.pl/importapi.php?u=usr&h=pas&w=1&z=kat2p

Specyfikacja xsd:[+-]

Pobranie informacji o produktach

Polega na sekwencyjnym wysyłaniu polecenia importu z parametrem z=prod i odbiorze kolejnych paczek danych. Ilość produktów zwróconych jednorazowo w paczce jest określona parametrem 'il' i powinna być dostosowana do możliwości środowiska, w którym pracuje program importujący. Zaleca się, aby była to liczba w zakresie 100-1000. Maksymalna dopuszczalna ilość to 10000.

Możliwe jest ograniczenie zakresu importowanych danych do produktów z wybranej kategorii wraz z podkategoriami.

Wśród danych opisujących produkt może być identyfikator zdjęcia. Zdjęcia produktów pobiera się pojedyńczo poleceniem podanym na wstępie instrukcji.

Uwaga. Ceny produktów znajdujących się w specyfikacji, są w kwocie brutto. Należy uwzględnić to podczas dostosowania współpracującego oprogramowania.

Parametry używane do pobrania informacji o produktach: Przykładowa postać polecenia:
http://adres-hurtowni.pl/importapi.php?u=usr&h=pas&w=1&z=prod&pp=1000&il=100

Specyfikacja xsd:[+-]

Komunikat błędu

W sytuacjach, kiedy polecenie nie może zostać prawidłowo wykonane, zamiast xml z danymi może zostać zwrócony xml z opisem błędu. Opcjonalnie może być podany numer błędu oznaczający Pozostałe błędy zawierają tylko opis słowny.

Specyfikacja xsd:[+-]