京東 API 深入探索:訂單與交易介面全解析

引言

商品 API 可用於展示、篩選與查看商品資訊,但唯有打通「訂單鏈路」,才能完成真正的電商交易流程。本文將深入解析以下內容:

  • 如何使用 jingdong.pop.orders.get 拉取訂單列表;

  • 如何使用 jingdong.pop.order.get 查詢單一訂單詳情;

  • 如何執行發貨流程;

  • 如何查詢物流追蹤資訊;

  • 常見錯誤代碼與處理建議。

一、訂單列表介面:jingdong.pop.orders.get

1. 功能說明

此介面用於查詢店鋪的訂單列表。開發者可根據下單時間、訂單狀態等條件進行篩選,並支援分頁返回結果,方便系統定時拉取新訂單進行處理。

2. 請求參數

參數名稱

類型

是否必填

範例

說明

order_state

string

WAIT_SELLER_STOCK_OUT

訂單狀態(詳見下方列舉)

start_date

string

2025-04-01 00:00:00

查詢區間的起始下單時間

end_date

string

2025-04-30 23:59:59

查詢區間的結束時間(建議小於7天)

optional_fields

string

order_total_price,payment_confirm_time

指定回傳欄位(提升效率)

page

int

1

分頁頁碼,預設為 1

page_size

int

20

每頁筆數,最大為 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

}

請注意,請求時仍需附帶系統級參數,例如 methodtimestampaccess_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": "江蘇省南京市..."

}

}

}

}

三、訂單狀態代碼列舉

狀態碼

狀態說明

WAIT_SELLER_STOCK_OUT

等待賣家出庫

WAIT_GOODS_RECEIVE_CONFIRM

已發貨,待買家確認收貨

FINISHED_L

訂單已完成

TRADE_CANCELED

訂單已取消

四、發貨介面: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": "到達南京分撥中心"

}

]

}

}

六、完整業務流程建議

  1. 使用者下單 → 系統定時調用 pop.orders.get 獲取新訂單;

  2. 拉取詳情 → 調用 pop.order.get 獲取商品明細與收件人資料;

  3. 系統完成打包發貨 → 調用 pop.order.ship 提交物流單號;

  4. 展示物流追蹤進度 → 調用 pop.order.track 取得物流節點;

  5. 後續處理如退貨退款,可延伸使用對應售後 API,例如退款申請、退貨流程與投訴處理等。

七、常見錯誤與處理建議

錯誤碼

發生原因

解決建議

3001

請求參數錯誤

請確認所有必填欄位與格式是否正確

401

access_token 已失效

重新發起授權流程並刷新 access_token

402

非法訂單編號或無權限存取

確認訂單編號正確,並檢查當前用戶是否有權存取

409

訂單狀態衝突(如重複發貨)

請查詢訂單當前狀態後再決定是否執行發貨

八、小結

透過本篇對京東交易類 API 的解析,我們可以構建起一套完整的訂單處理流程,包括訂單拉取、詳情查詢、發貨操作與物流追蹤等步驟。對於企業開發者而言,掌握這些核心介面將有助於打造穩定、高效的電商系統流程,也為後續的售後服務提供了可擴展的基礎能力。未來亦可根據業務需求拓展如退款、投訴、退貨等 API 模組,完善整體交易體驗。

Articles related to APIs :

如您需要方便快速使用 Jingdong API 可聯係我們:support@luckdata.com