接口

公(gong)共請求(qiu)參數

公共響應(ying)數據(ju)

1 用戶授(shou)權(quan)

OAuth2.0

1.1 構建授權鏈接

拼接(jie)登錄授權url給商(shang)家登錄授權，如下：

/oauth2/oauth_h?cmd=getAuthCode&client_id=xxx&platform_code=FKW

&redirect_uri=xxx&state=1，商家通過上面登錄授權后帶上code重定向到約定時的redirect_uri，如：redirect_uri?code=xxx&state=xxx

接口調(diao)用請求說明：

http請求方式：GET
舊請(qing)求地址：//waybill.api.jz.fkw.com/oauth2/oauth_h?
cmd=getAuthCode&client_id=xxx&platform_code=FKW&redirect_uri=xxx&;state=xxx
新請求(qiu)地址(zhi)：//waybill.api.jz.fkw.com/api/oauth
/getAuthCode?cmd=getAuthCode&client_id=xxx&platform_code=FKW&redirect_uri=xxx&state=xxx

請(qing)求參數(shu)說明(ming)：

商家登錄授(shou)權(quan)步驟如下(xia)：

1. 第三方(fang)平臺構(gou)建(jian)授權鏈接(jie)放置自己的網(wang)站(zhan)，商家點擊(ji)后(hou)，重定(ding)向(xiang)到我來(lai)登錄頁面；

2. 進行(xing)登錄(lu)，登錄(lu)成功會跳轉到授權頁(ye)面；

3. 選擇需要授(shou)權(quan)的站(zhan)點，然后點擊(ji)【確定授(shou)權(quan)】;

4. 商家授(shou)權確認(ren)之后，授(shou)權頁(ye)會自動跳轉進入(ru)回調 URI，并(bing)在 URL 參數中返回授(shou)權碼(redirect_url?code=xxx&state=xxx)

1.2 換(huan)取(qu)token

商家(jia)通過oauth登錄授權后會調用平臺約定(ding)的tokenUrl 換(huan)token，如下: tokenUrl為(wei) oauth2/access_token，那么第三方平(ping)臺(tai)將(jiang)以下參數(shu)post到該tokenUrl換取access token

接(jie)口調(diao)用請求說明：

http請求(qiu)方式：POST
舊請求地(di)址：https://waybill.api.jz.fkw.com/oauth/access_token?client_id=xxx
&client_secret=xxx&grant_type=authorization_code&code=xxx
新請求(qiu)地(di)址：https://waybill.api.jz.fkw.com/api/oauth/getAccessToken?client_id=xxx
&client_secret=xxx&grant_type=authorization_code&code=xxx

請求參數(shu)說(shuo)明：

1.2.1 換取token返回數據格(ge)式

以(yi)json格式返回，格式如下

{
    "shop_id": "11039290",
    "shop_name": "xxx",
    "user_id": "11039290",
    "re_expires_in": 2419200,
    "expires_in": 7200,
    "token_type": "xxx",
    "refresh_token": "pVAB0H8yC48cDkEOKY_Bq67_4VxEetSuX5QC8rIo",
    "access_token": "xn-9lDOA6HjvTpimEw3WzGNdz7LrSeX_rJxeBP20",
    "platform_code": "FKW"
}

回(hui)包參(can)數說明：

1.2.2 換取token錯(cuo)誤返回格式

以json格式返回，格式如(ru)下(xia)

{
    "rt": 100,
    "success": false,
    "msg": "授權(quan)碼已過期。"
}

1.3 刷新token

通過(guo)授權(quan)獲取的refresh_token（前置(zhi)條件：re_expires_in>0）可用來刷新access token的時長，如下: tokenUrl為 oauth2/access_token，第三方(fang)平臺(tai)將以下參數(shu)以post的請(qing)求方式發送refresh token url刷新access token時長

接口調用請求說明：

http請求(qiu)方式：POST
舊請求(qiu)地址：https://waybill.api.jz.fkw.com/oauth2/access_token?client_id=xxx
&client_secret=xxx&grant_type=refresh_token&refresh_token=xxx
新請求地址(zhi)：https://waybill.api.jz.fkw.com/api/oauth/refreshAccessToken?client_id=xxx
&client_secret=xxx&grant_type=refresh_token&refresh_token=xxx

