(My)Bertus API onboard manual

WHY DO WE PROVIDE AN API?

The standard way to interact with Bertus Distribution BV is to user our portal: https://my.bertus.com. Some of our customers want to communicate with our portal using their own systems. To facilitate these customers, we are providing an (REST) API.

HOW CAN YOU ACCESS OUR API?

To gain access to our API you first need to be a customer. If you already are, you may follow the instructions in this document to become an API consumer.

THE DEVELOPERS PORTAL

The developers portal is there to help you understand what endpoints are part of our API, how you can make a request to an endpoint and what type of responses you may expect. The url of this website is: https://myapi-portal.bertus.com.

Sign up

Choose sign up now and fill in this form:

LOGIN TO DEVELOPERS PORTAL

Remark: Some times authentication can get confused, especially if you have your own Azure account. USE INCOGNITO BROWSER IF AUTHENTICATION DOES NOT WORK.

Go to the developers portal and sign in.

After successful login your screen should look a bit like this

SUBSCRIBE TO A PRODUCT

The developers portal gives you access to one or more products. A product in the developers portal is a combination of an API and access rights. You must subscribe to a product to be allowed to use it. You may subscribe directly in the portal, but a Bertus employee will have to approve your subscription before you can use it. These are the steps:

Step 1: Go to products page

Step 2: Choose "MyBertus API 30 request/min"

Step 3: Enter any subscription name in "Your new product subscription name" textbox

Step 4: Click on Subscribe button

Once you click on Subscribe it will take you to Profile page where you can see the status of all your subscriptions as below

Note that the subscription I requested now has the state “Requested”. This means you are now waiting for a Bertus employee to accept your request for a subscription. After this is done, the state will show “active”.

You will also receive an e-mail when you subscription is accepted. It will look somewhat like this one:

Dear User,

Thank you for your interest in our MyBertus Api 30 requests per minute limit API product!

We were delighted to receive your subscription request. We will promptly review it and get back to you at User Email.

Thank you,

The Bertus API Team

FIND AN API ENDPOINT TO USE

After your subscription has been approved, you can use the developers portal to discover what exactly is in our API.

Now choose “MyBertus Api Stage”. You will see a list of all our endpoints:

Note that there’s an option to download the description of our API in several standard formats. This download can be used by some tools to generate (part of) an solution to use our API.

CALL AN API ENDPOINT

After your subscription has been approved, you can try and make your first request to the portal. This will verify you have acces to both the API and My.Bertus.

You will need:

1. Your primary or secondary subscription key. We recommend using your primary key for your application and the secondary key for testing purposes, like this.

2. Your My Bertus username, account number and password.

How to get you subscription key?

Go to: https://myapi-portal.bertus.com/developer and click on "profile" from the menu:

How do I get my user name, account number and password?

Go to https://my.bertus.com and register or login if you already have.

You can see your account number on the profile page.

How can I make my first request?

Go to the API’s section of the developers portal and select “My Bertus API production”. For this example we will choose the “Articles_Get” endpoint. This endpoint will enable you to retrieve details of a Bertus article, by its bertus article id. Select the “Articles_Get” endpoint and choose “Try it”

This page will show you what parameters must be filled in to make a successful request and will allow you to authenticate before making a request. The required subscription key is already filled in for you.

Your next step is to enter a value for all required fields.

For this api we need your account number and an article ID (if you don't know your account number, go to https://my.bertus.com/profile)

You also need to authenticate. This will make sure we know how you are so we can serve your data.

Choose "Authorization code" for Production Auth0 RS256 under the Authorization section and login with your my bertus user id and password:

When successful an authorization code will be included in your example request:

No we are ready to make our first request. Choose “Send” and look at the result.

The top part of the response will look like this:

USE THE API FROM A PROGRAM

There are several ways to use our API from a program. If you intend to allow your users to access our data thru our API. We recommend that you allow these users to login using one of the options offered by Auth0 (https://auth0.com/). In this instance I will assume you need to write a program that runs in the background at some scheduled moment(s). You may then store your user-id and password some where safe and use them in the program you write.

You may find a C# example in this repo: https://bitbucket.org/bertusdistributie/apiexamplescsharp/src/master/.

The important parts, I will highlight here: