Getting started
This document explains how to successfully call the Transport API. It will present how to request access to the API and how to deliver instructions to the API. The document presents how to send shipping orders to the interface but the explanation is general and can be used for any API.
Getting access
Having access to the API Portal you can:
Browse the API documentation providing all information necessary to make a request and to process a response.
Request authorization to use the BWS API.
Experiment with the BWS API interactively. An interactive console allows making API calls directly from the developer portal without writing any code.
Code samples are provided per API operation in a variety of languages.
This document describes how to sign up to the BWS API Portal and subscribe to specific API “products.” This way you can obtain credentials to use when calling APIs in BWS.
First step
To gain access to the API's firstly you must sign up to the API portal. It should be noted that Blue Water Shipping provides two environments that must be signed up to separately.
Environment
Link to BWS API Portal
Link to Sign Up
Test
Prod
The process is:
Follow the link to the BWS Developer Portal.
If you do not have an account already, sign up by filling in the Sign-up form.
Verify your account by following the instructions in the email from the Developer Portal.
Getting API Access - create a subscription
Follow the steps below to obtain a subscription key used to authorize all requests to the BWS APIs:
Login.
Navigate to Products section using the menu.
Click the product specified by BWS. If a specific product has not been mentioned to you, then ask your contact person at BWS. The “Customer” product is correct in many cases.
Subscribe by entering a subscription name and clicking the Subscribe button.
Please use your company name as subscription name.Await approval from a BWS Developer Portal Administrator.
After approval you will receive an e-mail and you can start sending requests from your IT-systems. Using the “Try it” button in the Developer Portal will automatically add your new subscription-key to all requests as explained in the next chapter.
Using the API
This section describes how the endpoints provided by subscribing to a product can be used. This section will focus on using the shipping order API but can be used for other API's to same effect.
The integration partner must be signed up in the BWS API Developer Portal and have access to the ShippingOrders API through an API product specified by Blue Water Shipping prior to this setup.
The steps for this is described in the previous chapter.
In the BWS API Portal select the APIs menu item and select the ShippingOrders api. This opens a list of operations for delivering Shipping Orders.
To deliver a ShippingOrder using the API portal’s interactive console, select the Submit a shipping order operation in the Operations list, and click the Try it button.
Use your subscription key received by email to authorize. It should be setup automatically in the Console if an admin has granted you access as described in “Getting access to the BWS API Developer Portal”. Notice that by selecting a subscription key in the drop-down, the header “Ocp-Apim-Subscription-Key" changes accordingly.
Note: When sending from your own IT-system, you can either provide the subscription-key in the header as shown above or as a query-parameter in the end of the URL like this:
https://api.bws.net/api/v2/shippingOrders?subscription-key=123
Do not change Parameters or Headers manually in the Console.
Enter a valid shipping order JSON structure in the Body and scroll down and click Send. Notice that the example provided is intended to show a full shipping order with all possible fields. This also means that some fields,
that are naturally mutually exclusive, are also filled out simultaneously.
The HTTP response for submitting a ShippingOrder successfully is 200 OK. It contains the transaction id assigned by the system for reference.
The message submitted is validated according to the BWS standard for shipping orders. If errors are found, the message is rejected with a description of what went wrong (HTTP response 400).