1.1 术语 1.2 接口规范 1.3 异常代码定义 1.4 接口访问地址 2.1 获取接口访问凭证 2.2 运输合同查询 2.3 司机注册接口 2.4 车辆注册接口 2.5 运单创建接口 2.6 回单接口 2.7 运单状态更新接口 2.8 运单轨迹接收接口 1、车辆类型定义 2、车长定义 3、车牌颜色代码定义 4、计量单位 5、装卸方式 6、运费计价方式

1、技术标准

对外开放接口平台提供对外接口访问协议为https,数据交互格式为JSON数据格式。

1.1 术语

缩写、术语 解 释
https https协议进行数据交换或数据集成。
JSON JSON(JavaScript Object Notation) 是一种轻量级的数据交换格式。采用完全独立于语言的文本格式,易于人阅读和编写,同时也易于机器解析和生成,因其独特特性,使其成为理想的数据交换语言。

1.2 接口规范

(1)所有外部系统采用https方式访问对外开放接口;
(2)所有开放接口https请求以POST方式提交数据;
(3)所有开放接口请求头部设置以下参数:
参数 含义 说明及举例
content-type 内容类型及编码 application/json;charset=UTF-8
partner_id 合作伙伴ID 由开放接口平台提供给合作伙伴的编码
access_token 接口访问凭证 由开放接口平台提供给合作伙伴的接口访问凭证。【获取访问凭证】接口不需要设置此参数。
(4)所有开放接口请求数据为JSON对象,JSON对象数据结构如下表所示:
字段 名称 类型及长度 必填 说明
api_code API接口代码 varchar(50) 合作伙伴系统请求的接口代码 用来校验接口请求是否发错
app_id 应用ID varchar(50) 合作伙伴系统发出请求的应用ID、应用名称、业务流水号、操作员、操作时间等,开放平台只记录此信息,用于运维时的数据核对。操作时间格式为:yyyyMMddHHmmssSSS
seq_no 流水号 varchar(50)
op_user 操作者 varchar(50)
op_time 操作时间 varchar(17)
callback_url 回调地址 varchar(255) 异步接口的回调地址
rows_count 数据量 number 请求所包含业务数据的记录数,此字段为字符串形式的整数,用来校验datas中包含的数据量
datas 业务数据 Array 复合类型的业务数据数组 若只有1条请求数据,也应处理为数组

请求数据示例:

{

"api_code": "getTaskDetail",

"app_id": "SF-App",

"app_name": "顺丰速运APP",

"seq_no": "SF2020122976459243",

"op_user": "032176",

"op_time": "20201231122531023",

""rows_count": 2,

"datas": [

{"task_code": "T202012300001"},

{"task_code": "T202012300017"}

]

}

(5)开放接口所有请求响应代码为200(Http Response Code),只代表开放接口平台成功处理了此请求,但不代表业务处理是否成功,业务处理是否成功需要通过返回的JSON数据进行判断,数据结构如下表所属:
字段 名称 类型及长度 必填 说明
api_code API接口代码 varchar(50) 反馈数据的接口代码 用来校验接口响应是否发错
app_id 应用ID varchar(50) 这部分数据由客户系统发送的请求得来,便于客户处理而业务数据
app_name 应用名称 varchar(50)
seq_no 流水号 varchar(50)
op_user 操作者 varchar(17)
op_time 操作时间 varchar(255)
result_code 处理结果 varchar(20) 本次请求的处理结:0代表成功,其他则代表具体的错误代码。
result_msg 处理消息 varchar(255) 返回的错误信息
serial_no 请求流水号 varchar(50) 开放接口平台返回的请求流水号
rows_count 数据量 number 响应所包含业务数据的记录数。此字段为字符串形式的整数,用表示datas中包含的数据量
datas 业务数据 Array 复合类型的业务数据数组,若只有1条响应数据,也应处理为数组。异步接口业务数据将通过回调方式返回。

响应报文示例:

{

"api_code": "getTaskDetail",

"app_id": "SF-App",

"app_name": "顺丰速运APP",

"seq_no": "SF2020122976459243",

"op_user": "032176",

"op_time": "20201231122531023",

"result_code": "0",

""rows_count": 1,

"datas": [

{

"id": 12345,

"task_code": "T202012300001",

"task_name": "测试运单",

. . .

}

]

}

(6)异步回调接口采用POST方式,请求数据格式同第(5)条规范所示。
(7)数据类型规范如下表所示
参数名称 约定说明
日期类型 格式为:yyyyMMdd
时间类型 格式为:yyyyMMddHHmmss
空值 为优化传输,当信息项没有值时,除特殊要求外,不传输空数据项
base64

格式为:data:数据类型/文件类型;base64,base64字符串

(1)图片

data:image/gif;base64,base64编码的gif图片数据

data:image/png;base64,base64编码的png图片数据

data:image/jpeg;base64,base64编码的jpeg图片数据

data:image/jpg;base64,base64编码的jpg图片数据

(2)文本

data:text/plain,bas64, base64编码的文本数据

(3)文档

data:application/pdf;base64,base64编码的pdf文件数据

data:application/doc;base64,base64编码的doc文件数据

data:application/docx;base64,base64编码的docx文件数据

data:application/xls;base64,base64编码的xls文件数据

data:application/xlsx;base64,base64编码的xlsx文件数据

data:application/ppt;base64,base64编码的ppt文件数据

data:application/pptx;base64,base64编码的pptx文件数据

(3)其他

data:application/xxx;base64,base64编码的xxx文件数据

1.3 异常代码定义

代码 描述
0 处理成功
400 无效的token或者token已过有效期
401 没有权限访问此接口
402 合作伙伴id或密钥错误
403 超过接口访问频次限制
405 请求方法被禁止,请使用post方式
1000 api_code与接口地址不一致
1001 callback_url为空
1002 rows_count与datas大小不一致
1003 数据校验失败
1004 http请求头[partner_id]为空

1.4 接口访问地址

测试环境:http://hhycs.cargocn.com/test-api/(待定)
正式环境:https://hhy-openapi.cargocn.com/open-api/(待定)

2、接口列表

2.1获取接口访问凭证

接口名称:获取接口访问凭证
接口代码:get_access_token
接口描述:通过开放接口平台提供给外部系统的合作方ID和密钥,获取访问接口的凭证。外部系统访问开放平台的业务接口时,需要设置访问凭证。每次获取凭证在一段时间内有效,超过有效期后,需重新获取凭证。
接口版本:V1.0
调用模式:同步
请求参数:
序号 参数编码 参数名称 数据类型 长度 是否必填 备注
1 partner_id 合作伙伴ID string 50 开放接口平台提供给外部系统的合作方ID
2 secret 密钥 string 100 开放平台提供给外部系统的密钥
反馈结果:
序号 字段编码 字段名称 数据类型 长度 是否必填 备注
1 access_token 访问凭证 string 255
2 expires_in 凭证有效时间 number 单位:秒,目前是7200秒。

2.2运输合同查询

接口名称:运输合同查询
接口代码:contract_query
接口描述:通过运输合同查询接口,开放好货云平台中托运人角色下,与承运人签订的状态为:执行中的承运合同信息,一个税号查询返回多个合同。
接口版本:V1.0
接口调用地址:[接口访问地址]/hhy/contract_query
调用模式:同步
请求参数:
序号 参数编码 参数名称 数据类型 长度 是否必填 备注
1 senderTaxNos 托运方税号 string[] 公司税号,可以为多个税号
反馈结果:
序号 字段编码 字段名称 数据类型 长度 是否必填 备注
1 contractNo 合同号 string 32
2 carrName 承运方 string 64 承运企业
3 carrTaxNo 税号 string 32 承运方税号
4 carrOrgName 部门 string 64 承运企业签署合同的部门
5 senderName 托运方 string 64 货主企业
6 senderOrgName 部门 string 64 货主企业签署合同的部门
7 senderTaxNo 税号 string 32 托运方税号
8 beginDate 合同起始日期 date 8 合同有效期起始日期: yyyyMMdd
9 endDate 合同截止日期 date 8 合同有效期截止日期: yyyyMMdd
10 signDate 签署日期 date 8 合同签署日期:yyyyMMdd
11 status 合同状态 number 2-执行中
12 contractFileUrl 合同附件 string 255 合同附件

2.3司机注册接口

接口名称:司机注册接口
接口代码:driver_register
接口描述:通过司机注册接口,采集司机注册信息,在好货云平台中完成司机注册,并返回注册结果值。
接口版本:V1.0
接口调用地址:[接口访问地址]/hhy/driver_register
调用模式:同步
请求参数:
序号 参数编码 参数名称 数据类型 长度 是否必填 备注
1 senderTaxNos 托运方税号 string[] 公司税号,可以为多个税号
2 driverName 司机姓名 string 64 司机姓名
3 driverMobile 司机电话 string 32 司机电话
4 idNo 身份证号 string 32 身份证号
5 licenseId 驾驶证号 string 32 驾驶证号
6 qualificationsNo 驾驶员从业资格证号 string 32 驾驶员从业资格证号
7 idFontImg 身份证人像面 base64 1MB 身份证人像面照片
8 idBackImg 身份证国徽面 base64 1MB 身份证国徽面照片
9 licenseMainImg 驾驶证正页 base64 1MB 驾驶证正页照片
10 licenseSubImg 驾驶证副页 base64 1MB 驾驶证负页照片
11 qualificationsImg 驾驶员从业资格证 base64 1MB 驾驶员从业资格照片
12 permitType 准驾车型 string 32 司机驾驶证上的准驾车型
13 address 住址 string 128 身份证识别上出来的住址
14 issuingOrganizations 驾驶证发证机关 string 160 驾驶证发证机关
15 licenseDate 初次领证日期 date 8 第一次领驾驶证日期: yyyyMMdd
16 validFrom 有效限期开始 date 8 驾驶证有效期开始日期: yyyyMMdd
17 validTo 有效限期结束 date 8 驾驶证有效期结束日期: yyyyMMdd
18 driverContractFile 司机合同 base64 1MB 司机签署的物流运输合同附件,照片或pdf文件
反馈结果:
序号 字段编码 字段名称 数据类型 长度 是否必填 备注
1 status 认证状态 number 1 1-已认证,0-认证失败
2 errorMsg 失败原因 string 64 1-司机信息与驾驶证信息不符;请重新提交信息照片 2-司机信息与驾驶员从业资格证信息不符;请重新提交信息照片 3-司机信息与身份证信息不符;请重新提交信息照片 4-信息不完整; 5-身份证号已存在,手机号不一致 6-手机号被其他司机占用 7-合同号无效

2.4车辆注册接口

接口名称:车辆注册接口
接口代码:vehicle_register
接口描述:通过车辆注册接口,采集车辆注册信息,在好货云平台中完成车辆注册,并返回注册结果值。
接口版本:V1.0
接口调用地址:[接口访问地址]/hhy/vehicle_register
调用模式:同步
请求参数:
序号 参数编码 参数名称 数据类型 长度 是否必填 备注
1 senderTaxNos 托运方税号 string[] 公司税号,可以为多个税号
2 plateNo 车牌号 string 16 车牌号
3 licenseNo 车辆识别码 string 32 车辆识别码
4 licenseMainImg 行驶证主页 base64 1MB 车辆行驶证主页正面照片,请重新提交信息照片
5 licenseSubImg 行驶证副页 base64 1MB 车辆行驶证副页照片,请重新提交信息照片
6 transPermitNo 道路运输证号 string 32 道路运输证号
7 transPermitImg 道路运输证 base64 1MB 道路运输证照片
8 issuingOrganizations 发证机关 string 160 发证机关
9 transPermitValid 驾驶证有效期 date 8 驾驶证有效期:yyyyMMdd
10 isHang 是否挂靠 number 1 1-是,0-否
11 ownerName 所有人 string 64 车辆所有人
12 actOwnerName 实际所有人姓名 string 64 是否挂靠为是的时候,填写实际所有人姓名
13 actOwnerPhone 实际所有人电话 string 16 是否挂靠为是的时候,填写实际所有人电话
14 vehicleEnergyType 车辆能源类型 string 16 汽油
15 totalWeight 车辆总质量 string 16 车辆总质量=牵引总质量+整备质量
16 vehicleCapacity 载重 number 83 车辆载重:吨
17 vehicleType 车辆类型代码 string 32 参见附录1
18 vehicleLength 车长 string 16 参见附录2
19 vehicleColorCode 车牌颜色代码 number 参见附录3
20 useFor 使用性质 string 32 行驶证上的使用性质
21 vehicleImg 车辆照片 base64 1MB 车辆照片
反馈结果:
序号 字段编码 字段名称 数据类型 长度 是否必填 备注
1 status 认证状态 number 1 1-已认证,0-认证失败
2 errorMsg 失败原因 string 64 1-车号信息与证件信息不符;请重新提交信息照片 2-信息不完整; 3-合同号无效 4-司机未认证;

2.5 运单创建接口

接口名称:运单创建接口
接口代码: task_create
接口描述:货运中国网平台根据对接托运人平台上传的运单数据,生成在途状态的运单
接口版本:V1.0
接口调用地址:[接口访问地址]/hhy/task_create
调用模式:异步,支持批量处理
请求参数:
序号 参数编码 参数名称 数据类型 长度 是否必填 备注
1 contractNo 合同号 string 30 货运中国网平台中的合同号
2 senderTaxNo 托运方税号 string 30
3 outTaskNo 客户运单号 string 30 托运人平台运单号
4 matName 货物名称 string 30
5 unit 计量单位 string 1 参见附录4
6 loadMethod 装卸方式 string 1 参见附录5
7 priceMethod 运费计价方式 string 1 参见附录6
8 sender 发货方 string 50
9 senderProvince 发货省 string 20 省、直辖市
10 senderCity 发货市 string 20 市/直辖市
11 senderAddress 发货详细地址 string 100 区/县、镇、村、街道、名称(能够获取到百度地图、腾讯地图等地图软件上的定位信息为准)
12 senderContact 发货联系人姓名 string 30
13 senderPhone 发货联系人电话 string 15
14 receiver 收货方 string 50
15 receiverProvince 收货省 string 20 省、直辖市
16 receiverCity 收货市 string 20 市/直辖市
17 receiverAddress 收货详细地址 string 100 区/县、镇、村、街道、名称(能够获取到百度地图、腾讯地图等地图软件上的定位信息为准)
18 receiverContact 收货联系人姓名 string 20
19 receiverPhone 收货联系人电话 string 15
20 plateNo 车牌号 string 15
21 driverName 司机姓名 string 30
22 driverIdNo 司机身份证号 string 30
23 taskDt 接单时间 string 14 运单生成时间、早于起运时间,格式:yyyyMMddHHmmss
24 startDt 起运时间 string 14 格式:yyyyMMddHHmmss
25 loadAmount 装车重量 number
26 payeeName1 收款人1姓名 string 30
27 payeeIdNo1 收款人1身份号 string 30
28 payeeMobile1 收款人1电话 string 15
29 payeeAccount1 收款人1银行卡号 string 30
30 payeeBank1 收款人1开户行 string 30
31 amount1 收款人1电话 string 15
32 payeeName2 收款人2姓名 string 30
33 payeeIdNo2 收款人2身份号 string 30
34 payeeMobile2 收款人2电话 string 15
35 payeeAccount2 收款人2银行卡号 string 30
36 payeeBank2 收款人2开户行 string 30
37 amount2 收款人2运单支付金额 number
反馈结果:
序号 字段编码 字段名称 数据类型 长度 是否必填 备注
1 taskId 运单号 string 30 货运中国网平台运单号
2 status 运单状态 number 1 0-在途;其他-运单创建失败
3 result 处理结果 string 100 处理结果描述
4 outTaskNo 客户运单号 string 30

2.6 回单接口

接口名称:回单接口
接口代码: task_receipt
接口描述:货运中国网平台根据对接托运人平台上传的回单数据,在平台内保存到对应的运单下
接口版本:V1.0
接口调用地址:[接口访问地址]/hhy/task_receipt
调用模式:异步
请求参数:
序号 参数编码 参数名称 数据类型 长度 是否必填 备注
1 taskId 运单号 string 30 货运中国网平台运单号
2 loadImg 装货现场照 base64 1MB
3 loadPoundImg 装货磅单照片 base64 1MB
4 unloadImg 卸货现场照片 base64 1MB
5 unloadPoundImg 卸货磅单/收货签收单照片 base64 1MB
反馈结果:
序号 字段编码 字段名称 数据类型 长度 是否必填 备注
1 taskId 运单号 string 30 货运中国网平台运单号
2 status 运单状态 number 0-成功;其他-失败
3 result 处理结果 string 处理结果描述: 装货现场照片,有/无 装货磅单照片, 有/无 卸货现场照片,有/无 卸货磅单/收货签收单照片有/无

2.7 运单状态更新接口

接口名称:运单状态更新接口
接口代码: task_status
接口描述:运单状态更新接口用于货运中国网平台接收平台内运单状态变化的指令
接口版本:V1.0
接口调用地址:[接口访问地址]/hhy/task_status
调用模式:异步,支持批量处理
请求参数:
序号 参数编码 参数名称 数据类型 长度 是否必填 备注
1 taskId 运单号 string 30 货运中国网平台运单号
2 status 运单状态 number 3-到达、0-删除
3 receiveDt 到达时间 string 14 格式:yyyyMMddHHmmss
4 unloadAmount 卸车重量 number 单位:吨
反馈结果:
序号 字段编码 字段名称 数据类型 长度 是否必填 备注
1 taskId 运单号 string 30 货运中国网平台运单号
2 status 处理状态 number 0-成功;其他-失败
3 result 处理结果 string 处理结果描述

2.8 运单轨迹接收接口

接口名称:运单轨迹接收接口
接口代码: task_track
接口描述:运单轨迹接收接口用于货运中国网平台接收平台内运单对应的轨迹经纬度值,并通过货运中国网平台形成轨迹
接口版本:V1.0
接口调用地址:[接口访问地址]/hhy/task_track
调用模式:异步
请求参数:
序号 参数编码 参数名称 数据类型 长度 是否必填 备注
1 taskId 运单号 string 30 货运中国网平台运单号
2 plateNo 车牌号 string 15
3 coordinates 运单轨迹列表 array 运单启运至到达时间点内的轨迹坐标点,间隔5min一个点。
4 longitude 经度 number
5 latitude 纬度 number
6 longitude 时间戳 string 14 格式:yyyyMMddHHmmss
反馈结果:
序号 字段编码 字段名称 数据类型 长度 是否必填 备注
1 taskId 运单号 string 30 货运中国网平台运单号
2 status 处理状态 number 0-成功;其他-失败
3 result 处理结果 string 处理结果描述

附录

1、车辆类型定义

