Warehouse Shipment Workflows: Headers, Lines, and Posting

Dragon Guard models outbound warehouse activity through Shipment Headers and Shipment Lines. A shipment starts as a draft (OPEN), gets released to the warehouse floor (RELEASED), handheld operators record shipped quantities line by line, and a supervisor posts the shipment to write negative inventory movements. Posting queues an outbound acknowledgment for ERP callback if a CallbackUrl is configured. All shipment endpoints are company-scoped. CompanyId is resolved from the bearer token or the optional ?companyId= query parameter.

Status Lifecycle

OPEN  ──►  RELEASED  ──►  SHIPPING / READY_TO_POST  ──►  PARTIALLY POSTED  ──►  POSTED (CLOSED)
                                                                                │
                                                          CANCELLED ◄──────────┘

Status	Meaning
`OPEN`	Draft, not visible to warehouse operators.
`RELEASED`	Released for picking; visible to handheld.
`SHIPPING` / `READY_TO_POST`	Handheld operational session active.
`PARTIALLY POSTED`	At least one line posted; remaining lines still open.
`POSTED`	All lines posted; document closed.

The additive documentStatus and processingStatus fields provide a client-friendly representation alongside the raw shipmentStatus.

Shipment Headers

List shipment headers

GET /api/shipmentheaders

pageNumber

integer

default:"1"

Page number.

pageSize

integer

default:"20"

Records per page (max 100).

status

string

Filter by shipmentStatus.

shipmentNo

string

Partial match on shipment number.

sortBy

string

default:"CreatedAt"

Sort field: CreatedAt or ShipmentNo.

sortDesc

boolean

default:"true"

Sort descending.

OPERATOR tokens only see shipments in RELEASED, SHIPPING, READY_TO_POST, or PARTIALLY POSTED status. ADMIN and SUPERVISOR see all statuses.

Response fields (ShipmentHeaderDto)

uuid

Shipment header UUID.

shipmentNo

string

Auto-generated shipment number (SHP-NNNNNN).

externalShipmentNo

string

ERP or external reference number.

salesOrderNo

string

Linked sales order number.

shipmentType

string

Type (e.g. STANDARD).

shipmentStatus

string

Raw status value.

documentStatus

string

Client-friendly: Open, Released, Closed, Cancelled.

processingStatus

string

Pending, PartiallyShipped, or Posted.

warehouseCode

string

Warehouse/location code. Falls back to tenant default.

customerCode

string

Customer code.

customerName

string

Customer display name.

plannedShipDate

datetime

Planned ship date.

actualShipDate

datetime

Populated on first post.

totalLines

integer

Number of shipment lines.

totalQty

decimal

Total ordered quantity across all lines.

isClosed

boolean

true when fully posted.

Get shipment header detail

GET /api/shipmentheaders/{id}

Returns the full ShipmentHeaderDetailDto including all lines, per-line alreadyPostedQty, postedQuantity, and remainingQuantity. Also includes isHandheldInUse and activeOperatorEmail when a handheld session is active.

Create a shipment

POST /api/shipmentheaders

Request body (CreateShipmentHeaderDto)

externalShipmentNo

string

ERP or external reference number.

referenceNo

string

Internal reference number.

salesOrderId

uuid

Link to an existing local sales order.

salesOrderNo

string

Sales order number. Auto-generated per-tenant when omitted or when the value is the placeholder SO-AUTO.

shipmentType

string

required

Shipment type (e.g. STANDARD).

customerId

uuid

Customer ID.

customerCode

string

Customer code.

customerName

string

Customer name.

shipToName

string

Ship-to contact name.

shipToAddress1

string

Ship-to street address.

shipToCity

string

Ship-to city.

shipToState

string

Ship-to state.

shipToPostalCode

string

Ship-to postal code.

shipToCountry

string

Ship-to country.

orderDate

datetime

Order date.

plannedShipDate

datetime

Planned ship date.

carrierCode

string

Carrier code.

carrierName

string

Carrier name.

serviceLevel

string

Carrier service level.

isBackorderAllowed

boolean

default:"false"

Allow backorder fulfillment.

isPartialAllowed

boolean

default:"false"

Allow partial shipment.

lines

array

required

At least one line with orderedQty > 0 is required.

