接口

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

公共(gong)響應數據

1 用(yong)戶授權(quan)

OAuth2.0

1.1 構建授權鏈接(jie)

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

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

&redirect_uri=xxx&state=1，商家通過上面(mian)登錄(lu)授權后帶(dai)上code重定向到約(yue)定時(shi)的redirect_uri，如(ru)：redirect_uri?code=xxx&state=xxx

接口調用請求說明：

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

請求參數說明：

商家登錄(lu)授權步驟如(ru)下：

1. 第三方(fang)平臺(tai)構(gou)建授權鏈接放置自己的網站，商家點擊后，重定向到我(wo)來登錄頁面；

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

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

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

1.2 換取token

商家通過oauth登錄授權后(hou)會調用平臺約定的tokenUrl 換token，如下: tokenUrl為 oauth2/access_token，那么第(di)三(san)方(fang)平臺將以下參數post到(dao)該tokenUrl換(huan)取access token

接口調用請求說明：

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

請求參數說明：

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

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

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

回包(bao)參數說(shuo)明：

1.2.2 換(huan)取token錯誤(wu)返回(hui)格式

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

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

1.3 刷(shua)新token

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

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

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

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

1.3.1 換取token返(fan)回數(shu)據格式

返(fan)回內容(rong)與1.2.1 一(yi)致

1.3.2 換取token錯誤返回格式

返回內容與1.2.2 一致

2商品

2.1 獲(huo)取商品列表

2.1.1 接口方法

method：getProductList

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

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

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

2.1.2 請求(qiu)參數

2.1.3 請求示例

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

2.1.4 響應(ying)數據

Product

Sku

2.1.5 響應示例

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

2.2更新(xin)庫(ku)存

2.2.1 接口方法

method：updateStock

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

