Allegro WebAPI

Interfejs programistyczny platformy Allegro

doGetItemsList

Ostatnia zmiana: ---
Dostępność:
Metoda pozwala na pobranie kompletu informacji o ofertach dostępnych na wszystkich listingach (kategorii, użytkownika, specjalnych) oraz w wynikach wyszukiwania. Możliwe jest filtrowanie danych na wiele różnych sposobów (m.in. po rodzaju listingu, słowie kluczowym i szczegółach wyszukiwania. cenie, typie oferty czy parametrach w kategorii), a także ich sortowanie wg dowolnego z dostępnych typów. Domyślnie (bez podania identyfikatora kategorii/działu) zwracana jest lista wszystkich kategorii głównych (bez informacji o ofertach) oraz lista stałych filtrów dla listingu ofert (w tym lista działów). Logika działania metody została oparta na systemie dynamicznych filtrów, zwracanych kontekstowo i pozwalających precyzyjnie sterować zakresem zwracanych danych. Tutorial opisujący zasadę działania dynamicznych filtrów znajduje się pod adresem: https://allegro.pl/webapi/tutorials.php/tutorial/id,281. Metoda zwraca dane z ostatnich dwóch miesięcy (także aukcje zakończone, które nie zostały jeszcze przeniesione do archiwum).

  1. webapiKey | string | wymagany
    Klucz WebAPI użytkownika.
  2. countryId | int | wymagany
    Identyfikator kraju, z którego pobrane mają zostać oferty (listę identyfikatorów krajów uzyskać można za pomocą metody doGetCountries).
  3. filterOptions | FilterOptionsType[] | niewymagany
    Kryteria filtrowania wyników (lista możliwych do ustawienia w danym kontekście filtrów, zwracana jest na wyjściu metody w ramach struktury filtersList).
    1. filterId | string | niewymagany
      Identyfikator filtra.
    2. filterValueId | string[] | niewymagany
      Identyfikator(y) wartości filtra (dla filtrów pojedynczych lub wielokrotnych).
    3. filterValueRange | RangeValueType | niewymagany
      Zakres wartości filtra (dla filtrów zakresowych).
      1. rangeValueMin | string | niewymagany
        Minimalna wartość filtra.
      2. rangeValueMax | string | niewymagany
        Maksymalna wartość filtra.
  4. sortOptions | SortOptionsType | niewymagany
    Sposób sortowania ofert.
    1. sortType | string | niewymagany
      Typ sortowania: endingTime - czas do końca/czas zakończenia (wartość domyślna dla wiekszości listingów), startingTime - czas wystawienia, price - cena, priceDelivery - cena z dostawą, popularity - popularność (liczba złożonych ofert), name - tytuł oferty, relevance - trafność.
    2. sortOrder | string | niewymagany
      Kierunek sortowania: asc - rosnąco (wartość domyślna dla większości listingów), desc - malejąco.
  5. resultSize | int | niewymagany
    Rozmiar porcji danych (min. 1, maks. 1000). Domyślna wartość: 100.
  6. resultOffset | int | niewymagany
    Sterowanie pobieraniem kolejnych porcji danych. Domyślna wartość: 0.
  7. resultScope | int | niewymagany
    Sterowanie zakresem zwracanych danych (maska, wartości można sumować): 1 - nie zwracaj struktury z filtrami, 2 - nie zwracaj struktury z kategoriami, 4 - nie zwracaj struktury z ofertami). Domyślnie zwracane są wszystkie dane.



Orientacyjna struktura wywołania metody

