出行网约车
  • 概述
      • 开发指南
      Android 开发指南
      iOS开发指南
      服务端API
    出行网约车
    服务端API
    订单信息同步(拼车)

    前言

    本文主要对网约车订单信息同步服务-拼车进行介绍，包括信息传输方式、协议、具体信息等内容。

    注意

    • 本服务以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]
    driver_orderid 否 string 司机预约单订单id
    注：status为3、5、6、7、8、9时必填，长度限制50字节，具体参考后面调用示例
    passenger_orderid 否 string 乘客预约单订单id
    注：status为0、2、3、4、5、6、7时必填，长度限制50字节，具体参考后面调用示例
    business_type 必 int 业务类型，用于区分不同业务间的订单，取值范围[1,200]
    例如：
    1. 业务A
    2.  业务B
    type 必 int 订单类型，可选值：
    4：拼车行程–司机
    5：拼车订单—乘客
    status 必 int 订单状态，可选值：
    司机端/服务端：
    2. 已派单（初始派单，接第一个乘客，创建行程）
    3. 已派单（将某乘客订单拼入已存在行程）
    4. 取消某订单
    5. 到达某乘客上车点
    6. 某乘客已上车
    7. 某乘客已下车
    8. 服务器通知行程取消
    9. 服务器通知行程完成
    乘客端：
    0. 创建订单
    uptime 必 int 订单状态变更的时间戳，秒为单位，需满足：UNIX时间戳+[-30min,30min]
    userid 否 string 网约车下单用户id
    注：status为0时必填
    userdev 必 string 网约车下单用户设备id
    Android系统:IMEI
    iOS系统: IDFV
    driverid 否 string 网约车接单司机id
    注：status为2、3时必填
    driverdev 否 string 网约车接单司机设备id
    Android系统:IMEI
    iOS系统: IDFV
    注：states为2、3时必填
    city 必 string 订单所在城市
    可通过https://lbs.qq.com/service/webService/webServiceGuide/webServiceDistrict 获取行政区划编码，6位，例如北京100000
    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
    getin_poiname 必 string 上车点poi名称
    注：没有poi名称时，填默认值”我的位置”
    getoff_lnglat 必 string 目的地位置经纬度，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。
    例如：116.307495,39.984102
    getoff_poiname 必 string 目的地poi名称
    getoff_poiid 否 string 目的地poiid，使用地图检索服务时，需要返回对应的poiid
    departure_time 必 string 出发时间，仅乘客端需要，对于乘客端，传递可接受的截止出发时间， unix时间戳，单位：秒
    例如：
    乘客端：1583121557 表示乘客从下单起到时间戳1583121557之间随时可以出发
    注意：此参数必须大于当前时间
    number_of_passenger 必 int 乘车人数,乘客订单确认,取值范围[1,4]
    capacity 必 int 载客量，司机订单确认,取值范围[1,4]
    estimate_price_for_carpool 否 string 乘客下单前，计算出的本单拼成的预估费用，单位：分
    estimate_price 否 int 乘客下单前，计算出的本单预估费用，单位：分
    estimate_distance 否 int 乘客下单前，计算出的本单预估里程，单位：米
    estimate_time 否 int 乘客下单前，计算出的本单预估时间，单位：秒
    user_lnglat 必 string 乘客下单时的位置经纬度，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。
    例如：116.307495,39.984102
    driver_lnglat 必 string 司机发布行程时的位置经纬度，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。
    例如：116.307495,39.984102
    driver_arrive_lnglat 否 string 司机到达上车点的位置经纬度，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。
    例如：116.307495,39.984102
    real_getin_lnglat 否 string 司机点击开始计费的位置(实际上车点位置经纬度)，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。
    例如：116.307495,39.984102
    real_getin_time 否 int 司机点击开始计费的时间戳，单位：秒
    real_getoff_lnglat 否 string 司机点击结束行程时的位置(实际上车点位置经纬度)，经度在前，纬度在后，经度和纬度用英文半角逗号","分隔，小数点后不得超过6位，单次只可以传入一组经纬度坐标对。
    例如：116.307495,39.984102
    real_getoff_time 否 int 司机点击结束行程时的时间戳，单位：秒

    响应结果

    名称 类型 必须 说明
    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

    乘客发布行程，创建订单之后，需要调用如下接口先创建订单

    // 请求body
{
	"city": "110000",
	"getin_lnglat": "116.30647,39.98494",      //用户上车点经纬度
	"getin_poiname": "中国技术交易大厦-北门西北侧",   
	"getoff_lnglat": "116.32098,39.89355",     //目的地经纬度
	"getoff_poiid": "15830929333498782236",  //目的地poiid   选填
	"getoff_poiname": "北京西站南1出站口",
	"business_type": 1,                     //业务类型   必填
	"cartype":  3,                          //车辆类型   选填
	"key": "<key>",
	"passenger_orderid": "330718659248078852",        //乘客订单ID
	"getin_cate": 1,                        //上车点类型   选填
	"getin_poiid": "3412412421523412423452", //上车点id     选填
	"estimate_price_for_carpool": 69,                  //拼成预估价   选填
	"estimate_price": 112,                  //未拼成预估价    选填
	"estimate_distance": 1234,              //预估距离        选填
	"estimate_time": 1234,                 //预估时间        选填
	"type": 5,                 
	"departure_time": "1583121357",
	"number_of_passenger": 1,
	"reqid": "f7ae6682-46ec-11e9-83d1-000000000000",
	"reqtime": 1552631919,
	"status": 0,   //乘客订单状态为等待邀请
	"uptime": 1552631919,
	"user_lnglat": "116.307147,39.984403",    //乘客下单时的位置经纬度
	"userdev": "355637052277589",          //乘客设备ID
	"userid": "314439427527204864"         //乘客ID
}

