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	平米/路线