API Reference¶

Base URL: /api

All endpoints require authentication via X-User-Token header (JWT from MSAL).

Purchase Orders¶

List Purchase Orders¶

GET /api/purchase-orders

Query Parameters:

Parameter	Type	Description
status	string	Filter by status label (e.g., "New", "Pending Approval")
vendor	string	Filter by vendor company name
search	string	Search PO number, style, or SKU
limit	number	Results per page (default: 50)
page	number	Page number (default: 1)
sortField	string	Sort column: id, vendor, poDate, xfDate, status, amount
sortDir	string	Sort direction: asc, desc

Response: { data: [...], pagination: { total, page, limit, totalPages } }

Get Single Purchase Order¶

GET /api/purchase-orders/{poRef}

Response: Full PO detail including original and vendor reply values.

Key fields:

Field	Description
originalXfd	Original ex-factory date from Cin7
vendorReplyXfd	Vendor's proposed ex-factory date
xfDate	Computed: COALESCE(vendorReplyXfd, originalXfd)
statusId	Integer status ID (100, 150, 200, etc.)
status	English status label
statusZh	Chinese status label
statusColor	Hex color for status badge
hasPendingChanges	Whether vendor has made edits

Update Purchase Order Header¶

PATCH /api/purchase-orders/{poRef}
Body: { vendor_reply_xfd, vendor_reply_factory, vendor_reply_comment, container_number, tracking_number }

Get Line Items¶

GET /api/purchase-orders/{poRef}/line-items

Response: Array of aggregated line items grouped by (code, style, color).

Each item contains:

{
    "code": "VENITA-CML",
    "style": "VENITA",
    "color": "CML",
    "unitPrice": 5.33,
    "originalUnitPrice": 5.33,
    "vendorReplyUnitPrice": null,
    "sizes": {
        "6M": { "qty": 200, "originalQty": 200, "vendorReplyQty": null, "rowHash": "abc123", "lineId": "1" }
    },
    "totalQty": 1200,
    "originalTotalQty": 1200,
    "totalAmount": 6396.00,
    "isModified": false
}

Update Line Items¶

PATCH /api/purchase-orders/{poRef}/line-items
Body: { lines: [{ rowHash: "abc123", vendorReplyQty: 250 }] }

Workflow Transitions¶

Execute Transition¶

POST /api/purchase-orders/{poRef}/transition
Body: { "action": "SUBMIT", "comment": "optional comment" }

Actions: SUBMIT, APPROVE, REJECT, RECALL, MOVE_TO_PRODUCTION, MARK_SHIPPED, CONFIRM_DELIVERY, CANCEL

Response:

{
    "success": true,
    "newStatusId": 200,
    "newStatus": "Pending Approval",
    "message": "Transition SUBMIT completed"
}

Get Available Actions¶

GET /api/lookups/actions?statusId=100&role=Vendor

Response: Array of valid transitions for the given status and role.

Get PO History¶

GET /api/purchase-orders/{poRef}/history

Response: Array of transition log entries.

Dashboard¶

KPIs¶

GET /api/dashboard/kpis

Response:

{
    "new": 45,
    "revision": 3,
    "pending": 12,
    "confirmed": 8,
    "production": 20,
    "shipped": 5,
    "delivered": 100,
    "cancelled": 2
}

Recent Activity¶

GET /api/dashboard/recent-activity

Response: Last 20 status transitions across all POs.

Filters¶

GET /api/po-filters

Response: { statuses: ["New", "Pending Approval", ...], statusDetails: [...], vendors: ["E1", ...] }

Authentication¶

GET /api/me

Response: Current user details including role and vendor code.