Getting started with the API integration

Introduction

Below you will find an overview of the different steps you will need to take to get started with the API integration of Bulkchain.

Bulkchain is an API-first product. However a User Interface (UI) is available for those parties that do not wish to integrate (just yet) and want to get started quickly. Please do note that NOT all features available through the API integration are also available in the UI.

We have documented the steps as well as possible below, but if you would still have any doubts or questions, don't hesitate to contact our https://nxtport.atlassian.net/servicedesk/customer/portal/47.

User Acceptance Testing vs Production

To ensure a high level of quality in our production environment we have a User Acceptance Testing environment; which allows both you, the companies you work with and NxtPort to perform the necessary tests before moving to production.

This step is mandatory for all API integrations to allow you access to production and access to support.

Since these two environments are separated for security reasons, you will need to perform the steps below on both the User Acceptance Testing as well as the Production environment.

1. Register your company on the User Acceptance Testing environment

In case you are subscribed to other NxtPort products such as CPu or IRP, it is advisable to request a subscription to Bulkchain for the same entity known by NxtPort.

In case you are not yet subscribed to other NxtPort products, register your company on the My Port of Antwerp-Bruges platform and request a subscription for Bulkchain:

• PRD: https://register.portofantwerpbruges.com/account

• UAT: https://register-accpt.portofantwerpbruges.com/account

Once this step of the registration process is successful and you receive the My Port of Antwerp-Bruges credentials, those can be used when logging in to the Bulkchain web application. When the Bulkchain web application is opened, the user will automatically be redirected to the login of MyPOAB. Upon a successful login, your subscription to Bulkchain will be validated. If you have an active subscription, you will be granted access to the Bulkchain web application. If you do not have an active subscription to Bulkchain, an error message will be displayed and access will be denied.

Login to MyPoAB:

• PRD: https://my.portofantwerpbruges.com/

• UAT: https://my-accpt.portofantwerpbruges.com/

2. API set-up

2.1 Create onboarding request

To start your integration process and get started on our UAT environment, you will need to create an onboarding ticket via our https://nxtport.atlassian.net/servicedesk/customer/portal/47. Our Support Team will gladly help you. You will need the following:

• Your company name (as registered in My Poab)

• Your VAT Number

• The Roles your company has in Bulkchain

2.2 Request client credentials

Once the registration of your company has been completed and an onboarding ticket has been created, you will receive a Client ID, Client Secret and a Subscription Key from our Support Team.

• A Client ID is part of your API credentials (aka your Bulkchain Client), which are needed to request a new access token. This follows a GUID format and is assigned to your company. An example of a Client ID is 82ca66b6-c5c6-42a3-88aa-b163e1953249.

• A Client Secret is the "password" for your Bulkchain client, which is also required when requesting new access tokens. The Client Secret should not be shared with anyone, not even with the support team. The support team will never ask you for your password or secret.

• A Subscription Key is a unique key that identifies your company's subscription to the Bulkchain API. It must be included in the header of every API request (typically as Ocp-Apim-Subscription-Key) alongside your access token. Like your Client Secret, the subscription key should be kept confidential and not shared publicly.

2.3 API Authentication & Authorization

2.3.1 API Authentication

In order to use the API's, you need to setup OAuth2 authentication (see https://auth0.com/docs/authenticate/protocols/oauth for more info). When you have received the necessary credentials from NxtPort, you will be able to request an access token from our authorization server with the following parameters:

UAT

POST https://b2cnxtweuuat.b2clogin.com/b2cnxtweuuat.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN_IDENTITY/oauth2/v2.0/token

Request body (x-www-form-urlencoded):

• grant_type: client_credentials

• scope: https://b2cnxtweuuat.onmicrosoft.com/f200a8ef-4b9d-4c45-aa84-03301d81bf4f/.default

• client_id: [Client ID received from NxtPort (ref. step 2.2)]

• client_secret: [Client Secret received from NxtPort (ref. step 2.2)]

PRD

POST https://b2cnxtweuprd.b2clogin.com/b2cnxtweuprd.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN_IDENTITY/oauth2/v2.0/token

Request body (x-www-form-urlencoded):

• grant_type: client_credentials

• scope: https://b2cnxtweuprd.onmicrosoft.com/4579a10e-8504-42a0-bedf-9f08eeacd456/.default

• client_id: [Client ID received from NxtPort (ref. step 2.2)]

• client_secret: [Client Secret received from NxtPort (ref. step 2.2)]

With the above information you can request an access token, valid for a period of 1 hour. This token is required to make successful API calls. For more information, see https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/

2.3.2 API Authorization

In order to call the Bulkchain API:

• Include the subscription key in your call: in the header as the Ocp-Apim-Subscription-Key parameter. (ref. step 2.2)

• Include the access token in your call using a header parameter with key Authorization and value Bearer {{TOKEN}}. Replace {{TOKEN}} with the token that you received in the previous step.

• External software developers will need to use the subscription key of the subscribed stakeholder for which they are integrating.

2.4 IP addresses

2.4.1 Your IP addresses

Provide your IP addresses per environment to NxtPort so they can be whitelisted for API communication. NxtPort support will ask to provide this info via a form. This is a mandatory onboarding step.

2.4.2 NxtPort's IP addresses

Bulkchain will push asynchronous feedback and status update messages to the sender system. To facilitate this, the sender system's firewall must permit incoming traffic from the following IP addresses:

Correlation ID

Upon positive technical validation for an asynchronous call, Bulkchain generates a unique correlationId for each received message. Each feedback or status update message from Bulkchain related to the asynchronous call will incorporate the generated correlationId.

The correlationId enables the sender system to correlate requests with the responses received from Bulkchain. Moreover, they facilitate traceability and efficient debugging.

3. Setup your notification channel

Bulkchain mainly uses an asynchronous notification mechanism using HTTPS POST endpoints. These asynchronous API calls have the following behaviour:

• A post returns a "202 accepted" HTTP response status code to indicate the message was successfully registered. The message information is not processed at this point.

• The message is processed internally. It may take some time to finalize the message processing, depending on the load of the platform.

• The result of the message processing is posted to the notification channel post-back URL once the message is fully processed. The return value may include:

  • An ok status when the message was processed: https://documentation.nxtport.com/bulkchain/success-notifications

  • An error message when an error occurred, as defined in the API call specification: https://documentation.nxtport.com/bulkchain/technical-and-business-validation#Error-messages

When integrating with an API integration, this is an essential step in order to receive the required information.

Contact NxtPort support and provide them the necessary info:

• Channel Name: The name of the channel to be able to distinguish the channel from other channels

• Endpoint URL: The address to where the POST request must be sent

• Headers: Optional headers will be added to the POST request when sending the notification. It is possible to add an 'Authorization' header when the Authentication Type is set to none

• Authentication Type: It is possible to let the NxtPort Notification Service fetch the access token itself, instead of using a static bearer token. This can be done by choosing OAuth2 Client Credentials or OAuth2 Password Flow. This is not mandatory. Add these fields if you want to use one of these types:

What's next?

• https://documentation.nxtport.com/bulkchain/messages

• https://documentation.nxtport.com/bulkchain/logistics-service-provider-integration-specificati

• https://documentation.nxtport.com/bulkchain/terminal-operator-integration-specifications

• https://documentation.nxtport.com/bulkchain/ship-agent-integration-specifications