# 网络货运开放接口文档
------
<!-- 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)
- [相关说明(请仔细阅读!)：](#%E7%9B%B8%E5%85%B3%E8%AF%B4%E6%98%8E%E8%AF%B7%E4%BB%94%E7%BB%86%E9%98%85%E8%AF%BB)
- [接口凭证](#%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)
- [财务类接口](#%E8%B4%A2%E5%8A%A1%E7%B1%BB%E6%8E%A5%E5%8F%A3)
- [核销](#%E6%A0%B8%E9%94%80)
- [参数说明](#%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. 注册并开通网络货运账号（正式环境账号联系我司实施或者商务获取）；
2. 使用网络货运的账号密码获取接口访问令牌（accessToken）；
3. 使用`accessToken`调用其他接口；
**请使用主账号获取对应的token再调用其他接口!!!**
## 相关说明(请仔细阅读!)：
1. **什么是主账号**：<br>即贵公司在我们系统中创建的第一个账号，其后所有的贵公司系统中的账号都是子账号。如果不知道自己是否使用的主账号或者主账号具体是哪个请联系相关负责人。
2. **接口统一URL地址**：<br>测试环境=https://openapi.wlhy.hw.56fanyun.com ，正式环境=待定
3. **测试环境系统地址**：<br>https://wlhy.hw.56fanyun.com
4. **测试环境账号**：<br>联系我司对接负责人获取。账号并不互通，测试账号对应的是测试环境的域名，正式环境无法使用！
5. **调用接口方式**：<br>`URL` + `?access_token=生成的token`，参数传递使用JSON格式。
`Content-Type: application/json;charset=UTF-8`。例：
https://wlhy.hw.56fanyun.com/order/create_order?access_token=fe12047e-52b1-418c-848c-d08a885095a5
**请勿将请求参数拼接在URL中传递！**
6. **调试接口**：<br>推荐使用Postman，或者访问接口URL，会跳转至调试界面
7. **时间格式**：<br>如无特殊说明，接口中所有时间均使用时间戳，精确到秒
8. **调用限制**：<br>为防止恶意攻击和滥用，接口都加上了调用限制，不同接口限制不同，请参考接口中调用限制的相关说明。例：60次/分钟，表示一分钟内最多请求60次，超过限制会拒绝请求，返回`操作太频繁`。
9. **状态码**：
|状态码|说明|
|:---:|---|
|200|调用接口成功|
|401|授权失败，需要重新登陆获取access_token|
|404|接口不存在，请检查调用的接口地址，协议的格式是否正确|
|500|服务异常，具体错误原因会在返回结果中说明|
10. **返回字段**：
|名称|说明|
|:---:|---|
|code|状态码|
|data|返回数据，接口调用成功（状态码为 200）之后返回的数据|
|message|错误信息，当接口调用失败（状态码为 非200）时，返回的错误信息，调用成功时返回null|
# 接口凭证
## 获取登陆凭证接口
**简要描述：** 获取登陆凭证，accessToken有效期`72小时`，refreshToken有效期`100天`，有效期内获取token返回的结果一样，accessToken到期后建议使用refreshToken进行刷新，而不是使用用户名密码重新获取
**请求 URL：** `/user/generate_access_token`
**请求方式：** GET, POST
**需要AccessToken：** 否
**调用限制：** 60次/分钟
**请求参数：**
|名称|说明|类型|
|---|---|---|
|**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
{
"code": 500,
"message": "账号或密码不正确"
}
```
## 更新登陆凭证接口
**简要描述：** 更新登陆凭证，更新后原token将失效
**请求 URL：** `/user/refresh_access_token`
**请求方式：** GET, POST
**需要AccessToken：** 否
**调用限制：** 60次/分钟
**请求参数：**
|名称|说明|类型|
|---|---|---|
|**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
{
"code": 500,
"message": "账号或刷新凭证不正确"
}
```
# 运单类接口
## 创建运单接口
**简要描述：** 开单
**请求 URL：** `/order/create_order`
**请求方式：** POST
**需要AccessToken：** 是
**调用限制：** 10000次/小时
**请求参数：**
|名称|说明|类型|
|---|---|---|
|**orders** <br>*必填*|运单列表 <br>**长度** : `1 - 50`|< [运单](#运单) > array|
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"data": ["1712051703640558"],
"message": null
}
```
- 调用失败示例
```java
{
"code": 500,
"message": "订单创建失败"
}
```
# 财务类接口
## 核销
**简要描述：** 核销
**请求 URL：** `/writeoff/writeoff`
**请求方式：** POST
**需要AccessToken：** 是
**调用限制：** 120次/分钟
**请求参数：**
|名称|说明|类型|
|---|---|---|
|**carNumber** <br>*必填*|车牌号码 <br>**长度** : `1 - 35`|string|
|**customerOrderNumbers** <br>*必填*|结算受理单列表|< string > array|
|**driverName** <br>*必填*|司机名称 <br>**长度** : `1 - 30`|string|
|**driverPhone** <br>*必填*|司机电话 <br>**长度** : `1 - 18`|string|
|**payFreight** <br>*必填*|支付金额 <br>**最小值** : `0` <br>**最大值** : `999999`|number (double)|
|**payType** <br>*必填*|支付方式，1：油卡，2：现金，3：支付宝，4：微信，5：银行转账，6：其它|integer (int32)|
|**tradeNo** <br>*必填*|资金流水号 <br>**长度** : `1 - 50`|string|
|**note** <br>*可选*|付款备注 <br>**长度** : `0 - 256`|string|
- 调用成功示例
```java
{
"code": 200,
"data": true,
"message": null
}
```
- 调用失败示例
```java
{
"code": 500,
"message": "xxxxxxxx"
}
```
# 参数说明
## 运单
|名称|说明|类型|
|---|---|---|
|**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|