Managing the Compatibility section (compatibilityList) in offers


As of August 2018, in selected categories sellers can add the compatibility section, to provide information on models the product they offer is compatible with. At present, the sellers are asked to provide the said information as text description.

In June 2019, we published a new version of the Compatibility section that is integrated with the TecDoc vehicle database. We include models the sellers introduced to the new version of the Compatibility section in our search engine. As a result, it will be easier and more convenient for buyers to find an offer and check the compatibility.

When you assign product to an offer - provide in offer details content of compatibility list matching selected product. You can find more details about assigning products to offers in our tutorial.

The new version of the Compatibility section is supported in selected categories. Depending on the category, you can fill in the section using one method only, i.e. by providing vehicle IDs or by entering a text description.

information

If the section in your offer is filled in as a text description, but the category supports only integrated vehicle database:

  • Transfer the unchanged content of the section using PUT /sale/offers/ and edit other data
  • If you want to edit the content of the Compatibility section, you need to switch to the integrated vehicle database.
Examples of categories with Compatibility list - vehicle database integration
- all subcategories in Car parts,
- all subcategories in Motorcycle parts,
- selected categories in Car accessories: Wiper blades, Car mats, Tow bars.
Examples of categories with Compatibility list - text description
- selected subcategories in Printers and scanners: Ink, Toner cartridges, Imaging units, Tools and accessories,
- selected subcategories in Laptop parts: Batteries, Laptop power adapters, Keyboards,
- selected subcategories in Machine parts: Parts for agriculture machines, Parts for construction machines, Parts for industrial machines, Forklift parts,
- selected subcategories in Lawnmowers: Parts and accessories for lawnmowers.

Which categories support Compatibility section

In response to GET /sale/compatibility-list/supported-categories you receive a list of categories which support Compatibility section. Along with the list you are provided with details: which version of Compatibility section is supported and validation rules for the category. You can also use it under Client_credentials authorization type.


Sample request

curl -X GET \
  'https://api.allegro.pl/sale/compatibility-list/supported-categories' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'


Click to view sample response:
{
  "supportedCategories": [                      – list of categories which support Compatibility section
      "inputType": "ID",                        – supported version of Compatibility section in
                                                given category:
                                                 ID - integrated with vehicle database
                                                 TEXT - text version.
      "categoryId": "620",                      – identifier of the category, where you can use
                                                the Compatibility section in an offer listed in
                                                the category or in all subcategories, which belongs to
                                                returned category.
      "itemsType": "CAR",                       –  type of products - suggest what kind of merchandise s
                                                hould be included in the section
      "validationRules": {                      – constraints assigned to the category
        "maxRows": 2000,                        – maximal number of rows (products)
        "maxCharactersPerLine": null            – maximal length of single row
      },
      "name": "Części samochodowe"              – name of supported category
    },
  …
    {
      "inputType": "TEXT",
      "categoryId": "9108",
      "itemsType": "PRINTER",
      "validationRules": {
        "maxRows": 200,
        "maxCharactersPerLine": 100
      },
      "name": "Tusze"
    },
   …
    {
      "inputType": "TEXT",
      "categoryId": "144442",
      "itemsType": "MOWER",
      "validationRules": {
        "maxRows": 200,
        "maxCharactersPerLine": 100
      },
      "name": "Części i akcesoria do kosiarek"
}, … { "inputType": "ID", "categoryId": "158", "itemsType": "MOTORCYCLE", "validationRules": { "maxRows": 2000, "maxCharactersPerLine": null }, "name": "Części motocyklowe"
} … ] }

Managing the Compatibility section (compatibilityList) – integrated vehicle database

Use the below resources to find product IDs you want to present in the Compatibility section:

  • GET /sale/compatible-products/groups?type={type} - retrieve a list of available makes for types of products

  • GET /sale/compatible-products?type={type}&group.id={group.Id} - retrieve a list of available products of given type

  • GET /sale/compatible-products?type={type}&phrase={phrase} - retrieve a list of available products based on a phrase.

Supported values for type parameter:

  • CAR - for TecDoc base of vehicles

  • MOTORCYCLE - for TecDoc base of motorcycles.

Next provide selected IDs to the compatibilityList section in the offer.

GET /sale/compatible-products/groups?type={type}

Use this resource to retrieve a list of products for given typeavailable in the TecDoc database. You can also use it under Client_credentials authorization type.