請求參數(shu)說明：

1.3.1 換取token返回數據格式

返回內容與(yu)1.2.1 一致

1.3.2 換(huan)取(qu)token錯誤返回格式

返(fan)回內容與1.2.2 一致

2商品

2.1 獲(huo)取商品列表

2.1.1 接(jie)口方法

method：getProductList

說明：默認(ren)以產品創建時間(jian)降序(xu)排序(xu)

接口調用請(qing)求(qiu)說明：

http請求方式：GET
舊請求地址(zhi)：https://waybill.api.jz.fkw.com?access_token=xxx&method=getProductList
&page_no=1&page_size=200
新(xin)請求(qiu)地(di)址：https://waybill.api.jz.fkw.com/api/product/getList?access_token=xxx
&method=getProductList&page_no=1&page_size=200

2.1.2 請求(qiu)參數(shu)

2.1.3 請(qing)求示(shi)例

{
   'page_no':1,
   'page_size':200
}

2.1.4 響應數據

Product

Sku

2.1.5 響應(ying)示例

{
   "rt":0,
   "success":true,
   "msg": "查詢成功",
   'product_list': [
    {
      'id': '1',
      'name': '商(shang)品(pin)1',
      'code': 'code',
      'picture': 'url',
      'create_time': '2020-01-01',
      'sku_list': [
        {
          'sku_id':'1_1',
          'price':1,
          "properties_name": "顏色:白(bai)色;尺碼(ma):XXL",
          'stock':10,
          'product_code':'bilibili'
        }
        ......
      ]
    }
    ......
   ]
}

2.2更(geng)新(xin)庫存

2.2.1 接口方法

method：updateStock

接口調用請(qing)求說明(ming)：

http請求(qiu)方式(shi)：POST
舊請求地址(zhi)：https://waybill.api.jz.fkw.com?access_token=xxx&method=updateStock
&product_id=1&sku_id=1_1&stock_amount=10
新請求地址：https://waybill.api.jz.fkw.com/api/product/updateStock?access_token=xxx
&method=updateStock&product_id=1&sku_id=1_1&stock_amount=10

2.2.2 請求參(can)數

2.2.3 請求示例

{
   "product_id": "1",
   "sku_id": "1_1",
   "stock_amount": 10
}

2.2.4 響應數據(ju)

返回數據(ju)與公共響應(ying)數據(ju)一(yi)致

2.3 添(tian)加(jia)實物商(shang)品

2.3.1 接口方法

method：addProduct

接(jie)口調用請求說明：

http請(qing)求方式：POST
請求地址：//waybill.api.jz.fkw.com/api/product/add?access_token=xxx&method=addProduct

2.3.2 請求參數

sku類型：

prop類型：

2.3.3 請求示例

{
"name": "方便(bian)面",
"lid": 1,
"introduction": "非常(chang)美味，買二(er)送一",
"img_url_list": ["//xxxx", "//xxxx", "//xxxx"],
    "media_id_list": ["ABUIABAAGAAgoZyylwYoqPW_rgI1", "ABUIABAAGAAgoZyylwYoqPW_rgI2", "ABUIABAAGAAgoZyylwYoqPW_rgI3"],
"prop_list": [{
"name": "容積",
"value": "5L"
}, {
"name": "重量",
"value": "5kg"
}],
"desc": "<p><img src=\"//xxxxx.jpg\&quot;><\/p>",
"sku_list": [{
"price": 25.5,
"properties_name": [{
"name": "顏色",
"value": "白色",
           "media_id":"id1"
}, {
"name": "尺碼",
"value": "XXL",
           "media_id":"id2"
}],
"stock": 998,
"product_code": "ABC-321123"
}, {
"price": 28.5,
"properties_name": [{
"name": "顏色",
"value": "白色",
           "media_id":"id1"
}, {
"name": "尺碼",
"value": "L",
           "media_id":"id3"
}],
"stock": 198,
"product_code": "CBA-123321"
}]
}

