Ship Agent Integration Specifications

Vessel Load Order (VLO)

Purpose

A Vessel Load Order (VLO) is initiated by a Logistics Service Provider (LSP) and shared with the Ship Agent (SA) for review, coordination, and enrichment. When ready, the SA shares the VLO with the Terminal Operator (TO) as a Loading Permit for execution.

Lifecycle and Roles

Draft (created/owned by LSP)
Master Permit (shared with SA; SA can edit limited info or share/reject)
Loading Permit (shared with TO)
Mate’s Receipt (set by TO)
Final Mate’s Receipt (set by TO)

Get VLO(s) as SA

When to use

Retrieve a specific VLO by key
List VLOs using filters
List all in-scope VLOs from the last 30 days (no filters)

Behavior

Synchronous processing
Scope: SA can retrieve from Master Permit onward
If no in-scope records are found, returns an empty result synchronously

Filters

vloKey
lspReference
permitNumber
No filters: last 30 days, in-scope

API specification

https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

Update VLO as SA

All SA update operations are asynchronous: the API responds 202 Accepted with a correlationId, and the business outcome is delivered via notifications.

Supported use cases

Update limited general info while Master Permit
Share with Terminal Operator (state → Loading Permit)
Reject and return to LSP (state → Draft)

General rules

Exactly one VLO per update (identify by vloKey)
Authorization and role checks are enforced

Update general info

Allowed only in Master Permit
Fields: permitNumber, vesselName, voyageNumber
Not allowed: SKU assignment, terminalCode, ports, shipAgent, lspReference

Share with TO

Allowed only in Master Permit
Set isConfirmed=true to promote to Loading Permit
Notifications to LSP, SA, TO

Reject to LSP

Allowed only in Master Permit
Set isRejected=true to return to Draft
Optional reason text
Notifications to SA and LSP

API specification

https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

Stock Keeping Unit (SKU)

Purpose

A Stock Keeping Unit (SKU) represents a cargo unit in Bulkchain. SKUs can be linked to a Terminal Delivery Order (TDO), a Vessel Load Order (VLO) and/or a Visit. When a VLO is shared with the Ship Agent for review, the Ship Agent can retrieve the related SKUs and—while the VLO is in Master Permit—update a limited subset of SKU data.

Get SKU(s) as SA

When to use

Retrieve a specific SKU by key
List SKUs using filters
List all in-scope SKUs from the last 30 days (no filters)

Behavior

Synchronous processing
Scope: only SKUs related to the calling Ship Agent
If no in-scope records are found, returns an empty result synchronously

Filters

skuKey
vloKey
No filters: last 30 days, in-scope

Returned data (high level)

The response returns the SKU data and (when available) related information such as:

Linkage keys: vloKey
terminalDeliveryConfirmation
goodsCondition

API specification

https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

Update SKU as SA

When to use

Update a limited subset of SKU information while the linked VLO is in Master Permit

Behavior

All SA update operations are asynchronous: the API responds 202 Accepted with a correlationId, and the business outcome is delivered via notifications.

General rules

Exactly one SKU per update (identify by skuKey)
Authorization and role checks are enforced (Ship Agent role + Bulkchain subscription)
The SKU must exist and be related to the calling Ship Agent
The linked VLO state must be Master Permit

Updatable fields (SA)

bookingNumber (cannot be nulled by SA)
loadingInstruction
stowageInstruction

All other attributes are not updatable by the Ship Agent.

Notifications

Refusal (business validation error): notification is sent to the Ship Agent (caller) only.
Successful update: notification is sent to LSP, SA and TO, including at minimum the skuKey and the updating Ship Agent’s NxtEntityId.

API specification

https://documentation.nxtport.com/bulkchain/open-api-specification-swagger

Role access matrix (SA)

VLO state	SA can retrieve VLO	SA can update VLO	SA can retrieve SKU(s)	SA can update SKU(s)
`Draft`	No	No	No	No
`Master Permit`	Yes	Yes	Yes	Yes
`Loading Permit`	Yes	No	Yes	No
`Mate’s Receipt`	Yes	No	Yes	No
`Final Mate’s Receipt`	Yes	No	Yes	No

Notes:

SKU retrieval is limited to SKUs linked to in-scope VLOs for the calling SA.
SKU updates are only allowed while linked VLO is in Master Permit and only for fields bookingNumber, loadingInstruction, stowageInstruction

Happy flow (SA perspective)

SA retrieves VLOs shared by LSP (Master Permit)
SA retrieves the related SKU(s) for the selected VLO using Get SKU(s)
If required, SA updates SKU fields (bookingNumber, loadingInstruction, stowageInstruction) while VLO is still Master Permit
SA updates permitNumber, vesselName, or voyageNumber if required (still Master Permit)
SA shares VLO with TO (state → Loading Permit) and TO is notified
SA monitors progress as TO moves to Mate’s Receipt and Final Mate’s Receipt using Get VLO(s) and, if needed, retrieves SKU(s) for status/confirmation.

References

OpenAPI: https://documentation.nxtport.com/bulkchain/open-api-specification-swagger
LSP integration specs: https://documentation.nxtport.com/bulkchain/logistics-service-provider-integration-specificati
TO integration specs: https://documentation.nxtport.com/bulkchain/terminal-operator-integration-specifications