Additionally, you can filter the list with the parameters:

  • (provide in header) If-Modified-Since - recent update of data:

    • if anything has been modified after the provided date, you will receive a complete set of data (status: 200 OK)

    • if nothing has been modified after the provided date, you will receive an empty response (status: 304 Not Modified).

Transfer the data as HTTP-date (pursuant to the format): “{day-name}, {day} {month} {year} {hour}:{minute}:{second} GMT” np. Sat, 01 Dec 2018 10:00:00 GMT.

  • offset - define a starting point for retrieving another batch of data. By default, the value of this field is 0.

  • limit - define a number of makes to be returned in the response. By default, the value of this field is 200.


Sample request

curl -X GET \
'https://api.allegro.pl/sale/compatible-products/groups?type=CAR&limit=3&offset=0' \
-H 'If-Modified-Since: Sat, 01 Dec 2018 10:00:00 GMT' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'


Click to view sample response:
-H ‘Last-Modified: Mon, 10 Dec 2018 15:15:17 GMT’               – header with the date
                                                                of the most recent update of data
                                                                received in the response
-d '{
    "groups": [
        {
            "id": "b0dfe6de8fb2f2b1309ad94c6cc4e09d",           – ID of the make
            "text": "ABARTH"                                    – name of the make
        },
        {
            "id": "4144e097d2fa7a491cec2a7a4322f2bc",
            "text": "AC"
        },
        {
            "id": "de3e2253f276cd1c757f58860d77b9bb",
            "text": "ACURA"
        }
    ],
    "count": 3,                                                 – number of returned elements
    "totalCount": 256                                           – number of all available makes
}’

GET /sale/compatible-products?type={type}&group.id={group.Id}

Use this resource to retrieve a list of products of a particular make and type. You can also use it under Client_credentials authorization type.

To retrieve the list, provide in the query:

groupId - required; ID of the make. You do not have to provide the value of this parameter if you transfer:

  • tecdoc.kTypNr - technical ID of a passenger car,truck, motorcycle from TecDoc database. Optional parameter.

  • tecdoc.nTypNr - technical ID of a commercial vehicle from TecDoc database. Optional parameter.

  • phrase - searched phrase.

Additionally, you can filter the list with the parameters:

  • (provide in header) If-Modified-Since - recent update of data:

    • if anything has been modified after the provided date, you will receive a complete set of data (status: 200 OK)

    • if nothing has been modified after the provided date, you will receive an empty response (status: 304 Not Modified)

    • if paramter phrase is given, this header is ignored.

    • Transfer the data as HTTP-date (pursuant to the format): “{day-name}, {day} {month} {year} {hour}:{minute}:{second} GMT” np. Sat, 01 Dec 2018 10:00:00 GMT.

  • tecdoc.kTypNr - for ?type=CAR and ?type=MOTORCYCLE - technical ID of a passenger car, delivery truck or motorcycle from TecDoc database.

  • tecdoc.nTypNr - for ?type=CAR - technical ID of a commercial vehicle from TecDoc database.

  • phrase - searched phrase.

  • offset - define a starting point for retrieving another batch of data. By default, the value of this field is 0.

  • limit - define a number of products to be returned in the response. By default, the value of this field is 200.


Sample request - with provided group.id and recent data update:

curl -X GET \
'https://api.allegro.pl/sale/compatible-products?type=CAR&group.id=a3c6ac924dd999674b48c8c10ce05391' \
-H 'If-Modified-Since: Sat, 01 Dec 2018 10:00:00 GMT' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'

Sample request - with provided tecdoc.kTypNr:

curl -X GET \
'https://api.allegro.pl/sale/compatible-products?type=CAR&tecdoc.kTypNr=15657' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'

Sample request - for Audi a3 8l 1.9 TDI 110KM:

curl -X GET \
'https://api.allegro.pl/sale/compatible-products?type=CAR&phrase=Audi%20a3%208l%201.9%20TDI' \
-H 'Accept: application/vnd.allegro.public.v1+json
-H 'Authorization: Bearer {token}'


Click to view sample response:
-H ‘Last-Modified: Mon, 10 Dec 2018 15:15:17 GMT’               – header with the date
                                                                of the most recent update of data
                                                                received in the response. Not returned
-d '{                                                           if phrase parameter is used
 "count": 200,                                                  – number of elements returned
                                                                in the compatibleProducts section
 "totalCount": 1276,                                            – number of all available results
                                                                Not returned if phrase parameter is used
