代驾

1. 接口说明

1.1 接口协议

• 除非特殊指定，默认请求方式均为 HTTPS + POST 方式
• 请求和响应统一规范为：application/json

1.2 字符编码

除非特殊指定，默认字符编码均为 UTF-8 编码格式

1.3 通用请求首部

字段名	字段类型	必填	说明
timestamp	long	是	时间戳，单位：毫秒
nonce	string	是	请求唯一随机字符串
accessKey	string	是	分配给请求方的唯一标识
sign	string	是	签名，用于识别请求方和校验数据是否篡改

1.4 通用响应数据

除非特殊指定，下文接口说明中响应数据均指 data 字段数据结构定义

字段名	字段类型	必填	说明
code	int	是	服务响应状态码
message	string	是	服务响应说明
data	object	是	服务响应数据

1.5 鉴权说明

双方采用相同的方式进行签名与验证，所有主调与被调接口都需要携带签名校验信息。

参与签名计算字段：accessKey、nonce、timestamp、secretKey，签名生成方式：

• 对通用请求头首部（不包括 sign）进行字母升序排列，组成 key=value 形式字符串（中间用&连接）

  • 即：accessKey=xxx&nonce=xxx&timestamp=xxx

• 然后，在字符串最后追加 &secretKey=xxx，

  • 即：accessKey=xxx&nonce=xxx&timestamp=xxx&secretKey=xxx

• 最后，对字符串进行 MD5 运算，得到 sign（转换为大写）

  • 即：OpenMD5Util.MD5Encode("accessKey=xxx&nonce=xxx&timestamp=xxx&secretKey=xxx", OpenMD5Util.UTF8).toUpperCase();

其中，accessKey 和 secretKey 由腾讯侧线下提供，测试环境跟生产环境区分

• secretKey 为双方保密内容，不在请求中传输，严禁公开

1.6 坐标系说明

除非特殊指定，所有涉及坐标位置的参数，默认使用国标GCJ02

1.7 城市编码说明

除非特殊指定，所有接口涉及的城市编码均以国家行政区域编码为准

1.8 单位说明

除非特殊指定，默认单位均以此说明为准：

• 时间：秒
• 里程：米
• 金额：分

1.9 环境说明

被调环境

• 测试环境：https://tai-drive-dev.map.qq.com

• 生产环境：https://aggrecb.map.qq.com

主调环境

• 由服务商提供给腾讯

2. 主调接口

• 调用方：腾讯出行
• 被调方：代驾服务商

2.1 周边空闲司机

接口说明

• 本接口用于请求周边空闲司机，服务商需返回距离乘客直线距离5公里内真实司机信息，如果司机数量大于10，最多返回10个距离最近的司机即可。

请求地址

• /dd/open/v1/driver/idle/list

请求参数

参数名称	类型	必填	说明
userPhone	string	否	用户手机号
latitude	double	是	纬度
longitude	double	是	经度
category	int	是	1:普通单；2:特惠一口价单

请求示例

{
    "userPhone": "15800000000",
    "latitude": 22.540558,
    "longitude": 113.934853,
    "category": 2
}

响应数据

参数名称	类型	必须	说明
minutesToArrive	int	是	最快到达时间，单位：秒
driverNumbers	int	是	空闲司机总数
idleDriverList	list	是	司机详细信息

idleDriverList 元素数据结构

参数名称	类型	必须	说明
driverId	string	是	司机编号
driverName	string	是	司机名称
driverPhone	string	是	司机手机号
pictureUrl	string	是	司机头像url
orderNumber	double	是	司机服务次数
newLevel	double	是	司机星级
year	double	是	司机驾龄
latitude	double	是	司机纬度
longitude	double	是	司机经度
distance	int	是	司机乘客距离，单位：米

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "minutesToArrive": 1,
        "driverNumbers": 1,
        "idleDriverList": [
            {
                "driverId": "x348978aa",
                "driverName": "王师傅",
                "driverPhone": "18811721029",
                "pictureUrl": "https://xx.com/picxx",
                "orderNumber": 16,
                "newLevel": 4,
                "year": 10,
                "latitude": 22.540444,
                "longitude": 113.935254,
                "distance": 1521,
            }
        ]
    }
}

2.2 订单费用预估

接口说明

• 本接口用于预估代驾订单费用

请求地址

• /dd/open/v1/charge/estimate

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
originInfo	object	是	出发地信息
destinationInfo	object	是	目的地信息
distance	long	是	预估里程，单位：米
duration	long	是	预估时间，单位：秒
cityId	string	否	出发地城市编码
bonusSn	string	否	优惠券码
category	int	是	1普通单；2:特惠一口价单

originInfo、destinationInfo 数据结构

