Wprowadzenie
System elibri udostępnia dane produktów w formacie ONIX 3.0, który jest powszechnie używanym formatem wymiany danych w branży księgarskiej na całym świecie. Ze względu na zróżnicowane potrzeby różnych rynków jego dokumentacja jest dosyć obszerna, w niniejszym dokumencie staramy się udokumentować używane przez nas elementy specyfikacji, wraz z przykładami. ONIX 3.0 pozwala na używanie tzw. długich i krótkich tagów - przy czym te długie są czytelne dla człowieka, któtkie natomiast skutkują znacznie mniejszymi plikami wynikowymi. W elibri używane są w tej chwili tylko te pierwsze, jesteśmy przekonani, że czytelność kodu jest ważniejsza, niż ilość pamięci RAM, którą wykorzystuje program.
Wymiana danych odbywa się przy użyciu protokołu http, metod GET i POST. Dla każdego odbiorcy danych tworzone są dwie kolejki danych. Pierwsza kolejka, meta, dotyczy zmian metadanych produktu, np. tytułu, numeru ISBN, okładki. Po każdej zmianie informacji przez wydawnictwo, cały rekord ONIX opisujący produkt trafia do kolejki i czeka na odbiór. Druga kolejka, stocks, zawiera dane o zmianach stanów magazynowych produktów. Udostępnione w tej kolejce rekordy ONIX zawierają tylko informacje o dostępności produktu.
Pomimo że numer ISBN jest powszechnie używanym numerem rozróżniającym książki, standard ONIX wprowadza dodatkowy identyfikator produktu, record reference. Jest to ciąg znaków, np. 22776bc36b605ecdfecb. Jest on unikalny w obrębie systemu, i jednoznacznie identyfikuje każdy rekord. Dlaczego nie numer ISBN? Po pierwsze wydawca może się zdecydować na udostępnienie informacji o książce wcześniej, niż zna jego numer ISBN. Poza tym część wydawców publikuje nowe wydania książek pod tym samym numerem ISBN, nawet wtedy, gdy cena książki uległa zmianie. Jest to zgodne z zaleceniami biura ISBN, ale niestety dość kłopotliwe dla rynku i systemów informatycznych.
Każde konto ma ograniczoną liczbę zapytań dziennych, które obsłuży (domyślnie pięć tysięcy). Po przekroczeniu tego limitu serwer odpowiada kodem 429.
Oprócz pobierania danych z kolejek istnieje jeszcze kilka innych operacji pomocniczych. Możemy pobrać listę wydawnictw, listę produktów wprowadzonego przez określonego wydawcę, możemy też pobrać dane określonego produktu. Istnieje też możliwość dodania do kolejek wszystkich produktów w systemie, co może być przydatne w przypadku wykrycia na przykład jakiegoś błędu, przez który jakaś informacja nie została właściwie zinterpretowana.
Dokumentacja w sekcji API HTTP zawiera przykładowe wywołania cURL. Przed ich wykonaniem należy ustawić odpowiednio zmienne środowiskowe z loginem i hasłem do API elibri. Np:
export ELIBRI_API_LOGIN=7792cdaced1a488dba6d export ELIBRI_API_PASSWORD=7792cdaced1a488dba6d