📄訂單

此 API 為 2024-10-04 後版本 v.2.62.11 開放。

最佳實踐

在進行系統整合時，將訂單（Order）資料關聯到客戶（Contact）上是至關重要的。以下是推薦的整合流程步驟：

1. 查找或建立客戶資料

   • 根據購買者的條件（如電子郵件、電話號碼等）查找現有客戶資料。

   • 若無匹配的客戶資料，則建立新的客戶資料。

   • 取得客戶的唯一識別碼（contact_id）。

2. 建立或更新訂單資料

   • 使用訂單編號（order_number）和客戶 ID（contact_id）來建立新的訂單或更新現有訂單。

   • 確保每筆訂單正確對應到相應的客戶，這有助於提升管理效率並保持數據的一致性。

遵循上述步驟，可有效優化 API 整合流程，確保訂單與客戶資料的準確關聯。

---

搜尋訂單

請求方法: GET 端點: /api/v1/contact-order 說明: 根據指定條件搜尋符合的訂單列表。

Curl 範例

curl -X GET \
     -H "Content-Type: application/json" \
     '{
       "order_number": "ORD202309260001"
     }' \
     https://{API_HOST}/api/v1/contact-order

URL 參數

參數名稱	必填	預設值	類型	說明
contact_id	否	NULL	Number	客戶系統編號，例如 5263
order_number	否	NULL	String	訂單編號，例如 O412554

回應結構

{
    "data": [
      {
          "id": 1,
          "order_source": "cyberbiz",
          "order_created_at": "2024-09-06 00:00:00",
          "order_updated_at": null,
          "order_number": "ORD202309260001",
          "order_name": "訂單 #1001",
          "receiver_name": null,
          "receiver_address": null,
          "receiver_phone": null,
          "subtotal_price": "4000.00",
          "total_discount": "400.00",
          "shipping_fee": "330.00",
          "total_tax": "230.00",
          "total_price": "5245.00",
          "financial_status": "paid",
          "fulfillment_status": "preparing",
          "return_status": "returning",
          "note": null,
          "extra_info": null,
          "contact_id": 2195878,
          "items": [],
          "created_at": "2024-09-27 10:02:25",
          "updated_at": "2024-09-27 14:20:27"
      }
    ],
    "links": {
        // 分頁相關連結
    },
    "meta": {
        // 分頁相關元數據
    }
}

回應欄位說明

欄位名稱	類型	說明
data	Array of objects	銷售單資料陣列
meta	Object	分頁相關元數據
links	Object	分頁相關連結

---

取得單筆訂單資料

請求方法: GET 端點: /api/v1/contact-order/{contact-order} 說明: 根據訂單 ID 取得單筆訂單詳細資料。

Curl 範例

curl -X GET \
     -H "Content-Type: application/json" \
     https://{API_HOST}/api/v1/contact-order/1

URL 參數

參數名稱	必填	預設值	類型	說明
id	是	NULL	Number	訂單的唯一識別碼

回應結構

{
    "data": {
          "id": 1,
          "order_source": "cyberbiz",
          "order_created_at": "2024-09-06 00:00:00",
          "order_updated_at": null,
          "order_number": "ORD202309260001",
          "order_name": "訂單 #1001",
          "receiver_name": null,
          "receiver_address": null,
          "receiver_phone": null,
          "subtotal_price": "4000.00",
          "total_discount": "400.00",
          "shipping_fee": "330.00",
          "total_tax": "230.00",
          "total_price": "5245.00",
          "financial_status": "paid",
          "fulfillment_status": "preparing",
          "return_status": "returning",
          "note": null,
          "extra_info": null,
          "contact_id": 2195878,
          "items": [],
          "created_at": "2024-09-27 10:02:25",
          "updated_at": "2024-09-27 14:20:27"
      }
}

回應欄位說明

欄位名稱	類型	說明
data	Object	單筆訂單資料
data.id	Number	訂單 ID
data.order_source	String	訂單來源
data.order_number	String	訂單編號
data.contact_id	Number	關聯的客戶唯一識別碼
...	...	其他訂單相關欄位

---

新增訂單

請求方法: POST 端點: /api/v1/contact-order 說明: 建立一筆新的訂單資料。

Curl 範例

curl -X POST \
     -H "Content-Type: application/json" \
     '{
       "order_number": "FL_968521",
       "order_name": "官網訂單#968521"
     }' \
     https://{API_HOST}/api/v1/contact-order

表單資料

欄位名稱	必填	預設值	類型	說明
order_source	是	NULL	EnumValue	訂單來源
order_number	是	NULL	String	唯一識別訂單的編號
contact_id	是	NULL	Number	關聯的客戶唯一識別碼
order_created_at	否	NULL	DateTime	訂單創建的時間戳
order_updated_at	否	NULL	DateTime	訂單最後更新的時間戳
order_name	否	NULL	String	訂單的顯示名稱
receiver_name	否	NULL	String	收件人的姓名
receiver_address	否	NULL	String	收件人的地址
receiver_phone	否	NULL	String	收件人的電話
subtotal_price	否	NULL	Decimal	所有商品的價格總和，未包含任何折扣、稅金、運費等額外費用
total_discount	否	NULL	Decimal	訂單中所有折扣的總金額
shipping_fee	否	NULL	Decimal	訂單的總運費金額
total_tax	否	NULL	Decimal	訂單的總稅金金額
total_price	否	NULL	Decimal	訂單的最終總金額
financial_status	否	NULL	EnumValue	付款狀態
fulfillment_status	否	NULL	EnumValue	履行狀態
return_status	否	NULL	EnumValue	退貨狀態
note	否	NULL	String	訂單的附加說明
extra_info	否	NULL	String	訂單的補充資訊

回應結構