http請(qing)求(qiu)方式(shi)：POST
舊(jiu)請(qing)求地址(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 請求參數(shu)

2.2.3 請求(qiu)示(shi)例(li)

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

2.2.4 響應數據(ju)

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

2.3 添加實物商品

2.3.1 接口方(fang)法(fa)

method：addProduct

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

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

2.3.2 請求參數(shu)

sku類型：

prop類型：

2.3.3 請求示例

{
"name": "方便面",
"lid": 1,
"introduction": "非常美(mei)味，買二送一",
"img_url_list": ["//xxxx", "//xxxx", "//xxxx"],
    "media_id_list": ["ABUIABAAGAAgoZyylwYoqPW_rgI1", "ABUIABAAGAAgoZyylwYoqPW_rgI2", "ABUIABAAGAAgoZyylwYoqPW_rgI3"],
"prop_list": [{
"name": "容積",
"value": "5L"
}, {
"name": "重量(liang)",
"value": "5kg"
}],
"desc": "<p><img src=\"//xxxxx.jpg\"><\/p>",
"sku_list": [{
"price": 25.5,
"properties_name": [{
"name": "顏色",
"value": "白(bai)色",
           "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": "尺(chi)碼",
"value": "L",
           "media_id":"id3"
}],
"stock": 198,
"product_code": "CBA-123321"
}]
}

2.3.4 響應數據

返回數據與(yu)公共(gong)響應數據一致

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

2.4.1 接口方法

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

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

2.4.2 請求參數

無

2.4.3 請求示例

無

2.4.4 響應數據

lib_info類(lei)型(xing):

2.4.5 響(xiang)應示例

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

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

2.5.1 接(jie)口方法

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

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

2.5.2 請求參數

無(wu)

2.5.3 請求(qiu)示例

無

2.5.4 響(xiang)應(ying)數據

group_info類(lei)型：

2.5.5 響(xiang)應示例(li)

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

3 訂單(dan)

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

3.1.1 接口方法(fa)

method：getOrder

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

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

3.1.2 請求(qiu)參數

3.1.3 請求示例

{
&nbsp;  "order_id":"20200101001"
}

3.1.4 響應數(shu)據

Order

OrderItem

3.1.5 響應示(shi)例

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

3.2 獲(huo)取多個訂單

3.2.1 方法名稱

method：getOrderList

說明：不(bu)允(yun)許獲(huo)取三個月前的訂單

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

http請(qing)求方式：GET
舊請求(qiu)地址：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
新請求地址：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 請(qing)求參數(shu)

3.2.3 請求示例

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

3.2.4 響應(ying)數(shu)據

3.2.5 請求示例

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

3.3 訂單支付

3.3.1 調用說明

接口調用請求說明：

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

3.3.2 請求參數

3.3.3 請求(qiu)示例

{

"order_id":"20200101001"

}

3.3.4 響應數據

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

3.4 訂單發貨

3.4.1 方法名稱

method：shipOrder

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

接口調用請求說明：

http請求方式：POST
舊(jiu)請求(qiu)地(di)址：https://waybill.api.jz.fkw.com?access_token=xxx&method=shipOrder
&order_id=20200101001&waybill_no=M2002115671&logistics_code=SHUNFENG&logistics_name=順豐(feng)速運
新(xin)請求(qiu)地址：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=順(shun)豐速運

3.4.2 請求參數

3.4.3 請求示例

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

3.4.4 響應數據

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

3.5 訂單完成

3.5.1 方法名稱

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

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

http請求方(fang)式：POST
請求地址：//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 請(qing)求參(can)數

3.5.3 請(qing)求示例(li)

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

3.5.4 響應(ying)數(shu)據

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

3.6 訂單取消

3.6.1 調(diao)用(yong)說明

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

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

3.6.2 請(qing)求參數

3.6.3 請(qing)求示例

{

"order_id":"20200101001"

}

3.6.4 響應數據

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

4 上傳

4.1 媒體上(shang)傳

4.1.1 接(jie)口方法

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

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

4.1.2 請求參數(shu)

4.1.3 請求示例

無

4.1.4 響應數(shu)據

4.1.5 響應示(shi)例(li)

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

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

1、 資源(yuan)庫空(kong)間不足(zu)會上(shang)傳(chuan)失敗(bai)

2、 上傳(chuan)文(wen)件超過限定大小會上傳(chuan)失敗

3、接口調用(yong)過于頻繁(fan)會(hui)上(shang)傳失敗

4.2 媒體直(zhi)接(jie)上傳文件

4.2.1 接口方法(fa)

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

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

4.2.2 請(qing)求參數(shu)

4.2.3 請求示例

無

4.2.4 響應數據

4.2.5 響應示例(li)

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

4.2.6 常見異常返回說明(ming)

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

2、上傳文(wen)件超(chao)過限定大小會(hui)上傳失敗

5~6 會員積分(fen)接(jie)口前置說(shuo)明

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

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

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

說(shuo)明2：會員接口只負責(ze)做(zuo)數據傳輸(shu)，不涉及任何任何功能實現(xian)，因此靜默登錄/無需二(er)次登錄(lu)效果是無法實現的。

5 會(hui)員接口

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

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

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

5.1.1 請求參數

5.1.2 請求示例

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

5.1.3 響應數據(ju)

5.1.4 響應示例

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


      }
        ......     
    ],
      "total": 20

}

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

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

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

5.2.1 請求參數

5.2.2 請求(qiu)示例(li)

{
   "id":1
}

5.2.3 響應數據

5.2.4 響應(ying)示例

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

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

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

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

5.3.1 請求參(can)數

*注意(yi)：傳參(can)(can)時(shi)必須確保對(dui)應參(can)(can)數，在(zai)我來商城(cheng)后臺(tai)已開(kai)啟【注冊時啟用】，否則無法傳入(ru)。

5.3.2 請求示例

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

5.3.3 響應(ying)數據(ju)

5.3.4 響應示(shi)例

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

6 積分(fen)接口

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

接口調用請求說明：

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

6.1.1 請求參數

6.1.2 請(qing)求示例

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

6.1.3 響應數據

6.1.4 響應示例(li)

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

7 常見問題(ti)

Q：新舊(jiu)請求路徑如(ru)何選擇？

選擇新請(qing)求(qiu)地址，舊請(qing)求(qiu)不再(zai)維護(hu)，計劃后續會逐(zhu)步廢掉；

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

當(dang)前(qian)接(jie)口參數(shu)為【請求參數(shu)】傳參，非【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過期時間為2個(ge)(ge)小(xiao)時，那是不是每2個(ge)(ge)小(xiao)時客戶就得授權(quan)一(yi)次？

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