About this guide

This guide aims at helping you migrate from WebAPI to REST API.

You may find the timetable for WebAPI phase out here.

If you are just getting started with REST API and Allegro integration, start with general information and getting started guide.

Comparison

Table below is a short comparison of terms and methods used in WebAPI to their REST API counterparts.

WebAPI REST API
Authorization WebAPI key Client ID and Client Secret of application generated in Allegro Developer Apps
Generally available data SOAP methods secured by WebAPI key Resources secured by JWT token generated by client_credentials OAuth2 flow
Logged in user data SOAP methods secured by session identifier Resources secured by JWT token generated by authorization_code or device_code OAuth2 flow
Logging in doLogin
doLoginEnc
User id contained in response
POST https://allegro.pl/auth/oauth/token
User id encoded in JWT
Session management Session renewed automatically Refreshing access_token by using refresh_token
Error handling Checking contents of SoapFault Checking HTTP response code and message
Creating offers doNewAuctionExt POST /sale/offers
Delivery methods doGetShipmentData GET /sale/delivery-methods
Shipping rates none GET /sale/shipping-rates
POST /sale/shipping-rates
PUT /sale/shipping-rates
GET /sale/offers/{offerId}/shipping-rates
Offer publication doNewAuctionExt
doFinishItem
doFinishItems
PUT /sale/offer-publication-commands/{id}
Validating offers doCheckNewAuctionExt
doNewAuctionExt
validation section in offer
POST /sale/offers
PUT /sale/offer-publication-commands/{id}
Editing offers 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}
Offer event journal doGetSiteJournal GET /sale/offer-events
My offers list doGetMySellItems
doGetMySoldItems
doGetMyNotSoldItems
doGetMyFutureItems
GET /sale/offers
Tracking numbers doAddPackageInfoToPostBuyForm POST /order/checkout-forms/{id}/shipments
Orders list doGetPostBuyData
doGetPostBuyFormsDataForSellers
doGetPostBuyFormsIds
doGetTransactionsIDs
doGetFilledPostBuyForms
GET /order/checkout-forms
GET /order/checkout-forms/{id}
GET /order/checkout-forms/{id}/shipments
Order events journal doGetSiteJournalDeals
doGetSiteJournalDealsInfo
GET /order/events
GET /order/event-stats

Migration guide

Authorization

A more detailed REST API authorization guide is available here.

In WebAPI you can authorize yourself by using doLogin and doLoginEnc methods. In those methods you input a WebAPI key, user login and password and retrieve a session identifier.

In REST API you use the /auth/oauth/token endpoint, to which you need to provide your application’s Client ID and Client Secret. You will get an access_token JWT in response. You need to pass this token in an HTTP Authorization header in every REST API request, for example:

 
    GET /sale/offers
    Authorization: Bearer eyJhbGciOiJIUssw5cdsdasw
    Accept: application/vnd.allegro.public.v1+json
 
where “eyJhbGciOiJIUssw5cdsdasw” is some sample access_token.

Some WebAPI methods and REST API resources are generally available and some require a logged in user to access.

Generally available methods and resources

Examples of generally available WebAPI methods are doGetCatsData and doGetSellFormFieldsForCategory. For those WebAPI methods you do not need to call doLogin(Enc), they just take your WebAPI key as a parameter.

When using REST API to access generally available resources, such as GET /offers/listing, you do not need user interaction in OAuth2 flow. If you use client_credentials OAuth2 flow, you just need to provide your application’s Client ID and Client Secret. You will obtain a JWT authorization token called access_token. This token does not contain logged in user info, but is valid for calls to generally accessible resources.

Resources and methods available for logged in user

Some resources and methods, such as POST /sale/offers and doNewAuctionExt require a logged in user context.

The WebAPI way of calling these is to call doLogin(Enc). This would return a session handle and a logged in user identifier. Session handle is then used as a parameter to call other secured methods.

In REST API there are two authorization flows that will grant you an access_token with a logged in user context: - if your application can redirect to, or display web pages (e.g. it is a web application) use authorization_code OAuth2 flow - otherwise use device_flow. You can then decode obtained token using one of many available libraries.

Retrieving logged in user info

WebAPI method doLogin(Enc) returns the logged in user’s identifier directly. In REST API, however, you will find the logged in user’s identifier in user_name field in decoded JWT access_token.

Lifecycle of sessions and tokens

WebAPI sessions are valid for one hour. However, whenever you use a session handle we renew its validity period.

In REST API, an access_token contains an expiry date, which you will find in the exp field of JWT access_token. We also return this date in expires_in field of response to the POST /auth/oauth/token request. Issuing a request with an expired access_token will result in a HTTP 401 Unauthorized status code response along with body:

 
    {"error":"invalid_token","error_description":"Access token expired: <token value>"}
 

To acquire new access_token without user interaction you can use refresh_token to refresh your access_token.

Token can be refreshed:

  • preemptively, when expiry time contained in the exp field is near
  • after expiry, in response to a 401 HTTP error
information

Refreshing the token returns a new access_token and refresh_token pair. Old refresh_token is now invalid and to refresh the access_token again you need to use its latest refresh_token.

Error handling

In SOAP API we respond to all errors (no matter if caused by invalid user input, server issues or authorization issues) with an HTTP status 500 and SoapFault, which contains error details.

In REST API the most important piece of information is the HTTP status code. It points to root cause of error, whether it was server overload or invalid input. Additional information is contained in an error response.

In case you need to contact us about some errors it would be helpful if you provide value of a Trace-Id header returned in response. It is good practice to log this value, at least when API error occurs. Providing a Trace-Id in an Allegro contact form or a github issue will help to track down the problem.

