O poradniku

Poniższy poradnik pomoże ci przejść z WebAPI na REST API.

Jeżeli szukasz informacji o tym, jak można zacząć pracę z REST API Allegro zapoznaj się z informacjami ogólnymi i poradnikiem jak zacząć.

Zestawienie pojęć

Poniżej znajdziesz podstawowe pojęcia i metody w WebAPI oraz ich odpowiedniki w REST API.

WebAPI REST API
Autoryzacja Klucz WebAPI Client ID i Client Secret aplikacji wygenerowanej w Allegro Developer Apps
Dane dostępne publicznie Metody autoryzowane po kluczu Zasoby autoryzowane tokenem oauth uzyskanym za pomocą flow client_credentials
Dane zalogowanego użytkownika Metody autoryzowane za pomocą id sesji Zasoby autoryzowane tokenem oauth uzyskanym za pomocą flow authorization_code lub device_code
Logowanie doLogin
doLoginEnc
Id zalogowanego usera zwracane z metody
POST https://allegro.pl/auth/oauth/token
Id zalogowanego użytkownika należy odkodować z tokena JWT
Zarządzanie sesją użytkownika Ponowne zalogowanie użytkownika po wygaśnięciu sesji Odświeżenie access tokena za pomocą refresh_tokena
Obsługa błędów Sprawdzanie zawartości SoapFaulta Sprawdzanie statusu HTTP i wiadomości
Tworzenie oferty doNewAuctionExt POST /sale/offers
Metody dostawy doGetShipmentData GET /sale/delivery-methods
Cenniki dostawy brak GET /sale/shipping-rates
POST /sale/shipping-rates
PUT /sale/shipping-rates
Publikacja oferty doNewAuctionExt
doFinishItem
doFinishItems
PUT /sale/offer-publication-commands/{id}
Walidacja oferty doCheckNewAuctionExt
doNewAuctionExt
sekcja validation w oferce
POST /sale/offers
PUT /sale/offer-publication-commands/{id}
Edycja oferty doChangeItemFields
doChangePriceItem
doChangeQuantityItem
GET /sale/offers/{id}
PUT /sale/offers/{id}
PUT /offers/{offerId}/change-price-commands/{id}
PUT /sale/offer-modification-commands/{id}
PUT /sale/offer-price-change-commands/{id}
PUT /sale/offer-quantity-change-commands/{id}
Lista moich ofert doGetMySellItems
doGetMySoldItems
doGetMyNotSoldItems
doGetMyFutureItems
GET /sale/offers
Listy przewozowe doAddPackageInfoToPostBuyForm POST /order/checkout-forms/{id}/shipments
Lista zamówień doGetPostBuyData
doGetPostBuyFormsDataForSellers
doGetPostBuyFormsIds
doGetTransactionsIDs
doGetFilledPostBuyForms
GET /order/checkout-forms
GET /order/checkout-forms/{id}
GET /order/checkout-forms/{id}/shipments
Dziennik zdarzeń o zamówieniach doGetSiteJournalDeals
doGetSiteJournalDealsInfo
GET /order/events
GET /order/event-stats

Poradnik migracji

Autoryzacja

Więcej na ten temat znajdziesz w tym artykule.

W WebAPI autoryzujesz się za pomocą metod doLogin i doLoginEnc. W tych metodach korzystasz z Klucza WebAPI, loginu i hasła użytkownika. W odpowiedzi otrzymujesz identyfikator sesji.

W REST API wykorzystujesz zasób /auth/oauth/token, w którym podajesz Client ID i Client Secret. W odpowiedzi otrzymujesz access_token JWT, który następnie przekazujesz w nagłówku HTTP Authorization dla wszystkich zasobów REST API. Np.:

 
    GET /sale/offers
    Authorization: Bearer eyJhbGciOiJIUssw5cdsdasw
    Accept: application/vnd.allegro.public.v1+json
 
gdzie “eyJhbGciOiJIUssw5cdsdasw” to przykładowy access_token.

Metody WebAPI i zasoby REST API dzielą się na publicznie dostępne oraz takie, które wymagają zalogowania użytkownika.

