Skip to main content
Skip table of contents

Terminal Operator Integration Specifications

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.

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

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 reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: 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

JSON
{
  "equipmentNumber": "string",
  "portLoCode": "string",
  "terminalCode": "string",
  "actionType": "Release",
  "releaseDateTimeUtc": "2023-12-20T08:14:31.123Z",
  "stayNumber": "string"
}
  • portLoCode: UN/LoCode of the operational port. “BEANR” for Antwerp

  • equipmentNumber: self-explanatory

  • releaseDateTimeUtc: ISO timestamp of action (in UTC)

  • terminalCode: your own terminal code, as provided to NxtPort during onboarding

  • stayNumber: unique number for “stay” of the sea vessel, assigned by the Port Authority (optional)

It is strongly recommended to provide stay number so that a 1:1 link can be made with a commercial release.

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 it will not be possible to pickup the container.

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 reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: 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

JSON
{
  "equipmentNumber": "string",
  "portLoCode": "string",
  "terminalCode": "string",
  "actionType": "Block",
  "releaseDateTimeUtc": "2023-12-20T08:14:31.123Z",
  "stayNumber": "string"
}
  • portLoCode: UN/LoCode of the operational port. “BEANR” for Antwerp

  • equipmentNumber: self-explanatory

  • releaseDateTimeUtc: ISO timestamp of action (in UTC)

  • terminalCode: your own terminal code, as provided to NxtPort during onboarding

  • stayNumber: unique number for “stay” of the sea vessel, assigned by the Port Authority (optional)

It is strongly recommended to provide stay number so that a 1:1 link can be made with a commercial release.

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 with value “DISCHARGED”, indicating:

  • the container has been discharged from the vessel

POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}

Request Headers:

  • External-Reference-Id (optional): your own reference

  • Authorization: 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

JSON
{
     "portLoCode": "",
     "equipmentNumber": "",
     "equipmentStatus": "import",
     "timestamp": "",
     "terminalCode": "",
     "stayNumber": "",
     "operationType": "Discharge",
     "fullEmptyIndicator": ""
}
  • portLoCode: UN/LoCode of the operational port. BEANR for Antwerp

  • equipmentNumber: self-explanatory

  • equipmentStatus: for import containers please indicate with “import" (optional)

  • timestamp: ISO timestamp of action (in UTC)

  • terminalCode: your own terminal code, as provided to NxtPort during onboarding

  • stayNumber: unique number for “stay” of the sea vessel, assigned by the Port Authority (optional)

  • fullEmptyIndicator: indication whether the container is “full" or "empty", for an empty container the Customs light value will be set to "NOTAPPLICABLE" with color “ORANGE" (optional)

It is strongly recommended to provide stay number so that a 1:1 link can be made with a commercial release.

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 In

Will set the Terminal Discharge light to GREEN with value “GATEIN”, indicating:

  • the container has arrived on the terminal from another deep sea terminal (shift / gate in)

POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}

Request Headers:

  • External-Reference-Id (optional): your own reference

  • Authorization: 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": "GateIn"

Request Body

CODE
{
     "portLoCode": "",
     "equipmentNumber": "",
     "equipmentStatus": "import",
     "timestamp": "",
     "terminalCode": "",
     "stayNumber": "",
     "operationType": "GateIn",
     "fullEmptyIndicator": ""
}
  • portLoCode: UN/LoCode of the operational port. BEANR for Antwerp

  • equipmentNumber: self-explanatory

  • equipmentStatus: for import containers please indicate with “import", this will set the Customs light to "PORTEQUALISATION" with color "YELLOW" (optional)

  • timestamp: ISO timestamp of action (in UTC)

  • terminalCode: your own terminal code, as provided to NxtPort during onboarding

  • stayNumber: unique number for “stay” of the sea vessel, assigned by the Port Authority (optional)

  • fullEmptyIndicator: indication whether the container is “full" or "empty", for an empty container the Customs light value will be set to "NOTAPPLICABLE" with color “ORANGE" (optional)

It is strongly recommended to provide stay number so that a 1:1 link can be made with a commercial release.

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.

POST https://api.nxtport.com/ingestion/v1/ingestion/{{your_ingestion_id}}

Request Headers:

  • External-Reference-Id (optional): your own reference

  • Authorization: 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

