Terminal Operator integration specifications

Terminal delivery order

To understand the context of how a Logistics Service Provider can manage a Terminal Delivery Order, please review https://documentation.nxtport.com/bulckchain/logistics-service-provider-integration-specificati. Below page is limited to the capabilities available for a Terminal Operator.

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.

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 terminal operator, the following update use cases are possible within a specific terminal delivery order:

• Update its general information (i.e., adding a terminal operator reference)

• Update an existing visit (i.e., adding a terminal operator reference)

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.

Update general terminal delivery order info

The terminal operator only has the option to add its own reference to the terminal delivery order.

Bulkchain will send a notification of the update success towards the original requester, being the terminal operator, and the logistics service provider, 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.

Update visit info in the terminal delivery order

The terminal operator only has the option to add its own reference to the visit.

Bulkchain will send a notification of the update success towards the original requester, being the terminal operator, and the logistics service provider, 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 this TDO Key, the updated full dataset of the related terminal delivery order can be retrieved from Bulkchain.

Terminal delivery confirmation

Once a specific visit from a terminal delivery order arrives at the terminal with its respective stock keeping units, the terminal operator needs to submit a terminal delivery confirmation for the stock keeping units on that visit, indicating that the stock keeping units have arrived and were well-received at the terminal.

When the visit arrives, the terminal operator has the possibility to confirm:

1. the full set of stock keeping units which were originally defined on that visit within the terminal delivery order, or

2. a subset of stock keeping units which were originally defined on that visit within the terminal delivery order, in case there were less stock keeping units on the physical transport. Both options are possible via the same message request.

In case there are (3) more stock keeping units on the physical transport than originally defined for that visit within the terminal delivery order, the terminal operator can only confirm the stock keeping units which exist in the terminal delivery order and that are planned on the Visit. Regarding the additional stock keeping units, they first need to be assigned by the logistics service provider for that visit, before the terminal operator can submit a new terminal delivery confirmation for them.

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 visit exists for the terminal operator which has submitted the request, and

• Check there’s no terminal delivery confirmation yet for one of the stock keeping units which is linked to that visit, and

• In case the terminal operator mentions a specific set of stock keeping units, these need to exist and be linked to the abovementioned visit, while not having a terminal delivery confirmation already.

When the business validation has passed, Bulkchain will send a notification of the terminal delivery confirmation success towards the original requester, being the terminal operator and the logistics service provider, including the original TDO Key as unique reference for the respective terminal delivery order, the TDC Key as unique reference for the respective terminal delivery confirmation and the Visit Key as unique reference for the respective visit.

Update of the stock keeping unit during the terminal stay

Once a specific stock keeping unit has been confirmed by the terminal operator, they get the ability to update that stock keeping unit. For the logistics service provider, the update remains possible as before the terminal delivery confirmation https://documentation.nxtport.com/bulckchain/logistics-service-provider-integration-specificati#LogisticsServiceProviderintegrationspecifications-UpdateSKUinfo.

As a terminal operator, the following update use cases are possible for a specific stock keeping unit:

• Update properties which physically describe the stock keeping unit

  • Identification code

  • Commodity description

  • Number of pieces within the stock keeping unit

  • Package code

  • Package description

  • Marks and numbers

  • Weight

  • Length

  • Width

  • Height

• Add a goods condition

Important to consider is the fact that Bulkchain only supports the usage of the Bulkchain-generated keys (TDO Key, SKU Key) for any update operation within Bulkchain on existing objects.

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, depending on the update use case:

• The SKU Key cannot be updated, as this is used as reference to indicate which stock keeping unit needs to be updated, and

• That it’s linked to that terminal operator, and

• It has received a terminal delivery confirmation, and

• Attributes an update is requested for are limited to those listed above, for input validation rules on the updateable attributes, please refer to https://documentation.nxtport.com/bulckchain/logistics-service-provider-integration-specificati#LogisticsServiceProviderintegrationspecifications-Keyinputdataelementsandvalidationrules.

• For Goods Condition: 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 https://documentation.nxtport.com/bulckchain/logistics-service-provider-integration-specificati#LogisticsServiceProviderintegrationspecifications-Keyinputdataelementsandvalidationrules.

In case one or more business validation errors are triggered, a notification will be sent out towards the 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.

In case the business validation has passed and thus the message is successfully processed, Bulkchain will perform the needed updates without any approvals and afterwards send out a notification indicating the success of the request towards both the logistics service provider and the terminal operator, please refer to https://documentation.nxtport.com/bulckchain/success-notifications.