Logistics Service Provider integration specifications
Terminal delivery order
Create terminal delivery order
Before having the goods arrive at the terminal, it is important for the logistics service provider to register them in Bulkchain via a terminal delivery order, as this is the starting point for all follow-up processes within Bulkchain.
A logistics service provider has the possibility to create:
a terminal delivery order without the goods (= stock keeping units) nor visits, or
a terminal delivery order only having the goods defined, without any visits, or
a terminal delivery order only having the visits defined, without any goods, or
a terminal delivery order with having both the visits and the goods on those visits defined. In this last case, the goods can be cross referenced with the visits so that it’s clear for the terminal which SKU(‘s) will be delivered per Visit.
Note that a Terminal Delivery Confirmation can only be successful when the SKU’s are assigned to the Visit!
Sequence diagram for ‘Create Terminal Delivery Order as logistics service provider’
Key input data elements and validation rules
TDO
Attribute | Description | Mandatory | Validation rule | Error reason |
lspReference | Unique reference for the TDO chosen by the LSP. | Yes | Must be unique in combination with lspNxtEntityId (of caller) within Bulkchain/ORP domain. | BCBV0001 |
terminalOperator | Terminal identifier where the goods will be delivered. | Yes | Must be registered for Bulkchain. | BCBV0002 |
weight | Expected weight the LSP would like to deliver in tons. | No | Field type restriction validation. | BCTV0001 |
portOfDestination | Final destination for the sea transport of the cargo that will be delivered. | No | Field type restriction validation. Must be 5 capital characters. | BCTV0001 |
commodityDescription | Free text description for the breakbulk cargo that will be delivered. | No | Field type restriction validation. | BCTV0001 |
expectedDeliveryDateTimeFrom | Date and timestamp from when the delivery is expected. | No | Must be in the future. | BCTV0002 |
expectedDeliveryDateTimeTo | Date and timestamp until when the delivery is expected. | No | Must be after expectedDeliveryDateTimeFrom. | BCTV0003 |
Please find the full spec: https://documentation.nxtport.com/bulckchain/open-api-specification-swagger
SKU
Attribute | Description | Mandatory | Validation rule | Error reason |
skuIdentificationCode | Reference for the SKU provided by the LSP or TO. This can be a barcode for example. | No | In case numberOfSku > 1, the amount of skuIdentificationCode should be equal to the numberOfSKU. | BCTV0001 |
commodityDescription | Free text description for the breakbulk cargo that is being handled. | No | Field type restriction validation. | BCTV0001 |
numberOfPieces | Number of pieces that the SKU consists of. This can be for example the “said to contain boxes”. | Yes | Must be at least 1. | BCTV0004 |
status | Outbound status for the SKU; this can be “exit” or “storage”. | Yes | Validated based on enum. | BCTV0001 |
incoTerms | International commercial terms. | Yes (conditional) | Rule 1: Validated based on enum Rule 2: Mandatory if status= “exit”. Otherwise, it cannot be provided. | Rule 1: BCTV0001 Rule 2: BCTV0006 |
bookingNumber | Reference number for the shipment booking that had been made with the Ship Agent. | Yes (conditional) | Mandatory if status= “exit”. Otherwise, it cannot be provided. | BCTV0006 |
packageCode | Code used to reference the packaging used or the SKU. | Yes | Validated with “CL017” codelist from Customs Authority: https://financien.belgium.be/sites/default/files/Customs/Ondernemingen/Applicaties/technische-documentatie/PNTS/pn-ts-dev-messsage-implementation-guide-v1.2.0.docx | BCBV0024 |
packageDescription | Free text description for the packaging used for the SKU. | No | Field type restriction validation | BCTV0001 |
marksAndNumbers | Marks and numbers that are visually added to the physical SKU, in order to be able to identify on terminal. | No | Field type restriction validation | BCTV0001 |
portOfDestination | Final destination for the sea transport of the SKU. | Yes (conditional) | Mandatory if status= “exit”. Otherwise, it cannot be provided. Must be 5 capital characters. | BCTV0006 |
weight | Weight of the SKU in kg. | Yes | Field type restriction validation. | BCTV0001 |
length | Length of the SKU in cm. | No | Field type restriction validation. | BCTV0001 |
width | Width of the SKU in cm. | No | Field type restriction validation. | BCTV0001 |
height | Height of the SKU in cm. | No | Field type restriction validation. | BCTV0001 |
handlingInstruction | Free text description that contains the instruction for how to properly handle the SKU. | No | Field type restriction validation. | BCTV0001 |
storageInstruction | Free text description that contains the instruction for how to properly store the SKU on the terminal. | No | Field type restriction validation. | BCTV0001 |
loadingInstruction | Free text description that contains the instruction for how to properly load the SKU on the ship. | No | Field type restriction validation. | BCTV0001 |
stowageInstruction | Free text description that contains the instruction for how to properly stow the SKU on the ship. | No | Field type restriction validation. | BCTV0001 |
goodsConditions | Description that contains the actual condition for a SKU. For example a SKU can be damaged, not sea worthy or any other state of the SKU that is worth registering in Bulkchain. | No | Field type restriction validation. | BCTV0001 |
dangerDescription | Free text description that contains any relevant information in case the SKU is a dangerous good. | No | Field type restriction validation. | BCTV0001 |
Please find the full spec: https://documentation.nxtport.com/bulckchain/open-api-specification-swagger
Visit
Attribute | Description | Mandatory | Validation rule | Error reason |
lspVisitReference | Reference for the Visit provided by the LSP. | Yes | Must be unique in combination with lspNxtEntityId. | BCBV0005 |
modeOfTransport | Indication of the transport mode the cargo will be delivered with to the terminal. | Yes | Validation based on enum. This can be Truck, Barge or Rail | BCTV0001 |
transportIdentificationCode | Free text description that can be used to reference a license plate, barge name, wagon number,… | No | Field type restriction validation. | BCTV0001 |
transportOperator | Identifier value for the transport operator company that can be VAT number,… | No | Field type restriction validation. | BCTV0001 |
terminalCode | Terminal code that enables to identify the physical location of the Terminal within a Port. | Yes | Correlation validated with the Terminal Operator element in TDO and according to following list: Terminalcodes.pdf | BCBV0006 |
portLoCode | Port location code that enables to identify the port where the terminal is located. | Yes | Correlation validated with the Terminal Operator element in TDO. Must be 5 capital characters. | BCBV0007 |
deliveryDateTime | Date and timestamp when the visit for delivery is expected to arrive. | Yes | Must be in the future. | BCTV0002 |
Please find the full spec: https://documentation.nxtport.com/bulckchain/open-api-specification-swagger
Key output data elements
Below data elements will be created as a result of a successful operation in Bulkchain:
Attribute | Description |
correlationId | Unique functional reference that enables to correlate the original request with subsequent asynchronous notifications. |
tdoKey | Bulkchain generated unique key for the Terminal Delivery Order. This key is used throughout the Bulkchain application to identify the TDO. |
skuKey | Bulkchain generated unique key for the Stock Keeping Unit. This key is used throughout the Bulkchain application to identify the SKU. |
visitKey | Bulkchain generated unique key for the Visit. This key is used throughout the Bulkchain application to identify the Visit. |
These keys must be used in any following operation on the respective object in Bulkchain (Get, Update and Delete).
Get list of terminal delivery orders
Both the logistics service provider and the terminal operator have the possibility to retrieve the dataset of either specific terminal delivery orders, or of all terminal delivery orders which were created in the last 30 days. Specific TDO’s can be requested by its respective Bulkchain-generated TDO Keys, Bulkchain will validate if the TDO Keys exist for the requester and if the requester is allowed to retrieve them.
If one or more TDO’s can be found, Bulkchain will respond synchronously by providing the full datasets of either the specifically requested terminal delivery orders, or the full datasets of the terminal delivery orders created in the last 30 days, all within one feedback response.
If no TDO can be found, Bulkchain will respond with a synchronous empty response.
Sequence diagram for ‘Get list of Terminal Delivery Orders as logistics service provider’
Update of the terminal delivery order
After the terminal delivery order has been created by the logistics service provider, both the logistics service provider and the terminal operator have the possibility to update that same terminal delivery order.
As a logistics service provider, the following update use cases are possible within a specific terminal delivery order:
Update its general information
Add a new stock keeping unit
Delete an existing stock keeping unit
Add a new visit
Delete an existing visit
Update an existing visit
Assign a stock keeping unit to a visit
Unassign a stock keeping unit from a visit
Important to consider is the fact that Bulkchain only supports the usage of the Bulkchain-generated keys (TDO Key, SKU Key, Visit Key) for any update/delete/assign/unassign operation within Bulkchain on existing objects. These keys are available in the success notifications, please go to https://documentation.nxtport.com/bulckchain/success-notifications for more information.
Across all update use cases, the general principle is that the request starts for one specific terminal delivery order by providing the TDO Key, which needs to exist in Bulkchain and which needs to be linked to the requester.
Sequence diagram for ‘Update Terminal Delivery Order as logistics service provider’
Update general terminal delivery order info
Here, the same technical input validation and business validation rules apply as in the flow regarding the creation of the terminal delivery order: https://documentation.nxtport.com/bulckchain/logistics-service-provider-integration-specificati#LogisticsServiceProviderintegrationspecifications-Keyinputdataelementsandvalidationrules.
Note that the following information cannot be updated by the logistics service provider:
The TDO Key
The terminal operator information
The reference of the terminal operator for the terminal delivery order
Bulkchain will send a notification of the update success towards the original requester, being the logistics service provider, and the terminal operator, including the original TDO Key as unique reference for the respective updated terminal delivery order. Via this TDO Key, the updated full dataset of the related terminal delivery order can be retrieved from Bulkchain.
Add new SKU
Here, the same technical input validation and business validation rules apply on the stock keeping unit (SKU) as in the flow for the creation of the terminal delivery order: https://documentation.nxtport.com/bulckchain/logistics-service-provider-integration-specificati#LogisticsServiceProviderintegrationspecifications-Keyinputdataelementsandvalidationrules.
However, in this use case there is no possibility to link/assign the stock keeping unit to a visit. To link/assign the newly created stock keeping unit to a visit, please go to https://documentation.nxtport.com/bulckchain/logistics-service-provider-integration-specificati#LogisticsServiceProviderintegrationspecifications-AssignSKUtovisitintheterminaldeliveryorder.
Bulkchain will send a notification of the addition success towards the original requester, being the logistics service provider, and the terminal operator, including the original TDO Key as unique reference for the respective terminal delivery order, as well as the generated SKU Key for the newly created stock keeping unit.
Via the TDO Key, the updated full dataset of the related terminal delivery order can be retrieved from Bulkchain.
Delete SKU
The logistics service provider also has the option to delete a stock keeping unit, by providing the SKU Key within its request, while considering the following business validation rule:
The stock keeping unit should not be already confirmed via a terminal delivery confirmation from the terminal operator.
Bulkchain will send a notification of the deletion success towards the original requester, being the logistics service provider, and the terminal operator, including the original TDO Key as unique reference for the respective terminal delivery order, as well as the SKU Key representing the stock keeping unit which was deleted.
Via the TDO Key, the updated full dataset of the related terminal delivery order can be retrieved from Bulkchain.
Add new visit in the terminal delivery order
Here, the same technical input validation and business validation rules apply as in the flow regarding the creation of the terminal delivery order. Stock keeping units, that are already existing in the same terminal delivery order, can be linked to that new visit as long as they don’t have a terminal delivery confirmation yet.
Bulkchain will send a notification of the addition success towards the original requester, being the logistics service provider, and the terminal operator, including the original TDO Key as unique reference for the respective terminal delivery order, as well as the generated Visit Key for the newly created visit.
Via the TDO Key, the updated full dataset of the related terminal delivery order can be retrieved from Bulkchain.
Delete visit in the terminal delivery order
The logistics service provider also has the option to delete a visit from a specific terminal delivery order, by providing the Visit Key within its request, while considering the following business validation rules:
The visit which the requester intends to delete, should exist within the respective terminal delivery order.
Next to that, the visit should not be already confirmed via a terminal delivery confirmation from the terminal operator.
Bulkchain will send a notification of the deletion success towards the original requester, being the logistics service provider, and the terminal operator, including the original TDO Key as unique reference for the respective terminal delivery order, as well as the Visit Key representing the visit which was deleted.
Via the TDO Key, the updated full dataset of the related terminal delivery order can be retrieved from Bulkchain.
Update visit info in the terminal delivery order
Here, the same technical input validation and business validation rules apply as in the flow regarding the creation of the terminal delivery order, next to that:
The visit which the requester intends to update, should exist within the respective terminal delivery order.
The visit should not be already confirmed via a terminal delivery confirmation from the terminal operator.
Note that the following information cannot be updated by the logistics service provider:
The Visit Key
The reference of the terminal operator for the visit
Bulkchain will send a notification of the update success towards the original requester, being the logistics service provider, and the terminal operator, including the original TDO Key as unique reference for the respective terminal delivery order, as well as the Visit Key representing the visit which was updated.
Via the TDO Key, the updated full dataset of the related terminal delivery order can be retrieved from Bulkchain.
Assign SKU to visit in the terminal delivery order
The logistics service provider has the possibility to assign an existing stock keeping unit to an existing visit within the same terminal delivery order. For this, the following business validation rules need to be considered:
It is important to know that both the stock keeping unit as the visit need to exist in the same terminal delivery order, and
That the stock keeping unit should not be assigned already to another visit. In that case, the stock keeping unit should first be unassigned from that other visit.
Bulkchain will send a notification of the assignment success towards the original requester, being the logistics service provider, and the terminal operator, including the original TDO Key as unique reference for the respective terminal delivery order, as well as the Visit Key representing the visit to which the stock keeping unit was assigned.
Via this TDO Key, the updated full dataset of the related terminal delivery order can be retrieved from Bulkchain.
Unassign SKU from visit in the terminal delivery order
The logistics service provider has the possibility to unassign an already assigned stock keeping unit from its visit within the same terminal delivery order. For this, the following business validation rules need to be considered:
The stock keeping unit and the visit need to exist in the same terminal delivery order, and
The stock keeping unit should already be assigned to that visit, before being able to be unassigned from it, and
The stock keeping unit cannot be unassigned from the visit if it already received a terminal delivery confirmation from the terminal operator.
Bulkchain will send a notification of the unassignment success towards the original requester, being the logistics service provider, and the terminal operator, including the original TDO Key as unique reference for the respective terminal delivery order, as well as the Visit Key representing the visit from which the stock keeping unit was unassigned.
Update SKU
The logistics service provider has the ability to update the properties of a stock keeping unit and can register a Goods Condition.
Sequence diagram for ‘Update Stock Keeping Unit as logistics service provider’
Update SKU info
The logistics service provider has the option to update a stock keeping unit by providing the SKU Key within its request, while considering the following business validation rules:
The same technical input validation rules apply on the stock keeping unit as in the flow for the creation of the terminal delivery order (https://documentation.nxtport.com/bulckchain/logistics-service-provider-integration-specificati#LogisticsServiceProviderintegrationspecifications-Createterminaldeliveryorder), except that the mandatory attributes now become optional. Attributes incoTerms, bookingNumber and portOfDestination are still conditionally mandatory following the business validation rules.
Also, the SKU Key cannot be updated.
Lastly, in this use case there is no possibility to link/assign the stock keeping unit to another visit. To link/assign a stock keeping unit to a visit, please go to https://documentation.nxtport.com/bulckchain/logistics-service-provider-integration-specificati#LogisticsServiceProviderintegrationspecifications-AssignSKUtovisitintheterminaldeliveryorder.
Bulkchain will send a notification of the update success towards the original requester, being the logistics service provider, and the terminal operator, including the SKU Key representing the stock keeping unit which was updated.
Via the SKU Key, the updated full dataset of the related stock keeping unit can be retrieved from Bulkchain.
Add goods condition to SKU
The logistics service provider has the possibility to add a goods condition to a stock keeping unit, following business validation rules need to be considered:
The stock keeping unit needs to exist within the terminal delivery order, and
The goods condition type and description need to be in conformity with the input validation rules as specified in the flow for creating a terminal delivery order.
Bulkchain will send a notification of the addition success towards the original requester, being the logistics service provider, and the terminal operator, including the original TDO Key as unique reference for the respective terminal delivery order, as well as the SKU Key representing the stock keeping unit for which a goods condition was added.
Deletion of the terminal delivery order
After the terminal delivery order has been created by the logistics service provider, it has the possibility to delete that same terminal delivery order.
Important to consider is the fact that Bulkchain only supports the usage of the Bulkchain-generated keys (TDO Key, SKU Key, Visit Key) for any update/delete/assign/unassign operation within Bulkchain on existing objects. These keys are available in the success notifications, please go to https://documentation.nxtport.com/bulckchain/success-notifications for more information.
Sequence diagram for ‘Delete Terminal Delivery Order as logistics service provider’
Upon successful technical validation by Bulkchain, asynchronous processing will be done by Bulkchain. Here, a set of business rules will be validated upon the received request:
Check that the terminal delivery order exists for the logistics service provider which has submitted the request, and
There cannot be a terminal delivery confirmation for one of the stock keeping units defined in that terminal delivery order.
In case one or more business validation errors are triggered, a notification will be sent out towards the original requester. This notification will contain a full list of business validation errors that have been encountered. For the full list of business rules and the related error codes, please refer to https://documentation.nxtport.com/bulckchain/technical-and-business-validation#Technicalandbusinessvalidation-Businessvalidation.
When the business validation has passed, Bulkchain will send a notification of the deletion success towards the original requester, being the logistics service provider, and the terminal operator, including the original TDO Key as unique reference for the respective terminal delivery order.