Documentation

Prerequisites for starting with the integration of the Certified Pick up process

Getting started

Introduction

Below you can find different guidelines for stakeholders that wish to integrate the Certified Pick up API into their systems. These documents are updated on a request base. Should you require additional documentation to align for your business process, don't hesitate to contact us through our Service desk.

Choose your connection

Certified Pick up will bean obligatory process to integrate into your processes for all stakeholders involved in the import of containers in the Port of Antwerp. As a stakeholder, there are multiple ways to join: 

  • An easy user interface application (available as of 1-Jul-20)
  • Integration via API's (available as of 1-Jul-20)
  • Re-usage of existing messages (for terminal & agents, read more)

UAT (LIVE) vs Production environment (Q4 2020)

The Certified Pick up case offers two separated environments for the API integration: a production environment for Live data and a User Acceptance environment for integration setup and testing.

This allows you to test your API-integration prior to linking your production environment. However, unlike most sandbox or user acceptance environments that work independent of other stakeholders while integrating, the Certified Pick up use case is a process that involves several stakeholders. It requires input from other relevant involved parties. As such, please make sure that the other companies you wish to integrate with are aware that you will be sending test data through the User Acceptance environment. 

The UAT environment has become operational as of July 1st 2020. As of that moment, you can find on this page all necessary information on how to subscribe to the Certified Pick up solution.
The Production environment will become operational as of December 15th 2020. As of that moment, you will find on this page all necessary information on how to subscribe to the Certified Pick up solution.

Getting started

When implementing the Certified Pick up API, a number of steps need to be taken before access can be obtained.

Register your company on C-point

Any stakeholder that wants to use the Certified Pick up API needs to be registered on the C-point platform. 

If these links are not working for you, please create a support ticket. Be sure to mention the corresponding environment in the ticket. 

Subscribe to the Certified Pick up application

Any stakeholder that wants to use the Certified Pick up API needs to subscribe to the application on the C-Point platform and sign the relevant terms & conditions.

Subscribers can have multiple roles. You will need to choose the role that fits with your profile. Your subscription will be verified and approved by the Certified Pick up team. 

  • Ship Agent
  • Forwarder, Transport Operator or BCO
  • Terminal

Subscription is done via the C-point dashboard. You can follow the second part of this tutorial.

Request your client ID & Secret

Once the registration of your company is completed, please create a support ticket via e-mail (support@nxtport.com) or via the ticketing portal to request the necessary Client Key. Our support team will help with the different environments and setting up the client ids for the Certified Pick-up API.

Create an API user

API-users are created within the NxtPort console. User accounts of C-point cannot be used for API calls via the NxtPort platform. To create users within the NxtPort console, follow these steps: 

  • Open the NxtPort console (UAT environment) and go to Organization > Users
  • Create a new user via Add User 
  • The new users will need to complete the registration

You can find a detailed description of the steps on the User management tutorial

Authentication & authorization

Authentication

In order to use the API’s, you need to setup Oauth2 authentication. When you have received the necessary keys from NxtPort, you will be able to setup a connection with the following parameters:

  • username: email address of the API-user (of a stakeholder entity, not a software developer) who is subscribed to the API
  • password: password of the API-user
  • grant_type: password
  • client_id: Client ID of the application builder (internal or third party), provided by NxtPort to the software developer (not the stakeholders)
  • client_secret: code to verify the client_id, also provided by NxtPort to the software developer (not the stakeholders)
  • scope: openid

With the above information you can request an access token, valid for a period of 1 hour, via https://login.nxtport.com/connect/token (production) or https://login-uat.nxtport.com/connect/token (UAT). This token is required to make successful API calls.

Authorization

In order to call a web API:

  • include the API key of the stakeholder in your call: You can put the API subscription key either in the header as the Ocp-Apim-Subscription-Key parameter, or in the query string as the subscription-key parameter. This key is found in the NxtPort Console (link UAT, link production).
  • include a token in your call using a header parameter with name “Authorization" and value “Bearer {TOKEN}”. Replace {TOKEN} with the token that you received in your call to get the token and remove the quotes, present here just to indicate the extent of the content. The authorization token is created using the client key of the application builder. Refer to the diagram in Paragraph 2 for more details.
  • External software developers will need to use the API key of a subscribed stakeholders for which they are integrating

Example of a Postman setup


Setup your notification channel

Certified Pick up uses an asynchronous notification mechanism using HTTP post end points. 

When integrating the use case with an API integration, this is an essential step in order to receive the required information from other stakeholders. 

  • Go to the NxtPort console on the relevant environment  
  • Open My organization > Notification channels. 
  • Click on the "Add notification channel" button

After you create your channel(s) you also need to link them to the Certified Pick up application. 

  • Go to Data user and open the Certified Pick up application (this will always show "Live", even on the UAT environment)
  • Click on the notifications tab
  • Click on the "Add notification" button
  • Enter a name for the notification
  • Select the corresponding channel you have setup in the previous step

For further information on how to setup your notification channels, please refer to the corresponding tutorial

Register your company