Terminal Operator Integration Guidelines
While all parties involved in the container import flow will be prompted to give release information, only two parties are considered to be “data providers”. These entities, being Shipping Agents and Terminal Operators, need to give their approval before a container can be picked up.
To participate in CPu as a Terminal Operator, you will need to follow the steps described below:
register and subscribe to Certified Pick up. You can find more information on this in the Getting Started with the API integration guide
Testing must be performed on User Acceptance Environment before moving to production
CPu requires you to provide the following actions / functions / transactions:
Discharge of a container
Gate in and Gate Out movements of the containers
Terminal Release confirmation
Please note that with CPu, the final responsibility to let a container leave the terminal will remain with the Terminal Operator.
The Terminal Operator can always overrule CPu and decide to release a blocked container.
This document describes how stakeholders of type Terminal Operator should integrate the CPu process within their applications.
Setting up your endpoint connection
To ensure our high security standards at NxtPort, we do not allow any anonymous API connection and we require of course a minimum set of security measures to be applied on any API connection. To that end, you will need to follow the steps below to set up the secure API connection with NxtPort.
You need to have completed the steps described on Getting Started with the API integration in order to proceed.
Asynchronous processing in CPu
To correctly integrate the set of API comprehended in the CPu application, it is important to be aware of the fact that CPu mainly works in an asynchronous fashion.
This means that you when making an API call, you will not get the result to your request in the response to your API call, but NxtPort will process your request and then send you a notification through the endpoint you have configured in the Getting Started process. To that end we advise you to pay quite close attention to the use of the Public Reference Id. This is the GUID you receive in the response of your API call.
This will allow you to keep track of the notifications in line with the request calls you have made.
When a API call returns a synchronous response, it is clearly marked in this guide.
Integration API calls
It is your responsibility to inform NxtPort in advance about which message type you’re using, as it requires a different setup on our end. You should have provided us this info during your onboarding as described on the Getting started with the API integration guide.
Integrating using EDIFACT messages
We strongly encourage you to integrate the CPu API with JSON messages instead of EDIFACT. If you wish to set up a connection with COARRI & CODECO messages, please contact support.
General remarks
Distinct request body fields
For different actions (submit, update, revoke etc.) you need to provide different actionType
values in the request body. These different fields are highlighted under distinct request body fields in the descriptions to help you use the correct ones.
URL’s provided are PRD
The request URL’s provided are for the PRD environment. For the UAT environment, replace api.nxtport.com
with api-uat.nxtport.com
. Important: both your API key and the your_ingestion_id
path variable are environment specific, so these also need to be changed if you call our UAT environment.
Release Lights
Submit Terminal Release
The Terminal Release cannot be sent to NxtPort through EDI messages. These can only be sent in either by API call or by using the User Interface.
Releases the container from the terminal yard, indicating that the container is ready to be picked up.
Will set the Terminal Release light to GREEN.
PUT https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/{{equipment_number}}/import/terminal-release
Request Headers:
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
port_locode
: UN/LoCode of the operational port (BEANR for Antwerp)equipment_number
: container number
Query Parameters:
N/A
Distinct request body fields
"actionType": "Release"
Request Body
{
"terminalCode": "",
"actionType": "Release",
"releaseDateTimeUtc": "",
"equipmentNumber": "",
"portLoCode": ""
}
portLoCode
: UN/LoCode of the operational port. BEANR for AntwerpequipmentNumber
: self-explanatoryreleaseDateTimeUtc
: ISO timestamp of action (in UTC)terminalCode
: your own terminal code, as provided to NxtPort during onboarding
Response & notifications
This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.
A successful request will generate a notification of type ReleaseLight
with action terminalRelease
that will be sent to
Your own notification channel and
Towards the Shipping agent
Towards the Release Right owner
To get the current state of a container, please refer to to the Get Release Detail section of this document.
Block Terminal Release
For as long as the container is not yet picked up, the terminal is able to block the container on the terminal. The container will still be present in the CPu backbone, but no Pick up right can be generated.
Will set the Terminal Release Light to RED.
PUT https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/{{equipment_number}}/import/terminal-release
Request Headers:
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
port_locode
: UN/LoCode of the operational port (BEANR for Antwerp)equipment_number
: container number
Query Parameters:
N/A
Distinct request body fields
"actionType": "Block"
Request Body
{
"terminalCode": "",
"actionType": "Block",
"equipmentNumber": "",
"portLoCode": ""
}
portLoCode
: UN/LoCode of the operational port. BEANR for AntwerpequipmentNumber
: self-explanatoryterminalCode
: your own terminal code, as provided to NxtPort during onboarding
Response & notifications
This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.
The endpoint for the update of the terminal release is identical to the one that is used when submitting a terminal release. Therefore, the responses will also be the same.
A successful request will generate a notification of type ReleaseLight
with action terminalBlocked
that will be sent to
Your own notification channel
Towards the Shipping agent
Towards the Release Right owner
Submit Terminal Discharge
Will set the Terminal Discharge light to GREEN, indicating either:
the container has been discharged from the vessel
the container has arrived on the terminal from another terminal (shift)
The old ingestion URL https://ingestion.nxtport.com/ingestion/{{your_ingestion_id}}
is still active, but will be disabled in the future. You will be informed well in advance when this happens.
POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}
Request Headers:
External-Reference-Id
(optional): your own referenceAuthorization
: authorization header (Bearer token)
Path Variables:
your_ingestion_id
: GUID; dedicated ID for your company. You should have received this ID from NxtPort Support during onboarding
Query Parameters:
N/A
Distinct request body fields
"operationType": "Discharge"
Request Body
{
"portLoCode": "",
"equipmentNumber": "",
"timestamp": "",
"terminalCode": "",
"operationType": "Discharge"
}
portLoCode
: UN/LoCode of the operational port. BEANR for AntwerpequipmentNumber
: self-explanatorytimestamp
: ISO timestamp of action (in UTC)terminalCode
: your own terminal code, as provided to NxtPort during onboarding
Response & notifications
This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.
Submit Terminal Gate Out
This action allows the terminal to register a gate out operation event for a container.
Will put the terminal gate out light to GREEN.
A Gate Out will FINALIZE the release and archive the container in the CPU system.
NOTE: NxtPort will process the Gate Out message as the FINAL step in the CPu process. Once the Gate Out is received, this will mark the container as being finalized and will “archive” it.
This means that if you have sent in a Gate Out for a container, this container will no longer be visible in the UI. This is also applicable in case the Gate Out message is received before any other transactions is received, meaning that for those containers where a Gate Out is received before a commercial release, there will be NO visibility on that release in CPu.
The old ingestion URL https://ingestion.nxtport.com/ingestion/{{your_ingestion_id}}
is still active, but will be disabled in the future. You will be informed well in advance when this happens.
POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}
Request Headers:
External-Reference-Id
(optional): your own referenceAuthorization
: authorization header (Bearer token)
Path Variables:
your_ingestion_id
: GUID; dedicated ID for your company. You should have received this ID from NxtPort Support during onboarding
Query Parameters:
N/A
Distinct request body fields
"operationType": "GateOut"
Request Body
{
"portLoCode": "",
"equipmentNumber": "",
"timestamp": "",
"terminalCode": "",
"operationType": "GateOut"
}
portLoCode
: UN/LoCode of the operational port. BEANR for AntwerpequipmentNumber
: self-explanatorytimestamp
: ISO timestamp of action (in UTC)terminalCode
: your own terminal code, as provided to NxtPort during onboarding
Response & notifications
This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.
Pick-up Right Validation
Asynchronous Pick-up validation truck
At any time, stakeholders that are allowed to see the information, can verify if an identification code (eg alfapass number) is allowed to pick-up a container. The response is sent in an asynchronous notification.
Using this call, you as a Terminal Operator can verify the status of any container and check if it can be picked up.
POST https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/validation/pickup/containers
Request Headers:
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
port_locode
: UN/LoCode of the operational port (BEANR for Antwerp)
Query Parameters:
N/A
Request Body
{
"portLoCode": "",
"alfapassNumber": "",
"releaseIdentification": [
{
"equipmentNumber": "",
"billOfLadingNumbers": [
"",
""
]
}
]
}
portLoCode
: the UN/Locode of the operational port. For Antwerp this is BEANRalfapassNumber
: self-explanatoryreleaseIdentification>equipmentNumber
: the container numberreleaseIdentification>billOfLadingNumbers
: array of Bill of Lading number(s) of the container
Response & notifications
This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.
Synchronous Pick-up validation truck
At any time, stakeholders that are allowed to see the information, can verify if an identification code (eg alfapass number) is allowed to pick-up a container. In this method, the requested information is returned in a synchronous response.
Using this call, you as a Terminal Operator can verify the status of any container and check if it can be picked up.
POST https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/sync-validation/pickup/containers
Request Headers:
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
port_locode
: UN/LoCode of the operational port (BEANR for Antwerp)
Query Parameters:
N/A
Request Body
{
"portLoCode": "",
"alfapassNumber": "",
"releaseIdentification": [
{
"equipmentNumber": "",
"billOfLadingNumbers": [
"",
""
]
}
]
}
portLoCode
: the UN/Locode of the operational port. For Antwerp this is BEANRalfapassNumber
: self-explanatoryreleaseIdentification>equipmentNumber
: the container numberreleaseIdentification>billOfLadingNumbers
: array of Bill of Lading number(s) of the container
Response & notifications
This is an synchronous call, you will get a direct API response:
Scenario | Response code + status | Explanation | Response body |
---|---|---|---|
Release valid - container ready for pick up | 200 - OK | This is the notification you will receive when a container is ready to be picked up. All Green Lights (except GateOperation, for the container has not left the terminal yet) are GREEN. |
JSON
|
Release not valid - container blocked | 200 - OK | Check the This array contains the status of all six Green Lights. See CPu variables overview | Green Light table for an overview of all possible statuses, their |
JSON
|
Error - unauthorized | 401 - Unauthorized | Your API key is not allowed to retrieve this data. Check if your API key is correct. |
JSON
|
Error - server error | 500 - Internal Server Error | Please ensure that you are using the correct endpoint. If this is the case, something is probably wrong at our side. Don’t worry, we are already notified, so you don’t have to take action. Check our statuspage for any possible downtime. The API could be temporarily out of service due to maintenance, incident, … Make sure you build in a retry mechanism on your end. |
CODE
|
Synchronous Pick-up validation barge & rail
At any time, stakeholders that are allowed to see the information, can verify if a barge or rail operator is allowed to pick-up a container. In this method, the requested information is returned in a synchronous response.
Using this call, you as a Terminal Operator can verify the status of any container and check if it can be picked up.
POST https://api.nxtport.com/certified-pickup/v2/{{port_locode}}/sync-validation/pickup/barge-rail/containers
Request Headers:
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyThis endpoint is v2, a new API key should be requested via https://nxtport.atlassian.net/servicedesk/customer/portal/9
Authorization
: authorization header (Bearer token)
Path Variables:
port_locode
: UN/LoCode of the operational port (“BEANR” for Antwerp)
Query Parameters:
N/A
Request Body
{
"equipmentNumber": "string",
"billOfLadingNumbers": [
"string"
],
"releaseId": "string",
"meansOfTransport": " use int value: 2 (Barge)",
"transportOperator": {
"identificationType": " use int value: 0 (NxtEntityId)",
"identificationCode": "string"
}
}
Mandatory values:
equipmentNumber
: the container numberbillOfLadingNumbers
: array of Bill of Lading number(s) of the container, this can be empty [ ] if no billOfLadingNumbers are known to the terminalmeansOfTransport
:“unknown”, or “truck”, or “barge”, or “rail”
or enum; use int value: “0” (Unknown), use int value: “1” (Truck), use int value: “2” (Barge) or use int value: “3” (Rail)
transportOperator
: identifier for the Transport OperatoridentificationType
: use int value: “0” (NxtEntityId), use int value: “1” (Tin), use int value: “2” (Eori), use int value: “3” (Duns), use int value: “4” (SCAC), use int value: “5” (Apcs), use int value: “6” (ExternalId)identificationCode
: identity value corresponding with identification type
Optional values:
releaseId:
the unique identifier for the release right. This release ID is communicated to you in the notifications you receive. NxtPort recommends using the releaseId so that a 1:1 match can be guaranteed.
Response & notifications
This is a synchronous call, you will get a direct API response:
Scenario | Response code + status | Explanation | Response body |
---|---|---|---|
Pickup valid - container ready for pick up | 200 - OK | This is the response you will receive when a container is ready to be picked up. The identity of the transport operator has been validated and is correct. The status of the container is “RELEASED”. All greenlights have color GREEN or YELLOW, in case of “FAVV” for example. GateOperation will be grey, until the container has left the terminal. See CPu variables overview | Green Light table for an overview of all possible statuses, their |
JSON
|
Pickup valid - container ready for pickup | 200 - OK | This is the response you will receive when a container is ready to be picked up to go to the scanner. The identity of the transport operator has been validated and is correct. The status of the container is “SELECTEDFORSCAN”. All greenlights have color GREEN or YELLOW, for Customs / TerminalReady lights. GateOperation will be grey, until the container has left the terminal. See CPu variables overview | Green Light table for an overview of all possible statuses, their |
JSON
|
Pickup not valid - container available | 200 - OK | See CPu variables overview | Green Light table for an overview of all possible statuses, their |
JSON
|
Pickup not valid - container blocked | 200 - OK | See CPu variables overview | Green Light table for an overview of all possible statuses, their |
JSON
|
Error - unauthorized | 401 - Unauthorized | Your API key is not allowed to retrieve this data. Check if your API key is correct. |
JSON
|
Error - server error | 500 - Internal Server Error | Please ensure that you are using the correct endpoint. If this is the case, something is probably wrong at our side. Don’t worry, we are already notified, so you don’t have to take action. Check our statuspage for any possible downtime. The API could be temporarily out of service due to maintenance, incident, … Make sure you build in a retry mechanism on your end. |
CODE
|
Validate Alfapass
This a synchronous call available to all CPu parties to verify if a provided Alfapass is valid or not.
The response will be a Boolean true or false.
GET https://api.nxtport.com/certified-pickup/v1/validation/pickup/identification
Request Headers:
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
N/A
Query Parameters:
N/A
Request Body
{
"identificationType": "Alfapass",
"identificationCode": ""
}
identificationType
: type of identification. Currently onlyalfapass
is allowed for the Port of AntwerpidentificationCode
: code linked to the identification (ie, the alfapass number)
Response & notifications
The synchronous response will be a Boolean true or false.
Validate Truck Release Right
Synchronous call
Validate if the queried Transport Operator holds the Release Right.
UPDATED with CPu version 2.19.0:
portLoCode
no longer mandatory in request bodyreleaseIdentification
object replaced byequipmentNumber
field ->releaseIdentification>billOfLadingNumbers
&releaseIdentification>releaseIdentification
no longer applicablenew possibilities for synchronous responses (added to table)
If both
ownerNxtEntityId
&alfapassNumber
(when provided) are invalid or unknown, the bodyerrorMessages
array will return multiple messages, detailing the relevant errors.The queried company
ownerNxtEntityId
must have the role of Transport Operator.
POST https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/validation/ownership/truck
Request Headers:
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
port_locode
: UN/LoCode of the operational port (BEANR for Antwerp)
Query Parameters:
N/A
Request Body
{
"portLoCode": "",
"ownerNxtEntityId": "",
"alfapassNumber": "",
"equipmentNumber": ""
}
portLoCode
: the UN/Locode of the operational port. For Antwerp this is BEANRownerNxtEntityId
(mandatory): NxtPort ID of the Transport Operator which needs to be validated. Only a Transport Operator ID can be usedalfapassNumber
: if entered, Alfapass number will also be validated. If this is omitted, validation will only occur on company levelequipmentNumber
(mandatory): self-explanatory
Response & notifications
This is an synchronous call, you will get a direct API response:
Response code | Response status | Response Body | Explanation |
---|---|---|---|
200 | OK |
JSON
| Queried company If |
200 | OK |
JSON
| Provided
|
200 | OK |
JSON
| Queried company |
200 | OK |
JSON
| Release Right is unknown, non-existing or no longer active. |
200 | OK |
JSON
| Release Right is assigned to different terminal by the Shipping Agent. |
200 | OK |
JSON
| Multiple release rights found, at least one is within given time window but OwnerEntityId does not match last stakeholder. |
200 | OK |
CODE
| Multiple Release Rights found for queried equipment number |
200 | OK |
JSON
| Self-explanatory |
200 | OK |
JSON
| Multiple release rights found, ALL outside time window. |
400 | Bad request |
JSON
| Bad request - malformed request body. Check the |
500 | Internal Server Error |
JSON
| Something went wrong. Check your request body. Possible causes:
|
Get Release Right detail as Terminal Operator
This API call will be made available with version 2.25. Keep an eye on https://documentation.nxtport.com/certified-pickup/release-notes or our Statuspage for when this release is expected.
This API call enables you to retrieve the details (including the Transport Operator identifiers, means of transport & Alfapass) of a Release Right of a container linked to your terminal.
GET https://api.nxtport.com/certified-pickup/v1/release-rights
Request Headers:
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
N/A
Query Parameters:
releaseId
: the unique identifier for the release right. This release ID is communicated to you in the notifications you receive.
Response & notifications
This is an synchronous call, you will get a direct API response (see below)
Synchronous responses
Response status | Response Body | Explanation |
---|---|---|
200 - OK |
JSON
| The releaseId you provided is valid, details of the Release Right are returned in the response body.
|
401 - Unauthorized | N/A | Role or scope forbids you from taking this action. Only Terminal Operators can perform this call |
403 - Forbidden | N/A | You are not allowed to fetch this resource. Check if the |
500 - Internal Server Error | N/A | Try again later. If the problem persists, contact NxtPort Support. |
Encryption of Alfapass number
In order to maximize security, the Alfapass number in the response body of the above call is encrypted.
In order for CPu to encrypt this, we will need to know your public key. You can share your public key using following call. The received public XML key will be stored in our database as a compressed string.
1. Generate a public and private RSA key pair
You can generate a key pair using attached executable.
SHA256 checksum: BD2E63F0E10E1A3395ABFE5D72B12F54C943BF552F62E37B034B342006F45D94
ConsoleRsaKey.runtimeconfig.zip
Download & unzip the zip file
Open the .exe file using a command prompt
Example output:

