|
|
@@ -1,37 +1,267 @@
|
|
|
# 网络货运开放接口文档
|
|
|
|
|
|
-#### 介绍
|
|
|
-网络货运开放接口文档
|
|
|
+------
|
|
|
|
|
|
-#### 软件架构
|
|
|
-软件架构说明
|
|
|
+<!-- TOC -->
|
|
|
|
|
|
+- [网络货运开放接口文档](#%E7%BD%91%E7%BB%9C%E8%B4%A7%E8%BF%90%E5%BC%80%E6%94%BE%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3)
|
|
|
+ - [接口简介(请仔细阅读!)](#%E6%8E%A5%E5%8F%A3%E7%AE%80%E4%BB%8B%E8%AF%B7%E4%BB%94%E7%BB%86%E9%98%85%E8%AF%BB)
|
|
|
+ - [接口说明](#%E6%8E%A5%E5%8F%A3%E8%AF%B4%E6%98%8E)
|
|
|
+- [接口凭证](#%E6%8E%A5%E5%8F%A3%E5%87%AD%E8%AF%81)
|
|
|
+ - [获取登陆凭证接口](#%E8%8E%B7%E5%8F%96%E7%99%BB%E9%99%86%E5%87%AD%E8%AF%81%E6%8E%A5%E5%8F%A3)
|
|
|
+ - [更新登陆凭证接口](#%E6%9B%B4%E6%96%B0%E7%99%BB%E9%99%86%E5%87%AD%E8%AF%81%E6%8E%A5%E5%8F%A3)
|
|
|
+- [运单类接口](#%E8%BF%90%E5%8D%95%E7%B1%BB%E6%8E%A5%E5%8F%A3)
|
|
|
+ - [创建运单接口](#%E5%88%9B%E5%BB%BA%E8%BF%90%E5%8D%95%E6%8E%A5%E5%8F%A3)
|
|
|
+- [参数说明](#%E5%8F%82%E6%95%B0%E8%AF%B4%E6%98%8E)
|
|
|
+ - [运单](#%E8%BF%90%E5%8D%95)
|
|
|
+ - [货物](#%E8%B4%A7%E7%89%A9)
|
|
|
+ - [承运人](#%E6%89%BF%E8%BF%90%E4%BA%BA)
|
|
|
+ - [地址](#%E5%9C%B0%E5%9D%80)
|
|
|
|
|
|
-#### 安装教程
|
|
|
+<!-- /TOC -->
|
|
|
|
|
|
-1. xxxx
|
|
|
-2. xxxx
|
|
|
-3. xxxx
|
|
|
+## 接口简介(请仔细阅读!)
|
|
|
|
|
|
-#### 使用说明
|
|
|
+本文档为网络货运开放接口文档，对接流程为：
|
|
|
+1. 注册并开通网络货运账号（正式环境账号联系实施或者商务，应该已经开通过了）；
|
|
|
+2. 获取接口访问令牌；
|
|
|
+3. 调用其他接口；
|
|
|
|
|
|
-1. xxxx
|
|
|
-2. xxxx
|
|
|
-3. xxxx
|
|
|
+**请使用主账号获取对应的token再调用其他接口!!!**
|
|
|
|
|
|
-#### 参与贡献
|
|
|
+- **什么是主账号**：即贵公司在我们系统中创建的第一个账号，其后所有的贵公司系统中的账号都是子账号。如果不知道自己是否使用的主账号或者主账号具体是哪个请联系相关负责人。
|
|
|
+- **接口统一URL地址**：测试环境=https://openapi.wlhy.hw.56fanyun.com ，正式环境=待定
|
|
|
+- **测试环境系统地址**：https://wlhy.hw.56fanyun.com
|
|
|
+- **测试环境账号**：联系对接负责人获取。账号并不互通，测试账号对应的是测试环境的域名，正式环境无法使用！
|
|
|
+- **调用接口方式**：`URL` + `?access_token=生成的token`，参数传递使用JSON格式，例：
|
|
|
+https://wlhy.hw.56fanyun.com/order/create_order?access_token=fe12047e-52b1-418c-848c-d08a885095a5
|
|
|
+**请勿将请求参数拼接在URL中传递！**
|
|
|
+- **调试接口**： 推荐使用Postman，或者访问接口URL，会跳转至调试界面
|
|
|
|
|
|
-1. Fork 本仓库
|
|
|
-2. 新建 Feat_xxx 分支
|
|
|
-3. 提交代码
|
|
|
-4. 新建 Pull Request
|
|
|
|
|
|
+## 接口说明
|
|
|
|
|
|
-#### 码云特技
|
|
|
+所有接口支持RESTful的方式访问，返回结果首先判断http状态码，有如下几种情况：
|
|
|
|
|
|
-1. 使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
|
|
|
-2. 码云官方博客 [blog.gitee.com](https://blog.gitee.com)
|
|
|
-3. 你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解码云上的优秀开源项目
|
|
|
-4. [GVP](https://gitee.com/gvp) 全称是码云最有价值开源项目，是码云综合评定出的优秀开源项目
|
|
|
-5. 码云官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
|
|
|
-6. 码云封面人物是一档用来展示码云会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
|
|
|
+1. 404表示接口不存在，请检查调用的接口地址，协议的格式是否正确
|
|
|
+2. 401表示授权失败，需要重新登陆获取access_token
|
|
|
+3. 200，201，20*表示调用接口成功，返回body中调用结果，是http JSON格式的，包含以下字段
|
|
|
+
|
|
|
+- **code**：状态码，取值有 200，非200；200 表示接口调用成功， 非200 表示接口调用失败
|
|
|
+- **message**：错误信息，当接口调用失败（状态码为 非200）时，返回的错误信息
|
|
|
+- **data**：返回数据，接口调用成功（状态码为 200）之后返回的数据
|
|
|
+
|
|
|
+**如无特殊说明，接口中所有时间均使用时间戳，精确到秒**
|
|
|
+
|
|
|
+
|
|
|
+# 接口凭证
|
|
|
+
|
|
|
+## 获取登陆凭证接口
|
|
|
+
|
|
|
+**简要描述：** 获取登陆凭证
|
|
|
+
|
|
|
+**请求 URL：** `/user/generate_access_token`
|
|
|
+
|
|
|
+**请求方式：** GET, POST
|
|
|
+
|
|
|
+**需要Token：** 否
|
|
|
+
|
|
|
+**请求参数：**
|
|
|
+
|
|
|
+|名称|说明|类型|
|
|
|
+|---|---|---|
|
|
|
+|**userName** <br>*必填*|账号|string|
|
|
|
+|**password** <br>*必填*|密码|string|
|
|
|
+
|
|
|
+**返回示例**
|
|
|
+
|
|
|
+- 调用成功示例
|
|
|
+
|
|
|
+```java
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "message": null,
|
|
|
+ "data": {
|
|
|
+ "accessToken": "9d0dfe02-2349-421c-90ec-4b9ea174701b",
|
|
|
+ "refreshToken": "9f8326bc-c29f-4a28-a512-26caa1a9850a"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+- 调用失败示例
|
|
|
+
|
|
|
+```java
|
|
|
+{
|
|
|
+ "status": 500,
|
|
|
+ "message": "账号或密码不正确"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+
|
|
|
+## 更新登陆凭证接口
|
|
|
+
|
|
|
+**简要描述：** 更新登陆凭证
|
|
|
+
|
|
|
+**请求 URL：** `/user/refresh_access_token`
|
|
|
+
|
|
|
+**请求方式：** GET, POST
|
|
|
+
|
|
|
+**需要Token：** 否
|
|
|
+
|
|
|
+**请求参数：**
|
|
|
+
|
|
|
+|名称|说明|类型|
|
|
|
+|---|---|---|
|
|
|
+|**userName** <br>*必填*|账号|string|
|
|
|
+|**refreshToken** <br>*必填*|刷新凭证|string|
|
|
|
+
|
|
|
+**返回示例**
|
|
|
+
|
|
|
+- 调用成功示例
|
|
|
+
|
|
|
+```java
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "message": null,
|
|
|
+ "data": {
|
|
|
+ "accessToken": "9d0dfe02-2349-421c-90ec-4b9ea174701b",
|
|
|
+ "refreshToken": "9f8326bc-c29f-4a28-a512-26caa1a9850a"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+- 调用失败示例
|
|
|
+
|
|
|
+```java
|
|
|
+{
|
|
|
+ "status": 500,
|
|
|
+ "message": "账号或刷新凭证不正确"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+# 运单类接口
|
|
|
+
|
|
|
+## 创建运单接口
|
|
|
+
|
|
|
+**简要描述：** 开单
|
|
|
+
|
|
|
+**请求 URL：** `/order/create_order`
|
|
|
+
|
|
|
+**请求方式：** POST
|
|
|
+
|
|
|
+**需要Token：** 是
|
|
|
+
|
|
|
+**调用限制：**
|
|
|
+
|
|
|
+**请求参数：**
|
|
|
+
|
|
|
+|名称|说明|类型|
|
|
|
+|---|---|---|
|
|
|
+|**orders** <br>*必填*|受理单列表|< [运单](#运单) > array|
|
|
|
+
|
|
|
+**返回示例**
|
|
|
+
|
|
|
+- 调用成功示例
|
|
|
+
|
|
|
+调用成功但是系统中查看不到时请先阅读<a href="PROBLEMS.md#通过创建接口创建的订单或受理单登陆系统以后没有查看到">常见问题</a>
|
|
|
+```java
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "data": ["1712051703640558"],
|
|
|
+ "message": null
|
|
|
+}
|
|
|
+```
|
|
|
+- 调用失败示例
|
|
|
+
|
|
|
+```java
|
|
|
+{
|
|
|
+ "status": 500,
|
|
|
+ "message": "订单创建失败"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+# 参数说明
|
|
|
+
|
|
|
+## 运单
|
|
|
+|名称|说明|类型|
|
|
|
+|---|---|---|
|
|
|
+|**originalOrderNumber** <br>*必填*|原始单号 <br>**长度** : `1 - 50`|string|
|
|
|
+|**businessType** <br>*必填*|业务类型|enum (干线普货运输, 城市配送, 农村配送, 集装箱运输, 其他)|
|
|
|
+|**carrier** <br>*必填*|承运人|[承运人](#承运人)|
|
|
|
+|**consignerName** <br>*必填*|发货人姓名 <br>**长度** : `1 - 45`|string|
|
|
|
+|**consignerPhone** <br>*必填*|发货人电话 <br>**长度** : `1 - 20`|string|
|
|
|
+|**consignerIdCard** <br>*必填*|发货人证件号 <br>**长度** : `1 - 35`|string|
|
|
|
+|**consignerAddress** <br>*必填*|发货人地址|[地址](#地址)|
|
|
|
+|**consigneeName** <br>*必填*|收货人姓名 <br>**长度** : `1 - 45`|string|
|
|
|
+|**consigneePhone** <br>*必填*|收货人电话 <br>**长度** : `1 - 20`|string|
|
|
|
+|**consigneeIdCard** <br>*可选*|收货人证件号 <br>**长度** : `0 - 35`|string|
|
|
|
+|**consigneeAddress** <br>*必填*|收货人地址|[地址](#地址)|
|
|
|
+|**appointArriveTime** <br>*可选*|预约送达时间。时间戳|integer (int32)|
|
|
|
+|**cargoList** <br>*可选*|货物列表|< [货物](#货物) > array|
|
|
|
+|**deliveryTime** <br>*可选*|提货时间。时间戳|integer (int32)|
|
|
|
+|**deliveryType** <br>*可选*|提送类型。1：自提；2：送货|integer (int32)|
|
|
|
+|**deviceNumber** <br>*可选*|绑定设备号|string|
|
|
|
+|**endAddress** <br>*可选*|目的地 <br>**长度** : `0 - 20`|string|
|
|
|
+|**note1** <br>*可选*|自定义备注1|string|
|
|
|
+|**note2** <br>*可选*|自定义备注2|string|
|
|
|
+|**note3** <br>*可选*|自定义备注3|string|
|
|
|
+|**note4** <br>*可选*|自定义备注4|string|
|
|
|
+|**note5** <br>*可选*|自定义备注5|string|
|
|
|
+|**note6** <br>*可选*|自定义备注6|string|
|
|
|
+|**note7** <br>*可选*|自定义备注7|string|
|
|
|
+|**note8** <br>*可选*|自定义备注8|string|
|
|
|
+|**note9** <br>*可选*|自定义备注9|string|
|
|
|
+|**note10** <br>*可选*|自定义备注10|string|
|
|
|
+|**note11** <br>*可选*|自定义备注11|string|
|
|
|
+|**note12** <br>*可选*|自定义备注12|string|
|
|
|
+|**organizationPath** <br>*可选*|组织机构|string|
|
|
|
+|**paymentCollect** <br>*可选*|代收货款 <br>**最小值** : `0` <br>**最大值** : `999999`|number (double)|
|
|
|
+|**receiptCount** <br>*可选*|回单数 <br>**最小值** : `0` <br>**最大值** : `999`|integer (int32)|
|
|
|
+|**remarks** <br>*可选*|备注 <br>**长度** : `1 - 250`|string|
|
|
|
+|**salesman** <br>*可选*|业务员 <br>**长度** : `0 - 20`|string|
|
|
|
+|**salesmanPhone** <br>*可选*|业务员电话 <br>**长度** : `0 - 12`|string|
|
|
|
+|**settlementName** <br>*可选*|结算方名称 <br>**长度** : `0 - 50`|string|
|
|
|
+|**settlementPhone** <br>*可选*|结算方电话 <br>**长度** : `0 - 20`|string|
|
|
|
+|**shipperPay** <br>*可选*|上游运费 <br>**最小值** : `0` <br>**最大值** : `9999999`|number (double)|
|
|
|
+|**shipperPayType** <br>*可选*|上游运费支付方式. 1：现付；2：到付；3：回付；4：周结；5：月结；6：货款扣；7：季度结；8：在线支付；9：到付月结|integer (int32)|
|
|
|
+|**startAddress** <br>*可选*|起始地 <br>**长度** : `0 - 20`|string|
|
|
|
+
|
|
|
+
|
|
|
+## 货物
|
|
|
+
|
|
|
+|名称|说明|类型|
|
|
|
+|---|---|---|
|
|
|
+|**name** <br>*必填*|货物名称 <br>**长度** : `1 - 150`|string|
|
|
|
+|**productModel** <br>*可选*|货物备注 <br>**长度** : `0 - 100`|string|
|
|
|
+|**quantity** <br>*可选*|件数 <br>**最小值** : `0` <br>**最大值** : `999999`|number (double)|
|
|
|
+|**status** <br>*可选*|货物状态|string|
|
|
|
+|**type** <br>*必填*|货物类型|可选值请参考《部网络货运信息交互系统代码集》|
|
|
|
+|**value** <br>*可选*|货值 <br>**最小值** : `0` <br>**最大值** : `9999999`|number (double)|
|
|
|
+|**volume** <br>*可选*|体积 <br>**最小值** : `0` <br>**最大值** : `9999`|number (double)|
|
|
|
+|**weight** <br>*必填*|重量(千克) <br>**最小值** : `0` <br>**最大值** : `99999999`|number (double)|
|
|
|
+|**note1** <br>*可选*|自定义备注1|string|
|
|
|
+|**note2** <br>*可选*|自定义备注2|string|
|
|
|
+|**note3** <br>*可选*|自定义备注3|string|
|
|
|
+|**note4** <br>*可选*|自定义备注4|string|
|
|
|
+|**note5** <br>*可选*|自定义备注5|string|
|
|
|
+|**note6** <br>*可选*|自定义备注6|string|
|
|
|
+
|
|
|
+## 承运人
|
|
|
+
|
|
|
+|名称|说明|类型|
|
|
|
+|---|---|---|
|
|
|
+|**carNumber** <br>*必填*|车牌号码 <br>**长度** : `1 - 20`|string|
|
|
|
+|**driverFreight** <br>*必填*|司机运费 <br>**最小值** : `0` <br>**最大值** : `999999`|number (double)|
|
|
|
+|**driverName** <br>*必填*|司机名称 <br>**长度** : `1 - 20`|string|
|
|
|
+|**driverPhone** <br>*必填*|司机电话 <br>**长度** : `1 - 20`|string|
|
|
|
+|**insuranceCompany** <br>*可选*|保险公司 <br>**长度** : `0 - 30`|string|
|
|
|
+|**insuranceNumber** <br>*可选*|保险单号 <br>**长度** : `0 - 30`|string|
|
|
|
+
|
|
|
+## 地址
|
|
|
+
|
|
|
+|名称|说明|类型|
|
|
|
+|---|---|---|
|
|
|
+|**address** <br>*必填*|地址 <br>**长度** : `1 - 100`|string|
|
|
|
+|**city** <br>*必填*|市。xx市，行政区划全称|string|
|
|
|
+|**district** <br>*必填*|区/县。xx区/县，行政区划全称。直辖市省市区样例：北京市-北京市-朝阳区；省直辖市。样例：湖北省-仙桃市-仙桃市|string|
|
|
|
+|**lat** <br>*可选*|纬度|number (double)|
|
|
|
+|**lng** <br>*可选*|经度|number (double)|
|
|
|
+|**province** <br>*必填*|省。xx省，行政区划全称|string|
|
gmw