Zasoby i metody ogólnie dostępne

Czyli takie, które nie wymagają, by użytkownik był zalogowany. Przykładowe zasoby, które udostępniliśmy publicznie to doGetCatsData w WebAPI i GET /offers/listing na REST API.

Dla takich metod w WebAPI nie musisz korzystać z metod doLogin(Enc). Wystarczy, że podasz w wywołaniu klucz api.

W przypadku REST nie musisz prosić użytkownika o logowanie. Wygeneruj token przy pomocy flow OAuth2 client_credentials JWT, który nie zawiera id zalogowanego użytkownika. Wystarczy, że podasz Client ID oraz ClientSecret aplikacji. Jeśli rozkodujesz otrzymany token, to nie będzie on zawierał informacji o zalogowanym użytkowniku.

Zasoby i metody dostępne dla zalogowanego użytkownika

W zasobach i metodach takich jak POST /sale/offers i doNewAuctionExt wymagamy, aby aplikacja wykonywała je w kontekście zalogowanego użytkownika.

W tym celu w WebAPI używasz metody doLogin(Enc), w której podajesz hasło i login użytkownika. Metoda zwraca identyfikator sesji oraz id zalogowanego użytkownika. Następnie identyfikator sesji możesz użyć do wywoływania kolejnych metod.

W REST API, aby działać w kontekście użytkownika: - jeśli tworzysz aplikację, która może wyświetlić przeglądarkę lub przekierować użytkownika na stronę logowania Allegro, skorzystaj z flow OAuth2 typu authorization_code - w innym przypadku, skorzystaj z device_flow. W efekcie otrzymasz access_token i refresh_token użytkownika, który zalogował się podczas procesu.

Informacje o zalogowanym użytkowniku

W przypadku WebAPI id zalogowanego użytkownika zwracamy w metodzie doLogin(Enc), natomiast w REST API znajdziesz je w polu user_name w odkodowanym access_tokenie JWT. Taki token odkoduj jedną z dostępnych dla wielu języków bibliotek. Id zalogowanego użytkownika znajdziesz w polu user_name tokena.

Czas życia sesji i tokena

W WebAPI sesja użytkownika jest ważna przez jedną godzinę. Czas ten odnawiasz przy każdym użyciu danego sessionId.

W REST API otrzymany access_token JWT ma ustaloną datę wygaśnięcia, która jest zakodowana w polu exp w formacie timestamp. Zwracamy ją również wraz z tokenem w odpowiedzi w polu expires_in. Jeśli skorzystasz z nieaktywnego tokena, zwrócimy błąd o statusie HTTP 401 Unauthorized i treścią odpowiedzi:

 
    {"error":"invalid_token","error_description":"Access token expired: <token value>"}
 
Aby uzyskać nowy access_token bez ponownego angażowania użytkownika użyj uzyskanego refresh_tokena do odświeżenia access_tokena.

Token możesz odświeżać:

  • prewencyjnie, kiedy zbliża się data wygaśnięcia zawarta w exp
  • gdy wygaśnie, w reakcji na otrzymany kod 401.
information

Gdy odświeżysz token, zwracamy ci nowy access_token oraz refresh_token. Refresh_token dla tej pary tokenów jest już zużyty i przy kolejnym odświeżeniu musisz skorzystać z nowego refresh_tokena.

Obsługa błędów

W SOAP wszystkie błędy - zarówno te, które spowodowane były nieprawidłowymi danymi wejściowymi, problemami po stronie serwera, jak i problemami z uwierzytelnianiem - zwracamy w postaci kodu błędu HTTP 500 i SoapFault z wyjaśnieniem w treści odpowiedzi.

W przypadku błędu w REST API, najważniejszą informacją jest kod odpowiedzi HTTP. To przede wszystkim on definiuje, czy problem wynika z niedostępności serwera, zbyt dużej liczby żądań od klienta, czy błędnymi danymi wejściowymi. Oprócz tego w treści odpowiedzi znajdziesz szczegółowy opis błędu.