JSON
{
     "portLoCode": "",
     "equipmentNumber": "",
     "timestamp": "",
     "terminalCode": "",
     "stayNumber": "",
     "operationType": "GateOut"
}
  • portLoCode: UN/LoCode of the operational port. BEANR for Antwerp

  • equipmentNumber: self-explanatory

  • timestamp: ISO timestamp of action (in UTC)

  • terminalCode: your own terminal code, as provided to NxtPort during onboarding

  • stayNumber: unique number for “stay” of the sea vessel, assigned by the Port Authority (optional)

It is strongly recommended to provide stay number so that a 1:1 link can be made with a commercial release.

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

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.

  • This endpoint is the unique reference to the final release decision

POST https://api.nxtport.com/certified-pickup/v1/{{port_locode}}/sync-validation/pickup/containers

Request Headers:

  • External-Reference-Id (optional): your own reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: authorization header (Bearer token)

Path Variables:

  • port_locode: UN/LoCode of the operational port (BEANR for Antwerp)

Query Parameters:

N/A

Request Body

JSON
{
  "alfapassNumber": "string",
  "releaseIdentification": [
    {
      "equipmentNumber": "string",
      "billOfLadingNumbers": [
        "string"
      ],
      "carrier": {
        "identificationType": " use int value: 0 (NxtEntityId)",
        "identificationCode": "string"
      }
    }
  ]
}
  • alfapassNumber: self-explanatory

  • releaseIdentification>equipmentNumber: the container number

  • releaseIdentification>billOfLadingNumbers: array of Bill of Lading number(s) of the container

  • releaseIdentification>carrier: identity of the carrier

    • releaseIdentification>carrier>identificationType: 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)

    • releaseIdentification>carrier>identificationCode: identity value corresponding with identification type

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 response you will receive when a container is ready to be picked up.

The Alfapass has been validated and is correct.

The status of the container is “RELEASED”. All greenlights have color GREEN.

See CPu variables overview | Green Light table for an overview of all possible statuses, their name, value & color and explanation.

JSON
{
    "alfapassNumber": "{{provided_alfapass_number}}",
    "releaseIdentification": [
        {
            "isValid": true,
            "errorMessages": null,
            "status": "RELEASED",
            "greenLights": [
                {
                    "greenLightName": "CommercialRelease",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "TerminalOperation",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "TerminalReady",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "Customs",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "CustomsProgress",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "GateOperation",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "PickupLight",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                }
            ],
            "equipmentNumber": "{{equipment_number}}",
            "billOfLadingNumbers": [
                "{{bl_number}}",
                "{{bl_number}}"
            ]
        }
    ]
}

Release valid - container ready for pick up

200 - OK

This is the response you will receive when a container is ready to be picked up with some condition.

The Alfapass has been validated and is correct.

The status of the container is “SELECTEDFORSCAN”, “FAVV”, “TRANSHIPMENT” or “PORTEQUALISATION”. All greenlights have color GREEN or YELLOW. 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 name, value & color and explanation.

JSON
{
    "alfapassNumber": "{{provided_alfapass_number}}",
    "releaseIdentification": [
        {
            "isValid": true,
            "errorMessages": null,
            "status": "SELECTEDFORSCAN",
            "greenLights": [
                {
                    "greenLightName": "CommercialRelease",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "TerminalOperation",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "TerminalReady",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "Customs",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "CustomsProgress",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "GateOperation",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "PickupLight",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                }
            ],
            "equipmentNumber": "{{equipment_number}}",
            "billOfLadingNumbers": [
                "{{bl_number}}",
                "{{bl_number}}"
            ]
        }
    ]
}

Release not valid - container blocked

200 - OK

This is the response you will receive when a container can not be picked up since the Alfapass is incorrect and/or since at least 1 Greenlight is RED.

Check the releaseIdentification.greenLights array to see which Light is still blocking.

This array contains the status of all Green Lights. See CPu variables overview | Green Light table for an overview of all possible statuses, their name, value & color and explanation.

Possible errorMessages

null when one of the Green Lights is “red”, this can be a reason for the pickup to be invalid

"Alfapass validation error: Pickup not allowed" when the container can’t be picked up with the provided Alfapass

"Alfapass validation error: No release right found" when there’s no release right in CPu for the provided releaseIdentification identifier(s)

"Pickup validation error: Could not find carrier for <NxtEntityId>" No carrier known in CPu with previously mentioned identifier