Public-private key generator output
The executable uses following codebase:
using System.Security.Cryptography;
string publicKey;
string privateKey;
using (var rsa = new RSACryptoServiceProvider())
{
// Get the public and private keys
publicKey = rsa.ToXmlString(false);
privateKey = rsa.ToXmlString(true);
}
Console.WriteLine("PRIVATE");
Console.WriteLine(privateKey);
Console.WriteLine("-----");
Console.WriteLine("PUBLIC");
Console.WriteLine(publicKey);
2. Submit the public key to NxtPort using the provided authenticated API
Important: it is your responsibility to maintain the corresponding private key at your end to decrypt the Alfapass number. If you lose this, you will need to submit a new public key to the CPu platform. All previously encrypted data will be rendered unusable if a new public key is received.
POST https://api.nxtport.com/certified-pickup/v1/pickup-rights/terminal/alfapassnumber/publickey
Request Headers:
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
N/A
Query Parameters:
N/A
Request body
{
"publicKey": "{{your_XML_Rsa_key_converted_to_base64_string}}"
}
Response
200 - OK
{
"errors": [
"string" // empty if all ok
],
"terminalNxtEntityId": "{{your_nxtport_id}}",
"publicKey": "{{your_compressed_public_key}}"
}
3. Use the private RSA key to decrypt the Alfapass number returned by the get Release Right Detail API
This needs to be implemented at your end, you can decrypt the Alfapass with the generated private key.
Generic Services
Get Release detail
At any time, stakeholders that are allowed to see the information, can retrieve the detail and greenlights of a specific container release.
This will trigger you to receive a notification on your predefined notification channel. Within you will receive the detail of the container with its corresponding greenlights.
GET https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/containers/import/release-rights/{{equipment_number}}?billOfLadingNumbers={{BL-numbers}}&releaseIdentification={{release-identification}}
Request Headers:
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
port_locode
: UN/LoCode of the operational port (BEANR for Antwerp)equipment_number
: container number
Query Parameters:
billOfLadingNumbers
releaseIdentification
Response & notifications
This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.
Company Registry
This a synchronous call available to all CPu parties, which allows for querying the NxtPort register for other existing CPu parties and their respective identification values.
At any time, stakeholders that are allowed to see the information, can retrieve the details of any CPu connected party.
GET https://api.nxtport.com/certified-pickup/v1/entities?<query-params>
Request Headers:
External-Reference-Id
(optional): your own reference (string)Ocp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
N/A
Query Parameters:
At least one of the optional query parameters needs to be provided, please keep in mind that providing multiple optional parameters at once combines the filters with an AND expression.
EORI
(optional) : an entity with matching EORI will be queried in our register;DUNS
(optional) : an entity with matching DUNS will be queried in our register;VAT
(optional) : an entity with matching VAT will be queried in our register;entityName
(optional) : an entity with a (partially) matching name will be queried in our register;apcsCode
(optional) : an entity with matching APCS code will be queried in our register;page
(default to 1) : determine which page of the results is queried;pageSize
(default to 25) : determine the page size of the queried results.
Response & notifications
This is an synchronous call, you will get a direct API response (see below)
Synchronous Responses
Response code | Response status | Response body | Response body fields | Action to take |
---|---|---|---|---|
200 | OK |
JSON
|
| N/A - all is good |
400 | Bad Request |
JSON
| N/A | Check the If you would run into any issues and not find the solution, please contact our Customer Success Team |
401 | Unauthorized - role or scope forbids you from taking this action |
JSON
| N/A - fields have no meaning when 401 is returned |
If you would run into any issues and not find the solution, please contact our Customer Success Team |
405 | Method not allowed |
JSON
| N/A - fields have no meaning when 401 is returned |
if you would run into any issues and not find the solution, please contact our Customer Success Team |
500 | Internal Server Error | N/A | N/A | CPu API not accessible - check our statuspage to see if there is any downtime and try again later |
Notification Service 1.0 (deprecated)
This version of the notification service will be retired with CPu release 2.25 . Please use version 2.0 (see below).
This API call allows you to retrieve the notification(s) sent to your notification channel by CPu. You will need either the equipment number OR the Public Reference ID OR the External Reference ID. Values can be combined.
Notifications can be retrieved up to 168 hours in the past from the time of your request (e.g. on 08 April at 13h00 you can retrieve all notifications dating from 01 April 13h00 onwards).
POST https://api.nxtport.com/certified-pickup/v1/notifications/query
Request Headers:
Ocp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path Variables:
N/A
Query Parameters:
N/A
Request Body
{
"equipmentNumber": "",
"publicReferenceId": "",
"externalReferenceId": ""
}
If you don’t supply all 3 identifiers, other values must be null
equipmentNumber
: self-explanatory;publicReferenceId
: the Public Reference ID you received in the synchronous API response;externalReferenceId
: the External Reference ID you supplied in your call.
Response & notifications
This is an synchronous call, you will get a direct API response:
Response code | Response status | Response body | Remarks |
---|---|---|---|
200 | OK |
JSON
|
|
200 | OK |
JSON
| The provided data is unknown in our system. Check your request body for any errors. |
401 | Unauthorized |
JSON
| Your API key is not allowed to retrieve this data. Check if your API key is correct. |
401
| Unauthorized Response header:
|
JSON
| The notification you requested was not sent to your company. Check the request body for any errors. |
500 | Internal Server Error |
JSON
| Please ensure that you are using the correct endpoints (eg fill in the {portLocode} variable in the URL). If this is the case, something is probably wrong at our side. Don’t worry, we are already notified, so you don’t have to take action. Check our statuspage for any possible downtime. The API could be temporarily out of service due to maintenance, incident, … Make sure you build in a retry mechanism on your end. |
Notification Service 2.0
This API call will be made available with CPu release 2.25. Check Release notes or our statuspage for when this release is expected.
This API call allows you to retrieve notifications sent to your company.
Notifications can be retrieved up to 168 hours in the past from the time of your request (e.g. on 08 April at 13h00 you can retrieve all notifications dating from 01 April 13h00 onwards).
GET https://api.nxtport.com/certified-pickup/v1/notifications
Request Headers
External-Reference-Id
(optional): your own referenceOcp-Apim-Subscription-Key
: your API keyAuthorization
: authorization header (Bearer token)
Path variables
N/A
Query Parameters
At least 1 parameter is needed, multiple parameters will be queried using an AND operator.
notificationEvent
: event of the corresponding notification
equipmentNumber
: self-explanatorypublicReferenceId
: GUID you received in the synchronous responsereleaseId
: ID (GUID) of the Release Right, returned in the notificationsstoredOn
: ISO timestamp of creation date/time of the notification
Responses
Status | Body | Explanation |
---|---|---|
200 - Success |
JSON
|
|
401 - Unauthorized |
JSON
| Missing API key or authorization token |
403 - Forbidden Response header:
|
CODE
| The notification you requested was not sent to your company, you are not allowed to view the contents |
405 - Invalid Input | N/A | No matching notifications found, check your query parameters |
500 - Internal Server Error |
JSON
| Please ensure that you are using the correct endpoint. If this is the case, something is probably wrong at our side. Don’t worry, we are already notified, so you don’t have to take action. Check our statuspage for any possible downtime. The API could be temporarily out of service due to maintenance, incident, … Make sure you build in a retry mechanism on your end. |
Additional information
Direct API responses to asynchronous calls
This overview contains the direct responses you might receive to the asynchronous calls.
Response code | Response status | Response body | What to do? |
---|---|---|---|
200 | OK |
JSON
| Nothing, all is good - the information you sent in has been received and will be processed. Any response will be provided through a notification with corresponding public reference id. |
202 | Accepted |
JSON
| Nothing, all is good - the information you sent in has been received and will be processed. Any response will be provided through a notification with corresponding public reference id. |
400 | Bad Request | Example if
JSON
| Review the request you have sent for syntax errors or conditions for the API call. |
401 | Unauthorized | N/A | You are not authorized to make that API call - this could be either because it is not available for your roll or because you are not allowed due to another CPU specific condition not being met (eg. the release right is not assigned to you… ). Please check if you:
|
500 | Internal Server Error | N/A | Please ensure that you are using the correct endpoint. If this is the case, something is probably wrong at our side. Don’t worry, we are already notified, so you don’t have to take action. Check our statuspage for any possible downtime. The API could be temporarily out of service due to maintenance, incident, … Make sure you build in a retry mechanism on your end. |
Notifications
As explained about the asynchronous handling within the CPu process, you - as a Terminal Operator - will receive various notifications.
Some of these will be asynchronous responses to calls you have submitted, some will be notifications triggered by actions performed by other parties in the release process.
You will find detailed information tailored to your role in CPu on Notifications for Terminal Operators .
Need any further assistance?