Allegro WebAPI

FAQ

Odpowiedzi na najczęściej zadawane pytania związane z WebAPI.

1. Czy mogę uzyskać więcej informacji na temat sesji?
   Identyfikator sesji, otrzymany w wyniku wywołania metod doLogin(Enc), zachowuje ważność przez jedną godzinę od momentu jego utworzenia. Dodatkowo - sesja ma charakter odnawialny. Oznacza to, że wywołanie jakiejkolwiek metody wymagającej podania identyfikatora sesji spowoduje, że czas trwania tej sesji będzie naliczany od nowa.
   
   Dla każdego użytkownika obowiązuje limit 10 jednocześnie otwartych sesji. W przypadku otwarcia 11-tej z kolei, ta najwcześniej utworzona zostanie automatycznie zamknięta.
2. Czy na wywoływanie metod nałożone są jakieś limity?
   Tak. W chwili obecnej w API obowiązują dwa główne limity:
   

   • Nałożony na każdy klucz - 2100 zapytań na minutę. Jego przekroczenie skutkuje 5-minutową blokadą klucza, podczas której zwracany jest komunikat błędu: ERR_MINUTE_LIMIT_EXCEEDED.

   • Zabezpieczający przez zbyt częstymi wywołaniami na sekundę z poziomu pojedynczego IP - jego wartość nie jest jawna. Po przekroczeniu tego limitu, zamiast XML-a z odpowiedzią z serwera SOAP, zwracany jest HTML z informacją: Twój adres IP został zablokowany z powodu nadmiernej liczby żądań. Aby zdjąć blokadę, przepisz kod z obrazka oraz CAPTCHA, za pomocą której konieczna jest weryfikacja użytkownika (ważne: weryfikacja musi nastąpić z tego samego adresu IP, z poziomu którego limit został przekroczony). Fakt przekroczenie tego limitu najczęściej sygnalizują komunikaty typu: looks like we got no XML document / Client found response content type of 'text/html; charset=UTF-8', but expected 'text/xml'.

   
   

   Dodatkowo istnieje także limit zabezpieczający przed zbyt dużą liczbą błędnych logowań na konto (dot. metod doLogin/doLoginEnc). W przypadku jego przekroczenia, zwracany zostaje kod błedu ERR_CAPTCHA_REQUIRED o treści bezpośrednio wskazującej na przyczynę i sposób rozwiązania problemu: Dostęp przez WebAPI dla tego Użytkownika został zablokowany z powodu zbyt dużej liczby błędnych logowań na konto. Odblokowanie dostępu nastąpi dopiero po poprawnym zalogowaniu się wskazanego Użytkownika z poziomu serwisu WWW (https://ssl.allegro.pl/enter_login.php?captcha=1). Ważne: Zdjęcie blokady nastąpi dopiero po zalogowaniu się przez WWW z tego samego adresu IP, z poziomu którego wywoływane były metody WebAPI służące do logowania.
3. Jakie serwisy są obsługiwane przez usługę WebAPI?

   Usługa Allegro WebAPI obsługuje praktycznie wszystkie serwisy aukcyjne Grupy Allegro. Używając konta założonego na jednym z poniższych serwisów (np. na allegro.pl) można logować się i korzystać z każdego z pozostałych (część serwisów narzuca ograniczenia na pojedyncze funkcjonalności dla kont z zagranicy):

   • allegro.pl (kod kraju 1)
   • allegro.by (kod kraju 22)
   • aukro.bg (kod kraju 34)
   • aukro.cz (kod kraju 56)
   • allegro.kz (kod kraju 107)
   • molotok.ru (kod kraju 168)
   • aukro.sk (kod kraju 181)
   • aukro.ua (kod kraju 209 - dla wersji rosyjskojęzycznej, kod kraju 232 - dla wersji ukraińskojęzycznej)
   • allegro.rs (kod kraju 222)

   Inaczej sprawa wygląda z serwisem aukro.ro (kod kraju 167, aktualna nazwa serwisu to tizo.ro), do którego mogą się logować wyłącznie użytkownicy kont utworzonych w tym serwisie.

   Całkowicie wyłączony z obsługi przez WebAPI został serwis teszvesz.hu (kod kraju 93).

   Osobno należy potraktować serwis testowy - testwebapi.pl (kod kraju 228). Działa on na oddzielnej bazie danych, dlatego do korzystania z niego konieczne jest utworzenie konta bezpośrednio w tym serwisie.

4. Do tej pory wszystko działało bez problemu, a teraz nagle otrzymuje błąd ERR_INVALID_VERSION_CAT_SELL_FIELDS.
   Powyższy błąd wskazuje na to, że w parametrze wywołania metody podany został niepoprawny (nieaktualny) klucz wersji. Klucze wersji są zmiennie, dlatego należy przede wszystkim sprawdzić czy przekazywana wartość klucza zgadza się z jego aktualną wartością (do sprawdzenia wartości kluczy wersji użyć można metod: doQuery(All)SysStatus).
5. W jaki sposób wystawić przez WebAPI aukcję, która będzie promowana na liście aukcji Eko-Użytkowników?
   Aby wystawiana przez API aukcja wyświetlała się na liście aukcji Eko-Użytkowników, nie ma potrzeby ustawiać żadnych dodatkowych wartości w polach formularza sprzedaży.  Status aukcji nadaje dokonana na konto fundacji All4Planet wpłata (w wysokości min. 5 zł). Aby dokonać wpłaty na ww. konto należy skorzystać z odnośnika, którego znaleźć można w e-mailu informującym o wystawieniu aukcji. Odnośnik ma postać:
   

   
   

   http://www.allegro.pl/country_pages/1/0/marketing/allforplanet/?oitem=[ID_AUKCJI]
6. Jakiej maksymalnie długości hasło przekazać można przy wywoływaniu metod doLogin(Enc)?
   Tak naprawdę przekazać można hasło dowolnej długości, jednak po stronie serwera API odczytane zostanie jedynie pierwsze 16 znaków (aktualny limit na długość hasła w serwisie) - pozostałe znaki zostaną zwyczajnie zignorowane.
7. Jak działają i co oznaczają maski dla opcji aukcji?
   Maski te (zwracane przez metody doMyAccount2, doGetItemsInfo, doShowItemInfoExt oraz doGetItemTransaction), to - przedstawione w systemie dziesiętnym - sumy logiczne wartości (będących kolejnymi potęgami dwójki), wskazujących na opcje wybrane dla aukcji. Wartości te oznaczają kolejno:

   • 1 - aukcja promowana przez pogrubienie tytułu na listingach,
   • 2 - aukcja promowana przez wyróżnienie na listingach,
   • 4 - aukcja promowana przez miniaturkę wyświetlaną na listingach,
   • 8 - aukcja sklepowa,
   • 16 - aukcja usunięta przez administratora serwisu,
   • 32 - wskazanie na fakt, że koszty przesyłki pokrywa kupujący,
   • 64 - wskazanie na fakt, że koszty przesyłki pokrywa sprzedający,
   • 128 - wybrana forma płatności: zwykły przelew,
   • 256 - wybrana forma płatności: płatność przy odbiorze,
   • 512 - maska zdezaktualizowana (zawsze wyłączona),
     
   • 1024 - maska zdezaktualizowana (zawsze wyłączona),
   • 2048 - maska zdezaktualizowana (zawsze wyłączona),
   • 4096 - maska zdezaktualizowana (zawsze wyłączona),
   • 8192 - aukcja promowana na stronie głównej,
   • 16384 - sprzedający zgadza się na wysyłkę za granicę,
   • 32768 - podano dodatkowe informacje o przesyłce i płatności,
   • 65536 - aukcja utworzona z czasem do wystawienia w przyszłości,
   • 131072 - aukcja wystawiona za pośrednictwem Allegro WebAPI,
   • 262144 - aukcja promowana przez podświetlenie na listingach,
   • 524288 - aukcja promowana na stronie kategorii,
   • 1048576 - aukcja prywatna,
   • 2097152 - aukcja wystawiona na otoMoto,
   • 4194304 - wybrana opcja dostawy: przesyłka pocztowa ekonomiczna,
     
   • 8388608 - wybrana opcja dostawy: przesyłka pocztowa priorytetowa,
     
   • 16777216 - wybrana opcja dostawy: przesyłka kurierska,
     
   • 33554432 - wybrana opcja dostawy: odbiór osobisty,
     
   • 67108864 - maska zdezaktualizowana (zawsze włączona).
     

   
   Aby odczytać poszczególne opcje, najprościej zamienić otrzymaną maskę na postać binarną i sprawdzić ustawienia kolejnych bitów.
8. Podczas wywoływania metody otrzymuje błąd ERR_NO_SESSION, chociaż jestem pewny, że identyfikator sesji, który podaje jest poprawny i aktualny.
   Błąd ten może być wynikiem jednego z zabezpieczeń, które stosowane jest w WebAPI. Podczas wywoływania metody wykorzystującej identyfikator sesji sprawdzane jest, czy IP z którego wywoływana jest metoda jest tym samym IP, z którego wywoływana była metoda zwracająca wspomniany identyfikator - czyli doLogin(Enc). Należy upewnić się, że obie metody wywoływane są z poziomu tego samego IP.
9. Które pola przekazać podczas wystawiania aukcji, aby poprawnie wystawić aukcję w Sklepie Allegro?
   Przede wszystkim w polu fid = 29 (Format sprzedaży) należy ustawić wartość 'Sklep (bez licytacji)'. Dodatkowo w polu fid = 4 (Czas trwania) przekazać należy wartość '30'.
10. Próbuję wystawić aukcję z terminem wystawienia na kilka minut naprzód, jednak aukcja wystawia się natychmiast.
    Podobnie jak na WWW, wszystkie aukcje dla których termin wystawienia zostanie ustalony do 10 minut naprzód od chwili wywoływania metody, traktowane są jako do wystawienia od razu (kwestia uwarunkowań technicznych). Aby faktycznie aukcja została wystawiona w terminie późniejszym, jako chwilę jej startu należy podać termin późniejszy od chwili obecnej o więcej niż 10 minut.
11. Mam problemy z obsługą WebAPI przy korzystaniu z narzędzi firmy Borland (Delphi 6, Delphi 7, Turbo Delphi).
    Przyczyną problemów są najprawdopodobniej nazwy struktur w API zawierające myślniki – wcześniejsze wersje IDE Borlanda mają kłopot z ich poprawną obsługą. Rozwiązaniem będzie tutaj własnoręczna ingerencja w źródła bibliotek SOAP dostarczanych wraz z oprogramowaniem - zgodnie z poniższymi wskazówkami.
    

    
    

    W pliku borland\src\soap\OPToSoapDomConv.pas (dla Delphi 6/7) lub w pliku borland\bds\4.0\source\win32\soap\OPToSoapDomConv.pas (dla Turbo Delphi), w okolicach linii 971, odnaleźć trzeba fragment:
    

    
    if MD.Params[J].Name = ExtractLocalName(Node.NodeName) then
    
    następnie należy podmienić go na:
    
    if StringReplace(MD.Params[J].Name, '_', '', [rfReplaceAll]) = StringReplace(ExtractLocalName(Node.NodeName), '-', '', [rfReplaceAll]) then
    
    Dodatkowo, w tym samym pliku, w okolicach linii 2300 odnaleźć należy:
    
    if SameText(InternalName, PropList[I].Name) then
    
    i zamienić na:
    
    if StringReplace(InternalName, '', '', [rfReplaceAll]) = StringReplace(PropList[I].Name, '_', '', [rfReplaceAll]) then
    
    W nowszych wersjach środowiska Delphi (od Delphi 8 w górę) problem ten już nie występuje.