Allegro Technical Scope [DRAFT]

Authentication

It's not difficult to start working with the Allegro restoration and all you need is a few simple steps. If you do not use the Allegro REST API yet, this technical scope will get you through the basics of working with Allegro API. Allegro offers a SandBox environment where we can conduct our testing.  The authentication is OAuth 2.0

We have to generate an access_token - which will identify the application and possibly the user. We require a token for all queries that you send to the Allegro API. To obtain an access token, you need the Client ID and Client Secret

The production end point - https://allegro.pl/auth/oauth/token The sandbox end point - https://allegro.pl.allegrosandbox.pl/auth/oauth/token GET We will have add parameter grant_type=client_credentials with header Authorization: Basic base64(clientId:secret)

After a successful request we will receive response:

{
  "access_token":"eyJ...dUA",
  "token_type":"bearer",
  "expires_in":43199,
  "scope":"allegro_api",
  "jti":"2184f3be-f6de-4a66-bd8f-b11347d7ba80"
}

Once we have the access token we will have to refresh at every 12 hours in order to do so we have to call: GET The production end point - https://allegro.pl/auth/oauth/token The sandbox end point - https://allegro.pl.allegrosandbox.pl/auth/oauth/token

We will have add parameter grant_type=refresh_token and refresh_token={access token value}

All this will require additional table account_allegro where we can store all specific account fields.

Taxonomy Flows

Allegro provide taxonomy which we have to use to validate our product data.  The taxonomy have to downloaded using three different calls:

1 Get IDs of main Allegro categories - GET https://api.allegro.pl/sale/categories Authorization:Bearer {access token} and Accept:application/vnd.allegro.public.v1+json

This call will return all parent categories which we have to save in table 2500 (marketplace_category)

2 Get category by ID - GET https://api.allegro.pl/sale/categories Authorization:Bearer {access token} and Accept:application/vnd.allegro.public.v1+json

Once we get the main categories we have to use their IDs as a parent ID until we get to the leaf category.  In order to do so we have to add a parameter parent.id = {id} https://api.allegro.pl/sale/categories?parent.id=5 This will return level 2 of category three id 5 then we use level 2 ids to get level 3 and so on until we reach the leaf category. The leaf category will be the final level of the category three.

This call will return all parent categories which we have to save in table 2500 (marketplace_category)

3 Get parameters by category ID - GET https://api.allegro.pl/sale/categories/{categoryId}/parameters Authorization:Bearer {access token} and Accept:application/vnd.allegro.public.v1+json

Once we have the complete category three we need to get each category attributes (marketplace_category_property) and values (marketplace_property_value)

This call will return all attributes for specific category which we have to save in table 2501 (marketplace_category_property)

This call will return all attributes values for specific category which we have to save in table 2502 (marketplace_property_value) Dictionary tag contains all enumerations for specific attribute. We only have values for attributes which enumeration is true.

Shipping Services

Then we have to create all shipping services we would like to offer and obtain their IDs. More information can be found here https://developer.allegro.pl/news/2018-08-14-cenniki_dostawy/TBA

Product flows

1. Offer Creation

Once we have the taxonomy and the shipping services we can start with creating the product. 

First we have to send the images to Allegro Server from where they will return the images new location.  Then we have to prepare our product title with the following requirements: We allow a maximum of 50 characters in the title of the offer. A list of letters, numbers and special characters that we allow to enter in the title of the offer can be found below.

The description of the offer allow certain HTML tags:

• h1 - title
• h2 - subtitle
• p - paragraph
• ul - bullets
• ol - listing
• li - list element
• b - bold.

and the maximum size of the entire description you can send is 40,000 bytes

What the description structure looks like

Sections (sections)

The offer description consists of at least one section, which you place in the section table. The description can have max. 100 sections.

{
    "sections": [
        { section1 },
        { section2 },
         ...
        ]
}

Description elements (item)

The sections group elements of description (item) into a column view:

• one column that occupies the entire width of the screen

{
      "items" : [
     { item1 }
     ]
}

• two columns, each of which takes up half the screen

{
      "items" : [
     { item1 }
     { item2 }
     ]
}

• You can not create a section with more columns.

Types of content in the description

Text