-d '{
"compatibleProducts": [ { "id": "91627723-0b38-47aa-b10b-a99957340d05", – product ID "text": "RENAULT 10 (119_) 196605-197210 1.1 45KM/33kW", – product name "group": { "a3c6ac924dd999674b48c8c10ce05391" – ID of the make } "attributes": [ – array of parameters and their values { that describe the product "id": "POWER_KW", "values": [ "33" ] }, { "id": "MODELFROM", "values": [ "196605" ] }, … { "id": "TYPE", "values": [ "1.1" ] } ] }, { "id": "07d4c144-20f6-4e92-8a97-b61791e3ca4b", – another product "text": "RENAULT 10 (119) 196907-197210 1.3 48KM/35kW", … ]}’

Completing the compatibilityList section with product IDs

Once you have the list of IDs you want to provide in the Compatibility section, transfer it in the compatibilityList section in offer data. You can do it while creating a new offer (POST /sale/offers) or editing the current one (PUT /sale/offers/) - to learn more, read this guide. Here is the example of completing the Compatibility section with product IDs:


Sample section

"compatibilityList": {
  "items": [
   {
    "id": "c8c73534-c781-418f-9186-1140f69c011f",   -- required; product ID
    "type": "ID",                                   -- required, type of data in the section;
                                                    if you provide product IDs, set "ID"
 "additionalInfo": [{
        "value":"Kod silnika 123"                   -- not required; brief description
    }]                                              that includes more details about the particular product
   },
   {
    "id": "e3278ed6-9022-4135-b03f-e5e8d03accd7",
    "type": "ID",
    "additionalInfo": []
   },
   {
    "id": "daff8488-02b7-4392-b251-9fe769b9aea5",
    "type": "ID",
    "additionalInfo": []
   },
   {
    "id": "9e8135b8-b941-450a-b2b4-63e32d932f80",
    "type": "ID",
    "additionalInfo": []
}]}

Providing description in the text version of compatibilityList section

You can do it while creating a new offer (POST /sale/offers) or editing the current one (PUT /sale/offers/) - to learn more, read this guide. Continue reading to learn how to use text to fill in the section with car makes and models that the part you offer is compatible with.


information
  • On the offer page, we recognize vehicle makes and groupthem into models. For example, if you add 15 different engine versions of “VW Golf”, we will display “VW” and provide the models below.
  • We have introduced limits for provided characters and amount of information, to this section:

    • 200 characters per row
    • 2000 rows.


Sample section

"compatibilityList": {
 "items": [
  {"text": "CITROËN AMI 1963/01-1968/05 6 (AM, AMB) 24KM/18kW"},
  {"text": "CITROËN ACADIANE 1978/08-1988/10 6 31KM/23kW"},
  {"text": "CITROËN ACADIANE 1978/08-1988/10 6 30KM/22kW"},
  {"text": "CITROËN C6 (TD_) 2005/09-2011/12 2.7 HDi 204KM/150kW"}
 ]}

How to search for the suggested Compatibility section

Use GET /sale/compatibility-list-suggestions to retrieve suggested compatibility list. Use this endpoint when you don’t have a compatibilityList section in your offer. Owing to the completed compatibilityList section, it is easier for the customers to find the product they are interested in. We create suggestions on the basis of compatibility lists from the other sellers offers. You can modify the list according to your needs, e.g. remove or add some of the elements.

Pass in the request one of the parameters on the basis of which we will return the suggested compatibilityList section:


Sample request

curl -X GET \
    'https://api.allegro.pl/sale/compatibility-list-suggestions?offer.id=6505550901' \
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.public.v1+json'


Sample response

{
    "type": "MANUAL",
    "items": [
        {
            "type": "ID",
            "id": "73ff4bae-958d-4b75-a49c-d0c11fdd233c",
            "text": "Toyota AVENSIS (_T22_) 2.0 VVT-i (AZT220_) (1AZ-FSE) 1998ccm 150KM/110kW 2000/10-2003/02",
            "additionalInfo": []
        },
        {
            "type": "ID",
            "id": "de7a2247-78fa-4a12-94f1-f43b5f33ac7e",
            "text": "Toyota AVENSIS (_T22_) 2.0 TD (CT220_) (2C-TE) 1975ccm 90KM/66kW 1997/09-2003/02",
            "additionalInfo": []
        }
    ]
}

The received list can be used when you list or edit an offer.

List of resources

You will find full documentation of resources in the swagger.yaml form file here.

List of basic resources used in tutorial: