celestia-api-doc

网络货运开放接口文档

---

• 网络货运开放接口文档
  • 接口简介(请仔细阅读!)
  • 接口说明
• 接口凭证
  • 获取登陆凭证接口
  • 更新登陆凭证接口
• 运单类接口
  • 创建运单接口
• 财务类接口
  • 核销
• 参数说明
  • 运单
  • 货物
  • 承运人
  • 地址

接口简介(请仔细阅读!)

本文档为网络货运开放接口文档，对接流程为：

1. 注册并开通网络货运账号（正式环境账号联系我司实施或者商务获取）；
2. 获取接口访问令牌；
3. 调用其他接口；

请使用主账号获取对应的token再调用其他接口!!!

相关说明：

1. 什么是主账号： 即贵公司在我们系统中创建的第一个账号，其后所有的贵公司系统中的账号都是子账号。如果不知道自己是否使用的主账号或者主账号具体是哪个请联系相关负责人。

接口统一URL地址： 测试环境=https://openapi.wlhy.hw.56fanyun.com ，正式环境=待定

测试环境系统地址： https://wlhy.hw.56fanyun.com

测试环境账号： 联系我司对接负责人获取。账号并不互通，测试账号对应的是测试环境的域名，正式环境无法使用！

调用接口方式： 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中传递！

调试接口： 推荐使用Postman，或者访问接口URL，会跳转至调试界面

时间格式： 如无特殊说明，接口中所有时间均使用时间戳，精确到秒

调用限制： 为防止恶意攻击和滥用，接口都加上了调用限制，不同接口限制不同，请参考接口中调用限制的相关说明。例：60次/分钟，表示一分钟内最多请求60次，超过限制会拒绝请求，返回操作太频繁。

接口说明

所有接口支持RESTful的方式访问，返回结果首先判断http状态码，有如下几种情况：

1. 404表示接口不存在，请检查调用的接口地址，协议的格式是否正确
2. 401表示授权失败，需要重新登陆获取access_token
3. 200，201，20*表示调用接口成功，返回body中调用结果，是http JSON格式的，包含以下字段

• code：状态码，取值有 200，非200；200 表示接口调用成功， 非200 表示接口调用失败
• message：错误信息，当接口调用失败（状态码为 非200）时，返回的错误信息
• data：返回数据，接口调用成功（状态码为 200）之后返回的数据

接口凭证

获取登陆凭证接口

简要描述： 获取登陆凭证，accessToken有效期72小时，refreshToken有效期100天，有效期内获取token返回的结果一样，accessToken到期后建议使用refreshToken进行刷新，而不是使用用户名密码重新获取

请求 URL： /user/generate_access_token

请求方式： GET, POST

需要AccessToken： 否

调用限制： 60次/分钟

请求参数：

名称	说明	类型
userName 必填	账号	string
password 必填	密码	string

返回示例

• 调用成功示例

{
    "code": 200,
    "message": null,
    "data": {
        "accessToken": "9d0dfe02-2349-421c-90ec-4b9ea174701b",
        "refreshToken": "9f8326bc-c29f-4a28-a512-26caa1a9850a"
    }
}

• 调用失败示例

{
    "code": 500,
    "message": "账号或密码不正确"
}

更新登陆凭证接口

简要描述： 更新登陆凭证，更新后原token将失效

请求 URL： /user/refresh_access_token

请求方式： GET, POST

需要AccessToken： 否

调用限制： 60次/分钟

请求参数：

名称	说明	类型
userName 必填	账号	string
refreshToken 必填	刷新凭证	string

返回示例

• 调用成功示例

{
    "code": 200,
    "message": null,
    "data": {
        "accessToken": "9d0dfe02-2349-421c-90ec-4b9ea174701b",
        "refreshToken": "9f8326bc-c29f-4a28-a512-26caa1a9850a"
    }
}

• 调用失败示例

{
    "code": 500,
    "message": "账号或刷新凭证不正确"
}

运单类接口

创建运单接口

简要描述： 开单

请求 URL： /order/create_order

请求方式： POST

需要AccessToken： 是

调用限制： 10000次/小时

请求参数：

名称	说明	类型
orders 必填	运单列表 长度 : 1 - 50	< 运单 > array

返回示例

• 调用成功示例

{
    "code": 200,
    "data": ["1712051703640558"],
    "message": null
}

• 调用失败示例

{
    "code": 500,
    "message": "订单创建失败"
}

财务类接口

核销

简要描述： 核销

请求 URL： /writeoff/writeoff

请求方式： POST

需要AccessToken： 是

调用限制： 120次/分钟

请求参数：

名称	说明	类型
carNumber 必填	车牌号码 长度 : 1 - 35	string
customerOrderNumbers 必填	结算受理单列表	< string > array
driverName 必填	司机名称 长度 : 1 - 30	string
driverPhone 必填	司机电话 长度 : 1 - 18	string
payFreight 必填	支付金额 最小值 : 0 最大值 : 999999	number (double)
payType 必填	支付方式，1：油卡，2：现金，3：支付宝，4：微信，5：银行转账，6：其它	integer (int32)
tradeNo 必填	资金流水号 长度 : 1 - 50	string
note 可选	付款备注 长度 : 0 - 256	string

• 调用成功示例

{
    "code": 200,
    "data": true,
    "message": null
}

• 调用失败示例

{
    "code": 500,
    "message": "xxxxxxxx"
}

参数说明

运单

名称	说明	类型
originalOrderNumber 必填	原始单号 长度 : 1 - 50	string
businessType 必填	业务类型	enum (干线普货运输, 城市配送, 农村配送, 集装箱运输, 其他)
carrier 必填	承运人	承运人
consignerName 必填	发货人姓名 长度 : 1 - 45	string
consignerPhone 必填	发货人电话 长度 : 1 - 20	string
consignerIdCard 必填	发货人证件号 长度 : 1 - 35	string
consignerAddress 必填	发货人地址	地址
consigneeName 必填	收货人姓名 长度 : 1 - 45	string
consigneePhone 必填	收货人电话 长度 : 1 - 20	string
consigneeIdCard 可选	收货人证件号 长度 : 0 - 35	string
consigneeAddress 必填	收货人地址	地址
appointArriveTime 可选	预约送达时间。时间戳	integer (int32)
cargoList 可选	货物列表	< 货物 > array
deliveryTime 可选	提货时间。时间戳	integer (int32)
deliveryType 可选	提送类型。1：自提；2：送货	integer (int32)
deviceNumber 可选	绑定设备号	string
endAddress 可选	目的地 长度 : 0 - 20	string
note1 可选	自定义备注1	string
note2 可选	自定义备注2	string
note3 可选	自定义备注3	string
note4 可选	自定义备注4	string
note5 可选	自定义备注5	string
note6 可选	自定义备注6	string
note7 可选	自定义备注7	string
note8 可选	自定义备注8	string
note9 可选	自定义备注9	string
note10 可选	自定义备注10	string
note11 可选	自定义备注11	string
note12 可选	自定义备注12	string
organizationPath 可选	组织机构	string
paymentCollect 可选	代收货款 最小值 : 0 最大值 : 999999	number (double)
receiptCount 可选	回单数 最小值 : 0 最大值 : 999	integer (int32)
remarks 可选	备注 长度 : 1 - 250	string
salesman 可选	业务员 长度 : 0 - 20	string
salesmanPhone 可选	业务员电话 长度 : 0 - 12	string
settlementName 可选	结算方名称 长度 : 0 - 50	string
settlementPhone 可选	结算方电话 长度 : 0 - 20	string
shipperPay 可选	上游运费 最小值 : 0 最大值 : 9999999	number (double)
shipperPayType 可选	上游运费支付方式. 1：现付；2：到付；3：回付；4：周结；5：月结；6：货款扣；7：季度结；8：在线支付；9：到付月结	integer (int32)
startAddress 可选	起始地 长度 : 0 - 20	string

货物

名称	说明	类型
name 必填	货物名称 长度 : 1 - 150	string
productModel 可选	货物备注 长度 : 0 - 100	string
quantity 可选	件数 最小值 : 0 最大值 : 999999	number (double)
status 可选	货物状态	string
type 必填	货物类型	可选值请参考《部网络货运信息交互系统代码集》
value 可选	货值 最小值 : 0 最大值 : 9999999	number (double)
volume 可选	体积 最小值 : 0 最大值 : 9999	number (double)
weight 必填	重量(千克) 最小值 : 0 最大值 : 99999999	number (double)
note1 可选	自定义备注1	string
note2 可选	自定义备注2	string
note3 可选	自定义备注3	string
note4 可选	自定义备注4	string
note5 可选	自定义备注5	string
note6 可选	自定义备注6	string

承运人

名称	说明	类型
carNumber 必填	车牌号码 长度 : 1 - 20	string
driverFreight 必填	司机运费 最小值 : 0 最大值 : 999999	number (double)
driverName 必填	司机名称 长度 : 1 - 20	string
driverPhone 必填	司机电话 长度 : 1 - 20	string
insuranceCompany 可选	保险公司 长度 : 0 - 30	string
insuranceNumber 可选	保险单号 长度 : 0 - 30	string

地址

名称	说明	类型
address 必填	地址 长度 : 1 - 100	string
city 必填	市。xx市，行政区划全称	string
district 必填	区/县。xx区/县，行政区划全称。直辖市省市区样例：北京市-北京市-朝阳区；省直辖市。样例：湖北省-仙桃市-仙桃市	string
lat 可选	纬度	number (double)
lng 可选	经度	number (double)
province 必填	省。xx省，行政区划全称	string