接口

公共請(qing)求參(can)數(shu)

公共響應數據(ju)

1 用戶授(shou)權

OAuth2.0

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

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

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

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

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

http請求方式：GET
舊(jiu)請(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

請求參數說明：

商家登錄授權步驟如下：

1. 第三方平臺構建(jian)授權鏈(lian)接放置(zhi)自(zi)己的網站(zhan)，商(shang)家點擊后，重定向到我來登(deng)錄頁面(mian)；

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

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

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

1.2 換取token

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

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

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

請求參數說明：

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

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

{
    "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)參數說明：

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

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

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

1.3 刷新token

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

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

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

請求參數說(shuo)明：

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

返回內(nei)容與1.2.1 一致

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

返回內容與1.2.2 一致

2商品

2.1 獲取(qu)商品列表

2.1.1 接口方法

method：getProductList

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

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

http請(qing)求方式：GET
舊請求地址：https://waybill.api.jz.fkw.com?access_token=xxx&method=getProductList
&page_no=1&page_size=200
新(xin)請求地址：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 響應數據(ju)

Product

Sku

2.1.5 響(xiang)應示例

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

2.2更(geng)新庫存(cun)

2.2.1 接(jie)口方法

method：updateStock

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

http請求方式：POST
舊請(qing)求地址：https://waybill.api.jz.fkw.com?access_token=xxx&method=updateStock
&product_id=1&sku_id=1_1&stock_amount=10
新請求(qiu)地址：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 請(qing)求參(can)數

2.2.3 請求示例

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

2.2.4 響應數(shu)據

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

2.3 添加實物商(shang)品

2.3.1 接(jie)口方法

method：addProduct

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

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

2.3.2 請求參數

sku類型：

prop類(lei)型：

2.3.3 請求示例

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

2.3.4 響應數據(ju)

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

2.4 獲取商品庫列表

2.4.1 接口(kou)方法

接口調用請求說明：

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

2.4.2 請求參數(shu)

無

2.4.3 請求示例(li)

無

2.4.4 響應數(shu)據

lib_info類型:

2.4.5 響應(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)取商(shang)品分類列表

2.5.1 接口方法

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

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

2.5.2 請(qing)求參數

無(wu)

2.5.3 請求示例(li)

無

2.5.4 響應數據

group_info類型(xing)：

2.5.5 響應示(shi)例

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

3 訂(ding)單

3.1 獲取單個訂單

3.1.1 接口(kou)方法(fa)

method：getOrder

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

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

3.1.2 請求參數(shu)

3.1.3 請求示例(li)

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

3.1.4 響(xiang)應數據

Order

OrderItem

3.1.5 響應示例

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

3.2 獲取多(duo)個訂單

3.2.1 方法名稱

method：getOrderList

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

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

http請求(qiu)方式(shi)：GET
舊(jiu)請求地(di)址(zhi)：https://waybill.api.jz.fkw.com?access_token=xxx&amp;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&amp;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 請求參數(shu)

3.2.3 請求示例

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

3.2.4 響應數據

3.2.5 請(qing)求示例(li)

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

3.3 訂(ding)單支付

3.3.1 調用說明(ming)

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

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

3.3.2 請求參數

3.3.3 請求示(shi)例(li)

{

"order_id":"20200101001"

}

3.3.4 響應數據(ju)

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

3.4 訂(ding)單(dan)發貨

3.4.1 方法名(ming)稱

method：shipOrder

說明(ming)：logistics_code請參照以(yi)下的(de)快(kuai)遞100快(kuai)遞公司標(biao)準編(bian)碼的(de)【公司編(bian)碼】，不(bu)能(neng)自定義

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

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

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

3.5 訂單完成

3.5.1 方法(fa)名稱

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

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

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

3.5.3 請求示例

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

3.5.4 響應(ying)數據

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

3.6 訂單取消

3.6.1 調用說明

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

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

3.6.2 請求參數

3.6.3 請(qing)求示例(li)

{

"order_id":"20200101001"

}

3.6.4 響(xiang)應數據

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

4 上傳(chuan)

4.1 媒體上傳(chuan)

4.1.1 接口方法

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

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

4.1.2 請(qing)求參數

4.1.3 請求示例

無

4.1.4 響應數據

4.1.5 響(xiang)應示例

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

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

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

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

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

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

4.2.1 接口方法

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

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

4.2.2 請(qing)求參(can)數

4.2.3 請求示例

無

4.2.4 響應數據

4.2.5 響應示(shi)例

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

4.2.6 常見(jian)異常返(fan)回說(shuo)明(ming)

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

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

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

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

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

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

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

5 會員接口

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

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

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

5.1.1 請求參(can)數

5.1.2 請求示例

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

5.1.3 響應數據

5.1.4 響應示例

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


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

}

5.2 單個(ge)會員與(yu)積分獲取接口 （同(tong)步(bu)我來商城會員數據到第三(san)方(fang)系統）

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

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

5.2.1 請求參數

5.2.2 請求示例

{
   "id":1
}

5.2.3 響(xiang)應數據

5.2.4 響應示例

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

5.3 新增會員(yuan)接口 （第(di)三(san)方系(xi)統將會員數據寫入(ru)到我來(lai)商城(cheng)后臺）

接(jie)口(kou)調(diao)用(yong)請(qing)求(qiu)說(shuo)明：

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

5.3.1 請(qing)求參數(shu)

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

5.3.2 請(qing)求示例

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

5.3.3 響應數(shu)據(ju)

5.3.4 響應示例(li)

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

6 積分接口

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

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

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

6.1.1 請求參(can)數

6.1.2 請求(qiu)示例

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

6.1.3 響應數(shu)據

6.1.4 響應示例

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

7 常見問題

Q：新舊請求路徑如何選擇？

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

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

當前接(jie)口參(can)數為【請(qing)求參(can)數】傳參(can)，非【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)(shi)間為2個(ge)小時(shi)(shi)，那是(shi)不是(shi)每2個(ge)小時(shi)(shi)客戶(hu)就(jiu)得授權(quan)一次？

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