参数名称	类型	必填	说明
latitude	double	是	纬度
longitude	double	是	经度
address	string	是	地址
name	string	否	名称

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "originInfo": {
        "latitude": 22.541046,
        "longitude": 113.934859,
        "name": "腾大广场-东侧",
        "address": "广东省深圳市南山区科研路18号"
    },
    "destinationInfo": {
        "latitude": 22.609581,
        "longitude": 114.029224,
        "name": "深圳北站",
        "address": "广东省深圳市龙华区民治街道致远中路28号"
    },
    "distance": 17690,
    "duration": 1620,
    "cityId": "440300",
    "bonusSn": "336471252784",
    "category": 2
}

响应数据

参数名称	类型	必须	说明
estimateId	string	是	预估ID，关联当次预估信息
estimateAmount	int	是	预估金额（优惠后金额），单位：分
estimateDistance	int	否	预估距离（行程回顾数据），单位：米
totalAmount	int	是	预估总额，单位：分
discountAmount	int	否	优惠金额，单位：分
feeDetailList	array	是	预估费用明细
dynamicInfo	object	否	动态调价信息
isFixedPrice	int	否	是否一口价：0､否；1､是；

feeDetailList 元素数据结构

参数名称	类型	必须	说明
amount	int	是	金额
unit	string	是	费用单位，例：元
feeName	string	是	费用名称
feeDesc	string	是	费用描述
op	int	是	费用增减描述：1､收款；-1､减免；

dynamicInfo 数据结构

参数名称	类型	必须	说明
type	int	是	动态调价类型 ：1､金额加价；2､倍数调整；
fee	int	否	动态加价费用：type 为 1 时解析，价格为原价上浮此字段，单位：分
rate	double	否	动态调价倍数：type 为 2 时解析，价格为原价的（1 + dynamicRate）倍
feeMax	int	否	最大加价金额，type 为 2 时解析，最高加价金额不超过feeMax，单位：分

响应示例

1. 普通预估响应示例：

{
    "code": 0,
    "message": "成功",
    "data": {
        "estimateId": "161795221",
        "estimateAmount": 10080,
        "totalAmount": 13080,
        "discountAmount": -3000,
        "feeDetailList": [
            {
                "unit": "元",
                "amount": 3,
                "feeName": "start_fee",
                "feeDesc": "起步价(含2公里)",
                "op": 1
            },
            {
                "unit": "元",
                "amount": 30,
                "feeName": "time_fee",
                "feeDesc": "时长费(共27分钟,封顶30元)",
                "op": 1
            },
            {
                "unit": "元",
                "amount": -30,
                "feeName": "coupon_fee",
                "feeDesc": "优惠券抵扣",
                "op": -1
            }
        ],
        "dynamicInfo": {
            "type": 1,
            "fee": 1000,
            "rate": 0.0,
            "feeMax": 0
        },
        "isFixedPrice": 0
    }
}

2. 特惠一口价响应示例
{
    "code": 0,
    "message": "成功",
    "data": {
        "estimateId": "161795221",
        "estimateAmount": 10080,
        "totalAmount": 13080,
        "discountAmount": -3000,
        "feeDetailList": [
            {
                "unit": "元",
                "amount": 30,
                "feeName": "start_fee",
                "feeDesc": "特惠一口价",
                "op": 1
            },
            {
                "unit": "元",
                "amount": -30,
                "feeName": "coupon_fee",
                "feeDesc": "优惠券抵扣",
                "op": -1
            }
        ],
        "dynamicInfo": {
            "type": 1,
            "fee": 1000,
            "rate": 0.0,
            "feeMax": 0
        },
        "isFixedPrice": 1
    }
}

2.3 创建订单

接口说明

• 本接口用于创建代驾订单

请求地址

• /dd/open/v1/order/create

请求参数

参数名称	类型	必填	说明
estimateId	string	是	预估ID
orderId	string	是	腾讯侧订单号
userCode	string	是	用户标识
userPhone	string	是	用户手机号
contactPhone	string	否	乘车人手机号，代叫订单时必填
originInfo	object	是	出发地信息
destinationInfo	object	是	目的地信息
publishInfo	object	否	发单地信息
dynamicInfo	object	否	动态调价信息
orderType	int	是	0:普通单 1:代叫单
payType	int	否	0:下单人支付 1:乘车人支付，代叫单时有效
payScoreType	int	否	是否开启支付分免密支付 1：是 0:否,支付分免密支付订单建议关闭线下支付入口
cityId	string	否	出发地城市编码
bonusSn	string	否	优惠券码
isFixedPrice	int	否	是否一口价：0、否；1､是；
channelInfo	object	否	下单渠道信息，主要用于渠道区分，以及分渠道催缴短信下发
category	int	是	1:普通单；2:特惠一口价单
prepayType	int	否	是否预付订单,1:是 0:否,预付订单建议关闭线下支付入口

originInfo、destinationInfo、publishInfo 数据结构

参数名称	类型	必填	说明
latitude	double	是	纬度
longitude	double	是	经度
address	string	否	地址
name	string	否	名称

dynamicInfo 数据结构

参数名称	类型	必须	说明
type	int	是	动态调价类型 ：1､金额加价；2､倍数调整；
fee	int	否	动态加价费用：type 为 1 时解析，价格为原价上浮此字段，单位：分
rate	double	否	动态调价倍数：type 为 2 时解析，价格为原价的（1 + dynamicRate）倍
feeMax	int	否	最大加价金额，type 为 2 时解析，最高加价金额不超过feeMax，单位：分

channelInfo 数据结构

参数名称	类型	必填	说明
id	int	是	渠道id, 43599-腾讯出行服务小程序, 50001-腾讯出行代驾百度小程序, 1-腾讯地图APP
name	string	是	渠道名称，比如"腾讯出行服务小程序"
viewOrderGuideText	string	是	查看订单指引文案, 如: 微信搜“腾讯出行服务”小程序，点右下角“我的-订单”，或进入代驾首页—行程订单
jumpShortUrl	string	是	订单跳转短链

请求示例

{
    "estimateId": "161795221",
    "orderId": "6949013848087461896",
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "contactPhone": "15800000000",
    "payScoreType": 0,
    "originInfo": {
        "latitude": 22.541046,
        "longitude": 113.934859,
        "name": "腾大广场-东侧",
        "address": "广东省深圳市南山区科研路18号"
    },
    "destinationInfo": {
        "latitude": 22.609581,
        "longitude": 114.029224,
        "name": "深圳北站",
        "address": "广东省深圳市龙华区民治街道致远中路28号"
    },
    "publishInfo": {
        "latitude": 22.540409,
        "longitude": 113.934768,
        "name": "腾大广场-东侧",
        "address": "广东省深圳市南山区科研路18号"
    },
    "dynamicInfo": {
        "type": 1,
        "fee": 10.0,
        "rate": 0.0,
        "feeMax": 0.0
    },
    "channelInfo": {
        "id": 43599,
        "name": "腾讯出行服务小程序",
        "viewOrderGuideText": "微信搜“腾讯出行服务”小程序，点右下角“我的-订单”，或进入代驾首页—行程订单"
    },
    "cityId": "440300",
    "bonusSn": "336471252784"
}

响应数据

参数名称	类型	必须	说明
spOrderId	String	是	服务商订单号
timeout	int	否	派单超时时间
isFixedPrice	int	否	是否一口价：0､否；1､是；

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "spOrderId": "6a6b8239b4ee66",
        "timeout": 300,
        "isFixedPrice": 0
    }
}

2.4 订单状态

接口说明

• 本接口用于平台下单后，定时轮询服务商侧的订单状态

请求地址

• /dd/open/v1/order/status

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "spOrderId": "6a6b8239b4ee66"
}

响应数据

参数名称	类型	必须	说明
orderStatus	int	是	订单状态（参考 4.2订单状态模型 定义）

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "orderStatus": 401
    }
}

2.5 订单详情

接口说明

• 本接口用于在服务商接单后，即服务商回调301状态码后，腾讯侧向服务商侧查询订单详情。

请求地址

• /dd/open/v1/order/detail

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "spOrderId": "6a6b8239b4ee66"
}

响应数据

参数名称	类型	必须	说明
orderStatus	int	是	订单状态（参考 4.2订单状态模型 定义）
isFixedPrice	int	否	是否一口价：0､否；1､是；
driverInfo	object	否	司机信息

driverInfo 数据结构

参数名称	类型	必须	说明
driverId	string	是	司机ID
driverPhone	string	是	司机手机号
driverName	string	是	司机名称
pictureUrl	string	是	司机头像地址
orderNumber	int	是	司机服务单数
newLevel	double	是	司机星级
year	double	是	司机驾龄

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "orderStatus": 401,
        "isFixedPrice": 0,
        "driverInfo": {
            "driverId": "TX00700",
            "driverName": "腾师傅",
            "driverPhone": "15800000000",
            "pictureUrl": "xxx",
            "orderNumber": 14,
            "newLevel": 5.0,
            "year": 13.0
        }
    }
}

2.6 司机位置

接口说明

• 本接口用于查询司机实时位置集
• 行程中（接单后），会通过此接口定时轮询司机实时位置集

请求地址

• /dd/open/v1/driver/location

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号
startTime	long	是	开始时间（增量获取），单位：秒

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "spOrderId": "6a6b8239b4ee66",
    "startTime": 1617953971
}

响应数据

参数名称	类型	必须	说明
locationList	array	是	司机最新位置集

locationList 元素数据结构