{
      "type": "TEXT",
      "content": "<p>opis tekstowy</p>"
}

You can use specific HTML tags here:

• h1 - title
• h2 - subtitle
• p - paragraph
• ul - bullets
• ol - listing
• li - list element
• b - bold.

The most important rules:

1. You must put content in HTML tags. Use only lowercase letters in HTML tags. CorrectIncorrectly

   {
             "type": "TEXT",
             "content": "<p>opis tekstowy</p>"
           }

   {
             "type": "TEXT",
             "content": "opis tekstowy"
           }

2. You can not format the h1 and h2 tags in addition. CorrectIncorrectly

   {
             "type": "TEXT",
             "content": "<h1>Tytuł sekcji</h1>"
           }

   {
             "type": "TEXT",
             "content": "<h1><b>Tytuł sekcji<b></h1>"
           }

3. You can use bold  </ b> in the tags:

   • </ p> - paragraph

   • </ ul> - bulleted list
     • </ ol> - numbered list

   • You can use the 

     </ p> paragraph tag in the tags:

     • </ ul> - bulleted list
       • </ ol> - numbered list

Photographs

You can only use images you previously uploaded using the POST method on the resource / sale / images.

{
    "type": "IMAGE",
    "url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
}

An example description structure

{
    "sections": [{
        "items": [{
            "type": "TEXT",
            "content": "<p>tekstowy opis przedmiotu</p>"
        }]
    }, {
        "items": [{
            "type": "IMAGE",
            "url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
        }]
    }, {
        "items": [{
            "type": "TEXT",
            "content": "<p>tekstowy opis przedmiotu</p>"
        }, {
            "type": "IMAGE",
            "url": "https://f.allegroimg.com/original/037738/bc72c2f24784b50774d7d078c7ef"
        }]
    }, {
        "items": [{
            "type": "IMAGE",
            "url": "https://0.allegroimg.com/original/032ac4/9c10035846bb970cf208f6982fc0"
        }, {
            "type": "IMAGE",
            "url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
        }]
    }]
}

Once we have send the images and have prepared the offer we can create a draft offer more details can be found here -

https://developer.allegro.pl/sale/#step-7-draft

The flow should be as follows:

The product in WAP should be send as follows:

Flow	Product Statuses Before Action	Product Statuses After Success Action
Send Images	List Update The Whole Item - Pending

Product Status - Awaiting Creation Listing Status -  Inactive | List Update The Whole Item - Pending Product Status - Images uploaded Listing Status - Inactive | | Send Draft | List Update The Whole Item - Pending Product Status - Images uploaded Listing Status - Inactive | List Update The Whole Item - Pending Product Status - Product Created Listing Status - Inactive | | Activate Draft | List Update The Whole Item - Pending Product Status - Product Created Listing Status - Inactive | List Update The Whole Item - Not Needed Product Status - Product Published Listing Status - Active |

2.Offer Full Update

IMPORTANT!In a single call you can edit up to 1000 offers. More info can be found here- https://developer.allegro.pl/my_offers/#3

3.Offer Stock

IMPORTANT! In a single call you can edit up to 1000 offers. Allegro does not provide a stock update call however we can set an internal logic once Quantity reach 0 to send  By PUT method on the resource / sale / offer-publication-commands / {commandId} you can also pause selected offers - just enter PAUSE in the action field.

4.Offer Price Update

IMPORTANT! In a single call you can edit up to 1000 offers. PUT / sale / offer-price-change-commands / {commandId} - this resource will ask you to change the price in selected offers.

5.Zero quantity updates

IMPORTANT! In a single call you can edit up to 1000 offers. By PUT method on the resource / sale / offer-publication-commands / {commandId} you can also pause selected offers - just enter PAUSE in the action field.

6.Delete offer

IMPORTANT! In a single call you can edit up to 1000 offers. By PUT method on the resource / sale / offer-publication-commands / {commandId} you can also end  selected offers - just enter END in the action field.

Orders flows

1. Get orders -
2. Ship orders -
3. Cancel orders -
4. Refund orders -
5. Any other -

Other - specifics

We need to use IS/VS values and map them with the values from the taxonomy and send the codes in the payload.

Outstanding questions

Do we would like to include offer tags and offer attachments?