Notifications for Terminal Operators

This page will guide you through the notifications you - as a Terminal Operator - might receive in Certified Pick up (CPu). We will guide you through the different types of notifications and what to do with them.

For Terminal Operators, there are two types of CPu notifications:

Validation responses: asynchronous responses sent to your notification channel after you have sent a validation request to the CPu API.
Release Light events: events which relate to the Release Lights of the container (Terminal release, Customs release, Commercial release - released, blocked etc.).

For each type there is an example for display purposes. Click the expand to see the full notification.

The notification schemes also contain CPu variables (between double curly braces {{}}) which are different for each notification you will receive. An overview & explanation of these CPu variables can be found on this page CPu variables overview .

Implementation of the notifications also requires you to have read Getting Started with the API integration !

Important: you need to have set up a notification channel for your company in order to receive and process these notifications. See https://documentation.nxtport.com/certified-pickup/getting-started-with-the-api-integration#GettingStartedwiththeAPIintegration-3.Setupyournotificationchannel if you have not done so already.

Notifications - generic fields

Every notification that is sent by NxtPort will be built up with a generic part, allowing integrators to identify the asset, sender, error or warning messages and a Use case or type specific body.

Field Name	Type	Allowed values	Field Description
assetId	string	Contains the name or ID of the asset	For CPu, the assetId (NxtPort identification number) is used and contains the value `00000000-0000-0001-0000-000000000037`
id	string	The unique ID linked to the notification	For CPu, the container number is included in this field.
PublicReferenceId	guid		Automatically generated GUID from NxtPort. This is a unique ID throughout our platform. In case of questions, please provide this ID, allowing us to clearly retrieve the corresponding information.
externalReferenceId	string		Your own reference, as provided in the request header (optional). Will be null in case the notification was triggered by another party.
senderId	string	NxtPort ID	The NxtPort ID of the owner that generated the notification. If a 3rd party triggered the event, this information will still be the owner of the original source that will be listed here.
receiverId	string	NxtPort ID	This should always be your NxtPort ID as you are the receiver of this message.
type	enumeration	releaseRight releaseLight pickUp terminalEvent	Depending on the notification, one of these values will be used. Within the NxtPort Console, you can use these type to filter out notifications to multiple channels.
event	enumeration	Multiple values allowed	Values will define the body of the notification and is explained further on in this document.
body	N/A	N/A	Contains the event specific body related to this notification. This body is included in the details of the notifications and described later on in this document.
timestamp	DateTime	UTC datetime	The timestamp when the notification was created by the Certified Pick-up platform. This will always be in UTC ISO 8601 format.
errors	Array	free text	These arrays are not used in CPu notifications. The error message can be found in the body of the notification.
warnings	Array	free text	These arrays are not used in CPu notifications. The warning message can be found in the body of the notification.

Notifications list

Responses

As stated previously, CPu is an asynchronous process (with some exceptions), meaning that when data is sent to the API, NxtPort will first receive and ‘store’ the data and then in a separate process will process the action in a CPu context. This means however, that not all errors or issues can be reported in a synchronous API response and that you will need to integrate the notifications you receive to make sure all data you provide is processed correctly.

Response notifications are asynchronous responses sent to your notification channel after you have sent a request tot the CPu API. These notifications indicate an error and are characterized by the "event": "NotValidated" field in the JSON body.

There is a problem with the action you performed for a Commercial Release. The error message is included in the "body" field, all possible messages are listed below, including the mitigation steps.

Notification	Explanation	How to mitigate?	Notification Body
Multiple releases	If multiple identical ACTIVE release rights are detected in CPu when processing a message (for example Terminal Discharge), these messages will not be linked and feedback will be sent via notifications to the relevant entity sending the message. Identifiers used for detecting a “double” release right depend on the message that is being processed. In case of Terminal Discharge this is Equipment Number, Terminal Code and Stay Number.	Check with Ship Agent that should delete the double releases.	CODE `{ "assetId": "00000000-0000-0001-0000-000000000037", "body": "Could not apply to single release right. Please provide keys that uniquely match the correct release right.", "errors": [], "event": "NotValidated", "externalReferenceId": "{{external_reference_id}}", "id": "{{equipment_number}}", "publicReferenceId": "{{nxtport_public_reference_id}}", "receiverId": "{{your_nxtport_id}}", "senderId": {{sender_nxtport_id}}, "timestamp": "{{ISO_timestamp}}", "type": "ReleaseRight", "warnings": [] }`

Release Light events

Event notifications are notifications sent to your notification channel when an event occurs on a Release Right for which you are a stakeholder.

Please find the full list of events: https://documentation.nxtport.com/certified-pickup/cpu-notifications-overview#CPunotificationsoverview-%E2%80%9Ctype%E2%80%9D:%E2%80%9CReleaseLight%E2%80%9D

You have reached the end of the page. Go back to the integration guidelines.

Notifications - generic fields

Notifications list

Responses

Multiple releases

Release Light events