CPu Documentation pages
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, ...)
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.
This document describes how stakeholders of type “Forwarder”, “Transport Company” or “Beneficial Cargo Owner (BCO)” 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, Transport Company, BCO,…). 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.
Forwarders, Transport Companies or BCO’s can receive the right to pick up cargo (ie a container) from the Ship Agent, once they have completed all necessary commercial agreements. As soon as the Terminal provides the terminal release (including the discharge confirmation and customs release), the container will be ready for pick up at the yard. The owner of the Pick up right can either decide to pick up the cargo themselves or distribute the right to pick up the container further down the supply chain.
The most straightforward way to implement this, is by using the Release Lights API.
Certified Pick up uses a real-time asynchronous notification mechanism. This means that, once the right to pick up a container is submitted or transferred, a notification is sent towards the other stakeholders. (the new Release Right owner.)
Several notifications, can be received. In the notification, the “Event” field allows to identify one of the following actions:
To setup your notification channels, you can find detailed information on this page.
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.
Each of the below requests will show you an example of the possible notifications that can be sent. You call view them by clicking on the title, which will unfold a json file.
PUT - {Host}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/release-rights
Swagger linkParameters
Headers
Body
{
"releaseIdentification": "string",
"equipmentNumber": "string",
"billOfLadingNumbers": [
"string"
],
"releaseFrom": {
"identificationType": "string",
"identificationCode": "string"
},
"releaseTo": {
"identificationType": "string",
"identificationCode": "string"
},
"actionType": "Accept",
"actionReason": "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 | 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 |
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": {
"sender": {
"nxtEntityId": "NXT2000001234",
"name": "sender name",
"eori": "",
"tin": "Sender vat"
},
"carrier": {
"nxtEntityId": "NXT2000001234",
"name": "carrier name",
"eori": "",
"tin": "carrier vat"
},
"releaseTo": {
"nxtEntityId": "NXT2000001234",
"name": "releasto name",
"eori": "",
"tin": "releaseto vat"
},
"releaseFrom": {
"nxtEntityId": "NXT2000001234",
"name": "releasefrom name",
"eori": "",
"tin": "releaseFrom vat"
},
"equipmentNumber": "test1234",
"equipmentType": "",
"portLoCode": "BEANR",
"terminalCode": "1234",
"actionType": "Accept",
"reasonForAction": null,
"billOfLadingNumbers": [
"BOL001",
"BOL002"
],
"releaseDatetimeUtc": "2020-12-18T14:33:42.8719897Z",
"expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
},
"errors": [],
"event": "Accepted",
"externalReferenceId": null,
"id": "test1234",
"publicReferenceId": "936678dc-c366-4785-be4a-32d39139be5e",
"receiverId": "NXT20000051292",
"senderId": null,
"timestamp": "2021-01-04T15:28:35.9434964Z",
"type": "ReleaseRight",
"warnings": []
}
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a request with a non-existing identification is performed or when the sender’s identity is different from the current owner (during transfer or revoke) or next owner (during accept or decline), a notification of type "ReleaseRight" and event "NotValidated" is sent to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": "Unable to perform SubmitReleaseRight action 'Accept' on TCLU1036476 due to invalid identification",
"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": []
}
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a request with a non-existing EquipmentNumber / BillOfLadingNumber(s) / ReleaseIdentification combination is performed, a notification of type "ReleaseRight" and event "NotValidated" is sent to
{
"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:
Webservice response
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-6ac8efacdba6f34aaf1718ce200618cd-05fdac685dad4745-00",
"errors": {
"PortLoCode": [
"'Port Lo Code' must be equal to 'BEANR'."
]
}
}
This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:
PUT - {Host}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/release-rights
Swagger linkParameters
Headers
Body
{
"releaseIdentification": "string",
"equipmentNumber": "string",
"billOfLadingNumbers": [
"string"
],
"releaseFrom": {
"identificationType": "string",
"identificationCode": "string"
},
"releaseTo": {
"identificationType": "string",
"identificationCode": "string"
},
"actionType": "Decline",
"actionReason": "string"
}
Field name | Type | Mandatory | Allowed value | Field Description |
---|---|---|---|---|
releaseIdentification | String | Yes | Free text | Unique release identification |
equipmentNumber | String | Yes | Free text | Container number |
billOfLadingNumbers | String | Yes | Free text | Bill of Lading number(s) of the container |
releaseFrom > identificationType | String | 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 | Decline | You can only use the value “Decline” 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 |
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
If the release right request was successfully processed, a notification of type "ReleaseRight" and action "Declined" is sent to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": {
"sender": {
"nxtEntityId": "NXT2000001234",
"name": "sender name",
"eori": "",
"tin": "Sender vat"
},
"carrier": {
"nxtEntityId": "NXT2000001234",
"name": "carrier name",
"eori": "",
"tin": "carrier vat"
},
"releaseTo": {
"nxtEntityId": "NXT2000001234",
"name": "releasto name",
"eori": "",
"tin": "releaseto vat"
},
"releaseFrom": {
"nxtEntityId": "NXT2000001234",
"name": "releasefrom name",
"eori": "",
"tin": "releaseFrom vat"
},
"equipmentNumber": "test1234",
"equipmentType": "",
"portLoCode": "BEANR",
"terminalCode": "1234",
"actionType": "Decline",
"reasonForAction": null,
"billOfLadingNumbers": [
"BOL001",
"BOL002"
],
"releaseDatetimeUtc": "2020-12-18T14:33:42.8719897Z",
"expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
},
"errors": [],
"event": "Declined",
"externalReferenceId": null,
"id": "test1234",
"publicReferenceId": "936678dc-c366-4785-be4a-32d39139be5e",
"receiverId": "NXT20000051292",
"senderId": null,
"timestamp": "2021-01-04T15:28:35.9434964Z",
"type": "ReleaseRight",
"warnings": []
}
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a request with a non-existing identification is performed or when the sender’s identity is different from the current owner (during transfer or revoke) or next owner (during accept or decline), a notification of type "ReleaseRight" and event "NotValidated" is sent to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": "Unable to perform SubmitReleaseRight action 'Accept' on TCLU1036476 due to invalid identification",
"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": []
}
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a request with a non-existing EquipmentNumber / BillOfLadingNumber(s) / ReleaseIdentification combination is performed, a notification of type "ReleaseRight" and event "NotValidated" is sent to
{
"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:
Webservice response
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-6ac8efacdba6f34aaf1718ce200618cd-05fdac685dad4745-00",
"errors": {
"PortLoCode": [
"'Port Lo Code' must be equal to 'BEANR'."
]
}
}
This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:
PUT - {Host}/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": "Eori",
"identificationCode": "string"
},
"actionType": "Transfer",
"reasonForAction": "string",
"releaseFrom": {
"identificationType": "Eori",
"identificationCode": "string"
},
"releaseTo": {
"identificationType": "Eori",
"identificationCode": "string"
}
}
Field name | Type | Mandatory | Allowed value | Field Description |
---|---|---|---|---|
releaseIdentification | String | No | 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. |
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
If the release right request was successfully processed, a notification of type "ReleaseRight" and action "Transfered" is sent to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": {
"sender": {
"nxtEntityId": "NXT2000001234",
"name": "sender name",
"eori": "",
"tin": "Sender vat"
},
"carrier": {
"nxtEntityId": "NXT2000001234",
"name": "carrier name",
"eori": "",
"tin": "carrier vat"
},
"releaseTo": {
"nxtEntityId": "NXT2000001234",
"name": "releasto name",
"eori": "",
"tin": "releaseto vat"
},
"releaseFrom": {
"nxtEntityId": "NXT2000001234",
"name": "releasefrom name",
"eori": "",
"tin": "releaseFrom vat"
},
"equipmentNumber": "test1234",
"equipmentType": "",
"portLoCode": "BEANR",
"terminalCode": "1234",
"actionType": "Transfer",
"reasonForAction": null,
"billOfLadingNumbers": [
"BOL001",
"BOL002"
],
"releaseDatetimeUtc": "2020-12-18T14:33:42.8719897Z",
"expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
},
"errors": [],
"event": "Transferred",
"externalReferenceId": null,
"id": "test1234",
"publicReferenceId": "936678dc-c366-4785-be4a-32d39139be5e",
"receiverId": "NXT20000051292",
"senderId": null,
"timestamp": "2021-01-04T15:28:35.9434964Z",
"type": "ReleaseRight",
"warnings": []
}
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a request with a non-existing identification is performed or when the sender’s identity is different from the current owner (during transfer or revoke) or next owner (during accept or decline), a notification of type "ReleaseRight" and event "NotValidated" is sent to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": "Unable to perform SubmitReleaseRight action 'Accept' on TCLU1036476 due to invalid identification",
"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": []
}
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a request with a non-existing EquipmentNumber / BillOfLadingNumber(s) / ReleaseIdentification combination is performed, a notification of type "ReleaseRight" and event "NotValidated" is sent to
{
"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:
Webservice response
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-6ac8efacdba6f34aaf1718ce200618cd-05fdac685dad4745-00",
"errors": {
"PortLoCode": [
"'Port Lo Code' must be equal to 'BEANR'."
]
}
}
This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:
PUT - {Host}/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": "Eori",
"identificationCode": "string"
},
"actionType": "Revoke",
"reasonForAction": "string",
"releaseFrom": {
"identificationType": "Eori",
"identificationCode": "string"
},
"releaseTo": {
"identificationType": "Eori",
"identificationCode": "string"
}
}
Field name | Type | Mandatory | Allowed value | Field Description |
---|---|---|---|---|
releaseIdentification | String | Yes | Free text | Unique release identification |
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. |
actionType | Enum | Yes | Revoke | You can only use the value Revoke when you wish to revoke 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 had sent 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 would have received 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. |
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
If the release right request was successfully processed, a notification of type "ReleaseRight" and action "Revoked" is sent to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": {
"sender": {
"nxtEntityId": "NXT2000001234",
"name": "sender name",
"eori": "",
"tin": "Sender vat"
},
"carrier": {
"nxtEntityId": "NXT2000001234",
"name": "carrier name",
"eori": "",
"tin": "carrier vat"
},
"releaseTo": {
"nxtEntityId": "NXT2000001234",
"name": "releasto name",
"eori": "",
"tin": "releaseto vat"
},
"releaseFrom": {
"nxtEntityId": "NXT2000001234",
"name": "releasefrom name",
"eori": "",
"tin": "releaseFrom vat"
},
"equipmentNumber": "test1234",
"equipmentType": "",
"portLoCode": "BEANR",
"terminalCode": "1234",
"actionType": "Revoke",
"reasonForAction": null,
"billOfLadingNumbers": [
"BOL001",
"BOL002"
],
"releaseDatetimeUtc": "2020-12-18T14:33:42.8719897Z",
"expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
},
"errors": [],
"event": "RevokedByPreviousParty",
"externalReferenceId": null,
"id": "test1234",
"publicReferenceId": "936678dc-c366-4785-be4a-32d39139be5e",
"receiverId": "NXT20000051292",
"senderId": null,
"timestamp": "2021-01-04T15:28:35.9434964Z",
"type": "ReleaseRight",
"warnings": []
}
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a request with a non-existing identification is performed or when the sender’s identity is different from the current owner (during transfer or revoke) or next owner (during accept or decline), a notification of type "ReleaseRight" and event "NotValidated" is sent to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": "Unable to perform SubmitReleaseRight action 'Accept' on TCLU1036476 due to invalid identification",
"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": []
}
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a request with a non-existing EquipmentNumber / BillOfLadingNumber(s) / ReleaseIdentification combination is performed, a notification of type "ReleaseRight" and event "NotValidated" is sent to
{
"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": []
}
Webservice response
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a revoke is performed on on a releaseright that is not ‘pending’ (awaiting accept or decline) but instead is f.e. active, a notification of type "ReleaseRight" and event "NotValidated" is sent to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": ""Unable to perform SubmitReleaseRight action 'Revoke' on TCLU1036476 because Release right is not 'Pending' but 'Accepted'",
"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:
Webservice response
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-6ac8efacdba6f34aaf1718ce200618cd-05fdac685dad4745-00",
"errors": {
"PortLoCode": [
"'Port Lo Code' must be equal to 'BEANR'."
]
}
}
This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:
It is possible to send multiple actions with a single request by using this bulk method. The following actions are supported:
PUT - {Host}/certified-pickup/v1/{port-locode}/containers/import/release-rights
Swagger linkParameters
Body
{
"portLoCode": "string",
"releaseRights": [
{
"releaseFrom": {
"identificationType": "NxtEntityId",
"identificationCode": "string"
},
"releaseTo": {
"identificationType": "NxtEntityId",
"identificationCode": "string"
},
"terminalCode": "string",
"billOfLadingNumbers": [
"string"
],
"equipmentNumber": "string",
"releaseIdentification": "string"
}
],
"actionType": "Transfer"
}
Field Name | Type | Mandatory | Allowed Value | Field Description |
---|---|---|---|---|
portLocode | String | Yes | UNLocode | Use the UNLocode of the port. For Antwerp, this is BEANR |
releaseRights | Array of ReleaseRights to which the ReleaseRight action should be applied | Yes (at least one) | N/A | |
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. |
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. |
terminalCode | String | Yes | Free text | The terminal where the container will be available for pickUp. |
billOfLadingNumbers | Array of strings | Yes | Free text | The unique combination of Container/BL/ReleaseIdentification will be used for the identification of the Container Release |
equipmentNumber | String | Yes | Free text | Container number |
releaseIdentification | String | Yes | Free text | Unique release identification |
actionType | Enum | Yes | Transfer / Accept / Decline / Revoke |
When the 202 result is returned, the right to Pick up the container will be granted to your entity.
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
A notification of type ReleaseRight with event Transferred, Accepted or Declined will be to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": {
"sender": {
"nxtEntityId": "NXT20000012345",
"name": "sender name",
"eori": "",
"tin": "sender vat"
},
"carrier": {
"nxtEntityId": "NXT20000012345",
"name": "carrier name",
"eori": "",
"tin": "carrier vat"
},
"releaseTo": {
"nxtEntityId": "NXT20000012345",
"name": "releaseto name",
"eori": "",
"tin": "release to vat"
},
"releaseFrom": {
"nxtEntityId": "NXT20000013245",
"name": "release form name",
"eori": "",
"tin": "release from vat"
},
"equipmentNumber": "test1234",
"equipmentType": "",
"portLoCode": "BEANR",
"terminalCode": "12345",
"actionType": "Transfer",
"reasonForAction": null,
"billOfLadingNumbers": [
"BOL001",
"BOL002"
],
"releaseDatetimeUtc": "2020-12-18T14:33:42.8719897Z",
"expirationDatetimeUtc": "2022-05-27T08:16:01.642Z"
},
"errors": [],
"event": "Transferred",
"externalReferenceId": null,
"id": "test1234",
"publicReferenceId": "936678dc-c366-4785-be4a-32d39139be5e",
"receiverId": "NXT20000012345",
"senderId": null,
"timestamp": "2021-01-04T15:28:35.9434964Z",
"type": "ReleaseRight",
"warnings": []
}
Response from the webservice
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a SubmitReleaseRightAction with a non-existing identification is performed or when the sender’s identity is different from the current owner (during transfer, revoke) or next owner (during accept, decline), a notification of type ReleaseRight with event NotValidated will be sent to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": "Unable to perform SubmitReleaseRight action 'Accept' on TCLU1036476 due to invalid identification",
"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": []
}
Response from the webservice
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a SubmitReleaseRightAction with a non-existing identification is performed or when the sender’s identity is different from the current owner (during transfer, revoke) or next owner (during accept, decline), a notification of type ReleaseRight with event NotValidated will be sent to
{
"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": []
}
Response from the webservice
{
"publicReferenceId": "GUID",
"externalReferenceId": "string"
}
Notifications
When a SubmitReleaseRight revoke is performed on on a releaseright that is not ‘pending’ (awaiting accept or decline) but instead is f.e. active, a notification of type ReleaseRight with event NotValidated will be sent to
{
"assetId": "00000000-0000-0001-0000-000000000037",
"body": ""Unable to perform SubmitReleaseRight action 'Revoke' on TCLU1036476 because Release right is not 'Pending' but 'Accepted'",
"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:
The below error message will be sent to your notification channel(s)
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-6ac8efacdba6f34aaf1718ce200618cd-05fdac685dad4745-00",
"errors": {
"PortLoCode": [
"'Port Lo Code' must be equal to 'BEANR'."
]
}
}
This error indicates that you do not have the rights to perform the requested action.To overcome this, please make sure that you are:
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"
}
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:
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": {}
}
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
{
"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'."
]
}
}
When your company is the (current) owner of the Release Right, you can assign a driver for the pick up of the container at the terminal. This driver needs to have a valid Alfapass.
PUT - {Host}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/pickup-rights
Swagger linkParameters
Headers
Body
{
"equipmentNumber": "string",
"portLocode": "string",
"terminalCode": "string",
"billOfLadingNumbers": [
"string"
],
"actionType": "Assign",
"releaseidentification": "string",
"pickupParty": {
"partyType": "Truck",
"identificationType": "alfapass",
"identificationCode": "0123456"
},
"timestamp": "2020-05-20T21:47:03.931Z"
}
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 | No | Free text | The terminal where the container will be available for pickUp. Can be updated later on in the process |
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 | Assign | You can only use the value Transfer when you wish to transfer the Release Right |
pickupParty > partyType |
String | Yes |
Truck Barge Rail |
Enter the type of the mode of transport |
pickupParty > identificationType |
String | Yes | alfapass |
Enter the type of the method used to identify the Pick up party. Currently only "alfapass" is allowed as value.
|
pickupParty > identificationCode |
String | Yes | Free text |
The code that is linked to the given identificationType. In case of alfapass, this is the number of the alfapass that is unique to the owner of the pass. If an invalid code is provided, this will return an error message to your notification channel. |
timestamp | DateTimeUTC | Yes | Date Time | Timestamp when you send the assign the pick up right to the driver |
When the 200 result is returned, your request has been successfully received.
{
"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": {}
}
When you wish to update the driver (or the mode of transport in the future) that is selected to perform the Pick up, you can update the Pick up Right owner. This will Revoke the right from the current assigned driver and recreate a new pick up right for the new driver. Obviously, the new driver needs to have a valid Alfapass.
PUT - {Host}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/pickup-rights
Swagger linkParameters
Headers
{
"equipmentNumber": "string",
"portLocode": "string",
"terminalCode": "string",
"billOfLadingNumbers": [
"string"
],
"actionType": "Update",
"pickupParty": {
"partyType": "Truck",
"identificationType": "alfapass",
"identificationCode": "0123456"
},
"timestamp": "2020-05-20T21:47:03.931Z"
}
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 | No | Free text | The terminal where the container will be available for pickUp. Can be updated later on in the process |
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 | Update | You can only use the value Update when you wish to update the Release Right |
pickupParty > partyType |
String | Yes | Truck Barge Rail | Enter the type of the mode of transport |
pickupParty > identificationType |
String | Yes | alfapass |
Enter the type of the method used to identify the Pick up party. Currently only "alfapass" is allowed as value.
|
pickupParty > identificationCode |
String | Yes | Free text |
The code that is linked to the given identificationType. In case of alfapass, this is the number of the alfapass that is unique to the owner of the pass. If an invalid code is provided, this will return an error message to your notification channel. |
timestamp | DateTimeUTC | Yes | Date Time | Timestamp when you send the assign the pick up right to the driver |
When the 200 result is returned, your request has been successfully received.
{
"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": {}
}
In case you have already sent out the Pick up right to a driver and the container has not yet been picked up, you can revoke the right.
PUT - {Host}/certified-pickup/v1/{port-locode}/containers/{equipment-number}/import/pickup-rights
Swagger linkParameters
Headers
Body
{
"equipmentNumber": "string",
"portLocode": "string",
"terminalCode": "string",
"billOfLadingNumbers": [
"string"
],
"actionType": "Revoke",
"timestamp": "2020-05-20T21:47:03.931Z"
}
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 | No | Free text | The terminal where the container will be available for pickUp. Can be updated later on in the process |
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 |
timestamp | DateTimeUTC | Yes | Date Time | Timestamp when you send the assign the pick up right to the driver |
When the 200 result is returned, your request has been successfully received.
{
"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": {}
}