This document describes how stakeholders of type “Ship Agent” should integrate the Certified Pick up process within their applications.
When an import container is commercially released, the 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, the Ship Agent does not create and distribute a PIN code, 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.
This process runs in parallel with the existing sharing of CUSCAR information through the “Import Consignment” API.
By accepting the API specific Terms & Conditions of the Certified Pick up process, we can use your CUSCAR data to increase the data quality. This information will not be shared with external sources for other purposes, following our general Terms & Conditions.
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).
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?”.
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, two parties will need to give their permission concerning this departure, being the Terminal and the Ship Agent. Only these two parties will use the Release Lights API.
NxtPort is also integrating the Customs Release Light (CCRM). Until the direct link with Customs is functional, this light is included in the Terminal Release.
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.
The Ship Agent provides crucial information that initiates the release proces: the Commercial release.
The most straightforward way to implement this, is by using the Release Lights API. Even more, if your call also provides information concerning the party you would like to give the Release Right to (e.g. Forwarder, BCO,…), the Release Lights API will be the only API you’ll need to integrate!
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}}.
In case of the Ingestion API, you will need a specified Channel that is setup for your organisation. Ship Agents that did not yet receive their dedicated Channel ID can create a support ticket on our helpdesk.
The question “Is it okay for the ship agent that a container leaves the terminal?” can be answered through the “Release Light” method.
POST - {{HOST - Ingestion}}/[your dedicated channel-ID]
Parameters
Headers
Body
{
"releaseIdentification": "string",
"releaseOrderReference": "string",
"equipmentNumber": "string",
"equipmentType": "string",
"billOfLadingNumbers": [
"string"
],
"portLoCode": "string",
"terminalCode": "string",
"actionType": "Release",
"carrier": {
"identificationType": "NxtEntityId",
"identificationCode": "string"
},
"releaseTo": {
"identificationType": "NxtEntityId",
"identificationCode": "string"
},
"releaseDateTimeUtc": "2020-04-30T13:06:11.385Z",
"expirationDateTimeUtc": "2020-04-30T13:06:11.385Z"
}
Field name
|
Type
|
Mandatory
|
Allowed value
|
Field Description
|
---|---|---|---|---|
releaseIdentification | String | Yes | Free text | Unique release identification (per carrier) |
releaseOrderReference | String | No | Free text | Release Order Reference |
equipmentNumber | String | Yes | Free text | Container number |
equipmentType | String | No | Free text | Use this field to indicate the type of equipment. You could use “Container” or the ISO container type code (eg 20GP or 22RT) |
billOfLadingNumbers | Array of strings | Yes | Free text | The unique combination of Cointainer/BL will be used for the identification of the Container Release |
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 commercial release |
carrier > identificationType |
String | Yes | Tin, Eori, Duns or APCS |
Enter the type of identification of the carrier.
Remark: Tin should be used for the VAT number of a company
|
carrier > identificationCode |
String | Yes | String | The value that belongs to the selected identification |
releaseTo > identificationType | String | No | Tin, Eori, Duns or APCS |
Enter the type of identification of the party that will receive the Release Right.
If the releaseTo party is not yet known at the moment of the commercial release, this information can be left out and updated later on in the process by using the “Release Rights ” method.
Remark: Tin should be used for the VAT number of a company
|
releaseTo > identificationCode | String | No | String |
The value that belongs to the selected identification. If the entry is valid, the release right will be given to the stated entity.
If the entry is not valid, you will still receive a 200 success response. A separate notification will be sent to your notification channel(s).
|
releaseDateTimeUtc | DateTimeUTC | Yes | Date Time | Date from which the Commercial release will be active |
expirationDateTimeUtc | DateTimeUTC | No | Date Time | Date until which the Commercial release will be active. If not entered, there is no expiration date applied |
When the 200 result is returned, the state of the container will be set to “Released”.
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
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:
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:
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": {}
}
For as long as the container is not yet picked up, the creator (the Ship Agent) is able to update the release information. This can be done for example:
POST - {{HOST - Ingestion}}/ingestion/[your dedicated channel-ID]
Parameters
Headers
Body
{
"releaseIdentification": "string",
"releaseOrderReference": "string",
"equipmentNumber": "string",
"equipmentType": "string",
"billOfLadingNumbers": [
"string"
],
"portLoCode": "string",
"terminalCode": "string",
"actionType": "Update",
"carrier": {
"identificationType": "NxtEntityId",
"identificationCode": "string"
},
"releaseTo": {
"identificationType": "NxtEntityId",
"identificationCode": "string"
},
"releaseDateTimeUtc": "2020-04-30T13:06:11.385Z",
"expirationDateTimeUtc": "2020-04-30T13:06:11.385Z"
}
Field name
|
Type
|
Mandatory
|
Allowed value
|
Field Description
|
---|---|---|---|---|
releaseIdentification | String | Yes | Free text | Unique release identification (per carrier) |
releaseOrderReference | String | No | Free text | Release Order Reference |
equipmentNumber | String | Yes | Free text | Container number |
equipmentType | String | No | Free text | Use this field to indicate the type of equipment. You could use “Container” or the ISO container type code (eg 20GP or 22RT) |
billOfLadingNumbers | Array of strings | Yes | Free text | The unique combination of Cointainer/BL will be used for the identification of the Container Release |
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 | Update | You can only use the value Update when you wish to do a commercial release |
carrier > identificationType |
String | Yes | Tin, Eori, Duns or APCS |
Enter the type of identification of the carrier.
Remark: Tin should be used for the VAT number of a company
|
carrier > identificationCode |
String | Yes | String | The value that belongs to the selected identification |
releaseTo > identificationType | String | No | Tin, Eori, Duns or APCS |
Enter the type of identification of the party that will receive the Release Right.
If the releaseTo party is not yet known at the moment of the commercial release, this information can be left out and updated later on in the process by using the “Release Rights ” method.
Remark: Tin should be used for the VAT number of a company
|
releaseTo > identificationCode | String | No | String |
The value that belongs to the selected identification. If the entry is valid, the release right will be given to the stated entity.
If the entry is not valid, you will still receive a 200 success response. A separate notification will be sent to your notification channel(s).
|
releaseDateTimeUtc | DateTimeUTC | Yes | Date Time | Date from which the Commercial release will be active |
expirationDateTimeUtc | DateTimeUTC | No | Date Time | Date until which the Commercial release will be active. If not entered, there is no expiration date applied |
When the 200 result is returned, the state of the container will be updated. The state will not change.
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
A successful request will generate a notification of type Release-Light with action update that will be sent to
Something in your call wasn’t what we were expecting. Please:
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:
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": {}
}
POST - {{HOST - Ingestion}}/ingestion/[your dedicated channel-ID]
Parameters
Headers
Body
{
"releaseIdentification": "string",
"equipmentNumber": "string",
"billOfLadingNumbers": [
"string"
],
"actionType": "Block"
}
Field name
|
Type
|
Mandatory
|
Allowed value
|
Field Description
|
---|---|---|---|---|
releaseIdentification | String | Yes | Free text | Unique release identification (per carrier) |
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 blocked that will be sent to
Something in your call wasn’t what we were expecting. Please:
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:
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": {}
}
POST - {{HOST - Ingestion}}/ingestion/[your dedicated channel-ID]
Parameters
Headers
Body
{
"releaseIdentification": "string",
"equipmentNumber": "string",
"billOfLadingNumbers": [
"string"
],
"actionType": "Unblock"
}
Field name
|
Type
|
Mandatory
|
Allowed value
|
Field Description
|
---|---|---|---|---|
releaseIdentification | String | Yes | Free text | Unique release identification (per carrier) |
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 | Unblock | You can only use the value Unblock when you wish to block a commercial release |
When the 200 result is returned, the state of the container will be set to “Released”.
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
A successful request will generate a notification of type Release-Light with action unblocked that will be sent to
Something in your call wasn’t what we were expecting. Please:
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:
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": {}
}
POST - {{HOST - Ingestion}}/ingestion/[your dedicated channel-ID]
Parameters
Headers
Body
{
"releaseIdentification": "string",
"equipmentNumber": "string",
"billOfLadingNumbers": [
"string"
],
"actionType": "Delete",
}
Field name
|
Type
|
Mandatory
|
Allowed value
|
Field Description
|
---|---|---|---|---|
releaseIdentification | String | Yes | Free text | Unique release identification (per carrier) |
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 | Delete | You can only use the value Delete when you wish to delete a commercial release |
When the 200 result is returned, the container will no longer be listed.
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
Something in your call wasn’t what we were expecting. Please:
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:
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": {}
}
At any time, stakeholders that are allowed to see the information, can retrieve the detail and greenlights of a specific container release.
GET - {Host}/certified-pickup/v1/{port-locode}/containers/import/release-rights/{equipment-number}
Swagger linkParameters
Headers
Body
N/A
{
"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).
{
"publicRefernceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"externalReferenceId": "string"
"portLoCode": "string",
"equipmentNumber": "string",
"billOfLadingNumbers": [
"string"
],
"terminalCode": "string",
"state": "Unknown"
}
Something in your call wasn’t what we were expecting. Please:
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:
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": {}
}
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": "MPET",
"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": "MSC",
"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": []
}
The question “Which party is authorised to pick up the container?” can be answered through the “Release Rights” method.
GET - {{HOST - CPU API}}/certified-pickup/v1/{port-locode}/containers/import/release-rights
Swagger linkParameters
Headers
When performing the get method, a list of parameters can be used to filter the results. All results will automatically be filtered to list only Pick up Rights linked to the Stakeholder that performs the request.
Available filters
Field name
|
Type
|
Mandatory
|
Allowed value
|
Field Description
|
---|---|---|---|---|
billofladingnumberfilter | String | No | Free text | Filters the rights depending on the Bill of Lading number. Uses the %like% statement. Not case sensitive. |
currentstakeholdernamefilter | String | No | Free text |
Filters the rights depending on the current stakeholder. This allows you
|
equipmentnumberfilter | String | No | Free text | Filters the rights depending on the Equipment number. Uses the %like% statement allowing you to filter through all containers of a specific carrier. Not case sensitive. |
page | Integer | Yes | Defaults to 1 | The response uses paging. Page numbering starts at 1. Default is 1. |
pageSize | Integer | Yes | Number | The response uses paging. No default set. To reduce process time we suggest to limit between 25 to 100 in pageSize |
portLoCode | String | Yes | UNLocode | Use the UNLocode of the port. For Antwerp, this is BEANR |
status | Enumeration | No | Unknown, Assigned, Pending, Accepted, Declined, Revoked, Archived, Paused, Expired, Resumed | Returns only the rights in the specified status. |
status | Enumeration | Yes | Active, Pending |
|
Body
N/A
Response fields
Field name | Type | Mandatory | Allowed value | Field Description |
---|---|---|---|---|
equipmentNumber | String | Yes | Free text | Container number |
billOfLadingNumbers | String | Yes | Free text | Bill of Lading number(s) of the container |
releaseFrom > identificationType | Sting | Yes | Tin, Eori, Duns or APCS | Enter the type of identification of the party that will forward the Release Right. |
releaseFrom > identificationCode | String | Yes | String | The value that belongs to the selected identification |
releaseTo > identificationType | String | Yes | Tin, Eori, Duns or APCS | Enter the type of identification of the party that will receive the Release Right |
releaseTo > identificationCode | String | Yes | String | The value that belongs to the selected identification |
actionType | Enum | Yes | Accept | You can only use the value “Accept” when you wish to accept a transferrede Release Right. The right will be transferred to your entity. |
actionReason | String | No | Free text | Can be used to add a comment or reason for accepting the Pick up right |
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). This is the information that will be sent to the notification channel with type Release-Right and action “overview”
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
{
"timestamp": "2019-08-28T09:41:18Z",
"publicReferenceId": "6d113ff6-4805-430f-be32-d8918fab83f1",
"privateReference": "your-reference-here",
"senderId": "NxtDummy001",
"receiverId": "NxtDummy002",
"asset": "Certified Pick Up",
"id": "your-reference-here",
"type": "Commercial Release Right",
"action": "overview",
"body": {
"currentStakeholder": {
"identificationType": "Eori",
"identificationCode": "string"
},
"page": 0,
"pageSize": 0,
"dateStart": "2020-05-05T15:06:23.642Z",
"dateEnd": "2020-05-05T15:06:23.642Z",
"status": "string",
"billOfLadingNumberFilter": "string",
"shippingAgentNameFilter": "string",
"shippingAgentTinFilter": "string",
"currentStakeholderNameFilter": "string",
"currentStakeholderTinFilter": "string",
"releaseRightStatusFilter": "Unknown",
"result": [
{
"equipmentNumber": "string",
"expirationDateTimeUtc": "2020-05-05T15:06:23.642Z",
"operationalStatus": "Unknown",
"originatorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"originatorName": "string",
"releaseDateTimeUtc": "2020-05-05T15:06:23.642Z",
"terminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"terminalName": "string",
"terminalCode": "string",
"portLoCode": "string",
"startDate": "2020-05-05T15:06:23.642Z",
"releaseFromId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"releaseFromName": "string",
"releaseFromNxtEntityId": "string",
"releaseFromVatNumber": "string",
"releaseToId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"releaseToName": "string",
"releaseToNxtEntityId": "string",
"releaseToVatNumber": "string",
"releaseRightStatus": "Unknown",
"billOfLadingNumbers": [
"string"
],
"actions": [
{
"label": "string",
"isEnabled": true
}
]
}
]
},
"errors": [],
"warnings": []
}
Something in your call wasn’t what we were expecting. Please:
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:
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": {}
}
PUT - {{HOST - CPU API}}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/release-rights
Swagger linkParameters
Headers
Body
{
"releaseIdentification": "string",
"equipmentNumber": "string",
"billOfLadingNumbers": [
"string"
],
"portLoCode": "string",
"terminalCode": "string",
"carrier": {
"identificationType": "NxtEntityId",
"identificationCode": "string"
},
"actionType": "Transfer",
"reasonForAction": "string",
"releaseFrom": {
"identificationType": "NxtEntityId",
"identificationCode": "string"
},
"releaseTo": {
"identificationType": "NxtEntityId",
"identificationCode": "string"
}
Field name | Type | Mandatory | Allowed value | Field Description |
---|---|---|---|---|
releaseIdentification | String | Yes | Free text | Unique release identification (per carrier) |
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 |
portLoCode | String | Yes | UNLocode | Use the UNLocode of the port. For Antwerp, this is BEANR |
terminalCode | String | No | Free text | The terminal where the container will be available for pickUp. Can be updated later on in the process |
actionType | Enum | Yes | Transfer | You can only use the value Transfer when you wish to transfer the Release Right |
carrier > identificationType |
String | Yes | Tin, Eori, Duns or APCS | Enter the type of identification of the carrier.
Remark: Tin should be used for the VAT number of a company
|
carrier > identificationCode |
String | Yes | String | The value that belongs to the selected identification |
releaseFrom > identificationType | String | Yes | Tin, Eori, Duns or APCS | Enter the type of identification of the party that will send the Release Right.
Remark: Tin should be used for the VAT number of a company
If this information is not included in the body, Eori will be automatically filled.
|
releaseFrom > identificationCode | String | Yes | String | The value that belongs to the selected identification. If the entry is valid, the release right will be taken from the stated entity.This information will be validated against the current Release Right owner in the Certified Pick up database.
If this information is not included in the body, the Eori from the credentials that perform the API call will be filled.
|
releaseTo > identificationType | String | Yes | Tin, Eori, Duns or APCS | Enter the type of identification of the party that will receive the Release Right. Remark: Tin should be used for the VAT number of a company |
releaseTo > identificationCode | String | Yes | String | The value that belongs to the selected identification. If the entry is valid, the release right will be given to the stated entity. |
When the 200 result is returned, the right to Pick up the container will be transferred to the provided recipient. He will have the possibility to accept or decline this right.
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
To get the current state of a container, please refer to to the Get status of the release light section of this document.
Before a Release Right is passed to another party, this party needs to accept this transfer. For as long as this “accept” has not occurred, the transfer can be “revoked” by the party that transfers the right.
Something in your call wasn’t what we were expecting. Please:
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:
{
"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"additionalProp1": {},
"additionalProp2": {},
"additionalProp3": {}
}
HTML
PUT - {{HOST - CPU API}}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/release-rights
Swagger linkParameters
Headers
Body
{
"releaseIdentification": "string",
"equipmentNumber": "string",
"billOfLadingNumbers": [
"string"
],
"actionType": "Revoke",
"reasonForAction": "string",
}
Field name | Type | Mandatory | Allowed value | Field Description |
---|---|---|---|---|
releaseIdentification | String | Yes | Free text | Unique release identification (per carrier) |
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 | Revoke | You can only use the value Revoke when you wish to revoke the Release Right |
When the 200 result is returned, your request has been successfully received. A notification of type “revoked” will be sent to your notification channel(s).
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
Something in your call wasn’t what we were expecting. Please:
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:
{
"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"additionalProp1": {},
"additionalProp2": {},
"additionalProp3": {}
}
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.
Several notifications, can be received. In the notification, the “Event” field allows to identify one of the following actions:
For the notifications of type Release-Light, the “Event” field allows to identify one of the following actions:
For the notifications of type Release-Right, the “Event” field allows to identify one of the following actions:
To setup your notification channels, you can find detailed information on our Wiki pages.
Every notification that is sent by NxtPort will be built up with a generic part, allowing integrators to identify the asset, sender, error or warning messages and a Use case or type specific body.
Field name | Type | Allowed values | Field Description |
---|---|---|---|
timestamp | DateTime | UTC datetime stamp | The timestamp when the notification was created by the Certified Pick up platform |
correlationId | GUID | GUID | The unique identifier of this event. When communicating with NxtPort, this Id will allow us to immediately know what you are referencing to. May be reused later on in the process |
senderId | String | APCS code | The APCS code of the owner that generated the notification. If a 3rd party triggered the event, this information will still be the owner of the original source that will be listed here. |
receiverId | String | APCS code | This should always be your APCS code as you are the receiver of this message. |
asset | String | Free Text | Name of the asset that generated the notification. For the Certified Pick up this will always be “CPu”. |
id | String | Free Text | For the Certified Pick up, this value will list the Equipment number, allowing integrators to quickly process the json message |
type | String | Release-Light, Release-Right | Will contain either Release Right or Release Light, depending on the type of message. As a terminal, you will receive notifications of type “Release Light”. |
event | Enumeration | release, update, delete, block, unblock, terminalRelease, terminalBlocked and terminalScan for Release Lights transferred, declinedByNextParty and acceptedByNextParty for Release Rights | See description above |
errors | Array | Free text | list of descriptive errors and warnings in the form of USECASE_ERROR|WARNING_SPECIFIC_DESCRIPTION |
warnings | Array | Free text | list of descriptive errors and warnings in the form of USECASE_ERROR|WARNING_SPECIFIC_DESCRIPTION |
Field name | Type | Allowed Values | Field description |
sender> tinNumber | String | TIN number | The TIN (VAT) number of the entity that caused the notification. This is the number that is stored in the NxtPort entity database. Will always contain a value. |
sender> name | String | Free text | The name of the entity that caused the notification. This is the name that is stored in the NxtPort entity database. Will always contain a value. |
sender> eori | String | EORI number | The EORI number of the entity that caused the notification. This is the EORI nu,ber that is stored in the NxtPort entity database. Can be empty |
releaseIdentification | String | Free text | Unique release identification (per carrier) |
releaseOrderReference | String | Free text | Release Order Reference |
equipmentNumber | String | Free text | Container number |
equipmentType | String | Free text | In most cases, this will be “Container” |
billOfLadingNumbers | Array of strings | Free text | The unique combination of Cointainer/BL will be used for the identification of the Container Release |
portLoCode | String | UNLocode | The UNLocode of the port. For Antwerp, this is BEANR |
terminalCode | String | Free text | The terminal yard where the container will be available for pickUp. |
actionType | Enumeration | release, update, delete, block, unblock, terminalRelease, terminalScan, terminalBlocked | Identifies the action that was taken to trigger the Release Light notification. |
carrier> tinNumber | String | TIN number | The TIN (VAT) number of the carrier. This is the number that is stored in the NxtPort entity database. Will always contain a value. |
carrier> name | String | Free text | The name of the carrier. This is the name that is stored in the NxtPort entity database. Will always contain a value. |
carrier> eori | String | EORI number | The EORI number of the carrier. This is the EORI nu,ber that is stored in the NxtPort entity database. Can be empty |
releaseDateTimeUtc | DateTimeUTC | Date Time |
Date from which the Commercial release will be active |
expirationDateTimeUtc | DateTimeUTC | Date Time | Date until which the Commercial release will be active. If not entered, there is no expiration date applied |
errors | Array | Free text | list of descriptive errors and warnings in the form of USECASE_ERROR|WARNING_SPECIFIC_DESCRIPTION |
warnings | Array | Free text | list of descriptive errors and warnings in the form of USECASE_ERROR|WARNING_SPECIFIC_DESCRIPTION |
{
"timestamp": "2019-08-28T09:41:18Z",
"publicReferenceId": "6d113ff6-4805-430f-be32-d8918fab83f1",
"ExternalReferenceId": "your-reference-here",
"senderId": "APCS001",
"receiverId": "APCS002",
"asset": "CPU",
"id": "ABCU1234560",
"type": "Release-Light",
"action": "create",
"body": {
"sender": {
"tinNumber": "BE0123456789",
"name": "Shipping agent name",
"eori": ""
},
"releaseIdentification": "xxxxx",
"releaseOrderReference": "Ref001",
"equipmentNumber": "ABCU1234560",
"equipmentType": "Container",
"billOfLadingNumbers": [
"ABCUAA123456"
],
"portLoCode": "BEANR",
"terminalCode": "123",
"actionType": "Release",
"carrier": {
"tinNumber": "BE0123456789",
"name": "Shipping agent name",
"eori": ""
},
"releaseDateTimeUtc": "2020-04-30T17:42:18.251Z",
"expirationDateTimeUtc": "2020-04-30T17:42:18.251Z",
"errors": [],
"warnings": []
},
"errors": [],
"warnings": []
}
Field name | Type | Allowed Values | Dield Description |
sender> tinNumber | String | TIN number | The TIN (VAT) number of the entity that caused the notification. This is the number that is stored in the NxtPort entity database. Will always contain a value. |
sender> name | String | Free text | The name of the entity that caused the notification. This is the name that is stored in the NxtPort entity database. Will always contain a value. |
sender> eori | String | EORI number | The EORI number of the entity that caused the notification. This is the EORI nu,ber that is stored in the NxtPort entity database. Can be empty |
releaseIdentification | String | Free text | Unique release identification (per carrier) |
equipmentNumber | String | Free text | Container number |
equipmentType | String | Free text | Use this field to indicate the type of equipment. You could use “Container” or the ISO container type code (eg 20GP or 22RT) |
portLoCode | String | UNLocode | The UNLocode of the port. For Antwerp, this is BEANR |
terminalCode | String | Free text | The terminal yard where the container will be available for pickUp. |
actionType | Enumeration | transferred, declinedByNextParty, acceptedByNextParty | Identifies the action that was taken to trigger the Release Light notification. This is the real action that was performed. not to be mistaken with the type of the Notification that might contain similar information. |
reasonForAction | String | Free Text | If you want to let a party know why you didn’t accept a Release Right, you can fill it in here |
billOfLadingNumbers | Array of strings | Free text | The unique combination of Cointainer/BL will be used for the identification of the Container Release |
releaseFrom> tinNumber | String | TIN number | The TIN (VAT) number of the entity described in the ReleaseFrom > NxtEntityId field. This is the number that is stored in the NxtPort entity database. Will always contain a value. |
releaseFrom> name | String | Free text | The name of the entity described in the ReleaseFrom > NxtEntityId field. This is the number that is stored in the NxtPort entity database. Will always contain a value. |
releaseFrom> eori | String | EORI number | The EORI number of the entity described in the ReleaseFrom > NxtEntityId field. This is the number that is stored in the NxtPort entity database. Can be empty |
releaseTo> tinNumber | String | TIN number | The TIN (VAT) number of the entity described in the ReleaseTo > NxtEntityId field. This is the number that is stored in the NxtPort entity database. Will always contain a value. |
releaseTo> name | String | Free text | The name of the entity described in the ReleaseTo > NxtEntityId field. This is the number that is stored in the NxtPort entity database. Will always contain a value. |
releaseTo> eori | String | EORI number | The EORI number of the entity described in the ReleaseTo > NxtEntityId field. This is the number that is stored in the NxtPort entity database. Can be empty |
carrier> tinNumber | String | TIN number | The TIN (VAT) number of the entity described in the carrier > NxtEntityId field. This is the number that is stored in the NxtPort entity database. Will always contain a value. |
carrier> name | String | Free text | The TIN (VAT) number of the entity described in the carrier > NxtEntityId field. This is the number that is stored in the NxtPort entity database. Will always contain a value. |
carrier> eori | String | EORI number | The TIN (VAT) number of the entity described in the carrier > NxtEntityId field. This is the number that is stored in the NxtPort entity database. Can be empty |
releaseDateTimeUtc | DateTimeUTC | Date Time | Date from which the Commercial release will be active |
expirationDateTimeUtc | DateTimeUTC | Date Time | Date until which the Commercial release will be active. If not entered, there is no expiration date applied |
errors | Array | Free text | list of descriptive errors and warnings in the form of USECASE_ERROR|WARNING_SPECIFIC_DESCRIPTION |
warnings | Array | Free text | list of descriptive errors and warnings in the form of USECASE_ERROR|WARNING_SPECIFIC_DESCRIPTION |
{
"timestamp": "2019-08-28T09:41:18Z",
"publicReferenceId": "6d113ff6-4805-430f-be32-d8918fab83f1",
"privateReference": "your-reference-here",
"senderId": "APCS001",
"receiverId": "APCS002",
"asset": "Certified Pick Up",
"id": "ABCU1234560",
"type": "Commercial Release Right",
"action": "transfer",
"body": {
"sender": {
"apcsCode": "APCS001",
"tinNumber": "BE0123456789",
"name": "Shipping agent name",
"eori": ""
},
"releaseIdentification": "xxxxx",
"equipmentNumber": "ABCU1234560",
"equipmentType": "Container",
"portLoCode": "BEANR",
"terminalCode": "K12345",
"actionType": "transfer",
"reasonForAction": "string",
"billOfLadingNumbers": [
"ABCUAA123456"
],
"releaseFrom": {
"apcsCode": "APCS001",
"tinNumber": "BE0123456789",
"name": "Shipping agent name",
"eori": ""
},
"releaseTo": {
"tinNumber": "BE0123456789",
"name": "forwarder name",
"eori": ""
},
"carrier": {
"apcsCode": "APCS001",
"tinNumber": "BE0123456789",
"name": "carrier name",
"eori": ""
},
"releaseDateTimeUtc": "2020-05-14T12:42:00.422Z",
"expirationDateTimeUtc": "2020-05-14T12:42:00.422Z",
"validFrom": "2020-05-14T12:42:00.422Z",
"errors": [],
"warnings": []
},
"errors": [],
"warnings": []
}