Logistics Service Provider integration specifications

Terminal Delivery Order (TDO)

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:

1. a terminal delivery order, without stock keeping units nor visits, or

2. a terminal delivery order only having the stock keeping units defined, without any visits, or

3. a terminal delivery order only having the visits defined, without any stock keeping units, or

4. a terminal delivery order with having both the visits and the stock keeping units on those visits defined. In this last case, the stock keeping units 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.

Key input data elements and validation rules

TDO

Please find the full spec: https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

SKU

Please find the full spec: https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

Visit

Please find the full spec: https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

Key output data elements

Below data elements will be created as a result of a successful operation in Bulkchain:

These keys must be used in any following operation on the respective object in Bulkchain (Get, Update and Delete).

Get (list of) terminal delivery order(s)

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.

Get (list of) stock keeping unit(s)

Both the logistics service provider and the terminal operator have the possibility to retrieve the stock keeping unit(s) dataset for either:

1. a specific stock keeping unit, or

2. a terminal delivery order, or

3. a get of all stock keeping units which were created in the last 30 days.

Specific stock keeping units can be requested by its respective Bulkchain-generated keys, Bulkchain will validate if the SKU Key or TDO Key exist for the requester and if the requester is allowed to retrieve them.

If one or more stock keeping units can be found, Bulkchain will respond synchronously by providing the full datasets of either the specifically requested stock keeping unit(s), or the full datasets of the stock keeping units created in the last 30 days, all within one feedback response.

If no stock keeping unit can be found, Bulkchain will respond with a synchronous empty response.

Get (list of) visit(s)

Both the logistics service provider and the terminal operator have the possibility to retrieve the visit(s) dataset for either:

1. a specific visit, or

2. a terminal delivery order, or

3. a get of all visits which were created in the last 30 days.

Specific visits can be requested by its respective Bulkchain-generated keys, Bulkchain will validate if the Visit Key or TDO Key exist for the requester and if the requester is allowed to retrieve them.

If one or more visits can be found, Bulkchain will respond synchronously by providing the full datasets of either the specifically requested visit(s), or the full datasets of the visits created in the last 30 days, all within one feedback response.

If no visit 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 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/bulkchain/success-notifications for more information.

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/bulkchain/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/bulkchain/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/bulkchain/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. Via the SKU Key, the dataset for the created SKU object can be retrieved from the database.

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.

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/bulkchain/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/bulkchain/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, Goods Reservation 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/bulkchain/success-notifications for more information.

As a result of a Delete TDO operation, all related objects such as Goods Reservation, SKU and Visit will be deleted as well.

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/bulkchain/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.

Vessel Load Order (VLO)

Purpose

A Vessel Load Order (VLO) is used by a Logistics Service Provider (LSP) to plan which outbound cargo (SKU’s) will be loaded onto a sea-going vessel. The VLO is then progressively shared with:

• the Ship Agent (SA) for review and further enrichment,

• and later the Terminal Operator (TO) for execution/loading follow-up.

VLO lifecycle (states)

A VLO progresses through the following states:

• Draft (created by LSP; not yet shared)

• Master Permit (shared by LSP with SA)

• Loading Permit (shared by SA with TO)

• Mate’s Receipt (set by TO)

• Final Mate’s Receipt (set by TO)

Note: Depending on role, Bulkchain restricts which VLO’s can be retrieved and which state transitions can be triggered.

Create Vessel Load Order

When to use

Create a VLO when you want to announce which cargo (SKU’s) will be loaded on a vessel, and which Ship Agent and Terminal Operator are involved.

Important behavior

• Processing is asynchronous:

  • If authorization + schema validation pass, Bulkchain responds synchronously with 202 Accepted and a correlationId.

  • Business validation and creation happen asynchronously and result in a notification.

• The initial VLO state depends on isConfirmed:

  • isConfirmed=false → VLO is created in Draft

  • isConfirmed=true → VLO is created in Master Permit (and is immediately shared with the Ship Agent)

Key input data elements and validation rules (Create VLO)

SKU assignment business rules (applied when skuKey[] is provided)