$dogetitemslist_request = array(
    'webapiKey' => '4y77dg10db8',
   'countryId' => 1,
   'filterOptions' => array(
     array(
      'filterId' => 'category',
      'filterValueId' => array('237548'))),
);


  1. itemsCount | int
    Liczba wszystkich ofert (we wskazanej kategorii i/lub wystawionych przez wskazanego użytkownika i/lub pasujących do danego zapytania).
  2. itemsFeaturedCount | int
    Liczba promowanych ofert (znajdujących się w zwróconej paczce danych).
  3. itemsList | ItemListType[]
    Informacje o ofertach.
    1. itemId | long
      Identyfikator oferty.
    2. itemTitle | string
      Tytuł oferty.
    3. leftCount | int
      Liczba przedmiotów dostępnych do kupienia.
    4. bidsCount | int
      Liczba kupionych przedmiotów.
    5. biddersCount | int
      Liczba użytkowników kupujących/licytujących w ofercie.
    6. quantityType | string
      Typ dostępnych w ofercie przedmiotów: pieces - sztuki, sets - komplety, pairs - pary.
    7. endingTime | datetime
      Planowy czas zakończenia oferty.
    8. timeToEnd | string
      Pozostały czas do zakończenia oferty (słownie).
    9. categoryId | int
      Identyfikator kategorii.
    10. conditionInfo | string
      Stan przedmiotu: new - nowy, used - używany, undefined - nieokreślony.
    11. promotionInfo | int
      Opcje promowania w ofercie (maska, wartości mogą być sumowane): 1 - wyróżnienie, 2 - podświetlenie, 4 - pogrubienie.
    12. additionalInfo | int
      Dodatkowe oznaczenia w ofercie (maska, wartości mogą być sumowane): 1 - Standard Allegro (PL)/Aukro+ (CZ)/Super Offer (UA)/Vatera Premium (HU), 2 - darmowa wysyłka.
    13. sellerInfo | UserInfoType
      Informacje o sprzedającym.
      1. userId | int
        Identyfikator użytkownika.
      2. userLogin | string
        Nazwa użytkownika.
      3. userRating | int
        0. Pole nieaktywne.Informacje o ocenach można pobrać przez REST API
      4. userIcons | int
        Dodatkowe informacje o użytkowniku (maska, wartości mogą być sumowane): 1 - konto Junior, 2 - strona "O mnie", 4 - konto Firma, 8 - sklep Allegro, 16 - Super Sprzedawca (RU).
      5. countryId | int
        Identyfikator kraju użytkownika (listę identyfikatorów krajów uzyskać można za pomocą metody doGetCountries).
    14. priceInfo | PriceInfoType[]
      Informacje o cenie przedmiotów.
      1. priceType | string
        Typ ceny: buyNow - Kup Teraz!, bidding - aktualna cena w licytacji, withDelivery - cena z dostawą.
      2. priceValue | float
        Kwota (w walucie kraju przekazanego w countryId).
    15. photosInfo | PhotoInfoType[]
      Tablica struktur zawierająca informacje o zdjęciach w ofercie.
      1. photoSize | string
        Rozmiar zdjęcia: small - małe (64x48), medium - średnie (128x96), large - duże (400x300).
      2. photoUrl | string
        Odnośnik do zdjęcia.
      3. photoIsMain | boolean
        Informacja o tym czy dane zdjęcie jest głównym w ofercie (i miniaturką na listingu): true/false.
    16. parametersInfo | ParameterInfoType[]
      Informacje o parametrach wybranych dla oferty.
      1. parameterName | string
        Nazwa parametru (do wyświetlenia w aplikacji).
      2. parameterValue | string[]
        Wartość parametru (pojedyncza, lista lub zakres od-do).
      3. parameterUnit | string
        Jednostka parametru (występuje tylko dla części parametrów).
      4. parameterIsRange | boolean
        Informacja o tym czy parametr jest typu zakresowego: true/false.
    17. advertInfo | AdvertInfoType
      Szczegóły ogłoszenia (zwracane tylko dla ofert typu ogłoszeniowego).
      1. serviceId | string
        Identyfikator serwisu z którego pochodzi ogłoszenie: otoMotoPl, otoDomPl, otoWakacjePl, alleWakacjePl, oferiaPl, tablicaPl, strefaMarekAllegroPl, ebookiAllegroPl, otoMotoCz, hotelCz, bezRealitkyCz, spaCz, turistikCz, wikiRealityCz, iDeveloperCz, slandoUa, promUa.
      2. advertId | string
        Identyfikator ogłoszenia.
  4. categoriesList | CategoriesListType
    Informacje o kategoriach.
    1. categoriesTree | CategoryTreeType[]
      Kategorie "siostrzane" i "dzieci" (pierwszego poziomu) dla identyfikatora kategorii podanej na wejściu lub lista kategorii głównych (jeżeli na wejściu nie podano konkretnej kategorii).
      1. categoryId | int
        Identyfikator kategorii.
      2. categoryName | string
        Nazwa kategorii.
      3. categoryParentId | int
        Identyfikator kategorii nadrzędnej.
      4. categoryItemsCount | int
        Liczba ofert wystawionych w kategorii.
    2. categoriesPath | CategoryPathType[]
      Pełna ścieżka kategorii prowadzących do kategorii podanej na wejściu (nie zwracana jeżeli kategoria nie została wskazana).
      1. categoryId | int
        Identyfikator kategorii.
      2. categoryName | string
        Nazwa kategorii.
      3. categoryParentId | int
        Identyfikator kategorii nadrzędnej.
  5. filtersList | FilterListType[]
    Informacje o filtrach możliwych do ustawienia w danym kontekście.
    1. filterId | string
      Identyfikator filtra.
    2. filterName | string
      Nazwa filtra.
    3. filterType | string
      Typ filtra: country - filtr globalny dla danego serwisu/kraju, category - filtr istniejący tylko w ramach przekazanej kategorii (parametr).
    4. filterControlType | string
      Typ kontrolki potrzebnej do wyświetlenia filtra: combobox (do wyboru pojedyncza wartość z listy), checkbox (do wyboru wiele wartości z listy), textbox (wartość do samodzielnego uzupełnienia).
    5. filterDataType | string
      Typ danych jakie przyjmuje filtr: string, int, long, float, datetime.
    6. filterIsRange | boolean
      Informacja o tym czy parametr jest typu zakresowego: true/false.
    7. filterArraySize | int
      Maksymalna liczba wartości jaką można przekazać dla danego filtra (zwracana tylko dla filtrów wielokrotnych).
    8. filterValues | FilterValueType[]
      Informacje o wartościach filtrów.
      1. filterValueId | string
        Identyfikator wartości filtra.
      2. filterValueName | string
        Nazwa wartości filtra (do wyświetlenia w aplikacji).
      3. filterValueCount | int
        Liczba ofert pasujących do danego filtra (zwracana tylko gdy jest możliwa do wyliczenia w danym kontekście).
    9. filterRelations | FilterRelationType
      Informacje o relacjach między filtrami.
      1. relationAnd | string[]
        Lista wszystkich identyfikatorów filtrów, z którymi dany filtr musi zostać użyty.
      2. relationOr | string[]
        Lista identyfikatorów filtrów, spośród których co najmniej jeden musi być użyty z danym filtrem.
      3. relationExclude | string[]
        Lista identyfikatorów filtrów, z którymi dany filtr nie może zostać użyty.
  6. filtersRejected | string[]
    Identyfikatory filtrów przekazanych na wejściu, które dla danego wywołania nie zostały aktywowane (są błędne lub niepoprawne w danym kontekście).



