京東 API 深入探索:訂單與交易介面全解析
引言
商品 API 可用於展示、篩選與查看商品資訊,但唯有打通「訂單鏈路」,才能完成真正的電商交易流程。本文將深入解析以下內容:
如何使用
jingdong.pop.orders.get
拉取訂單列表;如何使用
jingdong.pop.order.get
查詢單一訂單詳情;如何執行發貨流程;
如何查詢物流追蹤資訊;
常見錯誤代碼與處理建議。
一、訂單列表介面:jingdong.pop.orders.get
1. 功能說明
此介面用於查詢店鋪的訂單列表。開發者可根據下單時間、訂單狀態等條件進行篩選,並支援分頁返回結果,方便系統定時拉取新訂單進行處理。
2. 請求參數
參數名稱 | 類型 | 是否必填 | 範例 | 說明 |
---|---|---|---|---|
| string | 否 |
| 訂單狀態(詳見下方列舉) |
| string | 是 |
| 查詢區間的起始下單時間 |
| string | 是 |
| 查詢區間的結束時間(建議小於7天) |
| string | 否 |
| 指定回傳欄位(提升效率) |
| int | 否 |
| 分頁頁碼,預設為 1 |
| int | 否 |
| 每頁筆數,最大為 100 |
請求資料應打包為 360buy_param_json
,例如:
{"order_state": "WAIT_SELLER_STOCK_OUT",
"start_date": "2025-04-01 00:00:00",
"end_date": "2025-04-05 23:59:59",
"page": 1,
"page_size": 20
}
3. 回應資料範例
{"jingdong_pop_orders_get_responce": {
"order_info_list": {
"order_info": [
{
"order_id": 1234567890,
"order_total_price": 199.99,
"order_state": "WAIT_SELLER_STOCK_OUT",
"consignee_info": {
"name": "張三",
"full_address": "北京市朝陽區..."
}
}
]
}
}
}
二、訂單詳情介面:jingdong.pop.order.get
1. 功能說明
用於查詢單一訂單的詳細資訊,包括商品明細、收件人資訊、支付方式與配送狀態等。當系統需準備發貨或進一步處理時,建議優先拉取詳細資訊以確保準確性。
2. 請求參數
{"order_id": 1234567890
}
請注意,請求時仍需附帶系統級參數,例如 method
、timestamp
、access_token
等,參見京東 API 開發者文檔。
3. 回應資料範例
{"jingdong_pop_order_get_responce": {
"order_info": {
"order_id": 1234567890,
"freight_price": 8.00,
"order_state": "WAIT_SELLER_STOCK_OUT",
"items": [
{
"sku_id": 1000001,
"name": "小米手機",
"price": 899.00,
"num": 1
}
],
"payment_type": "線上支付",
"receiver_info": {
"name": "李四",
"address": "江蘇省南京市..."
}
}
}
}
三、訂單狀態代碼列舉
狀態碼 | 狀態說明 |
---|---|
| 等待賣家出庫 |
| 已發貨,待買家確認收貨 |
| 訂單已完成 |
| 訂單已取消 |
四、發貨介面:jingdong.pop.order.ship
此介面用於完成發貨操作,當商家將商品交由物流配送後,需透過此 API 將訂單狀態標記為已發貨,並提交對應的物流單號。
請求參數範例
{"order_id": 1234567890,
"logistics_id": 1010,
"waybill": "JD123456789CN",
"trade_no": "optional"
}
其中,logistics_id
為京東物流公司對應編號,需提前透過京東平台查詢或獲取該值。
五、物流資訊查詢介面:jingdong.pop.order.track
此介面可查詢訂單物流進度,用於顯示給買家或供系統監控物流狀態。
請求參數範例
{"order_id": 1234567890
}
回應資料範例
{"jingdong_pop_order_track_responce": {
"order_tracks": [
{
"time": "2025-05-01 10:00:00",
"content": "包裹已攬收"
},
{
"time": "2025-05-02 15:45:00",
"content": "到達南京分撥中心"
}
]
}
}
六、完整業務流程建議
使用者下單 → 系統定時調用
pop.orders.get
獲取新訂單;拉取詳情 → 調用
pop.order.get
獲取商品明細與收件人資料;系統完成打包發貨 → 調用
pop.order.ship
提交物流單號;展示物流追蹤進度 → 調用
pop.order.track
取得物流節點;後續處理如退貨退款,可延伸使用對應售後 API,例如退款申請、退貨流程與投訴處理等。
七、常見錯誤與處理建議
錯誤碼 | 發生原因 | 解決建議 |
---|---|---|
3001 | 請求參數錯誤 | 請確認所有必填欄位與格式是否正確 |
401 | access_token 已失效 | 重新發起授權流程並刷新 access_token |
402 | 非法訂單編號或無權限存取 | 確認訂單編號正確,並檢查當前用戶是否有權存取 |
409 | 訂單狀態衝突(如重複發貨) | 請查詢訂單當前狀態後再決定是否執行發貨 |
八、小結
透過本篇對京東交易類 API 的解析,我們可以構建起一套完整的訂單處理流程,包括訂單拉取、詳情查詢、發貨操作與物流追蹤等步驟。對於企業開發者而言,掌握這些核心介面將有助於打造穩定、高效的電商系統流程,也為後續的售後服務提供了可擴展的基礎能力。未來亦可根據業務需求拓展如退款、投訴、退貨等 API 模組,完善整體交易體驗。
Articles related to APIs :
JD Open Platform Practical Guide ③: Full Analysis of Product Query and Detail APIs
JD API Authentication and Signature Mechanism: A Complete Guide for Secure Integration
如您需要方便快速使用 Jingdong API 可聯係我們:support@luckdata.com