# 訂單 {% 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`：運送異常 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.firstline.cc/developer/api/contact-order.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.