{
    "data": {
          "id": 1,
          "order_source": "cyberbiz",
          "order_created_at": "2024-09-06 00:00:00",
          "order_updated_at": null,
          "order_number": "ORD202309260001",
          "order_name": "訂單 #1001",
          "receiver_name": null,
          "receiver_address": null,
          "receiver_phone": null,
          "subtotal_price": "4000.00",
          "total_discount": "400.00",
          "shipping_fee": "330.00",
          "total_tax": "230.00",
          "total_price": "5245.00",
          "financial_status": "paid",
          "fulfillment_status": "preparing",
          "return_status": "returning",
          "note": null,
          "extra_info": null,
          "contact_id": 2195878,
          "items": [],
          "created_at": "2024-09-27 10:02:25",
          "updated_at": "2024-09-27 14:20:27"
      }
}

---

更新訂單資料

請求方法: PUT 端點: /api/v1/contact-order/{contact-order} 說明: 更新指定訂單的資料。

Curl 範例

curl -X PUT \
     -H "Content-Type: application/json" \
     '{
       "order_number": "FL_968521",
       "order_name": "官網訂單#968521"
     }' \
     https://{API_HOST}/api/v1/contact-order/1

URL 參數

參數名稱	必填	預設值	類型	說明
id	是	NULL	Number	訂單的唯一識別碼

表單資料

欄位名稱	必填	預設值	類型	說明
order_source	否	NULL	EnumValue	訂單來源
order_number	否	NULL	String	唯一識別訂單的編號
contact_id	否	NULL	Number	關聯的客戶唯一識別碼
order_created_at	否	NULL	DateTime	訂單創建的時間戳
order_updated_at	否	NULL	DateTime	訂單最後更新的時間戳
order_name	否	NULL	String	訂單的顯示名稱
receiver_name	否	NULL	String	收件人的姓名
receiver_address	否	NULL	String	收件人的地址
receiver_phone	否	NULL	String	收件人的電話
subtotal_price	否	NULL	Decimal	所有商品的價格總和，未包含任何折扣、稅金、運費等額外費用
total_discount	否	NULL	Decimal	訂單中所有折扣的總金額
shipping_fee	否	NULL	Decimal	訂單的總運費金額
total_tax	否	NULL	Decimal	訂單的總稅金金額
total_price	否	NULL	Decimal	訂單的最終總金額
financial_status	否	NULL	EnumValue	付款狀態
fulfillment_status	否	NULL	EnumValue	履行狀態
return_status	否	NULL	EnumValue	退貨狀態
note	否	NULL	String	訂單的附加說明
extra_info	否	NULL	String	訂單的補充資訊

回應結構

{
    "data": {
          "id": 1,
          "order_source": "cyberbiz",
          "order_created_at": "2024-09-06 00:00:00",
          "order_updated_at": null,
          "order_number": "ORD202309260001",
          "order_name": "訂單 #1001",
          "receiver_name": null,
          "receiver_address": null,
          "receiver_phone": null,
          "subtotal_price": "4000.00",
          "total_discount": "400.00",
          "shipping_fee": "330.00",
          "total_tax": "230.00",
          "total_price": "5245.00",
          "financial_status": "paid",
          "fulfillment_status": "preparing",
          "return_status": "returning",
          "note": null,
          "extra_info": null,
          "contact_id": 2195878,
          "items": [],
          "created_at": "2024-09-27 10:02:25",
          "updated_at": "2024-09-27 14:20:27"
      }
}

---

訂單資料模型

欄位名稱	類型	說明
id	Number	產品 ID
order_source	String	訂單來源
order_created_at	String	訂單創建時間，格式為 YYYY-MM-DD HH:MM:SS
order_updated_at	String	訂單最後更新時間，格式為 YYYY-MM-DD HH:MM:SS
order_number	String	訂單編號
order_name	String	訂單的顯示名稱
receiver_name	String	收件人的姓名
receiver_address	String	收件人的地址
receiver_phone	String	收件人的電話
subtotal_price	Decimal	所有商品的價格總和，未包含任何折扣、稅金、運費等額外費用
total_discount	Decimal	訂單中所有折扣的總金額
shipping_fee	Decimal	訂單的總運費金額
total_tax	Decimal	訂單的總稅金金額
total_price	Decimal	訂單的最終總金額
financial_status	String	付款狀態（Enum）
fulfillment_status	String	履行狀態（Enum）
return_status	String	退貨狀態（Enum）
note	String	訂單的附加說明
extra_info	String	訂單的補充資訊
contact_id	Number	關聯的客戶唯一識別碼
items	Array	訂單中的商品列表
created_at	String	資料創建時間，格式為 YYYY-MM-DD HH:MM:SS
updated_at	String	資料更新時間，格式為 YYYY-MM-DD HH:MM:SS

訂單狀態列舉

• financial_status（付款狀態）:

  • pending：等待付款

  • paid：已收到款項

  • cod：貨到付款

  • remitted：已匯款未收到

  • failed：付款失敗

  • pending_refund：待退款

  • pending_partial_refund：待部分退款

  • partial_refunded：部分退款

  • refunded：已退款

• fulfillment_status（履行狀態）:

  • unshipped：未出貨

  • preparing：準備出貨

  • partial：部分出貨

  • fulfilled：已出貨

  • arrived：已到店

  • received：已收貨

  • returned：已退貨

  • expired：逾期未取

  • problem：運送異常

• return_status（退貨狀態）:

  • no_need：不需退貨

  • request_return：退貨申請

  • returning：退貨中

  • checking：退貨審查

  • refused：拒絕退貨

  • returned：已退貨

  • partial_return：部分退貨

  • in_origin_cvs：原寄件門市

  • in_hub：轉運中心

  • problem：運送異常