1. Úvod
  2. Developer
  3. Processes
  4. Components
  5. Allegro API

Allegro API

Verze:

21. 03. 2024

Zodpovědná osoba:

Dominik Šlechta

1. Introduction

  • Purpose: This is the documentation of the Allegro component which creates a bridge between our system and Allegro API.
  • Scope: Authorization, Proposing a new product, Proposing changes to an existing product, Proposing an Offer, Proposing changes to an offer
  • Audience: Developers

2. Allegro API Overview

  • API Description: The Allegro API can be used for complete management of our offers on Allegro.
  • API Documentation Reference: https://developer.allegro.pl/documentation

3. Process Authorization

  • Objective: To successfully interact with the Allegro API, we need to obtain an access token, which is then used in every request's header.
  • Prerequisites: Client ID and Client Secret (to obtain these two, you need to create an app in the Allegro system)
  • Authorization Flow:
    • The request is sent to this endpoint: 

      https://allegro.pl/auth/oauth/authorize
      with clientId, clientSecret and the redirectUri

    • If the request is successfull it's then redirected to the URL specified in the redirectUri parameter, which has to be same as the one connected to the application you created in the Allegro system.
    • The authorization code is sent to the redirectUri, which is our endpoint
    • We process the authorization code and send a POST request to  
      https://allegro.pl/auth/oauth/token

      with the authorization code in post data. And again we have to provide a redirectUri parameter, which has to be the same as the one connected to the application you created in the Allegro system

    • Then the response is returned from Allegro API to the redirectUri containing the access token
    • We proccess the access token and save it to our database prepared for future use.
  • Error Handling: No known errors yet.

4. Proposing a New Product

  • Objective: Proposing a product to Allegro, which must be then accepted by Allegro and can be used in our future offers.
  • Preparation: 
    • Images - urls to the images saved on allegro's server
    • Name - product name
    • Category - we need to provide a Allegro Category ID
    • Parameters - product's parameters. Each category has a different set of required parameters and its available options.
    • Language - Language of provided product data.
  • Submission Process:
    • Allegro Category ID:
      • we first need to set the product's Allegro Category ID. Which is the category ID the product should be in.
      • our component also can generate the XML tree, which contains all Allegro's categories, so you can take the ID from there.
    • Images:
      • before proposing a product we need to upload all its images. It includes the main product photo and all the photos in connected galleries.
    • Parameters:
      • we also need to send product's parameters. Every category has different set of required parameters, so first we need to obtain those required parameters and then dynamically generate our parameters.
      • The allegro parameters are mapped to our parameters. NOTE: not all the parameters have to be mapped correctly, so there is a room for future extension.
  • Best Practices: 
    • before proposing a product, you need to map our parameters to allegro parameters.

5. Proposing Changes to a Product

  • Objective: When the product's characteristics change (images, category, parameters), you need to propose that update to Allegro.
  • Change Proposal Process: 
    • The changes proposal differs from proposing a new product in only two things - it contains product's ID in allegro system a different endpoint.
    • Right now, when our product has allegro_id saved, which it gets after the proposal, you can update it
    • The update just sends current product's to allegro for approval

6. Proposing a new offer

  • Objective: Creating an offer in allegro with a certain product
  • Proposing offer Process: 
    • When you are proposing an offer, you can propose it with the product, which already exists in Allegro system, in that case you have to use its allegro_id
    • You can also propose a creation of a new product along with the offer proposing, but you have to included all required info, which is the same as in proposing a new product
    • Stock:
      • you need set the stock of the product, which is the number of the orders which can be made of this offer
    • SellingMode:
      • in the selling mode you set the format of the offer, which can be 'ADVERTISEMENT', 'BUY_NOW' or 'ADVERTISEMENT'
      • you also set the currency and the price of the product (offer)
    • Description:
      • you can set the description of the offer. If it's not set it will take the product's description (if set)
      • allegro accepts only these HTML tags: h1, h2, p, ul, ol, li, b
      • also it doesn't allow nested lists, so you have to format your text so it matches the restrictions

7. Proposing changes to the offer

  • Objective: Proposing changes to an existing offer
  • Proposing changes process: 
    • it requires the same data as the process of creating a new offer
    • only additional thing is the offerId, you need to include into the endpoint's path