2.3.4 響應(ying)數據(ju)

返回(hui)數(shu)據(ju)與公共響應(ying)數(shu)據(ju)一致

2.4 獲取商(shang)品庫(ku)列表

2.4.1 接(jie)口方法

接口調用請求說明：

http請求方式：GET
請求地址(zhi)：//waybill.api.jz.fkw.com/api/product/getProductLibList?access_token=xxx

2.4.2 請求參數

無(wu)

2.4.3 請(qing)求示例(li)

無

2.4.4 響應數據(ju)

lib_info類(lei)型:

2.4.5 響(xiang)應示例

{
   "rt":0,
   "success":true,
   "msg": "查(cha)詢成功",
   "lib_list": [
      {
          "lib_id": 1,
          "name": "庫1"
      },
      {
          "lib_id": 2,
          "name": "庫2"
      },
      {
          "lib_id": 3,
          "name": "庫(ku)3"
      }
   ]
}

2.5 獲取商(shang)品分(fen)類列表

2.5.1 接口(kou)方法

接口(kou)調用請求說明：

http請(qing)求方式(shi)：GET 請(qing)求地址：//waybill.api.jz.fkw.com/api/product/getProductGroupList?access_token=xxx

2.5.2 請求參數

無

2.5.3 請求(qiu)示例

無

2.5.4 響應數(shu)據

group_info類(lei)型：

2.5.5 響應示例

{
   "rt":0,
   "success":true,
   "msg": "查詢成功",
   "group_list": [
      {
          "group_id": 1,
          "name": "一(yi)級(ji)分類",
          "parent_id": 0
      },
      {
          "group_id": 2,
          "name": "二(er)級分類",
          "parent_id": 1
      },
      {
          "group_id": 3,
          "name": "三級分類",
          "parent_id": 2
      },
      {
          "group_id": 4,
          "name": "一級(ji)分類2",
          "parent_id": 0
      },
      {
          "group_id": 5,
          "name": "二級(ji)分類2",
          "parent_id": 4
      }
   ]
}

3 訂單

3.1 獲取單(dan)個訂單(dan)

3.1.1 接口方(fang)法(fa)

method：getOrder

接口調用請(qing)求說明：

http請(qing)求方式：GET
舊(jiu)請求地址：https://waybill.api.jz.fkw.com?access_token=xxx&method=getOrder&order_id=1
新請(qing)求地址：https://waybill.api.jz.fkw.com/api/order/get?access_token=xxx
&method=getOrder&order_id=1

3.1.2 請(qing)求參數

3.1.3 請求示例

{
   "order_id":"20200101001"
}

3.1.4 響應數據

Order

OrderItem

3.1.5 響(xiang)應示例

{
   "rt":0,
   "success":true,
   "msg": "查詢成功",
   "order":{
    "id": "20200101001",
    "buyer_acct": "test_acct",
    "province": "廣東省",
    "city": "廣州市",
    "district": "天(tian)河區",
    ......
    "order_item_list": [
      {
        "id": "1",
        "title": "測(ce)試商品",
        "product_id": "33333",
        ......
      }
    ]
   }
}

3.2 獲取多個訂(ding)單

3.2.1 方(fang)法名稱

method：getOrderList

說明：不允許獲取三個(ge)月前(qian)的訂單

接口調用請求說明：

http請求方式：GET
舊請求地址：https://waybill.api.jz.fkw.com?access_token=xxx&method=getOrderList
&status=wait_seller_ship&page_size=100&page_no=1&time_type=created&time_from=2021-02-23 16:00:00&time_to=2021-02-30 16:00:00
新(xin)請求地址：https://waybill.api.jz.fkw.com/api/order/getList?access_token=xxx
&method=getOrderList&status=wait_seller_ship&amp;page_size=100&page_no=1&time_type=created&time_from=2021-02-23 16:00:00&time_to=2021-02-30 16:00:00

3.2.2 請求參數(shu)

3.2.3 請(qing)求示例

