📄訂單

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

最佳實踐

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

查找或建立客戶資料
- 根據購買者的條件（如電子郵件、電話號碼等）查找現有客戶資料。
- 若無匹配的客戶資料，則建立新的客戶資料。
- 取得客戶的唯一識別碼（contact_id）。
建立或更新訂單資料
- 使用訂單編號（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 參數

回應結構

{
    "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": {
        // 分頁相關元數據
    }
}

回應欄位說明

取得單筆訂單資料

請求方法: 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 參數

回應結構

{
    "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"
      }
}

回應欄位說明

新增訂單

請求方法: 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

表單資料

回應結構

{
    "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 參數

表單資料

回應結構

{
    "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"
      }
}

訂單資料模型

訂單狀態列舉

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：運送異常

Previous產品 Next訂單品項

Last updated 1 month ago