W przypadku komunikacji z Allegro zwróć szczególną uwagę na zawartość nagłówka odpowiedzi Trace-Id. Warto logować te wartości, przynajmniej w przypadku występowania błędów. Jeśli kiedykolwiek natrafisz na problem z naszym API, podaj Trace-Id w zgłoszeniu przez formularz kontaktowy lub na naszym githubie. Dzięki temu łatwiej namierzymy przyczynę problemu i szybciej uzyskasz pomoc.

Zarządzanie ofertą

Więcej szczegółów na ten temat znajdziesz w poradnikach:

Tworzenie oferty

Główne zmiany w stosunku do WebAPI to:

Produktyzacja

Od początku 2019 roku grupujemy oferty z tym samym produktem. W REST API możesz wyszukać produkt, a następnie podać jego identyfikator w ofercie.

Inny sposób załączania zdjęć do oferty

W WebApi całą ofertę (wraz ze wszystkimi jej zdjęciami) wystawiasz metodą doNewAuctionExt. Efektem tego podejścia są duże zapytania, które musisz powtarzać w przypadku błędów.

W REST API zdjęcia przekazujesz za pomocą dedykowanego endpointu. W odpowiedzi otrzymasz linki do zdjęć, które dołączysz do oferty. Utworzysz ją za pomocą zasobu POST /sale/offers.

Metody dostawy

Listę dostępnych metod dostawy na WebAPI pobierasz metodą doGetShipmentData, natomiast na REST API możesz skorzystać z zasobu GET /sale/delivery-methods.

Przypisywanie cennika dostawy

Cenniki dostawy to nowy element, którego nie było na WebAPI. Dzięki temu, nie musisz w każdej ofercie podawać szczegółowych danych o opcjach dostawy. Utwórz cennik dostawy, a następnie podepnij go do oferty.

Dane oferty

W WebAPI funkcjonuje mechanizm FID-ów, gdzie każde pole oferty (zarówno parametry przedmiotu, jak i stałe pola takie jak cena) ma swój identyfikator.

W REST API pola, które są takie same w każdej kategorii (takie jak tytuł, cena, liczba sztuk) definiujesz bezpośrednio w żądaniu, np:

 
    { "name": "Przykładowy tytuł", "stock": { "available": 10, "unit": "SET" }, ... }
 
Parametry oferty, które są dostępne tylko we wskazanych kategoriach możesz pobrać dla wskazanej kategorii - liścia za pomocą GET /sale/categories/{categoryId}/parameters.
 {  
    "parameters": [{
        "id": "22728",
        "name": "Materiał wkładki",
        "dictionary": [
            { "id": "22728_215173", "value": "Skóra ekologiczna" },
            { "id": "22728_1",      "value": "Skóra naturalna" },
            ...
            { "id": "22728_3",      "value": "Inny materiał" }
        ],
        ...
    }]
}
Wówczas możesz przekazać je w tablicy parametrów oferty, jako parę identyfikator - wartość bądź listę wartości:
    {
        "name": "Przykładowa nazwa oferty",
        "parameters": [
            {"id" : "22728", "valuesIds" : [ "22728_215173" ]}
        ],
        ...
    }

Pobieranie informacji o kategoriach

W WebAPI możesz pobrać całe drzewo kategorii za pomocą doGetCatsData i doGetCatsDataLimit. Metody te zwracają kompletną listę kategorii.

W REST API zasób /sale/categories zawiera listę kategorii pierwszego rzędu. Jeżeli chcesz pobrać całe drzewo, użyj zasobu GET /sale/categories?parent.id={id} rekurencyjnie, aż do kategorii oznaczonych jako liście "leaf":true - tylko w nich możesz wystawić ofertę.

Pamiętaj, by sprawdzać listę parametrów i ich wartości, gdy wystawiasz i edytujesz ofertę, ponieważ lista kategorii i parametrów na Allegro ulega częstym zmianom.

Publikacja oferty

W WebAPI jeśli wykonasz doNewAuctionExt, to automatycznie opublikujemy w serwisie ofertę. W REST API, kiedy utworzysz nową ofertę, to jest ona w statusie INACTIVE. Dopiero, gdy wykonasz komendę publikacji opublikujemy ją w serwisie.