参数名称	类型	必须	说明
time	long	是	时间戳
latitude	double	是	纬度
longitude	double	是	经度
angle	double	否	方向角

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "locationList": [
            {
                "time": 1617953971,
                "latitude": 22.546114,
                "longitude": 113.94175
            },
            {
                "time": 1617953976,
                "latitude": 22.546115,
                "longitude": 113.94175
            }
        ]
    }
}

2.7 实时费用

接口说明

• 本接口用于查询订单实时费用
• 行程中，会通过此接口定时轮询订单实时费用

请求地址

• /dd/open/v1/charge/realtime

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "spOrderId": "6a6b8239b4ee66"
}

响应数据

参数名称	类型	必须	说明
totalFee	int	是	总金额，单位：分
distance	int	是	里程，单位：米
driveTime	int	是	时长，单位：秒

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "driveTime": 10,
        "distance": 40,
        "totalFee": 1501
    }
}

2.8 账单详情

接口说明

• 本接口用于查询订单完结后，即服务商回调701时，请求账单详情。 说明：当司机报单后，若有使用优惠券，则返回couponId，discountAmout字段，chargeInfoList增加优惠券信息。

请求地址

• /dd/open/v1/charge/detail

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "spOrderId": "6a6b8239b4ee66"
}

响应数据

参数名称	类型	必须	说明
settleAmount	int	是	结算金额（优惠后金额），单位：分
totalAmount	int	是	结算总额，单位：分
discountAmount	int	否	优惠金额，单位：分
extraAmount	int	否	附加费，单位：分
couponId	string	否	优惠券 ID
chargeInfoList	array	是	费用明细列表
changeFlag	int	否	是否有特惠一口价费用变更 ， 1是 0 否
changeDesc	string	否	描述费用变更信息给客户展示,内容产品侧沟通确定

chargeInfoList 元素数据结构。说明：其中mile,time,feeDescShow 应有一个有值。

参数名称	类型	必须	说明
feeName	string	是	费用名称，英文名，例：start_fee
feeDesc	string	是	费用描述，格式：费用名称(基本信息) 例：里程费(含6.11公里)，时长费(含22.4分钟)，节假日司机费用。用户可见。
amount	int	是	金额。用户可见。若为 0 则用户不可见。
unit	string	是	费用单位，例：元
op	int	是	费用增减描述：1､收款；-1､减免；
children	array	否	费用子项

children 元素数据结构

参数名称	类型	必须	说明
feeName	string	是	费用名称，英文名，例：start_fee
feeDesc	string	是	费用描述，格式：费用名称(基本信息) 例：里程费(含6.11公里)，时长费(含22.4分钟)，节假日司机费用。用户可见。
amount	int	是	金额。用户可见。若为 0 则用户不可见。
unit	string	是	费用单位，例：元

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "settleAmount": 1741,
        "totalAmount": 1741,
        "discountAmount": 0,
        "couponId": "123abc",
        "changeFlag": 1,
        "changeDesc": "eg:实际里程与预估里程相差较大，已重新计算一口价",
        "chargeInfoList": [
         {
                "amount": 30,
                "unit": "元",
                "feeName": "start_fee",
                "feeDesc": "起步价(共0公里)",
              	"children": [{
                  "amount": 0,
                  "unit": "元",
                  "feeName": "start_fee",
                  "feeDesc": "含时长 7 分钟，含里程 2.5 公里"
                }],
                "op": 1
            },
            {
                "amount": 44,
                "unit": "元",
                "feeName": "time_fee",
                "feeDesc": "时长费(共3分钟,封顶30元)",
                "op": 1
            },
            {
                "amount": 10,
                "unit": "元",
                "feeName": "dynamic_fee",
                "feeDesc": "固定调价(10元)",
                "op": 1
            },
            {
                "amount": -10,
                "unit": "元",
                "feeName": "coupon_fee",
                "feeDesc": "代驾券抵扣",
                "op": -1
            }

        ]
    }
}

2.9 查询取消费

接口说明

• 在腾讯侧用户发起取消之前调用
• 本接口用于查询用户取消订单时产生的总费用，并不会真正取消订单

请求地址

• /dd/open/v1/charge/cancellation

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "spOrderId": "6a6b8239b4ee66"
}

响应数据

参数名称	类型	必须	说明
waitTime	int	是	等待时间，单位：秒
totalCost	int	是	用户需支付的取消总费用，单位：分
cancelFee	int	是	取消费用，单位：分
waitFee	int	是	等待费用，单位：分

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "waitTime": 240,
        "totalCost": 1300,
        "cancelFee": 700,
        "waitFee": 600
    }
}

2.10 取消订单

接口说明

• 本接口用于行程开始前，用户或系统取消订单

请求地址

• /dd/open/v1/order/cancel

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号
cancelSource	int	否	取消来源，1是用户，3是系统

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "spOrderId": "6a6b8239b4ee66",
    "cancelSource": 3
}