lines[].itemId

uuid

Item UUID. Either itemId or itemNo required.

lines[].itemNo

string

Item number. Either itemId or itemNo required.

lines[].orderedQty

decimal

required

Ordered quantity (must be > 0).

lines[].unitOfMeasure

string

Unit of measure. Defaults to item’s UOM.

lines[].binId

uuid

Source bin for picking.

lines[].binCode

string

Source bin code.

Response

{ "shipmentId": "...", "shipmentNo": "SHP-000001" }

For items with allowNegativeAvailable = false, draft creation validates that orderedQty does not exceed current available inventory. Overselling is rejected with a field-level error before any rows are persisted.

Update a shipment

PUT /api/shipmentheaders/{id}

Permitted while the document is OPEN or RELEASED. Accepts the same body shape as create. Rules:

Posted lines cannot be removed; their orderedQty cannot drop below the already-posted quantity.
Non-posted lines may be freely added, updated, or removed.
Reopening RELEASED → OPEN is rejected when handheld activity exists on any line.
A per-shipment SQL application lock prevents concurrent edits.

Shipment Lines

List lines for a shipment

GET /api/shipmentlines?shipmentId={id}

shipmentId

uuid

required

Parent shipment UUID.

status

string

Filter by lineStatus.

pageNumber

integer

default:"1"

Page number.

pageSize

integer

default:"50"

Records per page (max 200).

For GrupoMASNative tenants where the shipment was sourced from MAS, lines are read from the MAS released shipment payload directly.

Get a single line

GET /api/shipmentlines/{id}

Update a shipment line

PUT /api/shipmentlines/{id}

The primary handheld write endpoint. Records the quantity an operator has confirmed for shipping.

shippedQty

decimal

required

Quantity to ship on this line. Must be ≥ 0.

Rules enforced:

Parent shipment must not be closed or posted.
alreadyPosted + shippedQty cannot exceed orderedQty.
Line lineStatus transitions to OPEN, PARTIAL, or READY_TO_POST.
A per-shipment SQL application lock is acquired.

Post a Shipment

Operators record shipped quantities

Handheld operators use PUT /api/shipmentlines/{id} to set shippedQty for each line, confirming the physical quantity loaded for shipment.

Supervisor posts the shipment

Call POST /api/shipmentheaders/{id}/post to commit inventory.

Inventory and history created

Dragon Guard creates PostedShipment, PostedShipmentLine records, and writes a negative InventoryMovements entry per line with movementType = "OUT".

ERP notified (when configured)

An OutboundAcknowledgment is queued and dispatched to the tenant CallbackUrl. Callback failure never blocks the post.

POST /api/shipmentheaders/{id}/post

Validations enforced at post time:

Shipment must not be closed or already posted.
Every posted line must have a binId.
shippedQty must not exceed remaining orderedQty.
For items with allowNegativeAvailable = false, available stock must cover shippedQty.
RFID evidence check runs when RFID enforcement is configured for SHIPMENTS.

Response

{
  "message": "Shipment posted successfully",
  "shipmentId": "...",
  "shipmentNo": "SHP-000001",
  "postedShipmentNo": "PS-000001",
  "status": "POSTED",
  "outboundAcknowledgmentId": "...",
  "outboundAcknowledgmentStatus": "QUEUED"
}

Partial posting is fully supported: after a partial post, shipmentStatus becomes PARTIALLY POSTED. Subsequent calls post remaining lines until all are fulfilled and the document closes.

Posted Shipment History

List posted headers

GET /api/posted-shipment-headers

Supports ?search= (matches postedShipmentNo, shipmentNo, customerCode, customerName, warehouseCode).

Get posted header detail

GET /api/posted-shipment-headers/{id}

By source shipment

GET /api/posted-shipment-headers/by-shipment/{shipmentId}

Posted lines

GET /api/posted-shipment-lines
GET /api/posted-shipment-lines/{id}
GET /api/posted-shipment-lines/by-header/{postedShipmentId}

Outbound Acknowledgments

After every successful shipment post, Dragon Guard:

Persists an OutboundAcknowledgment record within the same database transaction.
Attempts a best-effort POST to the tenant CallbackUrl with the full posted shipment payload.
Logs a warning if the callback fails — the shipment post is never rolled back due to a callback failure.