Za pomocą komendy publikacji:

  • możesz też zakończyć ofertę (odpowiednik doFinishItem i doFinishItems)
  • wznowić zakończoną ofertę - wtedy będzie ponownie dostępna w serwisie, pod tym samym id.

Edycja zakończonej oferty

W WebAPI nie możesz edytować i wznawiać zakończonych ofert. W REST API udostępniliśmy zarówno edycję, jak i wznowienie zakończonej oferty.

Walidacja oferty

W WebAPI do walidacji ofery możesz posłużyć się metodą doCheckNewItemExt, która sprawdza dane oferty oraz zwraca ewentualne błędy walidacji takiej oferty.

W REST API po tym, jak wykonasz POST /sale/offers, oferta którą zwrócimy za pomocą GET /sale/offers ma sekcję validation, gdzie znajdziesz informacje, jakich danych jeszcze brakuje lub jakie są nieprawidłowe.

Edycja oferty

W WebAPI wykorzystujesz doChangeItemFields do wprowadzania zmian w aktywnej ofercie. Dodatkowo możesz wywołać metody pomocnicze takie jak doChangePriceItem (która pozwala zmieniać cenę oferty bez złożonych ofert kupna) i doChangeQuantityItem (która pozwala zmienić liczbę dostępnych sztuk).

W REST API zmiany oferty możesz dokonać na kilka sposobów:

  1. Pojedynczo za pomocą endpointu PUT /sale/offers
  2. Hurtowo za pomocą komend:
    • do zmiany ceny PUT /sale/offer-price-change-commands/{commandId}
    • do zmiany ilości PUT /sale/offer-quantity-change-commands/{commandId}
    • do zmiany pozostałych pól PUT /sale/offer-modification-commands/{commandId}
  3. Pojedynczo za pomocą odrębnej komendy do zmiany ceny PUT /offers/{offerId}/change-price-commands/{commandId}

W REST API zdjęliśmy ograniczenie na zmiany ofert, w których są zakupy. Dodatkowo możesz też edytować zakończone oferty przed ich wznowieniem.

Lista moich ofert

W WebAPI lista ofert sprzedającego jest podzielona pomiędzy wiele zasobów:

  • doGetMySellItems
  • doGetMySoldItems
  • doGetMyNotSoldItems
  • doGetMyFutureItems

W REST API oferty możesz przeglądać jednym zasobem: GET /sale/offers.

Zarządzanie zamówieniami

Więcej szczegółów znajdziesz w tym poradniku.

W REST API udostępniliśmy następujące opcje, które pozwolą zarządzać zamówieniami:

  • pobierz informacje o nowych zdarzeniach z dziennika (W WebAPI realizowane przez doGetSiteJournalDeals)
  • pobierz szczegóły zamówienia (doGetPostBuyFormsForSellers, doGetPostBuyFormsIds)
  • dodaj numer trackingowy przesyłki (doAddPackageInfoToPostBuyForm).

Pobieranie zamówień

Zamówienia pobierzesz za pomocą GET /order/checkout-forms, który stanowi odpowiednik doGetPostBuyFormsDataForSellers. Zasób opisaliśmy szczegółowo w tym poradniku.

Pobieranie zdarzeń o zamówieniach

Odpowiednikiem dziennika zdarzeń doGetSiteJournalDeals jest zasób: GET /order/events, za pomocą którego pobierzesz najnowsze zdarzenia dotyczące zamówień. Istotną różnicą w stosunku do starego dziennika jest to, że w przypadku zakupów przez koszyk, możemy zwrócić więcej niż jedną ofertę w zamówieniu.

Załączanie numeru trackingowego do zamówienia

Odpowiednikiem doAddPackageInfoToPostBuyForm z WebAPI jest POST /order/checkout-forms/{checkoutFormId}/shipments. W przeciwieństwie do WebAPI, w REST API musisz wskazać id pozycji zamówienia, których dotyczy dany numer przesyłki.