代码 名称 备注
1 半挂一拖二
2 半挂一拖三
3 拖挂及轮轴
4 半挂二拖二
5 半挂二拖三
6 前四后四半挂
7 前四后六
8 前四后八
9 前四后十
A 后八轮
B 五轮车
C 单桥
D 双桥
E 四轴
F 五轴
G 六桥
H 全挂
I 6轴(6*4牵引+3轴半挂)
J 6轴(6*2牵引+3轴半挂)
K 5轴(6*4牵引+2轴半挂)
L 5轴(6*2牵引+2轴半挂)
M 4轴(4*2牵引+2轴半挂)
N 4轴(8*4载车)
O 4轴(8*2载车)
P 3轴(6*4牵引车)
Q 3轴(6*4载货车)
R 3轴(6*2牵引车)
S 3轴(6*2载货车)
T 2轴(4*2载货车)
U 其他
V 前四后四
W 重型半挂牵引车
H11 重型普通货车
H11 重型栏板货车
H12 重型厢式货车
H13 重型封闭货车
H13 重型封闭式货车
H14 重型罐式货车
H15 重型平板货车
H16 重型集装厢车
H16 重型集装箱车
H17 重型自卸货车
H18 重型特殊结构货车
H19 重型仓栅式货车
H21 中型普通货车
H21 中型栏板货车
H23 中型封闭货车
H23 中型封闭式货车
H24 中型罐式货车
H25 中型平板货车
H26 中型集装厢车
H26 中型集装箱车
H27 中型自卸货车
H28 中型特殊结构货车
H29 中型仓栅式货车
H31 轻型普通货车
H31 重型厢式货车
H32 轻型厢式货车
H33 轻型封闭货车
H33 轻型封闭式货车
H34 轻型罐式货车
H35 轻型平板货车
H37 轻型自卸货车
H38 轻型特殊结构货车
H39 轻型仓栅式货车
H41 微型普通货车
H41 微型栏板货车
H42 微型厢式货车
H43 微型封闭货车
H43 微型封闭式货车
H44 微型罐式货车
H45 微型自卸货车
H46 微型特殊结构货车
H47 微型仓栅式货车
H51 普通低速货车
H51 栏板低速货车
H52 厢式低速货车
H53 罐式低速货车
H54 自卸低速货车
H55 仓栅式低速货车
Q11 重型半挂牵引车
Q12 重型全挂牵引车
Q21 中型半挂牵引车
Q22 中型全挂牵引车
Q31 轻型半挂牵引车
Q32 轻型全挂牵引车
Z11 大型专项作业车
Z21 中型专项作业车
Z31 小型专项作业车
Z41 微型专项作业车
Z51 重型专项作业车
Z71 轻型专项作业车
D11 无轨电车
D12 有轨电车
M11 普通正三轮摩托车
M12 轻便正三轮摩托车
M13 正三轮载客摩托车
M14 正三轮载货摩托车
M15 侧三轮摩托车
M21 普通二轮摩托车
M22 轻便二轮摩托车
N11 三轮汽车
T11 大型轮式拖拉机
T21 小型轮式拖拉机
T22 手扶拖拉机
T23 手扶变形运输机
J11 轮式装载机械
J12 轮式挖掘机械
J13 轮式平地机械
G11 重型普通全挂车
G11 重型栏板全挂车
G12 重型厢式全挂车
G13 重型罐式全挂车
G14 重型平板全挂车
G15 重型集装箱全挂车
G16 重型自卸全挂车
G17 重型仓栅式全挂车
G18 重型旅居全挂车
G19 重型专项作业全挂车
G19 重型特殊用途全挂车
G21 中型普通全挂车
G21 中型栏板全挂车
G22 中型厢式全挂车
G23 中型罐式全挂车
G24 中型平板全挂车
G25 中型集装箱全挂车
G26 中型自卸全挂车
G27 中型仓栅式全挂车
G28 中型旅居全挂车
G29 中型专项作业全挂车
G29 中型特殊用途全挂车
G31 轻型普通全挂车
G31 轻型栏板全挂车
G32 轻型厢式全挂车
G33 轻型罐式全挂车
G34 轻型平板全挂车
G35 轻型自卸全挂车
G36 轻型仓栅式全挂车
G37 轻型旅居全挂车
G38 轻型专项作业全挂车
G38 轻型特殊用途全挂车
B11 重型普通半挂车
B11 重型栏板半挂车
B12 重型厢式半挂车

2、车长定义

代码 名称 备注
1 9.6M
2 10M
3 12M
4 13M
5 13.5M
6 16M
7 17.5M
8 4.2M
9 13.5M
A 6.2M
B 6.3M
C 6.8M
D 7.2M
E 7.5M
F 7.7M
G 7.8M
H 8M
I 8.7M
J 12.5M
K 其他
L 1.8M
M 2.7M
N 3.8M
O 7.8M
O 5M
P 8.2M
Q 11.7M
R 13.7M
S 15M

3、车牌颜色代码定义

代码 名称 备注
0 蓝色
1 黄色
2 黑色
3 白色
4 渐变绿色
5 黄绿渐变色
6 蓝白渐变色
9 未确定

4、计量单位

代码 名称 备注
1
2
3 立方
4
5
6 平米

5、装卸方式

代码 名称 备注
1 一装一卸
2 一装多卸
3 多装一卸
4 多装多卸

6、运费计价方式

代码 名称 备注
1 吨/路线
2 立方/路线
3 整车/路线
4 件/路线
5 个/路线
6 平米/路线