Documentation

Integration guidelines for the Certified Pick up API for the stakeholders with role Terminal

Terminal Integration guidelines

  1. Home
  2. Documentation
  3. Certified Pick up
  4. Terminal Integration guidelines

Quick links

Download the factsheet

CPu Documentation pages

Two environments

Certified Pick up uses two different environments. A UAT or testing environment and a Production environment. When reading this document, please use the relevant environment URL's and credentials. When you intend to use both environments, please remember that each of the environments will require each of the steps (signup, credentials, ...)

Asynchronous Notification response (webhooks)

Certified Pick up uses an asynchronous notification mechanism using HTTP post end points/webhooks. This means GET or POST calls will not generate a response with a body other than a Public Reference ID. Any response will be sent to your configured HTTPS endpoint(s). For further information on how to setup your notification channels, please refer to the corresponding tutorial.

Introduction

This document describes how stakeholders of type “Terminal” should integrate the Certified Pick up process within their applications.

When an import container is commercially released, a Ship’s Agent typically sends a PIN code to the Terminal and shares this code with the next party in the release chain (e.g. Forwarder, Transporter,…). This code, which is required to be granted access to the terminal and release the container, is distributed further in the supply chain until a party, which knows the PIN code, claims the container for pick up at the terminal.

By using the Certified Pick up platform, a Ship Agent will not create and distribute a PIN code to the Terminal, increasing the security of the release chain. Instead, the Ship Agent sends the commercial release information towards the Certified Pick up platform, which vouches for a secure transfer of the “Release Right” until it is assigned to an entitled transporter to pick up the container at the terminal. The code to release the container will be sent via a secured and audited communication channel towards the Terminal.

Integrate using existing messages

The Certified Pick up (CPu) process consists of multiple data elements and actions. Most of these will be provided through dedicated API’s. However, to facilitate the integration of CPu with existing processes, it is possible for Ship Agents and Terminals to communicate with existing message types to the CPu Backbone.

Read more about integrating with existing message types (Coarri & Codeco).

Integrate using API's

Release Lights vs Release Rights

To ensure a secure container release at the terminal, three questions are vital: “Is it okay for the terminal that the container leaves the yard?” ,“Is it okay for the ship agent that a container leaves the terminal?” and “Which party is authorised to pick up the container?”.

Release Lights

Just like traffic lights indicate that you can cross a street, the Release Lights API is used to obtain/capture information about the “release status” of a container, i.e. can this container leave the terminal or not.
At this moment, three parties will need to give their permission concerning this departure, being Customs, the Terminal and the Ship Agent. Only these parties will use the Release Lights API.

 

Release Rights

To know which party has the right to pick up a container at the terminal (assuming that both Terminal and Ship Agent have given their consent with the Release Lights API), a different API is used. When a commercial release has occurred, a “Release Right” is created and can be transferred from one party to another.

Your role as a Terminal

The Terminal provides crucial information that is required to release the container from the terminal: the Terminal Release. It covers

  • The container is physically available on the terminal (it has been discharged from the vessel)
  • The container is not blocked by any physical constraints (e.g. dagmage, ...)

The most straightforward way to implement this, is by using the Release Lights API.

In addition, the Terminal will provide the information needed to “close” the release chain: the Gate-Out event.

Process




 

Swagger files

Hostnames

Certified Pick-Up uses a separate API to ingest the Commercial Release information. Ship Agents therefore need to use two different endpoint hostnames when providing us the necessary information. Each of the API's described below will either mention {{HOST - Ingestion}} or {{HOST - CPU API}}. 

 

Receive and process Certified Pick up notifications

Certified Pick up uses a real-time asynchronous notification mechanism. GET requests are sent using the same mechanism to retrieve information from the platform. Even though this may be seen as a cumbersome solution while integration the Certified Pick up process, it increases security by adding a sort of “Two-factor Authentication” and prevents unauthorised access to information by 3rd parties. 

Each of the notifications that is triggered by the below API calls is listed. You can however also find the entire list of all notifications that are sent out, what triggers them and where you receive them on the Notification overview page. 

Release Lights

Submit terminal release


 
Endpoint - Release Light

