Skip to main content

API Documentation

Introduction​

This documentation provides details about the API endpoints and functionality of the BDL217 API.

Authentication​

To access the API endpoints, you need to include the API key (https://bdl217-api.collegedesproducteurs.be/user/api-tokens) in the request headers. Add the following header to your requests:

Authorization: Bearer <api_key>

Base URL​

The base URL for all API endpoints is: https://bdl217-api.collegedesproducteurs.be.

There is a sandbox environment available at https://bdl217-sandbox-api.collegedesproducteurs.be/ with some test data.

Exemple of api call request​

GET /products​

Retrieve a list of products.

Request​

  • Method: GET
  • Endpoint: /products
  • Headers:
    • Authorization: Bearer <api_key>

Taxonomy explanation​

User​

A user is a person that can interact with the platform. Each user has a name, email, and role. Each user have teams and can be part of a team.

Team​

A team is a group of users. Each team has a name and a slug and a team_type segment. A team is linked to a product. Each team should be validated by a BDL217 Admin.

Team Member​

A team member is a user that is part of a team. Each team member has a role in the team with different permissions.

Product​

A product can be identified in various ways :

  • Through the BDL217 product UUID assigned on creation
  • Using a barcode
    • Barcode registered by GS1 (GTINs)
      • Barcode for commercial units : those are barcode put on packaging units that are effectively sold to B2C end customers. They are unique per definition and can be stored in the gtin attribute of BDL217's products.
      • Barcode for logistics units (f.i boxes of 12 commercial units or pallets of 27 boxes) : those may not be stored in BDL 217.
    • barcode registered by third parties (seller specific coding, codes from codesabarres.be...) for commercial units are stored as external ids in BDL217. When creating/updating, you should use attributes external_type : "non_GS1_EAN" (tag_id: 35830) and external_id: the barcode value. When retrieving, you may find it in the those two attributes, as well as in the external_ids attribute.
  • Another identifier : BDL217 can store other identifiers using type/value pairs. Types are listed here : https://bdl217-api.collegedesproducteurs.be/api/tags?type=externalreferencetype. Please contact the platform support if you didn't find a type for your situation. When consulting, you may also find those other identifiers in the external_ids attribute.

Note : external_ids may only contain one value for each external_type. When updating a product, if an id is already defined for the external_type you're trying to set, the new value will replace the pre-existing one.

Categories​

Categories are the main classification that could be hierarchical. Each category has a name and a slug and a type.

Tags​

Tags are a way to classify products. Each tag has a name and a slug.

Taxonomy lists​

Team Types​

This is the list of team types that can be used to classify a team in BDL217.

https://bdl217-sandbox-api.collegedesproducteurs.be/api/categories?type=team_type&per_page=100

GS1 Categories​

https://bdl217-sandbox-api.collegedesproducteurs.be/api/gpc

Allergens​

This is the list of allergens that can be used to classify a product in BDL217.

https://bdl217-sandbox-api.collegedesproducteurs.be/api/tags?type=AllergenTypeCodes

UOM​

This is the list of units of measure that can be used to classify a product in BDL217 (dimension and weight).

https://bdl217-sandbox-api.collegedesproducteurs.be/api/categories?type=uom

The difference between categories and tags​

Categories are the main classification that could be hierarchical (with multi-level).

Tags are a way to classify products in a single level (there is no hierarchy). With some case of tags, we can allow to add any kind of tags so please handle it with care and dynamically.

Contact​

bdl217.support@collegedesproducteurs.be