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, shippingLine

• Not allowed: SKU assignment, terminalCode, portOfLoading, portOfDischarge, shipAgent, lspReference, contactPerson, contactPhone

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

Export Permit

When to use

Export a permit when an authorized API consumer needs a PDF version of an existing Vessel Load Order. The export is only available when the VLO is in Mate’s Receipt state.

Important behavior

• This operation is handled synchronously: when validation succeeds, Bulkchain returns the generated PDF document directly in the response.

• Supported callers are Logistics Service Provider / Forwarder, Ship Agent, and Terminal Operator, provided the requested VLO is within their allowed scope.

• The requested VLO must exist, be in scope for the caller, and have state Mate’s Receipt. If these checks fail, no PDF is generated.

• The generated permit clearly shows the current VLO state. For a successful export in this feature, that state is Mate’s Receipt.

• The export does not create, update, delete, or change the state of any VLO, SKU, Visit, or Goods Condition data.

• No asynchronous business notification is expected for this export flow.

Key input data elements and validation rules (Export Permit)

Key output

PDF generation rules

• The PDF uses the permit template and A4 page format.

• The current VLO state is shown as a variable value on the permit.

• Relevant VLO data and all linked SKU data are included according to the permit layout.

• If the SKU list spans multiple pages, additional pages are generated and page numbering reflects the actual number of pages.

• Optional fields that are not available may remain empty.

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

• batchKey

• 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) or by batchKey in case the SKU belongs to a batch

• 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)

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

• 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