Getting started with the API integration
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.
Registration and credentials
1. Register your company and request Bulkchain subscription
In case your 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 (not available yet)
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 to the Bulkchain web application will be denied.
2. Request credentials to access the API
In case your company would like to integrate the Bulkchain API, credentials must be requested via our service desk: Bulkchain Support Desk - Jira Service Management.
You will receive a Bulkchain client ID & secret, this set of credentials is used to make requests to Bulkchain REST APIs.
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.
Sending & Receiving messages
Access token
All API requests to the Bulkchain API must have a valid access token (aka Bearer token) in the Authorization header. An access token can be requested by following this cUrl example, replacing the placeholders with your client ID and client secret.
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_credentialsscope:https://b2cnxtweuuat.onmicrosoft.com/f200a8ef-4b9d-4c45-aa84-03301d81bf4f/.defaultclient_id: [Client ID received from NxtPort]client_secret: [Client secret received from NxtPort]
PRD
[will be added in another version]
Incoming traffic from Bulkchain
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:
[Placeholder]
[Placeholder]
[Placeholder]
[Placeholder]
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.
Bulkchain retry mechanism
Not in this version.
Managing message order
Not in this version.