响应数据

参数名称	类型	必须	说明
waitTime	int	是	等待时间，单位：秒
waitFee	int	是	等待费用，单位：分
cancelFee	int	是	取消费用，单位：分
totalCost	int	是	用户需支付的取消总费用，单位：分

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "waitTime": 240,
        "totalCost": 1300,
        "cancelFee": 700,
        "waitFee": 600
    }
}

2.11 支付通知

接口说明

• 本接口用于用户完成线上支付后，通知服务商支付结果

请求地址

• /dd/open/v1/pay/notify

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号
totalAmount	int	是	应付总金额
payAmount	int	是	客户实付金额
discountAmount	int	否	优惠金额
wxTradeNo	string	是	微信交易流水号
couponUseStatus	int	否	订单用券状态，0未用券 1用券
couponFrom	int	否	券来源，0是服务商自制券，1是腾讯商家券
couponId	string	否	优惠券ID
stockId	string	否	优惠券批次ID

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "spOrderId": "6a6b8239b4ee66",
    "payAmount": 1741,
    "totalAmount": 1741,
    "discountAmount": 0,
    "couponUseStatus": 1,
    "couponFrom": 1,
    "couponId": "xxxxas",
    "stockId": "MC-xsdsds"
}

响应数据

响应示例

{
    "code": 0,
    "message": "成功"
}

2.12 修改目的地费用预估

接口说明

• 本接口仅限于接单后至完单前的订单（301、401、501），用于预估用户修改目的地的费用预估

请求地址

• /dd/open/v1/charge/estimate/modify

请求参数

参数名称	类型	必填	说明
spOrderId	string	是	服务商订单号
destinationInfo	object	是	终点位置信息

destinationInfo 数据结构

参数名称	类型	必填	说明
latitude	double	是	纬度
longitude	double	是	经度
address	string	是	地址
name	string	否	名称

请求示例

{
    "spOrderId": "973874669",
  	"destinationInfo": {
        "latitude": 22.609581,
        "longitude": 114.029224,
        "name": "深圳北站",
        "address": "广东省深圳市龙华区民治街道致远中路28号"
    }
}

响应数据

参数名称	类型	必填	说明
spOrderId	string	是	服务商订单号
totalAmount	int	是	费用总金额（单位：分）
discountAmount	int	是	优惠金额（单位：分）
distance	int	是	当前位置到目的地的预估距离（单位：米）
duration	int	是	当前位置到目的地的预估时间（单位：分钟）

响应示例

{
  "code": 0,
  "message": "成功"
   "data": {
        "spOrderId": "973874669",
        "totalAmount": 15400,
        "discountAmount": 0,
        "distance": 1000,
        "duration": 22
   }
}

2.13 修改目的地

接口说明

• 本接口仅限于接单后至完单前的订单（301、401、501），用于用户确认修改订单目的地

请求地址

• /dd/open/v1/order/modify/destination

请求参数

参数名称	类型	必填	说明
spOrderId	string	是	服务商订单号
destinationInfo	object	是	终点位置信息

destinationInfo 数据结构

参数名称	类型	必填	说明
latitude	double	是	纬度
longitude	double	是	经度
address	string	是	地址
name	string	否	名称

请求示例

{
    "spOrderId": "973874669",
  	"destinationInfo": {
        "latitude": 22.609581,
        "longitude": 114.029224,
        "name": "深圳北站",
        "address": "广东省深圳市龙华区民治街道致远中路28号"
    }
}

响应数据

响应示例

{
    "code": 0,
    "message": "成功"
}

2.14 退款结果通知(开发中)

接口说明

• 本接口用于通知服务商订单退款结果，服务商需先调用 3.8接口 申请退款

请求地址

• /dd/open/v1/refund/notify

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号
refundFee	int	否	退款金额，单位：分
refundSucTime	int	否	退款成功时间，单位：秒
refundState	int	是	退款状态 2：退款失败 3：退款成功

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "spOrderId": "6a6b8239b4ee66",
    "refundFee": 1700,
    "refundSucTime": 1741921213,
    "refundState": 3
}

响应数据

响应示例

{
    "code": 0,
    "message": "成功"
}

2.15 行程结束订单路径

接口说明

• 本接口用于行程结束后(601)，查询订单实际行驶路径

请求地址

• /dd/open/v1/driver/route

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号
startTime	long	是	开始时间，单位：秒
endTime	long	是	结束时间，单位：秒

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "spOrderId": "6a6b8239b4ee66",
    "startTime": 1718696179,
    "endTime": 1718696479
}

响应数据

参数名称	类型	必须	说明
route	array	是	行驶轨迹

route 元素数据结构

