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?
If yes, go to https://my-accpt.portofantwerpbruges.com , log in using your testing credentials and follow flow B of the registration process;
If no, register your company at https://register-accpt.portofantwerpbruges.com and follow flow A of the registration process;
If you have no idea, follow flow C or contact the Customer Success Team, they will check it out for you;
The URL in the UAT environment is: https://crp-uat.nxtport.com;
If you go to the CPu UI in UAT, you are immediately directed to C-point login.
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 Authorization Server Host |
|
|
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 can be found in CPu, click on your name at the right top and click “Organisation Info”
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. Contact NxtPort support so they can create an API user for you.
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 theclient_idprovided in step 2.3;scope:openid.
Example of a PRD setup in Postman
Be sure to select the x-www-form-urlencoded format.
.png?inst-v=c37c5efa-6df4-463e-925d-c5d95c0bac59)
Oauth request PRD
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-Keyparameter. Contact support to receive your subscription key.include the access token in your call using a header parameter with key
Authorizationand valueBearer {{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
Authorization headers
2.5 IP addresses
Please note that shortly [date TBC], IP addresses change on PRD.
If applicable, the following IP addresses should be whitelisted:
UAT: 52.233.238.227 → discontinued from 27th of March 2024
PRD: 20.224.141.188 → discontinued from [date TBC]
New IP address whitelisting from 27th of March 2024 for UAT and [date TBC] for PRD:
Public IPs | Environment | Traffic Direction | Remarks |
|---|---|---|---|
13.94.136.122/32 | DEV | Inbound | |
23.97.142.110/32 | STG | Inbound | |
23.97.174.227/32 | UAT | Inbound | |
23.97.214.62/32 | PRD | Inbound | |
13.94.136.122/32 | DEV, STG, UAT, PRD | Outbound | All outbound ip addresses must be whitelisted by the customer, the firewall randomly selects one to select send traffic. This is a Limitation of Azure Firewall. |
3. Setup your notification channel
CPu mainly uses an asynchronous notification mechanism using HTTPS POST endpoints. These asynchronous API calls have the following behavior:
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
An error message when an error occurred, as defined in the API call specification (CPu notifications overview )
When integrating the use case with an API integration, this is an essential step in order to receive the required information.
The registration to the notification channel and the processing of the return calls is required.
Contact NxtPort support and provide them your notification channel url and security details so they can setup your notification channel.
What’s next?
Need any further assistance?