//响应示例
{
    "status": 0,
    "message": "query ok",
    "data": {
        "status": 0,
        "message": "ok"
    }
}

    派单给司机（初始派单，接第一个乘客，创建行程）

    // 请求body体
{
	"passenger_orderid": "863504035357778",         //乘客订单id
	"getin_lnglat": "116.30647,39.98494",      //乘客订单上车点经纬度
	"getoff_lnglat": "116.32098,39.89355",     //乘客订单目的地经纬度
	"business_type": 1,                     //业务类型   必填
	"key": "<key>",
	"reqid": "f7ae6682-46ec-11e9-83d1-000000000000",
	"reqtime": 1552631920,
	"driverdev": "863504035357778",         //司机的设备ID
	"driverid": "314435261423140864",        //司机ID
	"capacity": 3,                          //司机车辆的载客量
	"status": 2,                            //乘客订单状态变为已派单  司机行程状态变为行程中
	"driver_lnglat": "116.307175,39.984401",   //司机接单时的位置经纬度
	"uptime": 1552631921,
	"type": 4,         
}

//响应示例
{
    "status": 0,
    "message": "query ok",
    "data": {
        "status": 0,
        "message": "ok",
		"driver_orderid": "324124324123412",  //创建的司机行程id
    }
}

    派单给司机（将某乘客订单拼入已存在行程）

    // 请求body体
{
	"driver_orderid": "863504035357778",             //司机行程订单id, 使用上例(例2)中返回的driver_orderid
	"passenger_orderid": "863504035357778",         //乘客订单id
	"getin_lnglat": "116.30647,39.98494",      //乘客订单上车点经纬度
	"getoff_lnglat": "116.32098,39.89355",     //乘客订单目的地经纬度
	"key": "<key>",
	"reqid": "f7ae6682-46ec-11e9-83d1-000000000000",
	"reqtime": 1552631920,
	"driverdev": "863504035357778",                //司机的设备ID
	"driverid": "314435261423140864",              //司机ID
	"status": 3,                                  //乘客订单状态变为已派单 
	"driver_lnglat": "116.307175,39.984401",         //司机接单时的位置经纬度
	"uptime": 1552631921,
	"type": 4,         
}