参数名称	类型	必须	说明
time	long	是	时间戳，单位：秒
latitude	double	是	维度
longitude	double	是	经度
angle	double	否	方向角

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "route":[
            {
                "time": 1718696279,
                "latitude": 34.57352484408,
                "longitude": 119.1521658936
            },
        ]
    }
}

2.16 固定码绑劵

接口说明

• 本接口用于固定码绑券

请求地址

• /dd/open/v1/coupon/bind

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
bonusSn	string	是	批次号

请求示例

{
    "userPhone": "13812345678",
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "bonusSn": "154321"
}

响应数据

参数名称	类型	必须	说明
couponId	string	是	优惠券ID

响应示例

{
    "code":0,
    "message": "成功",
    "data": {
        "couponId": "123"
    }
}

2.17 查询优惠券列表

接口说明

• 查询用户优惠券列表

请求地址

• /dd/open/v1/coupon/list

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
state	int	是	优惠券状态：1：当前可使用 2：已使用 3：过期 4：全部（默认）

请求示例

{
    "userPhone": "13812345678",
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "state": 1
}

响应数据

参数名称	类型	必须	说明
couponInfoList	List	是	优惠券列表

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
    "couponInfoList": [{
            "couponId": "12432",
            "couponName": "xx优惠券",
            "couponDesc": "仅xx可用",
            "couponType": 1,
            "fixedNormalCoupon": {
                "couponAmount": 500,
                "transactionMinimum": 1
            },
            "receiveTime": ,
            "availableBeginTime": ,
            "availableEndTime": ,
            "state": 1
        }]
    }
}

2.18 查询优惠券详情

接口说明

• 查询优惠券详情

请求地址

• /dd/open/v1/coupon/detail

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
couponId	string	是	优惠券ID

请求示例

{
    "couponId": "15800000000",
    "userPhone":"1888888888",
    "userCode":"12345"
}

响应数据

参数名称	类型	必须	说明
couponInfo	object	是	优惠券信息

couponInfo对象数据

字段名	类型	必选	说明
couponId	String	是	优惠券id
couponName	String	是	优惠券名称
couponDesc	String	是	券描述
couponType	int	是	1 :满减券 2:折扣券
fixedNormalCoupon	object	否	满减券信息
discountCoupon	object	否	折扣券信息
receiveTime	long	是	优惠券领取时间，单位：秒
availableBeginTime	long	是	可用开始时间，单位：秒
availableEndTime	long	是	可用结束时间，单位：秒
state	int	是	优惠券状态：1：当前可使用 2：已使用 3：过期 4：全部（默认）

fixedNormalCoupon数据

字段名	类型	必选	说明
couponAmount	Integer	是	优惠券金额（单位：分）
transactionMinimum	Integer	是	优惠券使用门槛，最小值：1（单位：分）

discountCoupon数据

字段名	类型	必选	说明
amountMax	Integer	是	券最高可折扣金额(单位：分)
percent	Integer	是	折扣百分比，例如88-八八折

响应示例

{
    "code":0,
    "message": "成功",
    "data": {
        "couponInfo": {
            "couponId": "12432",
            "couponName": "xx优惠券",
            "couponDesc": "仅xx可用",
            "couponType": 1,
            "fixedNormalCoupon": {
                "couponAmount": 500,
                "transactionMinimum": 1
            },
            "receiveTime": ,
            "availableBeginTime": ,
            "availableEndTime": ,
            "state": 1
        }
    }
}

3. 被调接口

• 调用方：代驾服务商
• 被调方：腾讯出行

3.1 订单状态回调

接口说明

• 本接口用于通知腾讯出行平台代驾订单状态变更

请求地址

• /dd/gateway/v1/callback/std/order/status

请求参数

参数名称	类型	必选	说明
userCode	string	是	用户标识
spId	int	是	服务商ID(普通与特惠不同)
spOrderId	string	是	服务商订单号
orderId	string	是	腾讯侧订单号
timestamp	long	是	订单状态变更时间，单位：秒
orderStatus	int	是	订单状态（参考 4.2订单状态模型 定义）
hasWaitFee	boolean	否	当orderStatus=920时，该字段有效。表示司机取消时是否产生等候费，false、未产生 true、产生
mile	int	否	行驶里程数，单位：米，当行程结束后，orderStatus>=601，该字段有效
waitTime	int	否	用户总等待时间，单位：秒，当行程结束后，orderStatus>=601时，该字段有效，（行程回顾数据）
isFixedPrice	int	否	是否一口价：0､否；1､是；
changeFlag	int	否	是否有特惠一口价费用变更 ， 1是 0 否 701报单回调传
changeDesc	string	否	描述费用变更信息给客户展示(内容产品侧沟通确认) 701报单回调传

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "spId": 1000,
    "spOrderId": "6a6b8239b4ee66",
    "orderId": "6949013848087461896",
    "timestamp": 1617953971,
    "orderStatus": 501,
    "hasWaitFee": false,
    "isFixedPrice": 1,
    "changeFlag": 1,
    "changeDesc": "eg:实际里程与预估里程相差较大，已重新计算一口价"
}

