AI 下單介面

顧客在對話裡選好商品後，AI 起草一張訂單給顧客確認；顧客確認後，我們請你的系統建立一張待付款訂單，並把你回傳的付款連結交給顧客。我們不保存訂單，也不經手貨款。

在後台「機器人設定」填寫下單介面（不填則 AI 不能下單），可以再填登入頁網址：未登入的顧客想下單時，聊天視窗裡會出現「登入」按鈕。

前提：

• 只有登入顧客能下單，user_id 來自你簽發的 user_token（見 識別登入顧客）。
• 商品要透過開放 API 同步過來（見 知識庫和商品）；有規格的商品要帶 variants[].sku，我們下單時會把 sku 原樣傳給你。

顧客怎麼確認：

• 網頁聊天視窗：AI 起草後顯示訂單卡片，顧客點「確認下單」才建立訂單，建立好後卡片上會出現「去付款」按鈕。
• 微信小程式等只能傳文字的管道：AI 把訂單摘要發給顧客，顧客回覆「確認」後才建立訂單，建立好後發付款入口（見下文 mp_path）。

請求

同一個位址，依 mode 區分報價和建立訂單。簽章、驗簽方法與 訂單查詢介面 相同，逾時 10 秒。

POST {你的下单接口}
Content-Type: application/json
X-AICS-Timestamp: 1761120000
X-AICS-Signature: v1=<hex>

{
  "mode": "quote",
  "request_id": "chk_3f2a9c...",
  "user_id": "u_123",
  "conversation_id": "b3c1...",
  "channel": "widget",
  "language": "en",
  "country": "US",
  "items": [{"product_id": "w1", "sku": "w1-black", "qty": 1}]
}

回應

報價成功：

{
  "status": "quoted",
  "currency": "USD",
  "goods_amount": "399.00",
  "discount": "20.00",
  "discounts": [{"label": "新客券", "amount": "20.00"}],
  "shipping_fee": "0",
  "tax": "0",
  "total": "379.00"
}

建立訂單成功：

{
  "status": "created",
  "order_no": "T2026102300001",
  "pay_url": "https://shop.example.com/pay?orderno=T2026102300001",
  "mp_path": "pages/order/pay?orderno=T2026102300001",
  "expires_at": "2026-10-23T12:30:00Z",
  "currency": "USD",
  "goods_amount": "399.00",
  "discount": "20.00",
  "shipping_fee": "0",
  "tax": "0",
  "total": "379.00"
}

無法下單：

{"status": "rejected", "code": "OUT_OF_STOCK", "message": "这款黑色暂时缺货"}

• 金額都用字串。total 和 currency 必填，其餘可省略；discounts 最多顯示 5 條。
• pay_url 是網頁付款連結，必須是 https；在「接入」頁設定了網域白名單時，還必須落在白名單的網域或其子網域上，否則不會顯示。
• mp_path 是小程式裡的付款頁路徑，微信管道裡會作為小程式卡片發給顧客（封面用第一件商品的圖片）；沒有 mp_path 時發 pay_url。兩者至少要有一個。
• expires_at 是付款截止時間，會顯示在卡片上。
• code 可選值：OUT_OF_STOCK、SKU_UNAVAILABLE、REGION_UNAVAILABLE、NOT_LOGGED_IN、LIMIT、OTHER。message 會直接顯示給顧客，請用顧客能看懂的用語。
• 若不想提供報價，可以對 quote 回應 {"status": "unsupported"}，卡片會依商品庫裡的價格估算，並註明「最終金額以付款頁為準」。
• create 回應非 200 或格式不正確時，訂單確認會保留，顧客可以再點一次；請確保重複的 request_id 不會建立第二張訂單。

限制： 訂單確認 30 分鐘內有效，同一會話裡起草新的會讓舊的作廢；一張訂單最多 10 種商品、每種最多 20 件；同一會話 24 小時內最多建立 5 張訂單。