• SKU must exist and belong to the calling LSP.

• SKU must not already be assigned to another VLO.

• SKU portOfDestination must match the VLO portOfDestination (if present on SKU).

• SKU status must be exit.

• SKU Terminal Operator must match the VLO Terminal Operator.

Key output

API specification

See the full OpenAPI specification here:
https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

Get (list of) Vessel Load Order(s)

When to use

Retrieve:

• a specific VLO (by vloKey), or

• a list of VLO’s using optional filters, or

• all VLO’s from the last 30 days (default “get all” behavior).

Important behavior

• This operation is handled synchronously.

• Access scope depends on your role. As LSP, you can retrieve VLO’s linked to your company across all states.

Supported filters

• vloKey (specific VLO)

• lspReference

• permitNumber

• no filters → “get all” for the last 30 days

API specification

See the full OpenAPI specification here:
https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

Update Vessel Load Order (as LSP)

Supported update use cases

As LSP you can:

• Update general VLO info (limited set of fields)

• Assign SKU(s) to the VLO

• Unassign SKU(s) from the VLO

• Share the VLO with the Ship Agent (state change to Master Permit)

Important behavior

• Processing is asynchronous (same pattern as Create): 202 + correlationId synchronously, outcome via notification.

• A single update request must target exactly one VLO (vloKey).

Update general VLO info (allowed fields)

You can update:

• lspReference

• vesselName

• voyageNumber

• permitNumber

You cannot update (if these change, create a new VLO instead):

• terminalCode

• portOfLoading

• portOfDestination

• shipAgent

Assign SKU(s)

• Provide one or more skuKey.

• The same SKU business rules apply as in Create VLO.

Unassign SKU(s)

• A SKU can only be unassigned if it is currently assigned to the VLO.

Share VLO with Ship Agent

• Provide isConfirmed=true

• At least one SKU must already be assigned to the VLO.

API specification

See the full OpenAPI specification here:
https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

Delete Vessel Load Order (as LSP)

When to use

Delete a VLO when it is no longer valid.

Important behavior

• Processing is asynchronous (same pattern as Create/Update).

• Deletion is a soft delete of the VLO (SKU’s themselves are not deleted).

• Notification recipients depend on the current VLO state:

  • LSP always receives a notification

  • SA receives it if state is Master Permit or later

  • TO receives it if state is Loading Permit or later

API specification

See the full OpenAPI specification here:
https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

Small happy flow (end-to-end)

Happy flow — Create and execute a Vessel Load Order

1. LSP creates a VLO as Draft

   • LSP calls Create VLO with isConfirmed=false

   • Bulkchain returns 202 Accepted + correlationId (async outcome via notification)

2. LSP assigns SKU(s) to the VLO

   • LSP calls Update VLO (assign SKU(s))

   • Bulkchain returns 202 Accepted + correlationId (async outcome)

3. LSP shares VLO with Ship Agent (SA)

   • LSP calls Update VLO (share with SA) (isConfirmed=true)

   • VLO state becomes Master Permit

   • Notifications are sent (LSP + SA)

4. SA reviews and optionally updates general info

   • SA calls Update VLO (general info) (limited fields)

   • State remains Master Permit

   • Notifications are sent (SA + LSP)

5. SA shares VLO with Terminal Operator (TO)

   • SA calls Update VLO (share with TO) (isConfirmed=true)

   • VLO state becomes Loading Permit

   • Notifications are sent (LSP + SA + TO)

6. TO confirms loading progress

   • TO calls Update VLO (set Mate’s Receipt) → state becomes Mate’s Receipt

   • TO calls Update VLO (set Final Mate’s Receipt) → state becomes Final Mate’s Receipt

   • Notifications are sent (LSP + SA + TO)

Role access matrix (retrieve + update)

1) Retrieve permissions (Get VLO(s))

Notes for “Get” behavior

• If a VLO is not found or not in scope for the caller, Bulkchain returns a synchronous empty response.

• If no filter is provided, Bulkchain returns all VLO’s from the last 30 days related to the caller.

2) Update permissions (high-level)