响应数据

响应示例

{
    "code": 0,
    "message": "成功"
}

3.2 支付完成通知

接口说明

• 本接口用于用户在服务商渠道完成支付后，通知腾讯出行平台代驾订单支付完成；
• 注意：在腾讯侧线上支付的订单，由腾讯通知服务商，服务商收到支付结果后，不需要再回调此接口给腾讯；

请求地址

• /dd/gateway/v1/callback/std/pay/result

请求参数

参数名称	类型	必选	说明
userCode	string	是	用户标识
spId	int	是	服务商ID(普通与特惠不同)
spOrderId	string	是	服务商订单号
orderId	string	是	腾讯侧订单号
timestamp	long	是	支付时间，单位：秒
paidAmount	int	是	实付金额，单位：分
totalAmount	int	是	总金额，单位：分

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "spId": 1000,
    "spOrderId": "6a6b8239b4ee66",
    "orderId": "6949013848087461896",
    "timestamp": 1617953971,
    "paidAmount": 1741,
    "totalAmount": 1741
}

响应数据

响应示例

{
    "code": 0,
    "message": "成功"
}

3.3 关闭支付通知

接口说明

• 本接口用于服务商关闭订单支付，关闭后，用户不需要再支付订单，订单流转到999状态，价格为0；
• 注意：只有在订单待支付即701状态时，服务商才可以回调此接口，其他状态不会生效；

请求地址

• /dd/gateway/v1/callback/std/pay/close

请求参数

参数名称	类型	必选	说明
spId	int	是	服务商ID(普通与特惠不同)
spOrderId	string	是	服务商订单号
orderId	string	是	腾讯侧订单号

请求示例

{
    "spId": 10,
    "spOrderId": "6a6b8239b4ee66",
    "orderId": "6949013848087461896"
}

响应数据

响应示例

{
    "code": 0,
    "message": "成功"
}

3.4 订单改价通知

接口说明

• 本接口用于待用户支付时，通知腾讯出行平台代驾订单价格发生改动;
• 注意：调用该接口前需确保2.8接口可返回调价后的费用，否则不生效;

请求地址

• /dd/gateway/v1/callback/std/charge/adjustment

请求参数

参数名称	类型	必选	说明
userCode	string	是	用户标识
spId	int	是	服务商ID(普通与特惠不同)
spOrderId	string	是	服务商订单号
orderId	string	是	腾讯侧订单号
timestamp	long	是	改价时间，单位：秒
paidAmount	int	是	实付金额，单位：分
totalAmount	int	是	总金额，单位：分

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "spId": 1000,
    "spOrderId": "6a6b8239b4ee66",
    "orderId": "6949013848087461896",
    "timestamp": 1617953971,
    "paidAmount": 1741,
    "totalAmount": 1741
}

响应数据

响应示例

{
    "code": 0,
    "message": "成功"
}

3.5 车辆详情回调

接口说明

• 本接口用于行程完结后，通知腾讯出行平台代驾车主车辆信息

请求地址

• /dd/gateway/v1/callback/std/car/detail

请求参数

参数名称	类型	必选	说明
userCode	string	是	用户标识
spId	int	是	服务商ID(普通与特惠不同)
spOrderId	string	是	服务商订单号
orderId	string	是	腾讯侧订单号
userGender	int	是	车主性别：0、未知；1、男；2、女；
plateName	string	是	车牌号，例：粤B123456
brandName	string	是	车品牌，例：奥迪-奥迪A3
gear	int	是	挡位：0、未知；1、手动；2、自动；
mileAccurate	int	是	里程是否准确：0､不准确；1､准确；

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "spId": 1000,
    "spOrderId": "6a6b8239b4ee66",
    "orderId": "6949013848087461896",
    "userGender": 1,
    "brandName": "奥迪-奥迪A3",
    "plateName": "粤B123456",
    "gear": 2,
    "mileAccurate": 1
}

响应数据

响应示例

{
    "code": 0,
    "message": "成功"
}

3.6 改派司机通知

接口说明

• 本接口用于通知腾讯出行平台代驾司机变更，腾讯收到该通知后，会请求2.5中订单详情的接口，更新代驾司机

请求地址

• /dd/gateway/v1/callback/std/order/reAssignDriver

请求参数

参数名称	类型	必选	说明
userCode	string	是	用户标识
spId	int	是	服务商ID(普通与特惠不同)
spOrderId	string	是	服务商订单号
orderId	string	是	腾讯侧订单号

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "spId": 1000,
    "spOrderId": "6a6b8239b4ee66",
    "orderId": "6949013848087461896"
}