JSON
{
    "alfapassNumber": "{{provided_alfapass_number}}",
    "releaseIdentification": [
        {
            "isValid": false,
            "errorMessages": null,
            "status": "BLOCKED",
            "greenLights": [
                {
                    "greenLightName": "CommercialRelease",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "TerminalOperation",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "TerminalReady",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "Customs",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "CustomsProgress",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "GateOperation",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "PickupLight",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                }
            ],
            "equipmentNumber": "{{equipment_number}}",
            "billOfLadingNumbers": [
                "{{bl_number}}",
                "{{bl_number}}"
            ]
        }
    ]
}

Error - unauthorized

401 - Unauthorized

Your API key is not allowed to retrieve this data. Check if your API key is correct.

JSON
{
    "statusCode": 401,
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

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
{
    "identifier": "",
    "error": "An unexpected error has occured, please try again later. If the problem persists, please contact NxtPort Support.",
    "extraInfo": null
}

Error - too many requests

429 - Too Many Requests

You sent too many requests. We don’t accept more than 500 calls per minute.

N/A


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:

Path Variables:

  • port_locode: UN/LoCode of the operational port (“BEANR” for Antwerp)

Query Parameters:

N/A

Request Body

JSON
{
  "equipmentNumber": "string",
  "billOfLadingNumbers": [
    "string"
  ],
  "releaseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "meansOfTransport": " use int value: 0 (Unknown)",
  "transportOperator": {
    "identificationType": " use int value: 0 (NxtEntityId)",
    "identificationCode": "string"
  },
  "carrier": {
    "identificationType": " use int value: 0 (NxtEntityId)",
    "identificationCode": "string"
  }
}
  • Mandatory values:

    • equipmentNumber: the container number

    • billOfLadingNumbers: array of Bill of Lading number(s) of the container, this can be empty [ ] if no billOfLadingNumbers are known to the terminal

    • meansOfTransport:

      • “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 Operator

      • identificationType: 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.

    • carrier: identity of the carrier

      • identificationType: 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

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.

See CPu variables overview | Green Light table for an overview of all possible statuses, their name, value & color and explanation.

JSON
{
  "isValid": true,
  "errorMessages": "",
  "status": "RELEASED",
  "greenLights": [
    {
      "greenLightName": "CommercialRelease",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "TerminalOperation",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "TerminalReady",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "Customs",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "CustomsProgress",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "GateOperation",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "PickupLight",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    }
  ],
  "releaseId": "{{release_id}}",
  "equipmentNumber": "{{equipment_number}}",
  "billOfLadingNumbers": [
    "{{bl_number}}",
    "{{bl_number}}"
  ]
}

Pickup valid - container ready for pickup

200 - OK

This is the response you will receive when a container is ready to be picked up with some condition.

The identity of the transport operator has been validated and is correct.

The status of the container is “SELECTEDFORSCAN”, “FAVV”, “TRANSHIPMENT” or “PORTEQUALISATION”. All greenlights have color GREEN or YELLOW. 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 name, value & color and explanation.

JSON
{
  "isValid": true,
  "errorMessages": "",
  "status": "SELECTEDFORSCAN",
  "greenLights": [
    {
      "greenLightName": "CommercialRelease",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "TerminalOperation",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "TerminalReady",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "Customs",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "CustomsProgress",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "GateOperation",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "PickupLight",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    }
  ],
  "releaseId": "{{release_id}}",
  "equipmentNumber": "{{equipment_number}}",
  "billOfLadingNumbers": [
    "{{bl_number}}",
    "{{bl_number}}"
  ]
}

Pickup not valid - container available

200 - OK

This is the response you will receive when a container can not be picked up since the identity of the transport operator is incorrect.

The status of the container is “RELEASED” when all greenlights have color GREEN.

The status of the container is “SELECTEDFORSCAN”, “FAVV”, “TRANSHIPMENT” or “PORTEQUALISATION” when all greenlights have color GREEN or YELLOW.

See CPu variables overview | Green Light table for an overview of all possible statuses, their name, value & color and explanation.

Possible errorMessages

"Pickup validation error: Could not find transport operator for NXT2100005784"

"Pickup validation error: Invalid pickup right owner for transport operator <NxtEntityId> and release right with id <releaseId>"

"Pickup validation error: Pickup not allowed for transport operator"

"Pickup validation error: No release right found"

"Pickup validation error: Could not find carrier for <NxtEntityId>" No carrier known in CPu with previously mentioned identifier

JSON
{
  "isValid": false,
  "errorMessages": "<see possible errorMessages>",
  "status": "RELEASED" 
  "greenLights": [
    {
      "greenLightName": "CommercialRelease",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "TerminalOperation",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "TerminalReady",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "Customs",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "CustomsProgress",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "GateOperation",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "PickupLight",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    }
  ],
  "releaseId": "{{release_id}}",
  "equipmentNumber": "{{equipment_number}}",
  "billOfLadingNumbers": [
    "{{bl_number}}",
    "{{bl_number}}"
  ]
}

Pickup not valid - container blocked

200 - OK

This is the response you will receive when a container can not be picked up since the identity of the transport operator is incorrect and/or the status of the container is “BLOCKED” since at least 1 Greenlight is RED.

See CPu variables overview | Green Light table for an overview of all possible statuses, their name, value & color and explanation.

Possible errorMessages

null when one of the Green Lights is “red”, this can be a reason for the pickup to be invalid.

"Pickup validation error: Could not find transport operator for NXT2100005784"

"Pickup validation error: Invalid pickup right owner for transport operator <NxtEntityId> and release right with id <releaseId>"

"Pickup validation error: Pickup not allowed for transport operator"

"Pickup validation error: No release right found"

"Pickup validation error: Could not find carrier for <NxtEntityId>" No carrier known in CPu with previously mentioned identifier

JSON
{
  "isValid": false,
  "errorMessages": "<see possible errorMessages>",
  "status": "BLOCKED" 
  "greenLights": [
    {
      "greenLightName": "CommercialRelease",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "TerminalOperation",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "TerminalReady",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "Customs",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "CustomsProgress",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "GateOperation",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    },
    {
      "greenLightName": "PickupLight",
      "greenLightValue": "<see Green Light table>",
      "greenLightColor": "<see Green Light table>"
    }
  ],
  "releaseId": "{{release_id}}",
  "equipmentNumber": "{{equipment_number}}",
  "billOfLadingNumbers": [
    "{{bl_number}}",
    "{{bl_number}}"
  ]
}

Error - unauthorized

401 - Unauthorized

Your API key is not allowed to retrieve this data. Check if your API key is correct.

JSON
{
    "statusCode": 401,
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

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
{
    "PublicReferenceId": "2a8f053a-864f-451f-bd22-c7061fc63e8d",
    "HttpStatusCode": 500,
    "Message": "An unexpected error has occured, please try again later. If the problem persists, please contact NxtPort Support."
}

Error - too many requests

429 - Too Many Requests

You sent too many requests. We don’t accept more than 500 calls per minute.

N/A

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 reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: authorization header (Bearer token)

Path Variables:

N/A

Query Parameters:

N/A

Request Body

JSON
{
  "identificationType": "Alfapass",
  "identificationCode": ""
}
  • identificationType: type of identification. Currently only alfapass is allowed for the Port of Antwerp

  • identificationCode: 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.

  • If both ownerNxtEntityId & alfapassNumber (when provided) are invalid or unknown, the body errorMessages 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 reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: authorization header (Bearer token)

Path Variables:

  • port_locode: UN/LoCode of the operational port (BEANR for Antwerp)

Query Parameters:

N/A

Request Body

JSON
{
    "portLoCode": "",
    "ownerNxtEntityId": "",
    "alfapassNumber": "",
    "equipmentNumber": ""
}
  • portLoCode: the UN/Locode of the operational port. For Antwerp this is BEANR

  • ownerNxtEntityId (mandatory): NxtPort ID of the Transport Operator which needs to be validated. Only a Transport Operator ID can be used

  • alfapassNumber: if entered, Alfapass number will also be validated. If this is omitted, validation will only occur on company level

  • equipmentNumber (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
{
    "isValid: true,
    "errorMessages": []
}

Queried company ownerNxtEntityId is the current owner of the Release Right.

If alfapassNumber was provided: container has been assigned correctly.

200

OK

JSON
{
    "isValid: false,
    "errorMessages": [
        "Alfapass validation error: Unknown alfapass"
    ]
}

Provided alfapassNumber is incorrect:

  • Unknown: no Alfapass assigned to this release.

200

OK

JSON
{
    "isValid": false,
    "errorMessages": [
        "Entity not found"
    ]
}

Queried company ownerNxtEntityId is not current owner of the Release Right.

200

OK

JSON
{
    "isValid": false,
    "errorMessages": [      
        "Release not found"
    ]
}

Release Right is unknown, non-existing or no longer active.

200

OK

JSON
{
    "isValid": false,
    "errorMessages": [
        "Release is assigned to a different terminal"
    ]
}

Release Right is assigned to different terminal by the Shipping Agent.

200

OK

JSON
{
    "isValid": false,
    "errorMessages": [
        "Multiple release rights found",
        "Entity not found"
    ]
}

Multiple release rights found, at least one is within given time window but OwnerEntityId does not match last stakeholder.

200

OK

CODE
{
    "isValid": false,
    "errorMessages": [
        "Multiple release rights found"
    ]
}

Multiple Release Rights found for queried equipment number

200

OK

JSON
{
    "isValid": false,
    "errorMessages": [   
        "No release rights found within respected time window of 14 days"
    ]
}

Self-explanatory

200

OK

JSON
{
    "isValid": false,
    "errorMessages": [
        "Multiple release rights found",
        "No release rights found within respected time window of 14 days"
    ]
}

Multiple release rights found, ALL outside time window.

400

Bad request

JSON
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "GUID",
    "errors": {
        "OwnerNxtEntityId": [
            "'Owner Nxt Entity Id' must not be empty."
        ]
    }
}

Bad request - malformed request body. Check the errors object for details (here: ownerNxtEntityId was omitted).

500

Internal Server Error

JSON
{
    "identifier": "GUID",
    "error": "An unexpected error has occured, please try again later. If the problem persists, please contact NxtPort Support.",
    "extraInfo": null
}

Something went wrong. Check your request body. Possible causes:

  • Missing field(s) in request body;

  • ownerNxtEntityId is not a valid NxtPort ID ("NXT" + 11 numbers).

429

Too Many Requests

N/A

You sent too many requests. We don’t accept more than 500 calls per minute.


Get Release Right Details as Terminal Operator

Returns the greenlights and pick-up information. This endpoint can be used for fallback procedures. Please contact the NxtPort Support desk for more information.


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 reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization: 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 key

  • Authorization: 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;

  • NxtEntityId (optional) : an entity with matching NxtEntityId 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
{
  "searchFilter": {
    "eori": "string",
    "duns": "string",
    "vat": "string",
    "entityName": "string",
    "apcsCode": "string",
    "page": 1,
    "pageSize": 25
  },
  "phoneBookItems": [
    {
      "apcsCode": "string",
      "addresses": [
        {
          "addressTypeCode": "string",
          "street": "string",
          "postalCode": "string",
          "city": "string",
          "country": "string",
          "contactName": "string",
          "contactEmail": "string"
        }
      ],
      "nxtEntityId": "string",
      "name": "string",
      "vat": "string",
      "duns": "string",
      "eori": "string",
      "scac": "string",
      "apcs": "string"
    }
  ],
  "totalRows": 0,
  "totalPages": 0,
  "publicReferenceId": "string",
  "externalReferenceId": "string"
}

searchfilter: values you entered in the call, other values will be null;

  • eori: self-explanatory;

  • duns: Data Universal Numbering System (not always known);

  • vat: self-explanatory;

  • entityName: self-explanatory;

  • apcsCode: self-explanatory;

  • page: 1 (default)

  • pageSize: 25 (default)

phoneBookItems (returned values of requested company)

  • apcsCode: self-explanatory;

  • addresses

    • addressTypeCode: 1 for main address, 2 for billing address;

    • street: self-explanatory;

    • postalCode: self-explanatory;

    • city: self-explanatory;

    • country: self-explanatory;

    • contactName: self-explanatory;

    • contactEmail: self-explanatory;

  • nxtentityid: self-explanatory;

  • name: self-explanatory;

  • vat: self-explanatory;

  • duns: Data Universal Numbering System (not always known);

  • eori: self-explanatory;

  • scac: if applicable;

  • apcs: self-explanatory;

totalRows: self-explanatory;

totalPages: self-explanatory;

publicReferenceId: GUID generated by NxtPort to identify the call;

externalReferenceId: optional id you provided in request.

N/A - all is good

400

Bad Request

JSON
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-1fa221c60594f6428678fd0fe54140a8-d1aecb5a9485b64d-00",
    "errors": {
        "Page": [
            "'Page' must be greater than or equal to '1'."
        ]
    }
}

N/A

Check the errors field for the error message

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
{
  "type": "string",
  "title": "string",
  "status": 401,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}

N/A - fields have no meaning when 401 is returned

  • Check your credentials

  • Make sure you have a role assigned to your entity

If you would run into any issues and not find the solution, please contact our Customer Success Team

405

Method not allowed

JSON
{
  "type": "string",
  "title": "string",
  "status": 405,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}

N/A - fields have no meaning when 401 is returned

  • check the call you made and make sure you have entered valid information

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

429

Too Many Requests

N/A

N/A

You sent too many requests. We don’t accept more than 500 calls per minute.


Notification Service

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

  • This endpoint is the unique reference to the final release decision

The timeWindowFrom and timeWindowTo query parameters will be available starting from version 3.11.0 of the API.

GET https://api.nxtport.com/certified-pickup/v1/notifications

Request Headers

  • External-Reference-Id (optional): your own reference

  • Ocp-Apim-Subscription-Key: your API key

  • Authorization : 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

notificationEvent - enum
  • NotValidated

  • Transferred

  • AcceptedByNextParty

  • DeclinedByNextParty

  • RevokedByPreviousParty

  • ReleaseLightChanged

  • Update

  • GateOut

  • equipmentNumber: self-explanatory

  • publicReferenceId: GUID you received in the synchronous response

  • releaseId: ID (GUID) of the Release Right, returned in the notifications

  • storedOn: ISO timestamp of creation date/time of the notification

  • timeWindowFrom (optional): The starting time of the window for filtering notifications. Expects a time in ISO format (“07:30”).

  • timeWindowTo (optional): The ending time of the window for filtering notifications. Expects a time in ISO format (“19:25”).

Note: The timeWindowFrom and timeWindowTo parameters allow for a more precise filtering of notifications within a specified time range on the date provided in storedOn. Both parameters should be used together to define the start and end of the desired time window. The timeWindowTo may not be earlier than timeWindowFrom.

Responses

Status

Body

Explanation

200 - Success

JSON
[
  {
    "nxtEntityId": "string",
    "equipmentNumber": "string",
    "publicReferenceId": "string",
    "releaseId": "string",
    "externalReferenceId": "string",
    "storedOn": "ISO_Timestamp",
    "message": "string",
    "type": "string",
    "event": "string"
  }
  // object repeated for all notifications
]
  • nxtEntityId: your NxtPort ID

  • equipmentNumber: self-explanatory

  • publicReferenceId: GUID of the notification

  • releaseId: ID (GUID) of the Release Right

  • externalReferenceId: reference you provided in the request header

  • storedOn: ISO timestamp of creation date/time of the notification

  • message: notification as JSON string

  • type: ReleaseLight, ReleaseRight, TerminalEvent

  • event: event of the corresponding notification (see query parameters)

401 - Unauthorized

JSON
{
    "statusCode": 401,
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

Missing API key or authorization token

403 - Forbidden

Response header:

WWW-Authenticate: Bearer error="invalid_token"

CODE
// empty object

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
{
    "identifier": "2304c375-30e2-408b-ac74-4c1b67ceaabf",
    "error": "An unexpected error has occured, please try again later. If the problem persists, please contact NxtPort Support.",
    "extraInfo": null
}

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.

429 - Too Many Requests

N/A

You sent too many requests. We don’t accept more than 500 calls per minute.


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
{
  "publicReferenceId": "GUID",
  "externalReferenceId": "string"
}

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
{
  "publicReferenceId": "GUID",
  "externalReferenceId": "string"
}

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 equipmentNumber & portLoCode have been omitted in request body:

JSON
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-a5601c96c250de464a5305102370cc7e-011ec98b63cf25c4-00",
    "errors": {
        "PortLoCode": [
            "'Port Lo Code' must not be empty.",
            "'Port Lo Code' must be equal to 'BEANR'."
        ],
        "EquipmentNumber": [
            "'Equipment Number' must not be empty."
        ]
    }
}

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:

  • are registered on the Certified Pick up platform;

  • you have the correct role;

  • your credentials (username, password, Oauth access token) are ok.

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.

429

Too Many Requests

N/A

You sent too many requests. We don’t accept more than 500 calls per minute.


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?

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.