Supplier Data Manager API

#Getting started

#Prerequisites

To be able to follow this guide you need:

  • An active user account on the Supplier Data Manager (SDM) platform
  • A project (in the user's organization)
  • One or more output formats defined

#Step 1: Get your token

The API requires a token, you can generate one by calling this endpoint:

POST https://sdm.akeneo.cloud/api/v1/auth/token/
    {
        "email": "customer@company.com"
        "password": "MySecurePassword",
        "token_name": "any name"
    }
    

The token_name key can be arbitrarily decided, it is only used for administrative purposes.

The email and password keys must be those of your user account

The response contains the key in UUID v4 format:

{
        "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
    

This key allows you to authenticate on all SDM API endpoints, so it must be kept secret. From this stage, all requests must be authenticated by passing the token in the headers:

Authorization: Token ${key}
    

#Step 2: Send a file

SDM projects run on files with product data. Two possibilities to send it to the platform:

#Flat file upload

This file can have two formats:

  • Excel file, with the xlsx extension, encoded in utf-8, with the data in the first tab
  • CSV file, with csv extension, can use ,, ; or | as a separator and be encoded in utf-8 or ISO 8859-1 / Latin-1

In both cases, the file must have a header in the first line and be composed of at least the columns defined in the template.

To upload the file, you need to make the following request:

POST https://sdm.akeneo.cloud/api/v1/files/
    {
        "file": my file
    }
    

The request must have multipart/form-data in its headers.

The response is mainly composed of the id of the uploaded file, which must be kept for later.

{
        "id": 17
        ...
    }
    

More information on the files endpoint on our API reference

#Sending a JSON payload

The other option to create a file is to send the data in JSON. To do this you need to make the following request:

POST https://sdm.akeneo.cloud/api/v1/files/
    {
        "data": [
    			{"col1": "val1_1", "col2": "val1_2", ...},
    			{"col1": "val2_1", "col2": "val2_2", ...},
    			...
    		]
    }
    

The payload is a list of objects, each representing a line with a format "column name" : "column value". All the columns defined in the template must be present. Empty values can be ignored or set with the value null.

As for file sending, the response is mainly composed of the id key which must be kept for later.

{
        "id": 17
        ...
    }
    

#Step 3: Create a job

Now we can launch the processing of your file or data sent. First, you need to create what is called a job and link it to the previously uploaded file or payload sent.

It is necessary to have the id of the project that you want to use. You can use the endpoint to list projects, more information on our API reference

Send this request to create the job:

POST https://sdm.akeneo.cloud/api/v1/jobs/
    {
        "file_id": ${uploaded_file_id},
        "name": "any name you want",
        "project": ${project_id},
        "model_version": 0
    }
    

The response is mainly composed of the id key which is used to identify the job thus created.

{
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
    

Congrats, SDM platform is now processing your data!

#Step 4: Retrieve the results of a job

To know if your job is done, you need to check its status.

When a job is finished (status at done), you can retrieve the results:

GET https://sdm.akeneo.cloud/api/v1/jobs/${job_id}/download/${output_format_id}/
    

This request generates an output file in the format specified in the output format (CSV or Excel) which can be downloaded.

#Support

In case of questions, you can contact SDM’s support by creating a ticket in Akeneo’s portal.