响应数据

响应示例

{
    "code": 0,
    "message": "成功"
}

3.7 查询订单在腾讯侧的状态

接口说明

• 本接口用于服务商查询订单在腾讯侧的状态，以及支付详情

请求地址

• /dd/gateway/v1/callback/std/order/queryDetail

请求参数

参数名称	类型	必选	说明
userCode	string	是	用户标识
spId	int	是	服务商ID(普通与特惠不同)
spOrderId	string	是	服务商订单号
orderId	string	是	腾讯侧订单号

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "spId": 12,
    "spOrderId": "6a6b8239b4ee66",
    "orderId": "6949013848087461896"
}

响应数据

参数名称	类型	必须	说明
orderState	int	是	订单状态，参考附录4.2
payStatus	int	否	支付状态， 当orderState=701时，此值为0，当orderState=999时，此值为3（腾讯侧支付）或5（服务商线下支付）
payDetail	object	否	当payStatus=3时，此值非空

其中payDetail实体数据结构为：

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
spOrderId	string	是	服务商订单号
totalAmount	int	是	应付总金额
payAmount	int	是	客户实付金额
discountAmount	int	否	优惠金额
wxTradeNo	string	是	微信交易流水号
couponUseStatus	int	否	订单用券状态，0未用券 1用券
couponFrom	int	否	券来源，0是服务商自制券，1是腾讯商家券
couponId	string	否	优惠券ID
stockId	string	否	优惠券批次ID

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "orderState": 999,
        "payStatus": 3,
        "payDetail": {
            "userCode": "a0c1b41b7e425574e0416d0777c5f533",
            "userPhone": "15800000000",
            "spOrderId": "6a6b8239b4ee66",
            "payAmount": 1741,
            "totalAmount": 1741,
            "discountAmount": 0,
            "couponUseStatus": 1,
            "couponFrom": 1,
            "couponId": "xxxxas",
            "stockId": "MC-xsdsds"
        }
    }
}

3.8 申请退款(开发中)

接口说明

• 本接口用于服务商申请订单退款，仅订单支付完成后有效

请求地址

• /dd/gateway/v1/callback/std/order/applyRefund

请求参数

参数名称	类型	必选	说明
userCode	string	是	用户标识
spId	int	是	服务商ID(普通与特惠不同)
spOrderId	string	是	服务商订单号
orderId	string	是	腾讯侧订单号
refundReason	string	否	退款原因，不超过 50个字符
refundFee	int	是	待退款金额，单位（分）需大于 0,小于订单已支付金额

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "spId": 12,
    "spOrderId": "6a6b8239b4ee66",
    "orderId": "6949013848087461896",
    "refundReason": "重复支付",
    "waitRefundFee": 10
}

响应数据

响应示例

{
    "code": 0,
    "message": "成功",
    "data": null
}

3.9 优惠券状态回调

接口说明

• 本接口用于优惠券核销时状态回调

请求地址

• /dd/gateway/v1/callback/std/coupon/status

请求参数

参数名称	类型	必选	说明
userPhone	string	是	用户手机号
bonusSn	string	是	批次号
couponId	string	是	优惠券ID
orderId	string	是	腾讯侧订单号
eventTime	long	是	核销时间（秒时间戳）
couponStatus	int	是	状态，核销固定传2

请求示例

{
    "userPhone": "13812345678",
    "bonusSn": "154321",
    "couponId": "548037991763",
    "eventTime": 1699441730,
    "orderId": "973497172",
    "couponStatus" : 2
}

响应数据

响应示例

{
    "code":0,
    "message": "成功"
}

4. 附录

4.1 状态码

状态码	描述
0	成功
120001	服务内部错误
120010	当前城市未开城
120052	暂不支持改价
130003	无效的订单ID
130007	有未支付的订单
130009	有进行中的订单
130016	订单状态无效
200003	请求参数错误
200006	签名信息缺失
200007	签名信息无效
200009	签名随机数重复
200019	签名时间戳无效
200036	附近无空闲司机
200037	用户下单受限
200038	司机状态不匹配
200039	订单进行中，不能取消订单

4.2 订单状态模型

订单状态码

状态码	描述	说明
201	订单调度中
301	司机已接单	需服务商回调
401	司机已到达	需服务商回调
501	行程已开始	需服务商回调
601	行程已结束（待结算）	需服务商回调
701	司机已报单（待支付）	需服务商回调
905	取消费待支付（乘客取消订单产生待支付取消费）
910	乘客取消订单（未产生取消费或已支付取消费）
915	等候费待支付（司机取消订单产生待支付等候费）
920	司机取消订单	需服务商回调
950	派单失败（无服务商接单或下单失败）
999	订单完成（已支付）

订单状态机