Orientacyjna struktura odpowiedzi serwera

$dogetitemslistresponse = array(
    'itemsCount' => 312,
   'itemsFeaturedCount' => 78,
   'itemsList' => array(
      array(
        'itemId' => 3136513627,
        'itemTitle' => 'Wiedźmin - Sezon Burz',
        'leftCount' => 43,
        'bidsCount' => 7,
        'biddersCount' => 7,
        'quantityType' => 'pieces',
        'endingTime' => 2013-12-29T13:57:12+01:00,
        'timeToEnd' => '3 godz',
        'CategoryId' => 92466,
        'conditionInfo' => 'new',
        'promotionInfo' => 3,
        'additionalInfo' => 0,
        'sellerInfo' => array(
             'userId' => 5921761,
             'userLogin' => 'testowekonto',
             'userRating' => 0,
             'userIcons' => 14,
             'countryId' => 1),
        'priceInfo' => array(
           array(
             'priceType' => 'buyNow',
             'priceValue' => 29.9),
           array(
             'priceType' => 'withDelivery',
             'priceValue' => 39.9)),
        'photosInfo' => array(
           array(
             'photoSize' => 'small',
             'photoUrl' => 'http://img12.allegroimg.pl/photos/64x48/36/66/01/35/3136513627',
             'photoIsMain' => true),
           array(
             'photoSize' => 'medium',
             'photoUrl' => 'http://img12.allegroimg.pl/photos/128x96/36/66/01/35/3136513627',
             'photoIsMain' => true),
           array(
             'photoSize' => 'large',
             'photoUrl' => 'http://img12.allegroimg.pl/photos/400x300/36/66/01/35/3136513627',
             'photoIsMain' => true)),
        'parametersInfo' => array(
           array(
             'parameterName' => 'Stan',
             'parameterValue' => 'Nowy',
             'parameterIsRange' => false))),
      array(...))
   'categoriesList' => array(
        'categoriesTree' => array(
           array(
             'categoryId' => 92466,
             'categoryName' => 'Polskie',
             'categoryParentId' => 79156,
             'categoryItemsCount' => 7270),
           array(
             'categoryId' => 92465,
             'categoryName' => 'Zagraniczne',
             'categoryParentId' => 79156,
             'categoryItemsCount' => 36924)),
        'categoriesPath' => array(
           array(
             'categoryId' => 7,
             'categoryName' => 'Książki i Komiksy',
             'categoryParentId' => 0),
           array(
             'categoryId' => 79153,
             'categoryName' => 'Literatura piękna, popularna i faktu',
             'categoryParentId' => 7),
           array(
             'categoryId' => 79156,
             'categoryName' => 'Fantasy',
             'categoryParentId' => 79153),
           array(
             'categoryId' => 92466,
             'categoryName' => 'Polskie',
             'categoryParentId' => 79156))),
   'filtersList' => array(
      array(
        'filterId' => 'condition',
        'filterName' => 'Stan',
        'filterType' => 'country',
        'filterControlType' => 'checkbox',
        'filterDataType' => string,
        'filterIsRange' => false,
        'filterValues' => array(
           array(
             'filterValueId' => 'new',
             'filterValueName' => 'Nowe',
             'filterValueCount' => 5349),
           array(
             'filterValueId' => 'used',
             'filterValueName' => 'Używane',
             'filterValueCount' => 1920)),
        'filterRelations' => array(
             'relationOr' => array('category','departmentPage','search','special','userId'),
             'relationExclude' => array('categoryPage','mainPage'))),
      array(
        'filterId' => 75,
        'filterName' => 'Okładka',
        'filterType' => 'category',
        'filterControlType' => 'checkbox',
        'filterDataType' => int,
        'filterIsRange' => false,
        'filterValues' => array(
           array(
             'filterValueId' => '1',
             'filterValueName' => 'miękka',
             'filterValueCount' => 2690),
           array(
             'filterValueId' => '3',
             'filterValueName' => 'miękka z obwolutą',
             'filterValueCount' => 36),
           array(
             'filterValueId' => '2',
             'filterValueName' => 'twarda,
             'filterValueCount' => 236),
           array(
             'filterValueId' => '4',
             'filterValueName' => 'twarda z obwolutą',
             'filterValueCount' => 25)),
        'filterRelations' => array(
             'relationAnd' => array('category'))),
      array(...))
);


  • ERR_FILTER_DEPENDENCY_ALL
    Filtr nie może zostać użyty bez przekazania dodatkowo wszystkich podanych filtrów: lista filtrów.
  • ERR_FILTER_DEPENDENCY_AT_LEAST_ONE
    Filtr nie może zostać użyty bez przekazania dodatkowo przynajmniej jednego z podanych filtrów: lista filtrów.
  • ERR_FILTER_DEPENDENCY_MISMATCH
    Filtr nie może zostać użyty jednocześnie z przynajmniej jednym z podanych filtrów: lista filtrów.
  • ERR_INPUT_COUNTRY_ERROR
    Niepoprawny identyfikator kraju (wskazany kraj nie jest obsługiwany lub w parametrze przekazano zerową/pustą wartość).
  • ERR_INCORRECT_FILTER_VALUE
    Niepoprawna wartość identyfikatora wartości filtra (dla filtra pojedynczego, wielokrotnego lub zakresowego).
  • ERR_INCORRECT_RESULT_SCOPE
    Niepoprawna wartość zakresu zwracanych danych.
  • ERR_INCORRECT_RESULT_SIZE
    Niepoprawna wartość rozmiaru porcji danych (spoza zakresu 1-1000).
  • ERR_INCORRECT_RESULT_OFFSET
    Niepoprawna wartość offsetu (mniejsza od 0).
  • ERR_INCORRECT_SORT_ORDER
    Niepoprawna wartość kierunku sortowania.
  • ERR_INCORRECT_SORT_TYPE
    Niepoprawna wartość typu sortowania.
  • ERR_WEBAPI_EXPIRED
    Data ważności klucza WebAPI została przekroczona (nie dotyczy PL).
  • ERR_WEBAPI_KEY
    Niepoprawna wartość klucza WebAPI lub klucz został zablokowany.
  • ERR_WEBAPI_KEY_INACTIVE
    Klucz WebAPI na którym została wygenerowana sesja został zdezaktywowany (jego właściciel nie zaakceptował warunków Regulaminu WebAPI).