Commercial Orders API: Sales Orders and Purchase Orders

Commercial orders are the upstream transactional documents that drive outbound and inbound warehouse activity in Dragon Guard WMS. Sales orders are linked to shipments — when a shipment is created with a salesOrderId, the backend validates company ownership and populates commercial fields from the order snapshot. Purchase orders are linked to receipts, providing the expected-quantity context for the receiving flow. Both entity types are company-scoped and support creation, update, and listing from the web frontend.

Endpoints overview

Method	Path	Description
`GET`	`/api/sales-orders`	List all sales orders for a company
`POST`	`/api/sales-orders`	Create a new sales order
`PUT`	`/api/sales-orders`	Update an existing sales order
`GET`	`/api/purchase-orders`	List all purchase orders for a company
`POST`	`/api/purchase-orders`	Create a new purchase order
`PUT`	`/api/purchase-orders`	Update an existing purchase order

Sales Orders

Sales orders represent confirmed commercial commitments to customers. When a sales order is referenced by a shipment, the backend reads commercial data (customer, seller, prices, terms) from the order and writes a snapshot onto the shipment document.

List sales orders

GET /api/sales-orders?companyId={companyId}
Authorization: Bearer {token}

companyId

number

required

The ID of the active company. Returns sales orders belonging to this company only.

customerId

number

Filter by customer ID.

status

string

Filter by order status. Common values: Open, PartiallyShipped, Shipped, Cancelled.

string

Free-text search across order number, customer name, and external reference fields.

page

number

Page number (1-based). Defaults to 1.

pageSize

number

Records per page. Defaults to 50.

Example response

[
  {
    "id": 33,
    "orderNo": "SO-2024-0033",
    "customerId": 12,
    "customerName": "Retail Express S.A.",
    "sellerId": 9,
    "orderDate": "2024-07-10",
    "status": "Open",
    "companyId": 7
  }
]

Create a sales order

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

companyId

number

required

The company this sales order belongs to.

orderNo

string

required

Unique order number within the company. Duplicate order numbers return error code validation.salesOrderDuplicate.

customerId

number

required

The ID of the customer for this order. Must be an active customer in the same company.

orderDate

string

required

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

sellerId

number

Optional seller assigned to this order.

externalReference

string

Optional external order reference (e.g., customer’s PO number).

lines

array

Array of order line items.

Show Sales order line fields

lines[].itemId

number

required

The ID of the ordered item.

lines[].quantityOrdered

number

required

Quantity ordered for this line.

lines[].unitPrice

number

Unit price for the line item.

lines[].unitOfMeasure

string

Unit of measure code.

Example request

{
  "companyId": 7,
  "orderNo": "SO-2024-0034",
  "customerId": 12,
  "orderDate": "2024-07-12",
  "sellerId": 9,
  "lines": [
    { "itemId": 45, "quantityOrdered": 60, "unitPrice": 15.50, "unitOfMeasure": "BOX" }
  ]
}

Example response — 201 Created

{
  "id": 34,
  "orderNo": "SO-2024-0034",
  "status": "Open",
  "companyId": 7,
  "customerId": 12,
  "createdAt": "2024-07-12T12:00:00Z"
}

Update a sales order

PUT /api/sales-orders
Authorization: Bearer {token}
Content-Type: application/json

number

required

The ID of the sales order to update.

sellerId

number

Updated seller assignment.

externalReference

string

Updated external reference.

lines

array

Replacement set of order lines. Providing this array replaces all existing lines on the order.

Sales orders that have been fully shipped (status: "Shipped") are read-only. Only Open and PartiallyShipped orders may be edited.

Purchase Orders

Purchase orders represent committed procurement events from vendors. When referenced on a receipt header, the purchase order provides the expected items and quantities for the inbound receiving flow.

List purchase orders

GET /api/purchase-orders?companyId={companyId}
Authorization: Bearer {token}

companyId

number

required

The ID of the active company.

vendorId

number

Filter by vendor ID.

status

string

Filter by order status. Common values: Open, PartiallyReceived, Received, Cancelled.

string

Free-text search across order number, vendor name, and external reference.

page

number

Page number (1-based). Defaults to 1.

pageSize

number

Records per page. Defaults to 50.

