Knowledge Base

Getting started

Step 1 – Fetch all you need to get started

When you subscribe to Alkemics API access, Alkemics will provide to you:

A login and Password

Login and password are created during your account creation process.

Use these email/password to connect to the documentation of the Alkemics Data model to check the whole list of product data you can get using the API.
The documentation allows you to filter the list of attributes per product category, so that you can focus on the data you need and can retrieve.

See Data Model Documentation

See General API Documentation
(Authentication, examples of JSON results, filters, ...)

Credentials for testing your code

Credentials are a « client_id » and a « secret_id ».
These are a random alphanumeric string.
e.g.
client_id : 42d3c020i8FGhijkLd65f9952d567lkkkkkkkkm
client_secret : 67hjtuopm345JZNmpla091234567890

These credentials enable you to authenticate to the Alkemics API services and get a token. Use the token for all the others services call to get data.
The token manages your access rights scope e.g. access in read-only mode, access in read/write mode, etc.

These credentials are only for testing purposes. By using them, you will get fake products data. To get actual product data on actual suppliers’ catalog, use the live credentials (see next session Credentials for your live service and/or application)

For security means, a token is valid for 30 days. You can regenerate a new token using your testing credentials.

Credentials for your live usage

Live usage credentials are also « client_id » and a « secret_id ».

The credentials enable you to authenticate to the Alkemics API services and get a token. Use the token for all the others services call to get data.
The token manages your access rights scope e.g. access in read-only mode, access in read/write mode, etc.

These credentials are the ones to use. By using them, you will get actual product data according to your credential permissions. For testing purposes, use the test credentials (see earlier session Credentials for testing your code)

For security means, a token is valid for 30 days. You can regenerate a new token using your credentials. So keep your live credentials secure.

Step 2 – Authenticate to get your token

Service URL : https://apis.alkemics.com/auth/v2/token

Post Parameters and values :

  • client_id: YOUR_CLIENT_ID
  • client_secret: YOUR_CLIENT_SECRET
  • grant_type: client_credentials

Step 3 – Get the list of products

Service URL : https://apis.alkemics.com/public/v1/products

Post Parameters and values :

  • Authorization: Bearer GENERATED_TOKEN

This service enables you to get all the products of all manufacturers that granted you access to their catalog.

In order to filter the products on a specific organisation, you need to use the services with additional filters:

filter_owners_in allows you to specify the organisation identifier

filter_target_market allows you to request only product sold in France. (market code : 250, see ISO-3166 numeric country codes for more information).

https://apis.alkemics.com/public/v1/products?filter_target_market=250&filter_owners_in=ORG_ID

limit allows you to set the maximum number of products you want to retrieve. By default the limit parameter is set to 20. The max value is 500. To optimise performances we advice you to use a limit at 50 and then make multiple consecutive calls using offset parameter for pagination.

filter_source_include allows you to retrieve only some fields by specifying the list of fields. We strongly encourage you to use this filter to have better response times by restricting the amount of data returned to what is really necessary

To retrieve more than 10K elements you need to use "scroll search" by doing the following:

  • on the first call, set next_page to '' and set the limit (50 for instance) (offset parameter will be discarded)
  • on the following calls, pass the next_page parameter with the value returned by the previous call (next_page changes after each call). You still need to pass a limit parameter (you can actually change it after each call, but it's recommended not to change it)
  • you have 2 minutes between each calls to make the following call, after this, the next_page will be invalid and you will have to restart from the beginning (ie: set next_page to '')
📘

Choose the best pagination method

In order to choose the best pagination method you should use, you can make a first call to get the number of products matching your request.

Make a first call with all the filters to apply for the products you want to retrieve and set the parameters limit to 1 and filter_source_include with 1 specific field like uuid (to optimize the call).

curl --request GET \
  --url 'https://apis.alkemics.com/public/v1/products?filter_target_market=250&filter_product_languages=fr&limit=1&offset=0&filter_tags_in=exportable&filter_source_include=uuid' \
  --header 'Accept: application/json' \
  --header 'Accept-language: fr' \
  --header 'Authorization: Bearer AUTHORIZATION_TOKEN'

In the response, you will get a totalResults field showing you how many products matches your request and be able to choose the suited pagination method.

{
  "offset":0
  "data":[
    {
      "id":"123456"
      "uuid":"12345678-aaaa-bbbb-cccc-1234567890ab"
    }
  ]
  "totalResults":12345
}

Step 4 – Test your code

Use the testing credentials you were provided (see Step1 - Credentials for testing your code for the authentication).

Use the testing organization ID for ORGID (see [_Step1 - Data for testing your code](https://docs.alkemics.com/docs/getting-startedt#section-step-1-fetch-all-you-need-to-get-started)) when you call the service to get the products.

Refer to the list of testing GTINs provided to you by Alkemics to check your code (see Step1 - Data for testing your code)

Ready to use the enhanced services?

Step 5 – Implement enhanced services

Alkemics API permits you to use multiple filters to have the most accurate data you need.

  • Per “brand”: get the catalog for a set of brands
  • Per “GTIN”: get only the GTINs that interest you
  • Only the catalog update: get only the new GTINs in the catalog and GTINs for which data has changed, in a period interval
    See how to use advanced filters
  • Only a subset of product attributes: get only the pictures and description:
    See how to get rich content
  • Note that unless you specify the attributes you want to retrieve you will receive all attributes, even if the values are empty

Updated 10 months ago