PRISMA API - Business Information

Modified on:: Thu, 8 Apr, 2021 at 2:28 PM

Print

Introduction


The PRISMA API allows you to request and post data to the PRISMA platform directly from your IT system. With the PRISMA API, you can support the most important business processes in regards to capacity management.


You can migrate data from our system to yours in no time and with no hassle ensuring your compliance with internal and external process requirements. By importing your capacity data via the API, you can avoid human error and acquire the most accurate, up-to-date data for subsequent processing. 


The API works via a digital tool called Swagger, which renders the entire process safe and easy.


The KON Swagger API is available only for the Trader API service package subscribers. 


API Resources


The PRISMA API is organized around the following resources:


AreaAPI resourceDescription
Auction bookingshttps://platform.kon.prisma-capacity.cloud/api/v2/auction-bookingRequest the list of successful auction bookings for the shippers' company. Use filters to request specific auctions by ID or limit the results to a specific time frame.
FCFS bookingshttps://platform.kon.prisma-capacity.cloud/api/v2/fcfs-bookingRequest the list of successful FCFS bookings for the shippers' company. Use filters to request specific bookings by ID or limit the results to a specific transportation period.
Secondary Tradeshttps://platform.kon.prisma-capacity.cloud/api/v2/confirmed-secondary-tradeRequest the list of successful secondary trades for the shippers' company. Use filters to request specific secondary trades by ID or limit the results to a specific transportation period or time frame.


All responses will return JSON. 


We are using common approaches for the following:


FunctionDescription
DataThe PRISMA API data is JSON encoded with UTF-8. The PRISMA API JSON is either a single object or a list of objects.
AuthorizationA JSON Web Token is needed to authenticate. To use other rest resources of this API, the token has to be appended to an ‘Authorization’ header of each request. Important: The 'Bearer ' part must not be omitted.
Errors401 responses are returned in case of a missing/incorrect authentication.
Rate LimitingControls how many requests can be made in a defined time window.
HTTPMethods are used in accordance with HTTP (GET POST and DELETE are the primary methods used) and resources are identified using URIs. All API requests are sent over HTTPS.


How to Subscribe


To subscribe to the Shipper API service on behalf of your company, you must have administrator status. As an administrator, do the following:


1. Click on "Shipper Admin."


2. Then, click on "Premium Services."


3. Finally activate the toggle next to PRISMA API.



4. A pop-up window will appear. First, you will see an overview of the registration procedure and a link to the technical details of the functionality. To continue, click on "Next"



5. Upon doing so, you will find an overview of the three available API packages: (1) Reconciliation, (2) Analyst and (3) Trader. For further information on each of those packages, please contact our customer success team. Click on "Choose" beneath your desired package to continue.


6. On the following page, you'll be asked to provide a SEPA mandate to pay for the selected service. Your company details will be prefilled for your convenience. However, if you'd like to alter some information, just click on the pencil icon. Otherwise, check the box confirming the mandate. and move on to the next page.



7. Finally review your details, read and accept the terms and conditions. Press "Order Now" to conclude the process.




Token Authorization


Once you conclude the subscription process, your Premium Services page will look thus:


On this page, you can generate the token with which you may access and use the PRISMA API on the Swagger Platform. The token is the unique identifier of your company to which only you have access. It makes the functionality very safe and easy to use. It enables you to (1) interact with your PRISMA data, (2) use scripts to extract information from our platform and (3) automate some of your internal processes.


Developer Reference

Your colleagues in the IT department might be interested in much more detailed documentation of the resources that are available via the PRISMA API. 


As previously mentioned, the PRISMA API relies on Swagger to build our developer documentation from coding to problem-solving. Therefore, the latest updates are always available quickly.


You can find an example client for testing purposes here.


Swagger UI: All PRISMA API functions can be called from the Swagger UI.


On Swagger, you can tinker and experiment with abandon. It allows you to try different functionalities of the API and access documentation about query parameters or response structures of the REST resources.


Login: When performing API requests for querying booking data (auctions, FCFS, or secondary trading), you must enter a valid token -- the one you generate on your administrator page as explained above.


To go through the authentication process on Swagger, do as follows:


  1. Open the Swagger API in the browser (https://platform.kon.prisma-capacity.cloud/api/swagger/)

  2. Click on "Authorize".



Paste the valid token into the "Value" text field and click on "Authorize".

(The keyword Bearer is an important part of the token and must not be omitted)



  1. The dialogue should now display "Authorized" underneath the "API key authorization" header.
    (Swagger will even show "Authorized" if you used a wrong token, but the request won't work.)

  2. Close the dialogue by clicking on the "X" icon in the top right corner.



  1. Congratulations! You are now logged in and can test the REST API services.


Auction Booking Service

After login, the login information is transferred to the Server within the HTTP header.

Basically, everything works the same as with the login:

  1. Scroll to "Auction booking".

  2. If the "GET" button is not visible, click on the right arrow.

  3. Click on the "GET" button.



  1. Click on "Try it out".

  2. Enter selection criteria (auctionId, bookedAt, bookedSince).

  3. Click on the "Execute" button.


Scroll down to see the "Responses" area. If the request was successful, a code of 200 and a valid "Response body" is displayed.



Secondary booking and FCFS booking work similar to the auction booking interfaces.



Rate limitation

Our systems are built to deliver proper service and response times to all users equally. In case you are putting a heavy load on the system by flooding it with an unreasonable amount of requests from the API, we might have to either limit your request or shut your access down completely. 


Versioning

The PRISMA API is versioned. This means that with each request you send to the PRISMA platform, you can select what version of the interface you would like to make use of. In case you would like to request all your confirmed auction bookings, your system would need to send a request similar to the below to the PRISMA platform:


All auction bookings
curl -X GET "https://platform.prisma-capacity.eu/api/v1/auction-booking" -H  "accept: application/json" -H  "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxNjA1NjMzIiwibnVtYmVyIjoiMTYiLCJjcmVhdGVkIjoxNTAyMzc2NDcyNDY3LCJyb2xlcyI6WyJST0xFX1NISVBQRVJfQVBJX1VTRVIiXX0.XKNh7l8ZNLmfErK78tPvrIVbauaASXtYtcMAhhX9x8Spe1uw7GZ3sbnKTcbAz6uKK1Ux3w-ytpYUe5ZHrHginQ"


Note the URL of the request, it contains the version of the interface that is called. In the example above it is version 1 (.../api/v1/...). For requests to the current version 2, the URL of the request would need to be structured like this: .../api/v2/... 


S
Simona is the author of this solution article.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.