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 Certified Pick up (CPu).

CPu 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.

In addition to the differences between the API integration and the UI, the available actions depend on the Role your company has in CPu.

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 Support Team.

Before continuing, you need to make sure your company has been registered & you have subscribed to CPu.

Useful links

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

This process is nearly identical to the process described in How to register for Certified Pick up? , except for some minor changes:

Do you already have an account on the ACCPT (testing) environment of C-point?
1. If yes, go to https://my-accpt.portofantwerpbruges.com , log in using your testing credentials and follow flow B of the registration process;
2. If no, register your company at https://register-accpt.portofantwerpbruges.com and follow flow A of the registration process;
3. If you have no idea, follow flow C or contact the Customer Success Team, they will check it out for you;
The URLs in the UAT environment are:
1. NxtPort Console: https://console-uat.nxtport.com ;
2. CPu UI: https://crp-uat.nxtport.com ;
  be sure to use these URLs, otherwise the registration will not work;
If you go to the CPu UI in UAT, you will first be directed to the NxtPort login screen (as opposed to PRD where you are immediately directed to C-point login). Click on the red button “C-point (2FA)“ to continue.

2. API set-up

User Acceptance Testing UAT vs Production PRD environment

The CPu case offers two separated environments for the API integration: a Production environment for Live data and a User Acceptance Testing 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 CPu 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 Testing environment.

The following steps need to be done on both UAT & PRD environment

	URL UAT environment	URL PRD environment
NxtPort Console	`https://console-uat.nxtport.com`	`https://console.nxtport.com`
NxtPort Authorization Server Host	`https://login-uat.nxtport.com`	`https://login.nxtport.com`

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 this link. Our Support Team will gladly help you. You will need the following:

Your company name (as registered in C-point)
Your NxtPort ID (which can be found via How to find your CPu registration number / NxtPort ID? )
The Roles your company has been granted for CPu (Ship Agent, Terminal Operator, Release Party, Transport Operator)

2.2 Create API user

The authentication flow for API at NxtPort is based on a user-password protection flow. However, the users that are created when registering through C-point are not valid API users. You will need to create a separate user for this through the NxtPort environment.

You can create API users through the NxtPort console:

Log in to the NxtPort Console by using the red button “C-point“ & your C-point credentials and go to “My Organization” > “Users”;
Create a new user via “Add User”;
The new user will need to complete the registration.

2.3 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 & secret from our Customer Success Team.

2.4 API Authentication & authorization

2.4.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:

POST {{NxtPort Authorization Server Host}}/connect/token

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

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 in step 2.3;
client_secret: code to verify the client_id provided in step 2.3;
scope: openid.

Example of a PRD setup in Postman

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. This token is required to make successful API calls. For more information, see https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/

2.4.2 API Authorization

In order to call a web API:

include the API key of the stakeholder in your call: in the header as the Ocp-Apim-Subscription-Key parameter. This key is found in the NxtPort Console .
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. The authorization token is created using the client key of the application builder.
External software developers will need to use the API key of a subscribed stakeholders for which they are integrating

Example of a Postman setup

2.5 IP addresses

If applicable, the following IP addresses should be whitelisted:

Updated IP addresses

UAT: 52.233.238.227
PRD: 20.93.144.11

3. Setup your notification channel

CPu mainly uses an asynchronous notification mechanism using HTTPS POST endpoints.

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

Check out Setting up notification channels for the tutorial.

What’s next?

Need any further assistance?

Raise a support ticket on the NxtPort Support Portal