LightUp 第三方 API 契約已定案・端點已上線 v1.0.0 · 707394544381

訂單(預覽)

狀態:預覽(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 沒有列出訂單、修改訂單、退款或付款的操作。

範圍與授權

建立訂單: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 }
  ]
}

冪等: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)

讀取訂單:GET /v1/orders/{orderId}

GET https://api.lightup.tech/v1/orders/{orderId}
Authorization: Bearer <workload token>

回傳 Order,欄位與建立時相同。只能讀取這支應用程式自己建立的訂單。

回應的金額是 JSON 數字,不是字串。

取消訂單:POST /v1/orders/{orderId}/cancel

{ "reason": "客戶來電取消" }

reason 必填,1–500 個字元。

錯誤處理

狀態與代碼 意思 怎麼做
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 供稽核。

注意事項