Introduction


The PRISMA API allows you to request and post data to the PRISMA platform directly from your IT systems. Through 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 to internal and external process requirements. By importing your capacity date via the API, you can avoid human error and acquire the most accurate, up-to-date data for subsequent processes. 


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


API Resources


The PRISMA API is organized around the following resources:


AreaAPI resourceDescription
Auction bookingshttps://platform.prisma-capacity.eu/api/v1/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.prisma-capacity.eu/api/v1/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 or time frame.
Secondary Tradeshttps://platform.prisma-capacity.eu/api/v1/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 which 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 (not operational, yet).
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 as follows:


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 a 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 moment of coding to the moment of problem-solving. Therefore, the latest updates are always swiftly available.


Should you so require, we can provide an example client for testing purposes. Moreover, we offer support in a wide range of languages. Just contact our customer support team!


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.prisma-capacity.eu/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.


How to test the interface?

At the moment there is no dedicated test system available. As we are currently only sending data to you, we would allow you to test the interface against our productive system. To give you sufficient time to do so, you can use the interface free of charge for two months after the first activation.


How can we create a client in the language that fits our needs?

The documentation tool, swagger, provides an online editor, that you can use to easily generate a client in the development language of your choice.

Just navigate to https://editor.swagger.io which will display an online editor window that is split into two panes. The editor will show by default and example called "PetStore". The pane on the left is for an OpenAPI specification while the pane on the right will show an interactive interface using that spec. Load up the PRISMA spec by clicking on the "File" drop-down at the top and then clicking on "Import URL":



The current version of the Swagger specification for the PRISMA API is available from the URL https://platform.prisma-capacity.eu/api/v1/swagger.json. Paste the URL into the dialogue that appears after clicking "Import URL" and the left pane will populate with the PRISMA API specification.

In case the link to the JSON file does not work for your editor, feel free to download v1 of the PRISMA API specification here and use the Import File option instead: PRISMA-API-v1-swagger.json

Click on the "Generate Client" dropdown and choose the language of your preference. (e.g. csharp)



This will download a zip file containing a generated client for the language you have chosen. In the example depicted above - this would be C#. Extract this anywhere you would like so you can work with it.


Rate limitation

Our systems are built to deliver a proper service and response times to all users equally. In case you are putting a heavy load to 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/...). In case of changes to the version of the interface, PRISMA will inform all users of the service in due time about the changes.