接(jie)口(kou)

公共請求參數

公共(gong)響應數據

1 用戶授(shou)權

OAuth2.0

1.1 構(gou)建授權(quan)鏈接

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

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

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

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

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

請求參(can)數說明：

商家登錄授權步驟如下：

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

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

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

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

1.2 換取token

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

接口調用請求說明：

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

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

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

以(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"
}

回包參數說明(ming)：

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

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

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

1.3 刷新(xin)token

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

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

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

請求參數說明：

1.3.1 換(huan)取token返回(hui)數據格式

返(fan)回內容與1.2.1 一致(zhi)

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

返回內容與1.2.2 一致

2商品(pin)

2.1 獲(huo)取商品(pin)列表(biao)

2.1.1 接口方法

method：getProductList

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

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

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

2.1.2 請求參數

2.1.3 請求示例

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

2.1.4 響(xiang)應數據

Product

Sku

2.1.5 響應示例

{
   "rt":0,
   "success":true,
   "msg": "查詢成功",
   'product_list': [
    {
      'id': '1',
      'name': '商品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更(geng)新庫存

2.2.1 接(jie)口方法

method：updateStock

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

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

2.2.3 請求示例

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

2.2.4 響應數據

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

2.3 添(tian)加實物(wu)商品

2.3.1 接(jie)口(kou)方法

method：addProduct

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

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

2.3.2 請求(qiu)參數

sku類型：

prop類型：

2.3.3 請求示例

{
"name": "方(fang)便面",
"lid": 1,
"introduction": "非常(chang)美(mei)味，買二送一(yi)",
"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\"><\/p>",
"sku_list": [{
"price": 25.5,
"properties_name": [{
"name": "顏色(se)",
"value": "白色(se)",
           "media_id":"id1"
}, {
"name": "尺碼",
"value": "XXL",
           "media_id":"id2"
}],
"stock": 998,
"product_code": "ABC-321123"
}, {
"price": 28.5,
"properties_name": [{
"name": "顏(yan)色(se)",
"value": "白色",
           "media_id":"id1"
}, {
"name": "尺碼",
"value": "L",
           "media_id":"id3"
}],
"stock": 198,
"product_code": "CBA-123321"
}]
}

2.3.4 響應(ying)數據(ju)

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

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

2.4.1 接口方法

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

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

2.4.2 請求參數(shu)

無

2.4.3 請求示(shi)例

無

2.4.4 響應數據

lib_info類型:

2.4.5 響(xiang)應(ying)示例

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

2.5 獲(huo)取(qu)商品分類列表

2.5.1 接口(kou)方法

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

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

2.5.2 請求參數

無

2.5.3 請求示例

無

2.5.4 響應數據

group_info類型(xing)：

2.5.5 響(xiang)應示例

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

3 訂單

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

3.1.1 接(jie)口方(fang)法

method：getOrder

接口調用請求說明：

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

3.1.3 請求示例(li)

{
   "order_id":"20200101001"
}

3.1.4 響應數據

Order

OrderItem

3.1.5 響應示例

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

3.2 獲取多個訂單(dan)

3.2.1 方法名稱

method：getOrderList

說明：不(bu)允許獲取(qu)三(san)個月前的(de)訂單

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

http請(qing)求方式：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
新請求(qiu)地址：https://waybill.api.jz.fkw.com/api/order/getList?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

3.2.2 請求參數

3.2.3 請(qing)求示例

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

3.2.4 響應數據

3.2.5 請求示例(li)

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

3.3 訂單支(zhi)付

3.3.1 調用(yong)說明

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

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

3.3.2 請求參數

3.3.3 請求示例(li)

{

"order_id":"20200101001"

}

3.3.4 響應數據

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

3.4 訂單發貨

3.4.1 方(fang)法名稱

method：shipOrder

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

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

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

3.4.2 請求參(can)數

3.4.3 請求(qiu)示例

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

3.4.4 響應(ying)數據

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

3.5 訂單(dan)完成

3.5.1 方法(fa)名稱(cheng)

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

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

http請(qing)求方(fang)式：POST
請求(qiu)地址：//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":&quot;20200101001",
   "waybill_no":"M2002115671",
 ;  "logistics_code":"SHUNFENG",
   "logistics_name":"順豐速(su)運"
}

3.5.4 響應數據

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

3.6 訂(ding)單取消

3.6.1 調用說明

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

http請求方式：POST
請(qing)求地(di)址：//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 響應數據

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

4 上傳

4.1 媒體(ti)上傳

4.1.1 接口(kou)方法(fa)

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

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

4.1.2 請(qing)求參數

4.1.3 請求示例

無(wu)

4.1.4 響應(ying)數據

4.1.5 響應示(shi)例

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

4.1.6 常見異常返回說明

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

2、 上傳文件(jian)超過(guo)限(xian)定大小會上傳失敗

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

4.2 媒體直接上傳文件

4.2.1 接口方法

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

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

4.2.2 請求參(can)數

4.2.3 請求示例(li)

無

4.2.4 響(xiang)應數據(ju)

4.2.5 響(xiang)應示例

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

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

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

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

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

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

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

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

說明2：會員(yuan)接口只負責做數據傳輸，不(bu)涉及任何任何功能實(shi)現，因此(ci)靜(jing)默(mo)登(deng)錄/無需二次登錄效果是無法實(shi)現的。

5 會員接口

5.1 批(pi)量(liang)會員與積分獲取接口 （同步我來商城會員(yuan)數據到第三方系統）

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

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

5.1.1 請求參(can)數

5.1.2 請求示(shi)例(li)

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

5.1.3 響應數據

5.1.4 響應(ying)示例

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


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

}

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

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

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

5.2.1 請求參數(shu)

5.2.2 請求示例

{
   "id":1
}

5.2.3 響(xiang)應數(shu)據

5.2.4 響應示例

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

5.3 新增會員接口 （第三方系統將會員數據寫入到我(wo)來(lai)商(shang)城后(hou)臺(tai)）

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

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

5.3.1 請求參數

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

5.3.2 請求示例

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

5.3.3 響應數據

5.3.4 響應示例

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

6 積(ji)分接口

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

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

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

6.1.1 請求(qiu)參數

6.1.2 請求示(shi)例(li)

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

6.1.3 響(xiang)應數據

6.1.4 響應(ying)示例

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

7 常見問題

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

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

Q：請求報錯(cuo)，參數(shu)【xxx】為必填項(xiang)

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

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