Offer management

You will find more detailed explanations in guides describing REST Api Offer management:

Creating offers

Main differences between WebAPI and REST API are:

Productization

Since the beginning of 2019 we group offers with the same product. In REST API you can search for products, and then link them to offers.

A different way of uploading offer images

In WebAPI you can upload the whole offer (including all images) in one request to doNewAuctionExt. This results in big, bulky requests, that are prone to be disconnected and need to be retried.

In REST API we added a dedicated endpoint for image upload. After an upload finishes you will receive an image link that you can add to your (previously created by POST /sale/offers) offer.

Delivery methods

You can list available delivery methods in WebAPI by calling doGetShipmentData. Its REST API counterpart is the GET /sale/delivery-methods resource.

Assigning shipping rates

In WebAPI every offer has its delivery options specified separately. In REST API you need to define shipping rates first and attach them to an offer draft afterwards.
If you have an offer without shipping rate assigned , you can use GET /sale/offers/{offerId}/shipping-rates, to get delivery methods used in that offer.

Offer data

In WebAPI all offer fields are specified as FIDs (or field identifiers) which are defined on per-category basis. You can find out which fields are needed in order to list offers in specific category by calling doGetSellFormFieldsForCategory.

In REST API, fields that are common across all categories (such as name, price, stock) are defined directly in an offer resource, e.g.:

 
    { "name": "Offer name", "stock": { "available": 10, "unit": "SET" }, ... }
 
Offer parameters that vary depending on category are defined in the GET /sale/categories/{categoryId}/parameters resource:
 {  
    "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ł" }
        ],
        ...
    }]
}
You can then set these parameters in an offer, using a call to PUT /sale/offers. The value can be a single identifier or a list:
    {
        "name": "Offer name",
        "parameters": [
            {"id" : "22728", "valuesIds" : [ "22728_215173" ]}
        ],
        ...
    }

Retrieving category information

In WebAPI you can download all categories using doGetCatsData and doGetCatsDataLimit.

In REST API the /sale/categories resource contains list of main categories. If you want to download whole category tree, use GET /sale/categories?parent.id={id} to traverse it recursively. You can list offers only in leaf categories which are marked as "leaf":true.

Remember, to check the category tree and parameters list, when you are listing or editing offers, as these change quite dynamically in Allegro.

Offer publication

In WebAPI, after you call doNewAuctionExt, the offer is automatically listed.

In REST API, after call to POST /sale/offers, the offer is in INACTIVE status. Only after you execute a publication command the offer will become visible.

Using a publication command you can also: - end an offer (equivalent of WebAPI doFinishItem and doFinishItems methods) - start an offer that was ended (it’s going to be visible in Allegro with the same identifier)

Changing ended offers

In WebAPI changing an ended offers was impossible, because you could not start them again. In REST API you can edit and restart your ended offers at will.

Validating offers

In WebAPI you can use the special doCheckNewItemExt method, which checks an offer data and returns validation errors, if any.

In REST API, after you create the INACTIVE draft offer by calling POST /sale/offers, returned offer contains a validation section where you can find what changes you need to make before the offer can be published.

Editing offers

In WebAPI the method doChangeItemFields allows changing active offers. You can also use separate helper methods, such as doChangePriceItem or doChangeQuantityItem.

In REST API you have multiple ways of editing you offers:

  1. Individually using the PUT /sale/offers endpoint
  2. In bulk using commands:
    • to change the price: PUT /sale/offer-price-change-commands/{commandId}
    • to change available quantity: PUT /sale/offer-quantity-change-commands/{commandId}
    • to change other fields: PUT /sale/offer-modification-commands/{commandId}
  3. Individually using separate command to change the price PUT /offers/{offerId}/change-price-commands/{commandId}

In contrast to WebAPI, in REST API you can make changes to offers which already have been purchased.
You can also edit ended offers before starting them.

Offer event journal

GET /sale/offer-events is the counterpart for event journal method - doGetSiteJournal. It allows you to get the newest events in offers listed by authorized seller. In contrast to the doGetSiteJournal method, GET /sale/offer-events resource:

  • Returns events concerning changes in offers listed by authorized seller, as doGetSiteJournal does with entry parameter infoType set to 0.
  • Response contains events that occurred within the last 24 hours.
  • Provides new event types - for changes in stock and price. Event with stock changes is also returned when there is a purchase in the offer.
  • Does not returns purchase events in the offer. You can follow these events via Order events journal.

My offers list

In WebAPI you have multiple methods which allow you to retrieve your offers:

  • doGetMySellItems
  • doGetMySoldItems
  • doGetMyNotSoldItems
  • doGetMyFutureItems

In REST API you can view your offers using a single resource: GET /sale/offers.

Order managements

You will find a more detailed order management guide here,

API order management allows you to:

  • retrieve your order data
  • retrieve events about your orders
  • add tracking numbers

Retrieving your order data

You can list your orders by using GET /order/checkout-forms, which is equivalent of calling doGetPostBuyFormsDataForSellers.

Retrieving events about your orders

The resource GET /order/events in REST API, just like the doGetSiteJournalDeals WebAPI method, returns latest events about your orders. There is one difference, however. In REST API, if a purchase is made via cart, one event can contain multiple items. In WebAPI you will receive multiple events in this case.

Adding a tracking number to order

To add a tracking number to an order in WebAPI you call doAddPackageInfoToPostBuyForm. In REST API, you need to issue request to POST /order/checkout-forms/{checkoutFormId}/shipments. In contrast to WebAPI, where you would just add a tracking number to the whole order, in REST API you need to specify line items which are sent by tracked package.