PUT - {Host}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/terminal-release

Swagger link

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
  "terminalCode": "string",
  "actionType": "Release",
  "releaseDateTimeUtc": "2020-09-17T09:35:25.189Z",
  "equipmentNumber": "string",
  "portLoCode": "string"
}
Field name
Type
Mandatory
Allowed value
Field Description
equipmentNumber String Yes Free text Container number
portLoCode String Yes UNLocode Use the UNLocode of the port. For Antwerp, this is BEANR
terminalCode String Yes Free text The terminal where the container will be available for pickUp. Can be updated later on in the process.
actionType Enum Yes Release You can only use the value Release when you wish to do a terminal release
releaseDateTimeUtc DateTimeUTC Yes Date Time Date from which the Terminal release will be active

When the 200 result is returned, the state of the container will be set to “Released” or “SelectedForScan”.

{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

Notifications

A successful request will generate a notification of type Release-Light with action terminalRelease that will be sent to

  • Your own notification channel and
  • Towards the Ship agent
  • Towards the Release Right owner

To get the current state of a container, please refer to the "Get status of the release light" section of this document.

The Certified Pick up API uses an async mechanism that does not allow to return a full json body. To verify the information that was stored, you can process the notification that will be sent to your notification channel(s) or use the "Get status of the release light" request.

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action. To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Terminal” role

The below error message will be sent to your notification channel(s)


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

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 Certified Pick up backbone, but no Pick up right can be generated.
Endpoint - Release Light

PUT - {Host}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/terminal-release

Swagger link

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
  "terminalCode": "string",
  "actionType": "Block",
  "equipmentNumber": "string",
  "portLoCode": "string"
}
Field name
Type
Mandatory
Allowed value
Field Description
equipmentNumber String Yes Free text Container number
billOfLadingNumbers Array of strings Yes Free text The unique combination of Cointainer/BL will be used for the identification of the Container Release
actionType Enum Yes Block You can only use the value Block when you wish to block a commercial release

When the 200 result is returned, the state of the container will be set to “Blocked”.

