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)

Only for API integration - User Acceptance Testing UAT vs Production PRD environment

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. 

If you wish to use our UAT/testing environment, please send a request to support@nxtport.com and we will provide you with the necessary information.

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.

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.

Only for API integration - Request your client ID & Secret

Once the registration of your company is completed, please create a support ticket via e-mail (support@nxtport.com) 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.

Only for API integration - 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 (https://console.nxtport.com) 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

Only for API integration - Authentication & authorization

API 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

Example of a setup in postman is shown in the below image. Be sure to select the x-www-form-urlencoded format. 

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). This token is required to make successful API calls.

API 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 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

IP addresses

If applicable, the following IP addresses should be whitelisted: 

  • Production: 20.76.217.177

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