{
   "status":"wait_buyer_pay&quot;,
   "page_no":1,
   "page_size":100，
&nbsp;  &quot;time_type":"created",
   &quot;time_from&quot;:"2021-02-23 16:00:00",
  &nbsp;"time_to":"2021-02-30 16:00:00"
}

3.2.4 響應(ying)數據(ju)

3.2.5 請求示例

{
   "rt":0,
   "success":true,
   "msg": "查詢成功(gong)",
   "order_list":[
    {
      "id": "20200101001",
      "buyer_acct": "test_acct",
      "province": "廣東省",
      "city": "廣州市(shi)",
      "district": "天河區",
      ......
      "order_item_list": [
        {
          "id": "1",
          "title": "測試商(shang)品",
          "product_id": "33333",
          ......
        }
      ]
    }
    ......
   ],
   "total": 10
}

3.3 訂(ding)單支付

3.3.1 調用(yong)說(shuo)明

接口調用(yong)請(qing)求(qiu)說明：

http請求方式：POST
請求地址：//waybill.api.jz.fkw.com/api/order/pay?access_token=xxx&order_id=20200101001

3.3.2 請求(qiu)參(can)數

3.3.3 請(qing)求(qiu)示例

{

"order_id":"20200101001"

}

3.3.4 響應數據(ju)

返回內(nei)容(rong)與公共(gong)響應數據一致

3.4 訂(ding)單發(fa)貨

3.4.1 方法名稱

method：shipOrder

說明：logistics_code請(qing)參照以下的快遞100快遞公司(si)(si)標準編(bian)碼的【公司(si)(si)編(bian)碼】，不能(neng)自定義

接口調用請求說(shuo)明：

http請(qing)求方式(shi)：POST
舊(jiu)請求地址：https://waybill.api.jz.fkw.com?access_token=xxx&method=shipOrder
&order_id=20200101001&waybill_no=M2002115671&logistics_code=SHUNFENG&logistics_name=順(shun)豐速運
新(xin)請求地(di)址：https://waybill.api.jz.fkw.com/api/order/ship?access_token=xxx&method=shipOrder
&order_id=20200101001&waybill_no=M2002115671&logistics_code=SHUNFENG&logistics_name=順豐速(su)運(yun)

3.4.2 請求參數(shu)

3.4.3 請求(qiu)示例

{
   "order_id":"20200101001",
   "waybill_no":"M2002115671",
   "logistics_code":"shunfeng",
   "logistics_name":"順豐速運(yun)"
}

3.4.4 響應數據

返(fan)回內容與(yu)公共響應數據一致

3.5 訂(ding)單完成(cheng)

3.5.1 方法名稱

說明(ming)：logistics_code請參照以下的快遞(di)100快遞(di)公(gong)(gong)司標準編碼(ma)的【公(gong)(gong)司編碼(ma)】，不(bu)能自(zi)定義

接口(kou)調用(yong)請求說明：

http請求方(fang)式：POST
請(qing)求地(di)址(zhi)：//waybill.api.jz.fkw.com/api/order/complete?access_token=xxx&order_id=20200101001&waybill_no=M2002115671&logistics_code=SHUNFENG&logistics_name=順豐速運

3.5.2 請求參數

3.5.3 請求示例

{
   "order_id":"20200101001",
   "waybill_no":"M2002115671&quot;,
   "logistics_code":";SHUNFENG",
&nbsp;  "logistics_name":"順豐速運"
}

3.5.4 響應數(shu)據(ju)

返回(hui)內容與公共響(xiang)應數據一致(zhi)

3.6 訂單取消

3.6.1 調(diao)用說(shuo)明

接口調(diao)用請求說(shuo)明：

http請(qing)求(qiu)方(fang)式：POST
請求地址：//waybill.api.jz.fkw.com/api/order/cancel?access_token=xxx&order_id=20200101001

3.6.2 請求參數

3.6.3 請求示例

{

"order_id":"20200101001"

}

3.6.4 響(xiang)應數據

返回內容與公共響應數據一致(zhi)

4 上傳

4.1 媒體(ti)上傳

