訂單(預覽)
狀態:預覽(
preview),2026-10-17 加入。 三項能力的契約已定案,但尚未適用正式版的支援與棄用保證:欄位、錯誤細節與行為在轉為ga之前仍可能調整,調整會照版本與棄用公告。轉為ga時會在變更紀錄公告。
這三個操作讓租戶自己的後台工具,以機器流程為租戶的客戶建立未付款訂單。客戶之後在租戶的店面付款;付款不經過本 API。
| 能力 | 操作 | 作用 |
|---|---|---|
lightup.order.create |
POST /v1/orders |
建立未付款訂單 |
lightup.order.read |
GET /v1/orders/{orderId} |
讀取這支應用程式建立的訂單 |
lightup.order.cancel |
POST /v1/orders/{orderId}/cancel |
取消這支應用程式建立的未付款訂單 |
本 API 沒有列出訂單、修改訂單、退款或付款的操作。
範圍與授權
- 只限機器流程。 呼叫者必須持有 service account 的 token(
client_credentials,workload,TTL 15 分,沒有 refresh)。使用者本人的 token 呼叫這三個操作會得到 403profile_not_supported,與換不換 token 無關——換成機器流程才行。 - 方案等級 L2 起。 低於 L2 的租戶會得到 403
plan_capability_excluded。 - 資源是租戶,不是人員。 買家(
customerPersonId)是訂單上的一個欄位,不是被讀取或被授權的資源。授權是租戶層級的,不會因為某位客戶還沒有在平台的人員資料裡登記就整筆被拒。 - 租戶要先核准。 三項能力都要由租戶管理員在後台核准給這支應用程式(見登記與憑證);只核准其中一項,其他兩項仍會被拒(403
capability_not_granted)。
建立訂單:POST /v1/orders
POST https://api.lightup.tech/v1/orders
Authorization: Bearer <workload token>
Idempotency-Key: order-2026-10-17-0001
Content-Type: application/json
標頭
| 標頭 | 必填 | 說明 |
|---|---|---|
Authorization |
是 | Bearer 加上機器流程取得的 token |
Idempotency-Key |
是 | 1–200 個可見 ASCII 字元(0x21–0x7E),不可有空白。見下一節 |
X-LightUp-Operator |
否 | 聲明是哪位員工操作,例如 usr_…; name=%E7%8E%8B。只是註記,見下方「X-LightUp-Operator 只是註記」一節 |
缺漏 Idempotency-Key,或格式不對,回 422 schema_invalid,而且在判權之前就回。
本文
{
"customerPersonId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
"items": [
{
"productId": "ae886b43-83d5-4ce7-8a0f-7ffc7daa39da",
"quantity": 1,
"attributes": { "leaveId": "lv_example_0001" }
}
],
"remark": "選填備註",
"expiresAt": "2026-10-20T18:00:00+08:00"
}
| 欄位 | 必填 | 說明 |
|---|---|---|
customerPersonId |
是 | 買家的 psn_ TypeID(psn_ 加 26 個字元)。使用平台給你的值。若你手上只有本平台舊版的客戶 UUID(例如既有訂單上的客戶 id),它和 psn_ 是同一個 128 位元值,可以依 TypeID 規範(jetify-com/typeid 的 spec)無損轉換(UUID → 26 字元 Crockford base32 小寫,前綴 psn_);不要用其他方式拼裝。Gateway 會把它換回訂單服務的客戶 id |
items |
是 | 1–50 個品項 |
items[].productId |
是 | 商品目錄的 id,1–128 個字元 |
items[].quantity |
是 | 整數,1–999 |
items[].attributes |
否 | 字串對字串,最多 20 組。鍵 1–64 個字元,值最多 1000 個字元。它們附在該品項上 |
remark |
否 | 最多 1000 個字元 |
expiresAt |
否 | 付款期限,RFC 3339。見下方「付款期限」一節 |
未知欄位一律 422 schema_invalid,包括任何單價欄位。
價格一律取自商品目錄
請求裡沒有單價,也不能指定單價。每個品項的 unitPrice(單價)與 lineTotal(小計)由平台依商品目錄算出,回在回應的 items 裡。如果你的後台要顯示金額,請以回應為準,不要用自己算的數字取代。
商品不存在於目錄時,回 422 product_unavailable,而且整筆訂單不會建立。
成功回應
成功時回 Order 物件(欄位的完整定義見 OpenAPI 的 Order):
{
"orderId": "…",
"orderNumber": "…",
"status": "PENDING",
"paymentStatus": "UNPAID",
"total": 150,
"netPaidTotal": 0,
"expiresAt": "2026-10-20T18:00:00+08:00",
"createdAt": "2026-10-17T09:30:00+08:00",
"items": [
{ "productId": "ae886b43-83d5-4ce7-8a0f-7ffc7daa39da", "quantity": 1, "unitPrice": 150, "lineTotal": 150 }
]
}
- 201:新建立的訂單。
- 200:同一個
Idempotency-Key、同一份請求的重送,回傳原來那張訂單,沒有建立第二張。
冪等:Idempotency-Key
建單是有副作用的寫入,所以每一次建立都要帶一個 key。同一筆意圖的重送要用同一個 key 與同一份請求;不同的訂單要用不同的 key。
| 情境 | 結果 |
|---|---|
| 第一次送出這個 key | 201,建立新訂單 |
| 同一個 key、同一份請求,24 小時內重送 | 200,回傳原來那張訂單 |
| 同一個 key、不同的請求內容 | 409 idempotency_key_reused |
| 同一個 key 的上一次請求還在處理中 | 409 request_in_progress,回應帶 Retry-After: 2 |
網路逾時、或收到 503 而不知道訂單有沒有建立:用同一個 key、同一份請求重送。如果第一次其實已經成功,你會拿到 200 與原來那張訂單,不會重複建單。不要為了「重試」換一個新的 key,那會建出第二張訂單。
付款期限(expiresAt)
- 選填,RFC 3339 格式。
- 有給的話,必須晚於現在,且不超過現在起 10 年;否則 422
schema_invalid。 - 沒有給的話,訂單會在 30 分鐘後自動取消(由下游訂單服務執行)。
- 回應的
expiresAt反映下游訂單的值:有期限時是 RFC 3339 字串,沒有時是null。
讀取訂單:GET /v1/orders/{orderId}
GET https://api.lightup.tech/v1/orders/{orderId}
Authorization: Bearer <workload token>
回傳 Order,欄位與建立時相同。只能讀取這支應用程式自己建立的訂單。
- 別的 client 建立的、別的租戶的、或根本不存在的訂單,一律回 404
not_found,不分辨。 orderId不是 1–128 個[A-Za-z0-9_-]字元,也回 404。
回應的金額是 JSON 數字,不是字串。
取消訂單:POST /v1/orders/{orderId}/cancel
{ "reason": "客戶來電取消" }
reason 必填,1–500 個字元。
- 成功:回 200 與取消後的
Order。 - 不可取消(已取消、已付款,或已進入不可取消的狀態):回 409
order_not_cancellable。detail是下游訂單服務的代碼與訊息,格式"{code}: {message}",例如ORDER_ALREADY_CANCELLED: …。409 時沒有任何東西被改變。 - 重送已取消的訂單,會得到 409
order_not_cancellable(ORDER_ALREADY_CANCELLED),不是 200。要確認現況,讀GET /v1/orders/{orderId}的status。
錯誤處理
| 狀態與代碼 | 意思 | 怎麼做 |
|---|---|---|
401 invalid_token |
token 本身不可用 | 換一張新的機器 token,再試一次;仍失敗就停 |
403 profile_not_supported |
這是使用者本人的 token | 改用機器流程(workload)的 token。換同一種 token 不會變好 |
403 capability_not_granted、plan_capability_excluded、tenant_not_enabled 等 |
授權或方案不准 | 不要重試。照錯誤・限流・重試的 403 表格,找租戶管理員處理 |
404 not_found |
訂單不存在,或不是這支應用程式建立的 | 確認 orderId 來自建單的回應,不是自己拼的 |
409 idempotency_key_reused |
同一個 key 用在了不同的請求上 | 不要重送。要建立另一張訂單,請換一個新的 key |
409 request_in_progress |
同一個 key 的上一次請求還在處理 | 等 Retry-After(2 秒)後,用同一個 key、同一份請求重送 |
409 order_not_cancellable |
訂單目前不能取消 | 不要重試。讀 GET 確認現況,detail 有原因 |
422 schema_invalid |
請求內容或標頭不符合 schema | 照 OpenAPI 修正請求。不要原樣重送 |
422 product_unavailable |
訂單中有品項的 productId 不在目錄中 |
確認 productId 來自商品目錄 |
429 rate_limited |
限流 | 依 Retry-After 等待後再試,加上抖動 |
503 authorization_unavailable |
現在判不了(授權服務或訂單服務暫時不可用) | 指數退避後重試。建單的重試要用同一個 Idempotency-Key |
403 與 503 永遠不一樣:403 是「不准」,不會因為重試而變成允許;503 是「現在判不了」,應該重試。這條區分在錯誤・限流・重試有完整說明。
X-LightUp-Operator 只是註記
X-LightUp-Operator 記錄「是哪位員工透過後台操作」,方便事後追查。Gateway 會把它交給授權服務,由授權服務簽進下游 token 供稽核。
- 它不參與授權。 填什麼值,都不會讓一個沒有權限的操作變成允許,也不會讓一個有權限的操作被拒。
- 它不會被轉送到訂單服務。
- 格式:非空白、最多 256 個位元組、不含控制字元。格式不對回 422
schema_invalid。 - 不帶也可以建單。