Shipments API: Create, Update, and Query Outgoing Documents

The Shipments API manages outbound inventory documents (shipmentheaders) in Dragon Guard WMS. The web frontend supports listing, inspecting, creating, and editing shipment headers. As with receipts, the physical pick-and-ship process and the final posting step are driven by warehouse handheld devices — calling the post action from the web client is strictly forbidden. Admin users can additionally use the config package endpoints to export, preview, and bulk-apply shipment configurations.

Endpoints overview

Method	Path	Description
`GET`	`/api/shipmentheaders`	List all shipment headers for a company
`GET`	`/api/shipmentheaders/{id}`	Retrieve a single shipment header by ID
`POST`	`/api/shipmentheaders`	Create a new shipment header document
`PUT`	`/api/shipmentheaders/{id}`	Update an existing shipment header

List shipment headers

GET /api/shipmentheaders?companyId={companyId}
Authorization: Bearer {token}

Returns all shipment headers belonging to the specified company.

Query parameters

companyId

number

required

The ID of the active company. Must match active_company_id in sessionStorage for tenant users.

Example response

[
  {
    "id": 55,
    "documentNo": "SHP-2024-0017",
    "customerId": 12,
    "shipDate": "2024-07-18",
    "shippedQty": 0,
    "status": "Open",
    "companyId": 7
  }
]

Get shipment header by ID

GET /api/shipmentheaders/{id}
Authorization: Bearer {token}

Path parameters

number

required

The unique identifier of the shipmentheader document.

Example response

{
  "id": 55,
  "documentNo": "SHP-2024-0017",
  "customerId": 12,
  "customerName": "Retail Express S.A.",
  "salesOrderId": 33,
  "shipDate": "2024-07-18",
  "shippedQty": 0,
  "lines": [],
  "status": "Open",
  "companyId": 7,
  "createdAt": "2024-07-11T08:00:00Z"
}

Create a shipment header

POST /api/shipmentheaders
Authorization: Bearer {token}
Content-Type: application/json

Creates a new outbound shipment document in Open status.

Request body

companyId

number

required

The ID of the company this shipment belongs to.

customerId

number

required

The ID of the customer receiving the shipment.

shipDate

string

required

Planned shipment date in ISO 8601 format (YYYY-MM-DD).

shippedQty

number

required

Must be 0 at creation. Physical shipping quantities are recorded by handheld devices.

salesOrderId

number

Optional reference to an existing sales order. When provided, the backend validates that the order belongs to the active company and populates commercial fields from the order snapshot.

sellerId

number

Optional reference to the seller associated with this shipment.

lines

array

Array of shipment line items.

Show Line item fields

lines[].itemId

number

required

The ID of the item to ship.

lines[].quantityToShip

number

required

Planned quantity for this line.

lines[].unitOfMeasure

string

Unit of measure code (e.g., EA, BOX, PALLET).

Example request

{
  "companyId": 7,
  "customerId": 12,
  "shipDate": "2024-07-20",
  "shippedQty": 0,
  "salesOrderId": 33,
  "lines": [
    { "itemId": 45, "quantityToShip": 60, "unitOfMeasure": "BOX" }
  ]
}

Example response — 201 Created

{
  "id": 56,
  "documentNo": "SHP-2024-0018",
  "status": "Open",
  "companyId": 7,
  "customerId": 12,
  "shippedQty": 0,
  "createdAt": "2024-07-12T10:30:00Z"
}

Update a shipment header

PUT /api/shipmentheaders/{id}
Authorization: Bearer {token}
Content-Type: application/json

Updates the editable fields of an existing shipment header. Only Open documents may be edited; documents that have been picked or posted are read-only.

Path parameters

number

required

The unique identifier of the shipment header to update.

Request body

Supply any combination of updatable fields. Fields omitted from the body retain their current values.

shipDate

string

Updated planned shipment date (YYYY-MM-DD).

sellerId

number

Updated seller reference.

lines

array

Replacement set of shipment lines. Providing this array replaces all existing lines.

Business rules

Forbidden from the web client: POST /api/shipmentheaders/{id}/post must never be called from the Angular frontend. Posting a shipment is a privileged operation performed exclusively by warehouse handheld devices. Exposing this action in the web UI is a critical implementation error.

shippedQty must always be 0 when creating a shipment header. Shipped quantities are written by the handheld pick-and-ship flow and must not be pre-populated from the web.

When salesOrderId is provided, the backend validates the order belongs to the active_company_id. Commercial fields on the shipment are populated from the order snapshot and become read-only from the web.
Posted progress is driven by the backend and handheld devices, not by web editing.
Customers, sellers, and items referenced in the body must all belong to the same companyId.

Config package endpoints (admin only)

Config package endpoints allow administrators to export the current configuration, preview a proposed configuration change, and apply it in bulk. All six endpoints follow the same three-step workflow.

Export current config

Call the export-config endpoint to download the current configuration as a portable package.

Preview proposed changes

Submit the modified package to the preview-config endpoint to see a diff of what will change before committing.

Apply the config

Submit the validated package to the apply-config endpoint to persist the changes to the database.

Shipment Headers config

Method	Path	Description
`GET`/`POST`	`/api/shipmentheaders/export-config`	Export current header configuration
`GET`/`POST`	`/api/shipmentheaders/preview-config`	Preview proposed header config changes
`GET`/`POST`	`/api/shipmentheaders/apply-config`	Apply header configuration package

Shipment Lines config

Method	Path	Description
`GET`/`POST`	`/api/shipmentlines/export-config`	Export current line configuration
`GET`/`POST`	`/api/shipmentlines/preview-config`	Preview proposed line config changes
`GET`/`POST`	`/api/shipmentlines/apply-config`	Apply line configuration package

Config package endpoints are restricted to admin-level roles. See Config Packages API for full documentation on the export/preview/apply pattern, request and response schemas, and cross-entity config management.

Error codes

HTTP Status	Meaning
`400`	Validation error — `shippedQty` ≠ 0, invalid `salesOrderId`, missing fields
`401`	Missing or expired JWT token
`500`	Internal server error

Authentication

Inventory

Commercial

Admin

Shipments API: Create, Update, and Query Outgoing Documents

Endpoints overview

List shipment headers

Query parameters

Get shipment header by ID

Path parameters

Create a shipment header

Request body

Update a shipment header

Path parameters

Request body

Business rules

Config package endpoints (admin only)

Shipment Headers config

Shipment Lines config

Error codes

Build docs developers (and LLMs) love

Authentication

Inventory

Commercial

Admin

Documentation Index

​Endpoints overview

​List shipment headers

​Query parameters

​Get shipment header by ID

​Path parameters

​Create a shipment header

​Request body

​Update a shipment header

​Path parameters

​Request body

​Business rules

​Config package endpoints (admin only)

​Shipment Headers config

​Shipment Lines config

​Error codes

Build docs developers (and LLMs) love

Endpoints overview

List shipment headers

Query parameters

Get shipment header by ID

Path parameters

Create a shipment header

Request body

Update a shipment header

Path parameters

Request body

Business rules

Config package endpoints (admin only)

Shipment Headers config

Shipment Lines config

Error codes