4.1.1 接口方法

接口調用(yong)請求說明：

http請求(qiu)方(fang)式(shi)：POST 請求(qiu)地址：//waybill.api.jz.fkw.com/api/upload/uploadMedia?access_token=xxx

4.1.2 請求參數(shu)

4.1.3 請求示例

無

4.1.4 響應數據

4.1.5 響應示例

{
    "rt": 0,
    "success": true,
    "msg";: "上(shang)傳成功",
    "media_id": "ABUIABAAGAAgoZyylwYoqPW_rgI",
    "media_url": "//xxxxxx/x/x/ABUIABAAGAAgoZyylwYoqPW_rgI.png"
}

4.1.6 常見(jian)異常返回說明

1、 資源庫空(kong)間不足會上傳失敗

2、 上傳文件超過限定大小會上傳失敗

3、接口調用過(guo)于(yu)頻繁會上傳(chuan)失敗

4.2 媒體(ti)直接上傳(chuan)文件

4.2.1 接(jie)口方法

接口調用請求(qiu)說明：

http請求方式：POST/FORM （用FORM表(biao)單(dan)方式上傳一個多媒體文(wen)件）
請求地址：//waybill.api.jz.fkw.com/api/upload/uploadMediaByFile?access_token=xxx

4.2.2 請求參數

4.2.3 請求示例

無

4.2.4 響(xiang)應(ying)數據

4.2.5 響應示例

{
    "rt": 0,
    "success": true,
    "msg": "上傳成功",
    "media_id": "ABUIABAAGAAgoZyylwYoqPW_rgI",
    "media_url": "//xxxxxx/x/x/ABUIABAAGAAgoZyylwYoqPW_rgI.png"
}

4.2.6 常(chang)見異(yi)常(chang)返回說明

1、資(zi)源(yuan)庫(ku)空間不足會上傳失(shi)敗

2、上(shang)傳文(wen)件超過(guo)限定(ding)大小(xiao)會上(shang)傳失(shi)敗

5~6 會員(yuan)積分接口前置說明

說明(ming)1：如您對接的(de)是小(xiao)程序，我(wo)來商城必須獲(huo)取到會員微(wei)信unionid，用手機號/賬號是不行(xing)的。因此要求：

（1）您(nin)需將我來(lai)商城小程序，綁定至(zhi)您自己(ji)的開放平(ping)臺下-保證同個會員unionid**性 （)

（2）您需(xu)自行(xing)存儲好小程序客戶的unionid----------------會員新(xin)增時需傳給我來(lai)

說(shuo)明2：會(hui)員接口只負責做數據(ju)傳輸，不涉及任(ren)何(he)任(ren)何(he)功能(neng)實現(xian)，因(yin)此(ci)靜默登錄/無需(xu)二次登錄(lu)效果是無法實(shi)現的。

5 會員接口

5.1 批量(liang)會(hui)員與積(ji)分(fen)獲(huo)取接口(kou) （同步我(wo)來商城(cheng)會員數(shu)據(ju)到第三方系統）

接口調用請求說明(ming)：

http請(qing)求方式：GET
請求地址：https://waybill.api.jz.fkw.com/api/member/getList?access_token=xxx

5.1.1 請求參數(shu)

5.1.2 請求示例

{
   "page_no":1,
   "page_size":100
}

5.1.3 響應數據

5.1.4 響應示例

{
    "rt": 0,
    "success": true,
    "msg": "查詢成功",
    "member_list":[
    {
          "id": "1",
          "acct": "acct1",
          "name": "會員1",
&nbsp;         "mobile": "",
      &nbsp;   "email": "",
      &nbsp;   "level": 0,
  &nbsp;       "wxAppUnionId":"xxxxxxxxx",
         ; "currentIgt&quot;:10,
  &nbsp;   &nbsp;   "totalIgt":20,
          "propList":{"name":"地區","value":"廣州"},{"name":"面積","value":"小超市"}
      },
      {
 ;    ;     "id": "2",
          "acct";: "acct2",
          "name": "會(hui)員2",
&nbsp;         &quot;mobile": "",
          "email": "",
   ;     &nbsp; "level": 2,
&nbsp;         "wxAppUnionId":"xxxxxxxxx",
          "currentIgt":10,
    &nbsp;     "totalIgt":20,
          "propList":{"name":"地區","value":"廣州"},{"name":"面積","value":"小超市"}


      }
    &nbsp;   ......     
    ],
      "total": 20

}

