After the registration to the service, as described here, the PRISMA shipper API is activated immediately. It is possible to upgrade at any time, downgrading or cancelling the service will only be effective from the next payment period.
The shipper admin can generate the token that is necessary to authenticate your system while using the API service by going to the gear box in the top-right corner of the screen under "Premium services".
The token is visible only once after its generation for security reasons. The user can copy the token by clicking "Copy to clipboard" or by manually copying it from the token field.
If you would like to change your token or need a new one, it can be easily done by pressing the "Generate token" button.
Note: You can only have one token per company active at the same time. This means if one admin generates a new token, any previously generated tokens for your company are void.
To start using the API, you will need to insert this token in your authentication header of your call towards the platform. There are different ways and tools how you can request data via the API. One option to try it out before implementing it in your system is to use the tool Postman. Our technical API documentation (SWAGGER) offers a direct link to use the collection in your Postman application.
After creating and selecting a workspace or selecting an existing workspace of your choice where you want to import the PRISMA API doc to, you can start setting up your parameters to create your first call.
The following example will use the simple request GET/auction-calendar, which will return a list of currently published auction calendars for the specific auction type "MONTH".
Click on the Collection (1) to open it, select a subfolder (2) and select the query (3).
A tab opens where you then can modify your request. Postman will now help you to build your request with the following pieces:
1. Parameters
Here you set the parameters that fine-tune your request. Most calls need at least one parameter to be set, to return data. Otherwise, you will receive a 400 or a 404 error. Furthermore, the more refined your request, the less load on the system and the quicker your results will be there.
In our example, we will use periodType = MONTH.
2. Authorization
Select Type "Bearer Token". Here, please paste the bearer token that was generated above. Using Postman, please only copy the cryptic part of the token and omit the "Bearer".
This set of information will be enough for your first request. Hit the "Send" Button (1). The results for your query will then be shown below in the response body (2).
This response JSON is what will be ingested into your system for further processing once you integrate the API in your application.
Error example:
If you query for something that (currently) does not exist, you should receive an error 404 which in Postman looks like this. The error code (404) and an error description is shown above the response window.
When using the SWAGGER UI on the test system in the browser, you can authenticate yourself as follows.
Step 1:
Click on 'Authorize'
Step 2:
Paste the generated token from the clipboard into the 'Value' field (The keyword Bearer is an important part of the token and must not be omitted).
The dialogue should present now the 'Authorize' button. By pressing the button, Swagger will check the inserted token.
Step 3:
You are now authorized and can close the overlay by clicking the "x".
You are logged in now, and you can use the PRISMA shipper API services via swagger.