// 响应示例
{
    "status": 0,
    "message": "query ok",
    "data": {
        "status": 0,
        "message": "ok"
    }
}

    司机到达某个乘客订单上车点

    // 请求body体
{
	"driver_orderid": "863504035357778",   //司机行程订单id
	"passenger_orderid": "863504035357778",         //乘客订单id
	"key": "<key>",
	"reqid": "f7ae6682-46ec-11e9-83d1-000000000000",
	"reqtime": 1552631920,
	"status": 5,                        //乘客订单状态变为司机已到达
	"driver_arrive_lnglat":"116.30647,39.98494",   //司机到达上车点的位置经纬度
	"uptime": 1552631921,
	"type": 4,         
}

    乘客上车后，司机调用如下接口标识开始送驾

    // 请求body体
{
	"driver_orderid": "863504035357778",         //司机行程订单id
	"passenger_orderid": "863504035357778",         //乘客订单id
	"getin_lnglat": "116.30647,39.98494",      //乘客订单上车点经纬度
	"getoff_lnglat": "116.32098,39.89355",     //乘客订单目的地经纬度
	"key": "<key>",
	"reqid": "f7ae6682-46ec-11e9-83d1-000000000000",
	"reqtime": 1552631920,
	"status": 6,                               //司机状态为行程中
	"uptime": 1552631921,
	"type": 4, 
	"real_getin_lnglat": "116.307555,39.984127",  //司机点击出发的位置
	"real_getin_time": 1552632029,             //司机点击出发的时间   
}

    司机将乘客送到目的地，需要调用如下接口标识订单结束

    // 请求body体
{
	"driver_orderid": "863504035357778",             //司机行程订单id
	"passenger_orderid": "863504035357778",         //乘客订单id
	"getin_lnglat": "116.30647,39.98494",      //乘客订单上车点经纬度
	"getoff_lnglat": "116.32098,39.89355",     //乘客订单目的地经纬度
	"key": "<key>",
	"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": "f7ae6682-46ec-11e9-83d1-000000000000",
	"reqtime": 1552631920,
	"status": 7,
	"type": 4, 
	"uptime": 1552631921,
}

    取消某订单

    // 请求body体
{
    "driver_orderid": "863504035357778",        //司机行程订单id  非必选，如果乘客订单已经绑定了行程，则必填
	"passenger_orderid": "863504035357778",    //乘客订单id
	"getin_lnglat": "116.30647,39.98494",      //乘客订单上车点经纬度
	"getoff_lnglat": "116.32098,39.89355",     //乘客订单目的地经纬度
	"key": "<key>",
	"reqid": "396f9584-46ed-11e9-83d2-000000000000",
	"reqtime": 1552632029,
	"status": 4,                           //司机同步取消某子订单
	"type": 4, 
	"uptime": 1552632029,
}

// 响应示例
{
	"status": 0,
    "message": "query ok",
    "data": {
		"status": 0,
		"message": "ok"
	}
}

    服务器通知取消行程（行程中的最后一个订单被取消，因此行程中没有未完成订单）

    // 请求body体
{
	"driver_orderid": "863504035357778",        //司机行程订单id
	"key": "<key>",
	"reqid": "396f9584-46ed-11e9-83d2-000000000000",
	"reqtime": 1552632029,
	"status": 8,                           // 服务器通知
	"type": 4, 
	"uptime": 1552632029,
}

// 响应示例
{
    "status": 0,
    "message": "query ok",
    "data": {
        "status": 0,
        "message": "ok"
    }
}

    服务器通知行程完成（行程中的最后一个订单完成后）

    // 请求body体
{
	"driver_orderid": "863504035357778",        //司机行程订单id
	"key": "<key>",
	"reqid": "396f9584-46ed-11e9-83d2-000000000000",
	"reqtime": 1552632029,
	"status": 4,                           //服务器通知
	"type": 9, 
	"uptime": 1552632029,
}

// 响应示例
{
    "status": 0,
    "message": "query ok",
    "data": {
        "status": 0,
        "message": "ok"
    }
}

    附录

    如需查询返回值中的status和message的具体对应关系，请查看文档《开放平台错误对照表》。

    本页内容