5.2 單個會員與積分獲(huo)取接口 （同步我來商城(cheng)會員數據到第(di)三方系統）

接口調用(yong)請求說明：

http請求方式：GET
請求地址：https://waybill.api.jz.fkw.com/api/member/get?access_token=xxx&id=1

5.2.1 請求參(can)數

5.2.2 請求(qiu)示例

{
   "id":1
}

5.2.3 響應數據

5.2.4 響應示例

{
    "rt": 0,
    "success": true,
    "msg": "查詢成功",
    "member":{
&nbsp;         "acct": "acct1",
          "name": "會員1",
          "mobile": &quot;",
      &nbsp;   "email": "",
        &nbsp; "level": "黃金會員",
          "currentIgt":10,
          "totalIgt":20,
          "propList":{"name":"地區","value":"廣州"},{"name":&quot;面積","value":"小超市"}
     
      }
}

5.3 新增會(hui)員接口 （第三(san)方系統將(jiang)會員數(shu)據(ju)寫入到(dao)我來商城后(hou)臺）

接口調用請(qing)求說(shuo)明：

http請求方式：POST
請求地址：https://waybill.api.jz.fkw.com/api/member/add?access_token=xxx

5.3.1 請求參數

*注意：傳參時必須確(que)保對應參數，在(zai)我來(lai)商城后臺已開啟【注冊(ce)時啟用】，否(fou)則無法傳入(ru)。

5.3.2 請求示例

{
   "acct":"test1",
   "pwd&quot;:"abc123456",
   "name":"測試1",
   "mobile":"",
   "email":"",
   "level":1,
   "union_id":"xxxxxxxx",
   "prop_list":[{"name":"地區(qu)","value":"廣州"}, {"name":"商戶名","value":"小超市"}]
}

5.3.3 響應(ying)數據

5.3.4 響應示例

成(cheng)功
{
    "rt": 0,
    "success": true,
    "msg": "新增成功(gong)",
    "id":1
}
失敗
{
    "rt": -2,
    "success": false,
    "msg": "密(mi)碼格式錯誤"
}

6 積分接口(kou)

6.1 積分增減(jian)接(jie)口 （第三方系統對我來商城(cheng)積(ji)分做新增或扣減）

接(jie)口調用請求說明：

http請求方(fang)式：POST
請求地址：https://waybill.api.jz.fkw.com/api/member/setIgt?access_token=xxx&id=1

6.1.1 請求參數

6.1.2 請求示例

{
   "id":1,
   "operate":0,
   "alter_num":5,
   "detail":"主動增(zeng)加5積分(fen)"
}

6.1.3 響應數據

6.1.4 響應示(shi)例

{
    "rt": 0,
    "success": true,
    "msg": "商家贈送積分(fen)成功"
}

7 常見問(wen)題

Q：新(xin)舊請(qing)求路徑如何(he)選(xuan)擇？

選擇新(xin)請求地址，舊請求不再維護，計劃后(hou)續(xu)會逐步廢掉(diao)；

Q：請求報錯，參數【xxx】為(wei)必填(tian)項

當前接口參數為【請(qing)求(qiu)參數】傳參，非(fei)【json】格式傳參。如換取token請求為

//waybill.api.jz.fkw.com/api/oauth/getAccessToken?client_id=xxx&client_secret=xxx&grant_type=authorization_code&code=xxx

Q：access_token過期時(shi)間為(wei)2個(ge)小時(shi)，那是不是每2個(ge)小時(shi)客戶就(jiu)得(de)授權一次？

不是(shi)！！！access_token過期可以通過refresh_token調用【刷新token】接口換取新的access_token，refresh_token的過期時間為28天，客戶每隔28天授權一次即可。