# 訂單 {% hint style="success" %} 此 API 為 2024-10-04 後版本 v.2.62.11 開放。 {% endhint %} ## 最佳實踐 在進行系統整合時，將訂單（Order）資料關聯到客戶（Contact）上是至關重要的。以下是推薦的整合流程步驟： 1. **查找或建立客戶資料** * 根據購買者的條件（如電子郵件、電話號碼等）查找現有客戶資料。 * 若無匹配的客戶資料，則建立新的客戶資料。 * 取得客戶的唯一識別碼（`contact_id`）。 2. **建立或更新訂單資料** * 使用訂單編號（`order_number`）和客戶 ID（`contact_id`）來建立新的訂單或更新現有訂單。 * 確保每筆訂單正確對應到相應的客戶，這有助於提升管理效率並保持數據的一致性。 遵循上述步驟，可有效優化 API 整合流程，確保訂單與客戶資料的準確關聯。 *** ## 搜尋訂單 **請求方法**: `GET`\ **端點**: `/api/v1/contact-order`\ **說明**: 根據指定條件搜尋符合的訂單列表。 **Curl 範例** ```bash curl -X GET \ -H "Content-Type: application/json" \ '{ "order_number": "ORD202309260001" }' \ https://{API_HOST}/api/v1/contact-order ``` **URL 參數**
參數名稱必填預設值類型說明
contact_id否NULLNumber客戶系統編號，例如 5263
order_number否NULLString訂單編號，例如 O412554
order_created_at__start否NULLString訂單建立開始時間，可能由專員手動，或由第三方電商／外部系統透過同步機制寫入，例如 2025-11-01
order_created_at__end否NULLString訂單建立結束時間，可能由專員手動，或由第三方電商／外部系統透過同步機制寫入，例如 2025-11-01
**回應結構** ```json { "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 範例** ```bash curl -X GET \ -H "Content-Type: application/json" \ https://{API_HOST}/api/v1/contact-order/1 ``` **URL 參數** | **參數名稱** | **必填** | **預設值** | **類型** | **說明** | | -------- | ------ | ------- | ------ | -------- | | `id` | 是 | NULL | Number | 訂單的唯一識別碼 | **回應結構** ```json { "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 範例** ```bash 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 | 訂單的補充資訊 | **回應結構** ```json { "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 範例** ```bash 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 | 訂單的補充資訊 | **回應結構** ```json { "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`：運送異常