前言
本文主要对网约车订单信息同步服务-专车进行介绍，包括信息传输方式、协议、具体信息等内容。
注意
-
本服务以HTTPS方式进行访问。
-
本接口为高级接口，默认不可调用，使用请与腾讯位置服务商务人员取得联系，开放调用配额后，即可使用。
-
接口中的参数key和调用示例中的
(含尖括号), 请使用您在https://lbs.qq.com/key.html中申请的key。 -
如无特殊说明，所有接口的输入参数和输出参数编码全部统一为UTF-8。
概述
本服务为司乘同显服务配套后端WebService接口，用于网约车订单信息变更时将相应数据进行同步。用户需要在创建订单，派单给司机，司机接驾，行程结束，订单取消时调用此服务。
请求URL
URL: https://apis.map.qq.com/ws/tls/v1/order/sync
Method: POST
Content-Type: application/json
请求参数
| 名称 | 必填 | 类型 | 说明 | |
|---|---|---|---|---|
| key | 必 | string | 客户注册的访问webservice的key | |
| reqid | 必 | string | 需要全局唯一，推荐使用UUID生成 例如：b7be9806-0b13-11e9-9aed-6c92bf46a458 |
|
| reqtime | 必 | int | 调用方服务器请求接口时的本地时间 单位：秒 需满足：UNIX时间戳+[-30min,30min] |
|
| orderid | 必 | string | 网约车订单id，长度限制为50字节。 | |
| business_type | 否 | int | 业务类型，用于区分不同业务间的订单，取值范围[1,200] 例如： 1. 业务A 2. 业务B |
|
| status | 必 | int | 订单状态，可选值： 1 未派单 2 已派单 201 司机到达上车点（可选状态） 3 开始计费 4 订单撤销 6 结束行程 |
|
| uptime | 必 | int | 订单状态变更的时间戳，秒为单位，需满足：UNIX时间戳+[-30min,30min] | |
| userid | 否 | string | 网约车下单用户id 注：status=1时必填非空值 |
|
| userdev | 否 | string | 网约车下单用户设备id Android系统:IMEI iOS系统: IDFV 注：status=1时必填非空值 |
|
| driverid | 否 | string | 网约车接单司机id 注：status=2,3时必填非空值 |
|
| driverdev | 否 | string | 网约车接单司机设备id Android系统:IMEI iOS系统: IDFV 注：status=2,3时必填非空值 |
|
| city | 必 | string | 订单所在城市 注：status=1,2,4时必填非空值 可通过https://lbs.qq.com/service/webService/webServiceGuide/webServiceDistrict 获取行政区划编码，6位，例如北京100000 |
|
| type | 必 | int | 订单类型，可选值： 1：实时订单（本文档只对应实时订单） 2：顺风车—司机/服务器 3：顺风车—乘客 4：拼车----司机/服务器 5：拼车----乘客 |
|
| cartype | 必 | int | 订单车辆类型，可选值： 0：所有分类 1：出租车 2：新能源 3：舒适型 4：豪华型 5：商务型 |
|
| getin_cate | 必 | int | 上车点类型： 1：推荐上车点-交通枢纽 2：推荐上车点-通用 3：POI SUG 4：逆地址解析 5：戳点的经纬度 |
|
| getin_poiid | 必 | string | 上车点id 如果getin_cate为1或2时，填入推荐上车点ID 如果getin_cate为3或4时，填入上车点的POIID 如果getin_cate为5时，不传递此参数 |
|
| getin_lnglat | 必 | string | 上车点位置经纬度，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。 例如：116.307495,39.984102 注：status=1,2,4时必填非空值 |
|
| getin_poiname | 否 | string | 上车点poi名称 注：status=1,2,4时必填,没有poi名称时，填默认值”我的位置” |
|
| getoff_lnglat | 否 | string | 目的地位置经纬度，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。 例如：116.307495,39.984102 |
|
| getoff_poiname | 否 | string | 目的地poi名称 | |
| getoff_poiid | 否 | string | 目的地poiid，使用地图检索服务时，需要返回对应的poiid | |
| estimate_price | 否 | int | 乘客下单前，计算出的本单预估费用，单位：分 | |
| estimate_distance | 否 | int | 乘客下单前，计算出的本单预估里程，单位：米 | |
| estimate_time | 否 | int | 乘客下单前，计算出的本单预估时间，单位：秒 | |
| user_lnglat | 必 | string | 乘客下单时的位置经纬度，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。 例如：116.307495,39.984102 注：status=1,2,4时必填非空值 |
|
| driver_lnglat | 必 | string | 司机接单时的位置经纬度，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。 例如：116.307495,39.984102 注：status=2,4时必填非空值 |
|
| driver_arrive_lnglat | 否 | string | 司机到达上车点的位置经纬度，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。 例如：116.307495,39.984102 注：status=201时必填非空值 |
|
| real_getin_lnglat | 否 | string | 司机点击开始计费的位置(实际上车点位置经纬度)，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。 例如：116.307495,39.984102 注：status=3,6时必填非空值 |
|
| real_getin_time | 否 | int | 司机点击开始计费的时间戳，单位：秒 注：status=3,6时必填非空值d |
|
| real_getoff_lnglat | 否 | string | 司机点击结束行程时的位置(实际上车点位置经纬度)，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。 例如：116.307495,39.984102 注：status=6时必填非空值 |
|
| real_getoff_time | 否 | int | 司机点击结束行程时的时间戳，单位：秒 注：status=6时必填非空值 |
|
| driver_highway_price | 否 | int | 高速费，司机结束行程时，填入的高速费，分为单位，如果没有此费用，此参数应设为：0 注：status=6时必填非空值 |
|
| driver_toll_price | 否 | int | 过路费，司机结束行程时，填入的过路费，分为单位，如果没有此费用，此参数应设为：0 注：status=6时必填非空值 |
|
| driver_park_price | 否 | int | 乘车费用，司机结束行程时，填入的停车费，分为单位，如果没有此费用，此参数应设为：0 注：status=6时必填非空值 |
|
| driver_other_price | 否 | int | 其他费用，司机结束行程时，填入的其他费，分为单位，如果没有此费用，此参数应设为：0 注：status=6时必填非空值 |
|
响应结果
| 名称 | 类型 | 必须 | 说明 | ||||
|---|---|---|---|---|---|---|---|
| status | int | 必 | 状态码，0正常返回，表示接受到正常信息 | ||||
| message | string | 必 | 错误信息 | ||||
| data | object | 必 | 接口返回信息 | ||||
| status | int | 否 | 状态码，0正常返回，表示接受到正常信息 | ||||
| message | stirng | 必 | 错误信息 | ||||
示例
Methond：POST
Content-Type: application/json
URL：https://apis.map.qq.com/ws/tls/v1/order/sync
status=1时
用户发起叫车，创建订单之后，需要调用如下接口先创建订单
// 请求body
{
"city": "110000",
"driver_lnglat": "", //创建订单，此时还没有司机接单，司机相关信息填空
"driverdev": "",
"driverid": "",
"getin_lnglat": "116.30647,39.98494", //用户上车点经纬度
"getin_poiname": "中国技术交易大厦-北门西北侧",
"getoff_lnglat": "116.32098,39.89355", //目的地经纬度
"getoff_poiid": "15830929333498782236", //目的地poiid
"getoff_poiname": "北京西站南1出站口",
"business_type": 1,//业务类型
"key": "<key>",
"orderid": "330718659248078852",//订单ID
"getin_cate": 1,//上车点类型
"getin_poiid": "3412412421523412423452", //上车点id
"estimate_price": 112,//预估价
"estimate_distance": 1234,//预估距离
"estimate_time": 1234,//预估时间
"real_getin_lnglat": "",//创建订单，此时用户还未上车，相关用户实际上车信息填空
"real_getin_time": 0,
"real_getoff_lnglat": "",
"real_getoff_time": 0,
"reqid": "f7ae6682-46ec-11e9-83d1-000000000000",
"reqtime": 1552631919,
"status": 1,
"uptime": 1552631919,
"user_lnglat": "116.307147,39.984403", //乘客下单时的位置经纬度
"userdev": "355637052277589", //乘客设备ID
"userid": "314439427527204864" //乘客ID
}
// 响应结果
{
"status": 0,
"message": "query ok",
"data": {
"status": 0,
"message": "ok"
}
}
status=2时
服务端进行派单，将用户订单分配给某个司机之后，需要调用如下接口创建司乘匹配关系
// 请求body体
{
"city": "110000",
"driver_lnglat": "116.307175,39.984401", //司机接单时的位置经纬度
"driverdev": "863504035357778", //司机的设备ID
"driverid": "314435261423140864", //司机ID
"getin_lnglat": "116.30647,39.98494", //用户上车点经纬度
"getin_poiname": "中国技术交易大厦-北门西北侧",
"getoff_lnglat": "116.32098,39.89355", //目的地经纬度
"getoff_poiid": "15830929333498782236", //目的地poiid
"getoff_poiname": "北京西站南1出站口",
"business_type": 1, //业务类型
"key": "<key>",
"orderid": "330718659248078852", //订单ID
"real_getin_lnglat": "", //此时用户还未上车，相关用户实际上车信息填空
"real_getin_time": 0,
"real_getoff_lnglat": "",
"real_getoff_time": 0,
"reqid": "f7ae6682-46ec-11e9-83d1-000000000000",
"reqtime": 1552631920,
"status": 2,
"uptime": 1552631921,
"user_lnglat": "116.307147,39.984403", //乘客下单时的位置经纬度
"userdev": "355637052277589",
"userid": "314439427527204864"
}
// 响应结果
{
"status": 0,
"message": "query ok",
"data": {
"status": 0,
"message": "ok"
}
}
status=201时
司机到达乘客上车点，需要调用如下接口标识司机已经到达乘客上车点
// 请求body体
{
"city": "110000",
"driver_lnglat": "116.307175,39.984401", //司机接单时的位置经纬度
"driverdev": "863504035357778", //司机的设备ID
"driverid": "314435261423140864", //司机ID
"getin_lnglat": "116.30647,39.98494", //用户上车点经纬度
"getin_poiname": "中国技术交易大厦-北门西北侧",
"getoff_lnglat": "116.32098,39.89355", //目的地经纬度
"getoff_poiid": "15830929333498782236", //目的地poiid
"getoff_poiname": "北京西站南1出站口",
"business_type": 1, //业务类型
"key": "<key>",
"orderid": "330718659248078852", //订单ID
"driver_arrive_lnglat":"116.30647,39.98494", //司机到达上车点的位置经纬度
"real_getin_lnglat": "", //此时用户还未上车，相关用户实际上车信息填空
"real_getin_time": 0,
"real_getoff_lnglat": "",
"real_getoff_time": 0,
"reqid": "f7ae6682-46ec-11e9-83d1-000000000000",
"reqtime": 1552631920,
"status": 201,
"uptime": 1552631921,
"user_lnglat": "116.307147,39.984403", //乘客下单时的位置经纬度
"userdev": "355637052277589",
"userid": "314439427527204864"
}
// 响应结果
{
"status": 0,
"message": "query ok",
"data": {
"status": 0,
"message": "ok"
}
}
status=3时
司机到达乘客位置，乘客上车之后，需要调用如下接口标识已经开始送驾
// 请求body体
{
"city": "110000",
"driver_lnglat": "116.307175,39.984401",
"driverdev": "863504035357778",
"driverid": "314435261423140864",
"getin_lnglat": "116.30647,39.98494",
"getin_poiname": "中国技术交易大厦-北门西北侧",
"getoff_lnglat": "116.32098,39.89355",
"getoff_poiid": "15830929333498782236",
"getoff_poiname": "北京西站南1出站口",
"business_type": 1, //业务类型
"key": "<key>",
"orderid": "330718659248078852",
"real_getin_lnglat": "116.307555,39.984127", //司机点击开始计费的位置（乘客实际上车点位置经纬度）
"real_getin_time": 1552632029, //司机点击开始计费的时间
"real_getoff_lnglat": "",
"real_getoff_time": 0,
"reqid": "396f9584-46ed-11e9-83d2-000000000000",
"reqtime": 1552632029,
"status": 3,
"uptime": 1552632029,
"user_lnglat": "116.307147,39.984403",
"userdev": "355637052277589",
"userid": "314439427527204864"
}
// 响应结果
{
"status": 0,
"message": "query ok",
"data": {
"status": 0,
"message": "ok"
}
}
status=4时
司机或乘客取消订单之后，需要调用如下接口标识订单已撤销
// 请求body体
{
"city": "110000",
"driver_lnglat": "116.307135,39.984401",
"driverdev": "863504035357778",
"driverid": "314435261423140864",
"getin_lnglat": "116.307493,39.984977",
"getin_poiname": "中国技术交易大厦-北门附近",
"getoff_lnglat": "116.32168,39.89604",
"getoff_poiid": "7595626187498717294",
"getoff_poiname": "北京西站北1出站口",
"business_type": 1, //业务类型
"key": "<key>",
"orderid": "330720738024824834",
"real_getin_lnglat": "",
"real_getin_time": 0,
"real_getoff_lnglat": "",
"real_getoff_time": 0,
"reqid": "8e879563-46ed-11e9-83e8-000000000000",
"reqtime": 1552632172,
"status": 4,
"uptime": 1552632172,
"user_lnglat": "116.307329,39.984394",
"userdev": "355637052277589",
"userid": "314439427527204864"
}
// 响应示例
{
"status": 0,
"message": "query ok",
"data": {
"status": 0,
"message": "ok"
}
}
status=6时
司机将乘客送到目的地，需要调用如下接口标识订单结束
{
"city": "110000",
"driver_lnglat": "116.307175,39.984401",
"driverdev": "863504035357778",
"driverid": "314435261423140864",
"getin_lnglat": "116.30647,39.98494",
"getin_poiname": "中国技术交易大厦-北门西北侧",
"getoff_lnglat": "116.32098,39.89355",
"getoff_poiid": "15830929333498782236",
"getoff_poiname": "北京西站南1出站口",
"business_type": 1, //业务类型
"key": "<key>",
"orderid": "330718659248078852",
"real_getin_lnglat": "116.307555,39.984127",
"real_getin_time": 1552632029,
"real_getoff_lnglat": "116.32098,39.89355", //司机点击结束行程时的位置(实际上车点位置经纬度)
"real_getoff_time": 1552632131, //司机点击结束行程时的时间
"driver_highway_price":0,
"driver_toll_price":0,
"driver_park_price":0,
"driver_other_price":0,
"reqid": "7611d381-46ed-11e9-8395-000000000000",
"reqtime": 1552632131,
"status": 6,
"uptime": 1552632131,
"user_lnglat": "116.307147,39.984403",
"userdev": "355637052277589",
"userid": "314439427527204864"
}
//响应示例
{
"status": 0,
"message": "query ok",
"data": {
"status": 0,
"message": "ok"
}
}
附录
如需查询返回值中的status和message的具体对应关系，请查看文档《开放平台错误对照表》。
试试AI总结
不想看文档？直接问AI～
这篇文档对您是否有帮助？
有帮助
没帮助
本页内容