Example response

[
  {
    "id": 18,
    "orderNo": "PO-2024-0018",
    "vendorId": 5,
    "vendorName": "Distribuidora Norte S.A.",
    "orderDate": "2024-07-08",
    "status": "Open",
    "companyId": 7
  }
]

Create a purchase order

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

companyId

number

required

The company this purchase order belongs to.

orderNo

string

required

Unique order number within the company. Duplicate order numbers return error code validation.purchaseOrderDuplicate.

vendorId

number

required

The ID of the vendor for this order. Must be an active vendor in the same company.

orderDate

string

required

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

expectedDeliveryDate

string

Expected delivery date (YYYY-MM-DD). Passed to the receipt header when a receiving document is created from this order.

externalReference

string

Optional external reference (e.g., vendor confirmation number).

lines

array

Array of purchase order line items.

Show Purchase order line fields

lines[].itemId

number

required

The ID of the item being ordered.

lines[].quantityOrdered

number

required

Quantity ordered for this line.

lines[].unitCost

number

Unit cost for the line item.

lines[].unitOfMeasure

string

Unit of measure code.

Example request

{
  "companyId": 7,
  "orderNo": "PO-2024-0019",
  "vendorId": 5,
  "orderDate": "2024-07-12",
  "expectedDeliveryDate": "2024-07-20",
  "lines": [
    { "itemId": 88, "quantityOrdered": 200, "unitCost": 4.75, "unitOfMeasure": "BOX" }
  ]
}

Example response — 201 Created

{
  "id": 19,
  "orderNo": "PO-2024-0019",
  "status": "Open",
  "companyId": 7,
  "vendorId": 5,
  "createdAt": "2024-07-12T13:00:00Z"
}

Update a purchase order

PUT /api/purchase-orders
Authorization: Bearer {token}
Content-Type: application/json

number

required

The ID of the purchase order to update.

expectedDeliveryDate

string

Updated expected delivery date.

externalReference

string

Updated external reference.

lines

array

Replacement set of order lines.

Business rules

Sales order ↔ Shipment link

When a shipment is created with a salesOrderId:

The backend validates that the referenced sales order belongs to the same active_company_id as the shipment. Cross-company order references are rejected with a 400 validation error.
Commercial fields on the shipment (customer, seller, pricing terms) are populated from the order snapshot at the time of shipment creation.
Once the snapshot is written, subsequent changes to the sales order will not propagate to the shipment.

{
  "companyId": 7,
  "customerId": 12,
  "salesOrderId": 33,
  "shippedQty": 0
}

The commercial field snapshot ensures that historical documents remain accurate even if master data or order values change after the shipment is created.

Duplicate validation

Entity	Duplicate error code	Key fields
Sales Order	`validation.salesOrderDuplicate`	`CompanyId + OrderNo`
Purchase Order	`validation.purchaseOrderDuplicate`	`CompanyId + OrderNo`

Error codes

HTTP Status	Meaning
`400`	Validation error — missing fields, cross-company `salesOrderId`, duplicate order number (`validation.salesOrderDuplicate`, `validation.purchaseOrderDuplicate`)
`401`	Missing or expired JWT token
`500`	Internal server error

Authentication

Inventory

Commercial

Admin

Commercial Orders API: Sales Orders and Purchase Orders

Endpoints overview

Sales Orders

List sales orders

Create a sales order

Update a sales order

Purchase Orders

List purchase orders

Create a purchase order

Update a purchase order

Business rules

Sales order ↔ Shipment link

Duplicate validation

Error codes

Build docs developers (and LLMs) love

Authentication

Inventory

Commercial

Admin

Documentation Index

​Endpoints overview

​Sales Orders

​List sales orders

​Create a sales order

​Update a sales order

​Purchase Orders

​List purchase orders

​Create a purchase order

​Update a purchase order

​Business rules

​Sales order ↔ Shipment link

​Duplicate validation

​Error codes

Build docs developers (and LLMs) love

Endpoints overview

Sales Orders

List sales orders

Create a sales order

Update a sales order

Purchase Orders

List purchase orders

Create a purchase order

Update a purchase order

Business rules

Sales order ↔ Shipment link

Duplicate validation

Error codes