Bulkchain User Documentation
Bulkchain User Documentation
Breadcrumbs

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 365 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 365 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

  • Provide action = "confirm" to promote to Loading Permit

  • Notifications to LSP, SA, TO

Reject to LSP

  • Allowed only in Master Permit

  • Provide action = "reject" 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 365 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 365 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)

  1. SA retrieves VLOs shared by LSP (Master Permit)

  2. SA retrieves the related SKU(s) for the selected VLO using Get SKU(s)

  3. If required, SA updates SKU fields (bookingNumber, loadingInstruction, stowageInstruction) while VLO is still Master Permit

  4. SA updates permitNumber, vesselName, or voyageNumber if required (still Master Permit)

  5. SA shares VLO with TO (state → Loading Permit) and TO is notified

  6. 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