ERP integrations that prefer polling can query GET /api/outbound-acknowledgments at any time; the status field transitions from QUEUED → DISPATCHED → ACKNOWLEDGED.

Sales Orders

GET /api/sales-orders

Returns sales order headers for the active tenant. For GrupoMASNative tenants, orders are read live from MAS. Shipments can be linked to a sales order via salesOrderId / salesOrderNo to enable automatic SO progress tracking (quantities shipped, outstanding, and status OPEN → PARTIALLY SHIPPED → SHIPPED).

Pick Headers

GET /api/pickheaders

Returns warehouse pick-list documents linked to shipments. Supports filtering by status, assignedUser, and pickNo, and sorting by pickNo, status, assignedUser, completedAt, or createdAt.

GET /api/pickheaders/{id}

Returns full PickHeaderDetailDto for a single pick document, including pickNo, status, assignedUserName, salesOrderNo, warehouseShipmentNo, createdAt, and completedAt.

Transfer Headers

GET /api/transferheaders

Returns inter-location transfer documents for tenants that support transfer execution (SupportsTransferExecution = true). For tenants that do not support transfers, the endpoint returns an empty paged result.

POST /api/transferheaders/post

Posts a completed transfer result back to the integration provider (GrupoMASNative only). The request body is a GrupoMasTransferPostingResultDto; the operatorEmail and postedAtUtc fields are set server-side from the authenticated user and current UTC time.

Configuration Packages

Dragon Guard supports Excel-based bulk operations for shipment data using the same WMS_CONFIG_PACKAGE_V1 format as items.

Shipment headers package

Export

GET /api/shipmentheaders/export-config

Downloads shipment_headers_config_package.xlsx.

Preview

POST /api/shipmentheaders/preview-config
Content-Type: multipart/form-data

Returns CREATE/UPDATE preview and validation errors.

Apply

POST /api/shipmentheaders/apply-config
Content-Type: multipart/form-data

Applies the validated package.

Header package columns: ShipmentNo, ShipmentStatus, WarehouseCode, SalesOrderNo, OrderDate, PlannedShipDate, CustomerName, ExternalShipmentNo, ReferenceNo, IsBackorderAllowed, IsPartialAllowed.

Shipment lines package

Export

GET /api/shipmentlines/export-config

Preview

POST /api/shipmentlines/preview-config
Content-Type: multipart/form-data

Apply

POST /api/shipmentlines/apply-config
Content-Type: multipart/form-data

Line package columns: ShipmentNo, LineNo, ItemNo, SourceSalesOrderNo, OrderedQty, ShippedQty, UnitOfMeasure, BinCode.

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Warehouse Shipment Workflows: Headers, Lines, and Posting

Status Lifecycle

Shipment Headers

List shipment headers

Get shipment header detail

Create a shipment

Update a shipment

Shipment Lines

List lines for a shipment

Get a single line

Update a shipment line

Post a Shipment

Posted Shipment History

List posted headers

Get posted header detail

By source shipment

Posted lines

Outbound Acknowledgments

Sales Orders

Pick Headers

Transfer Headers

Configuration Packages

Shipment headers package

Export

Preview

Apply

Shipment lines package

Export

Preview

Apply

Build docs developers (and LLMs) love

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Documentation Index

​Status Lifecycle

​Shipment Headers

​List shipment headers

​Get shipment header detail

​Create a shipment

​Update a shipment

​Shipment Lines

​List lines for a shipment

​Get a single line

​Update a shipment line

​Post a Shipment

​Posted Shipment History

List posted headers

Get posted header detail

By source shipment

Posted lines

​Outbound Acknowledgments

​Sales Orders

​Pick Headers

​Transfer Headers

​Configuration Packages

​Shipment headers package

Export

Preview

Apply

​Shipment lines package

Export

Preview

Apply

Build docs developers (and LLMs) love

Status Lifecycle

Shipment Headers

List shipment headers

Get shipment header detail

Create a shipment

Update a shipment

Shipment Lines

List lines for a shipment

Get a single line

Update a shipment line

Post a Shipment

Posted Shipment History

Outbound Acknowledgments

Sales Orders

Pick Headers

Transfer Headers

Configuration Packages

Shipment headers package

Shipment lines package