Allegro WebAPI
Interfejs programistyczny serwisu Allegro
Informacje ogólne
Przekrojowe informacje na temat Allegro WebAPI, które ułatwią Ci rozpoczęcie pracy z usługą.
Klucze | Klucz Allegro WebAPI | Klucze wersji | Statystyki | Mechanizm licencjonowania | Serwis testowy
WebAPI w pigułce
Allegro WebAPI jest usługą umożliwiającą dostęp do zasobów i logiki serwisu bez pośrednictwa warstwy interfejsu. Usługa przeznaczona jest dla programistów zainteresowanych budowaniem własnych rozwiązań korzystających z danych i mechanizmów udostępnianych przez serwis.
Działanie API serwisu zostało (w sposób uproszczony) przedstawione na poniższym schemacie:
Allegro WebAPI to usługa sieciowa opierająca swoje działanie na protokole SOAP, wykorzystująca język XML jako format tworzenia komunikatów oraz protokół RPC do ich przenoszenia pomiędzy klientem (aplikacją), a serwerem WebAPI. Pełny opis usługi zdefiniowany został za pomocą języka WSDL i znaleźć go można w tym miejscu (dostępny także w formie szyfrowanej).
Wykorzystanie protokółu RPC determinuje architekturę usługi. Allegro WebAPI zbudowane jest z szeregu metod, które stanowią odwzorowanie poszczególnych funkcji serwisu. Za pomocą naszego API można m.in.:
- wystawiać oferty na Allegro,
- listować oferty wystawione w danych kategoriach oraz przez danych użytkowników,
- obsługiwać wyszukiwarkę,
- przeglądać informacje o ofertach wystawionych w serwisie,
- pobierać dane kontaktowe użytkowników, którzy zakupili towar w ofertach danego użytkownika,
- listować i wystawiać komentarze kontrahentom,
- pobierać zawartość poszczególnych zakładek Mojego Allegro,
- składać oferty kupna,
- obsługiwać w pełni system zwrotów prowizji działający w serwisie,
- pobierać informacje dot. statusu wpłat dokonywanych za pośrednictwem PayU.
Allegro WebAPI jest usługą wielojęzykową oraz wieloserwisową. Odpowiednio parametryzując dane metody, można za ich pomocą obsługiwać również zagraniczne odpowiedniki serwisu Allegro (Aukro.cz, Aukro.ua, Molotok,ru itd.), a wszelkie zwracane informacje (również komunikaty błędów), tłumaczone będą na język odpowiedni dla wybranego kraju.
Klucze
Usługa dostępna jest w pełni za darmo dla każdego użytkownika serwisu (z zastrzeżeniem posiadania w pełni aktywowanego konta i bez nałożonej na nie żadnej blokady), który wystąpi do serwisu z prośbą o wygenerowanie klucza dostępowego korzystając z formularza kontaktowego (każdy klucz ważny jest 12 miesięcy od chwili jego wygenerowania; na tydzień przed zakończeniem jego ważności wysyłany jest e-mail przypominający o tym fakcie).
Przyznanie dostępu do usługi równoznaczne jest z wygenerowaniem dla danego konta unikalnego i niezmiennego klucza Allegro WebAPI, jednoznacznie identyfikującego użytkownika w usłudze. Klucz API zostaje przyporządkowany do danego konta w momencie jego generowania, jednak nie jest to równoznaczne z ograniczeniem możliwości korzystania z niego tylko do wskazanego konta. Każdy użytkownik Allegro znając klucz API innego użytkownika może użyć go, otwierając sobie w ten sposób dostęp do usługi (a punkt III.2. Regulaminu WebAPI jasno wskazuje na zakres odpowiedzialności w takim przypadku). Dlatego należy unikać bezpośredniego udostępniania wartości naszego klucza użytkownikom postronnym, a w celu upewnienia się, że z naszego klucza faktycznie nie korzystają osoby niepowołane, zalecanym jest włączenie mechanizmu licencjonowania na danym kluczu.
Dodatkowo warto pamiętać, że klucze API są case sensitive – podanie X123Y456Z w miejsce x123y456z skutkowało będzie zwróceniem przez serwer informacji o nieprawidłowej wartości klucza.
W momencie wygenerowania stałego klucza API otwierającego dostęp do usługi, użytkownik otrzymuje także komplet kluczy wersji (o wartościach unikalnych w ramach każdego klucza API) – po jednym dla każdego z krajów, w których udostępniamy API (na chwilę obecną jest ich 10 – wliczając serwis testowy). Wartość kluczy wersji – w odróżnieniu od klucza API, zmienia się każdorazowo gdy zaktualizowane zostaną pewne dynamiczne komponenty, które ulegają zmianie z uwagi na swoją naturę (najczęściej dotyczy to struktury drzewa kategorii oraz pól formularza sprzedaży). Fakt zmiany kluczy jest z poziomu API zgłaszany przez dość charakterystyczny komunikat błędu. Daty ostatnich aktualizacji wymienionych komponentów podejrzeć można np. w dolnej części strony głównej strony usługi.
Podsumowując temat kluczy:
| Klucz Allegro WebAPI |
Klucze wersji |
|
| Rola | Dostęp do usługi |
Informowanie o zmianach w komponentach |
| Liczba kluczy | 1 | 10 |
| Zmienność | Nie | Tak |
| Podgląd wartości |
Moje Allegro > WebAPI |
Moje Allegro > WebAPI + dedykowane metody API |
Dodatkowe narzędzia
Posiadacze kluczy WebAPI otrzymują dodatkowo dostęp (z poziomu: Mojego Allegro > WebAPI) do dwóch specjalnych narzędzi przydatnych w codziennej pracy z usługą. Są to:
- Statystyki, przedstawiane w formie przejrzystych wykresów obrazujących liczby wywołań wszystkich metod z podziałem na poszczególne kraje/serwisy. Statystyki obejmują 7 ostatnich miesięcy (wliczając bieżący) i są sumowane tygodniowo. Oprócz statystyk dla każdej z metod z osobna, dostępne są także statystyki obrazujące 10 najczęściej wykorzystywanych metod (także z podziałem na kraje/serwisy).
- Mechanizm licencjonowania, pozwalający na zarządzanie przydzielaniem czasowego dostępu do aplikacji opartej na przyporządkowanym do konta kluczu API, jedynie d
o grona użytkowników, dla których wyrażona zostanie na to uprzednio zgoda. Innymi słowy – jest to mechanizm oferujący tworzenie białych list zawierających uwierzytelnionych przez nas własnoręcznie użytkowników. Mechanizm ten wykorzystać można np. do zarządzania dostępem do aplikacji (jest on pewniejszy niż analogiczny mechanizm zbudowany po stronie klienta, ponieważ jest odporny na ew. próby reverse engineeringu - w całości działa na serwerach Allegro). Dodatkowo możliwa jest również obsługa mechanizmu za pomocą dedykowanych metod API.
Serwis testowy
Aby umożliwić użytkownikom testowanie API poza serwisem produkcyjnym, udostępniamy serwis testowy (dostępny jedynie w języku angielskim), pozwalający na testowanie tej części metod, których funkcjonalność została zawarta w środowisku testowym. Serwis testowy pozwala m.in. na:
- wystawianie ofert w serwisie,
- listowanie ofert wystawionych w danych kategoriach oraz przez danych użytkowników,
- obsługę wyszukiwarki,
- przeglądanie informacji o ofertach wystawionych w serwisie,
- listowanie i wystawianie komentarzy kontrahentom,
- pobieranie zawartości poszczególnych zakładek testowej wersji Mojego Allegro,
- składanie ofert kupna.
Co najważniejsze – wszelkie możliwe operacje dokonywane na środowisku testowym są darmowe. Nie obowiązują tutaj także żadne zakazy i ograniczenia zawarte w Regulaminie Allegro, które są w mocy na serwisach produkcyjnych. Powyższe implikuje fakt, że serwis testowy jest zupełnie odseparowany od reszty serwisów i w związku z tym konieczne jest zarejestrowanie nowego konta, aby móc z niego korzystać z poziomu WebAPI. Identyfikator kraju serwisu testowego to 228. Serwis posiada również przyporządkowany do niego, odrębny klucz wersji.
Korzystanie z serwisu oznacza akceptację regulaminu