{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

Notifications

A successful request will generate a notification of type Release-Light with action terminalBlocked that will be sent to

  • Your own notification channel
  • The ship agent
  • The Release Right owner (if the right was previously given by the agent)

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action. To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Terminal” role

The below error message will be sent to your notification channel(s)


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

Submit Terminal Discharge

This action allows the terminal to change the Terminal Operation/Discharge green light for a container. In case you want to use your existing COARRI discharge message, please refer to Using existing messages.
Endpoint - Ingestion

POST - {{HOST - Ingestion}}/[your dedicated channel-ID]

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Body

{
     "portLoCode": "BEANR",
     "equipmentNumber": "string",
     "timestamp": "2021-01-01T00:00:00",
     "terminalCode": "string",
     "operationType": "Discharge"
}
Field Name Type Mandatory Allowed Value Field Description
portLocode String Yes UNLocode Use the UNLocode of the port. For Antwerp, this is BEANR
equipmentNumber String Yes (at least one) Free text  
timestamp DateTimeUTC Yes Valid UTC datetime UTC DateTime of the registered terminal operation/discharge
terminalCode String Yes Free text The terminal yard where the container will be available for pickUp.
operationType Enum Yes Load / Discharge / CancelLoad / CancelDischarge Specifies which gate operation is applied to the container

Result from the webservice.

{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

Notifications

A successful request will generate a notification of type ReleaseLight with event ReleaseLightChanged that will be sent to

  • Your own notification channel and
  • Towards the Ship agent
  • Towards the Release Right owner
  • Other subscribed parties

Possible values

  • UNKNOWN
  • DISCHARGED
  • DISCHARGECANCELED
  • LOADED
  • LOADCANCELED

 { 
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "carrier": {
      "nxtEntityId": "NXT20000012345",
      "name": "carrier name",
      "eori": null,
      "tin": "carrier vat"
    },
    "terminalCode": "1234",
    "equipmentNumber": "TTTT1234567",
    "billOfLadingNumbers": [
      "BOL001",
      "BOL002"
    ],
    "releaseIdentification": "updateEquipment",
    "greenLightName": "TerminalOperation",
    "originalValue": "Unkown",
    "newValue": "SELECTEDFORSCAN"
  },
  "errors": [],
  "event": "ReleaseLightChanged",
  "externalReferenceId": null,
  "id": "TTTT1234567",
  "publicReferenceId": "f37062c2-c616-4068-8638-02ab075f36c4",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T11:03:04.0618663Z",
  "type": "ReleaseLight",
  "warnings": []
}

 

Response from the webservice

{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

Notifications

When a Terminal/Commercial/… Light is received but the value is identical to the existing value for this light, a notification of type ReleaseLight and event NotValidated is sent to

  • Your own notification channel (sender)
  • Ship agent
  • Release Right owner (if applicable)
  • Other subscribed parties
{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": "No change detected for Light 'GateOperation' - Value: GATEOUTRECEIVED",
  "errors": [],
  "event": "NotValidated",
  "externalReferenceId": null,
  "id": "TTTT1234567",
  "publicReferenceId": "fcb478a4-894f-419c-ae46-00929a9a2e4d",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T13:14:23.2930754Z",
  "type": "ReleaseLight",
  "warnings": []
}

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

This error indicates that you do not have the rights to perform the requested action. To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Terminal” role

The below error message will be sent to your notification channel(s)

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.

Submit Terminal Gate out

This action allows the terminal to register a gate out/operation event for a container. In case you want to use your existing CODECO message, please refer to Using existing messages.
Endpoint - Ingestion

POST - {{HOST - Ingestion}}/[your dedicated channel-ID]

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter

Body

{
     "portLoCode": "BEANR",
     "equipmentNumber": "string",
     "timestamp": "2021-01-01T00:00:00",
     "terminalCode": "string",
     "operationType": "GateOut"
}
Field Name Type Mandatory Allowed Value Field Description
portLocode String Yes UNLocode Use the UNLocode of the port. For Antwerp, this is BEANR
equipmentNumber String Yes (at least one) Free text  
timestamp DateTimeUTC Yes Valid UTC datetime UTC DateTime of the registered terminal operation/discharge
terminalCode String Yes Free text The terminal yard where the container will be available for pickUp.
operationType Enum Yes GateOut / GateIn / CancelGateOut / CancelGateIn Specifies which terminal operation is applied to the container green light

Result from the webservice.

{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

Notifications

When a valid GateOut request is received and the release right is subsequently archived, a notification of type ReleaseLight with event ReleaseLightChanged is sent to

  • Your own notification channel and
  • Towards the Ship agent
  • Towards the Release Right owner
  • Other subscribed parties 

 {
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "carrier": {
      "nxtEntityId": "NXT20000051292",
      "name": "MSC Belgium SA",
      "eori": null,
      "tin": "BE0464255361"
    },
    "terminalCode": "01700",
    "equipmentNumber": "TTTT1234567",
    "billOfLadingNumbers": [
      "BOL001",
      "BOL002"
    ],
    "releaseIdentification": "Container_is_property_of_arne",
    "greenLightName": "GateOperation",
    "originalValue": "UNKNOWN",
    "newValue": "GATEOUTRECEIVED"
  },
  "errors": [],
  "event": "ReleaseLightChanged",
  "externalReferenceId": null,
  "id": "TTTT1234567",
  "publicReferenceId": "2fcdb045-1d08-4a9c-be97-b1e337f9fd59",
  "receiverId": "NXT20000050787",
  "senderId": null,
  "timestamp": "2021-01-06T20:02:48.9938871Z",
  "type": "ReleaseLight",
  "warnings": []
}

Response from the webservice

{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

Notifications

When a Terminal/Commercial/… Light is received but the value is identical to the existing value for this light, a notification of type ReleaseLight and event NotValidated is sent to

  • Your own notification channel (sender)
  • Ship agent
  • Release Right owner (if applicable)
  • Other subscribed parties
{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": "No change detected for Light 'TerminalReady' - Value: RELEASED",
  "errors": [],
  "event": "NotValidated",
  "externalReferenceId": null,
  "id": "TTTT1234567",
  "publicReferenceId": "fcb478a4-894f-419c-ae46-00929a9a2e4d",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T13:14:23.2930754Z",
  "type": "ReleaseLight",
  "warnings": []
}

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

This error indicates that you do not have the rights to perform the requested action. To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Terminal” role

The below error message will be sent to your notification channel(s)

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.

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.

Endpoint - Release Detail

GET - {Host}/certified-pickup/v1/{port-locode}/containers/import/release-rights/{equipment-number}

Swagger link

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter
  • billOfLadingNumbers: Bill of Lading number(s) of the container. Mandatory parameter.
  • releaseIdentification: The unique identification for te release. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

N/A

{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

Notification

This is an example of the response you can expect over the predefined notification channel.

{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
    "equipmentNumber": "TTTT1234567",
    "releaseIdentification": "ReleaseID1",
    "billOfLadingNumbers": [
      "BOL001"
    ],
    "releaseOrderReference": "TTTT1234567",
    "terminalName": "Terminal name",
    "terminalCode": "01700",
    "portLoCode": "BEANR",
    "lights": [
      {
        "greenLightName": "CommercialRelease",
        "greenLightValue": "OK",
        "color": 1,
        "label": "Commercial Release",
        "isEnabled": true,
        "isVisible": true
      },
      {
        "greenLightName": "TerminalReady",
        "greenLightValue": "RELEASED",
        "color": 1,
        "label": "Terminal Ready",
        "isEnabled": true,
        "isVisible": true
      },
      {
        "greenLightName": "TerminalOperation",
        "greenLightValue": "UNKNOWN",
        "color": 4,
        "label": "Terminal Operation",
        "isEnabled": false,
        "isVisible": true
      },
      {
        "greenLightName": "CCRM",
        "greenLightValue": "UNKNOWN",
        "color": 4,
        "label": "Customs Release",
        "isEnabled": false,
        "isVisible": true
      },
      {
        "greenLightName": "NGPS",
        "greenLightValue": "UNKNOWN",
        "color": 4,
        "label": "Customs Status",
        "isEnabled": false,
        "isVisible": true
      },
      {
        "greenLightName": "GateOperation",
        "greenLightValue": "UNKNOWN",
        "color": 4,
        "label": "Gate Operation",
        "isEnabled": false,
        "isVisible": true
      },
      {
        "greenLightName": "PickupLight",
        "greenLightValue": "UNKNOWN",
        "color": 4,
        "label": "Pick-up Light",
        "isEnabled": true,
        "isVisible": true
      }
    ],
    "releaseDateTimeUtc": "2020-12-19T00:00:00Z",
    "expirationDateTimeUtc": "2020-12-20T00:00:00Z",
    "shippingAgentName": "agent name",
    "publicReferenceId": "498ea4e5-6b32-4020-8254-66695d03c194",
    "externalReferenceId": null
  },
  "errors": [],
  "event": "GetReleaseDetail",
  "externalReferenceId": null,
  "id": "Unknown",
  "publicReferenceId": "498ea4e5-6b32-4020-8254-66695d03c194",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T09:01:09.4563365Z",
  "type": "ReleaseRight",
  "warnings": []
}
{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

Notification

This is an example of the response you can expect over the predefined notification channel.

{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": "Could not find release right for unique key TCLU1036476, BOL0001 BOL0002, ReleaseIdentifcation01"
  "errors": [],
  "event": "NotValidated",
  "externalReferenceId": null,
  "id": "TCLU1036476",
  "publicReferenceId": "f7f13626-b1d5-40ed-a3c4-5cfffb852d57",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-01-04T09:44:34.8243447Z",
  "type": "ReleaseRight",
  "warnings": []
}

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Ship Agent” role OR
  • You are the current owner of the Release Right of the requested container

The below error message will be sent to your notification channel(s)


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

Release Rights

Validate Release Right

Check container release ownership for entity identification

Endpoint - Validate Release Right

POST - {Host}/certified-pickup/v1/{port-locode}/validation/preannouncement/ownership

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter
  • billOfLadingNumbers: Bill of Lading number(s) of the container. Mandatory parameter.
  • requestingParty: The identification type & corresponding code of the party you wish to verify. Mandatory parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
  "portLoCode": "string",
  "requestingParty": {
    "identificationType": "NxtEntityId",
    "identificationCode": "string"
  },
  "releaseIdentification": [
    {
      "equipmentNumber": "string",
      "billOfLadingNumbers": [
        "string"
      ]
    }
  ]
}
{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

When the 200 result is returned, the call was successful and the information of the requested container will be sent to your Notification Channel(s).

Notification

This is an example of the response you can expect over the predefined notification channel.

{
    "assetId": "00000000-0000-0001-0000-000000000037",
    "body": {
        "requestingParty": {
            "identificationType": "APCS/TIN/..",
            "identificationCode": "string"
        },
        "releaseIdentification": [
            {
                "isOwner": true,
                "errorMessages": null,
                "equipmentNumber": "C44550011",
                "billOfLadingNumbers": [
                    "124558885",
                    "11145A"
                ]
            },
            {
                "isOwner": false,
                "errorMessages": "Requesting party is not the release right owner for this container.",
                "equipmentNumber": "C44550012",
                "billOfLadingNumbers": [
                    "124558885",
                    "11145A"
                ]
            }
        ]
    },
    "errors": [],
    "event": "PreannouncementValidation",
    "externalReferenceId": null,
    "id": "",
    "publicReferenceId": "e5056634-b42b-4e56-bf5a-3f65242fd89f",
    "receiverId": "NXT20000051292",
    "senderId": null,
    "timestamp": "2021-03-12T09:24:36.5670215Z",
    "type": "TerminalEvent",
    "warnings": []
}

 

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Ship Agent” role OR
  • You are the current owner of the Release Right of the requested container

The below error message will be sent to your notification channel(s)


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

 

Pick-up Rights

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 True or False

Applies to

  • Forwarders
  • Terminals
  • Ship agents
Endpoint - Company Registry

GET - {Host}/certified-pickup/v1/validation​/pickup​/identification

  • IdentificationType: The type of identification. Currently only alfapass is allowed for the Port of Antwerp
  • IdentificationCode: The code linked to the identification (ie, the alfapass number)

Body

{
  "identificationType": "alfapass",
  "identificationCode": "0123456"
}
true or false 
{
    "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'."
        ]
    }
}

Validate Pick-up right (Asynchronous response)

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. 

Endpoint - Verify Pick-up party

POST - {Host}/certified-pickup/v1/{port-locode}/validation/pickup/containers

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter
  • billOfLadingNumbers: Bill of Lading number(s) of the container. Optional parameter.
  • releaseIdentification: The unique identification for te release. Optional parameter

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body

{
  "portLoCode": "string",
  "alfapassNumber": "string",
  "releaseRightPickupIdentifiers": [
    {
      "equipmentNumber": "string",
      "billOfLadingNumbers": [
        "string"
      ]
    }
  ]
}


 
{
    "publicReferenceId": "GUID",
    "externalReferenceId": "string"
}

Notification

This is an example of the response you can expect over the predefined notification channel.

{
  "assetId": "00000000-0000-0001-0000-000000000037",
  "body": {
   "alfapassNumber": '124567',
   "releaseRightPickupIdentifiers": [
       {
           "isValid": true,
           "errorMessages": null,
           "equipmentNumber": "C44550011",
           "billOfLadingNumbers": [ "124558885", "11145A"]
       },
         {
           "isValid": false,
           "errorMessages": "No pickup allowed for this container",
           "equipmentNumber": "C44550012",
           "billOfLadingNumbers": [ "124558885", "11145A"]
       }
   ]
},
  "errors": [],
  "event": "AlfapassPickUpValidation",
  "externalReferenceId": null,
  "id": "TESTALFAPASCNTPKP04",
  "publicReferenceId": "e5056634-b42b-4e56-bf5a-3f65242fd89f",
  "receiverId": "NXT20000051292",
  "senderId": null,
  "timestamp": "2021-03-12T09:24:36.5670215Z",
  "type": "TerminalEvent",
  "warnings": []
}

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be sent to your notification channel(s)


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

This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Ship Agent” role OR
  • You are the current owner of the Release Right of the requested container

The below error message will be sent to your notification channel(s)


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

Validate Pick-up right (Synchronous response)

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 requrested information is returned in a synchronous response

Endpoint - Verify Pick-up party

POST - {Host}/certified-pickup/v1/{port-locode}/sync-validation/pickup/containers

Parameters

  • port-locode: the UN/Locode of the operational port. For Antwerp this is BEANR. Mandatory parameter.
  • equipment-number: the container number. This number will be used onwards in the process. Mandatory parameter
  • billOfLadingNumbers: Bill of Lading number(s) of the container. Optional parameter.

Headers

  • External-Reference-Id (optional); Your own reference (string)

Body


{
  "portLoCode": "BEANR",
  "alfapassNumber": "string",
  "releaseIdentification": [
    {
      "equipmentNumber": "string",
      "billOfLadingNumbers": [
        "string"
      ]
    }
  ]
}
   
   
 

Response


{
  "alfapassNumber": "string",
  "releaseIdentification": [
    {
      "isValid": true,
      "errorMessages": "string",
      "status": "string",
      "greenLights": [
        {
          "greenLightName": "string",
          "greenLightValue": "string",
          "greenLightColor": "string"
        }
      ],
      "equipmentNumber": "string",
      "billOfLadingNumbers": [
        "string"
      ]
    }
  ]
}

Possible Values (greenLightValue + greenLightColor)

greenLightName: Commercial Release

OK – Green
NOK - Red

greenLightName: TerminalOperation

UNKNOWN – Grey – No terminal information has been received
LOADED – Red  – Container has been loaded on sea vessel (exceptional)
DISCHARGED – Green  – Container has been discharged from sea vessel
LOADCANCELED – Grey  – Correction: Previous “Loaded” message was incorrect
DISCHARGECANCELED – Grey - Correction :Previous “Discharged” message was incorrect
GATEIN – Green – Container has entered the terminal through the gate
(truck, barge or rail)

greenLightName: TerminalReady

UNKNOWN – Grey – No terminal information has been received
RELEASED – Green – No terminal blocks on container
BLOCKED – Red – Container is blocked at the terminal
ARCHIVED – Red – Container is archived (not present in active CPu system)

greenLightName: Customs

NOTRELEASED – Red – Container is not released by customs
SELECTEDFORSCAN – Yellow – Container is selected for scan
RELEASED – Green – Container is released by customs
TRANSHIPMENT – Grey – Transhipment container. Customs light not applicable
TRANSFER – Grey – Transfer container. Customs light not applicable
NOTAPPLICABLE – Orange – (General) customs light not applicable

greenLightName: PickupLight

UNKNOWN - Grey – No alfapass coupled to the release
ASSIGNED – Green – Alfapass coupled to the release
REVOKED – Red – No alfapass coupled to the release, but previously it was

Something in your call wasn’t what we were expecting. Please:

  • Verify if you have included all mandatory fields
  • Verify if you are following the restrictions as defined in the above fields description

The below error message will be returned on your request


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

This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:

  • Registered on the Certified Pick up platform
  • You have (at least) a “Ship Agent” role OR
  • You are the current owner of the Release Right of the requested container

The below error message will be returned on your request


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

Generic services

Company Registery

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.

Applies to

  • Forwarders
  • Terminals
  • Ship agents
Endpoint - Company Registry

GET - {Host}/certified-pickup/v1/entities

Swagger link
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 ApcsCode will be queried in our register
  • Page (default to 1) : determine which page of the results is queried
  • PageSize (default to 25) : determine the pagesize of the queried results 
{
  "searchFilter": {
    "eori": "string",
    "duns": "string",
    "vat": "string",
    "entityName": "string",
    "apcsCode": "string",
    "page": 0,
    "pageSize": 0
  },
  "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"
    }
  ],
  "totalRows": 0,
  "totalPages": 0,
  "publicReferenceId": "string",
  "externalReferenceId": "string"
}
{
    "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'."
        ]
    }
}

Solutions built for ports

We introduce you to the port of tomorrow. Join the community and help your port be on the forefront of innovation!

Documentation

Contact

The Beacon - 5th floor Sint-Pietersvliet 7 2000 Antwerp Belgium

More info

Register your company