码上驾到

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

主调环境

• 由代驾saas服务商提供给腾讯

2. 主调接口

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

2.1 周边空闲司机

接口说明

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

请求地址

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

请求参数

参数名称	类型	必填	说明
userPhone	string	否	用户手机号
latitude	double	是	纬度
longitude	double	是	经度

请求示例

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

响应数据

参数名称	类型	必须	说明
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 订单费用预估

接口说明

• 本接口用于Saas服务商预估代驾订单费用，可以返回多个代驾公司的预估记录

请求地址

• /dd/open/v2/charge/estimate

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	用户手机号
originInfo	object	是	出发地信息
destinationInfo	object	是	目的地信息
distance	long	是	预估里程，单位：米
duration	long	是	预估时间，单位：秒
cityId	string	否	出发地城市编码
saasCode	string	否	码信息
orderSourceType	int	是	下单类型，0普通线上下单，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",
    "saasCode": "xzx3sas*MP",
    "orderSourceType": 2
}

响应数据

参数名称	类型	必须	说明
serviceProvider	string	是	代驾公司名
serviceProviderLogoUrl	string	是	代驾公司logo的url
serviceProviderSlogan	string	是	代驾公司slogan
serviceProviderCompanyId	string	是	代驾公司id
serviceProviderPhone	string	是	代驾公司客服电话
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，单位：分

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "list": [
            {
                "serviceProvider": "xx代驾",
                "serviceProviderLogoUrl": "https://xx.com/xxx",
                "serviceProviderSlogan": "xx代驾，优惠到家",
                "serviceProviderCompanyId": "x11aas00",
                "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": 1
            },
            {
                "serviceProvider": "yy代驾",
                "serviceProviderLogoUrl": "https://xx.com/xxx",
                "serviceProviderSlogan": "yy代驾，优惠到家",
                "serviceProviderCompanyId": "yyihaas79",
                "estimateId": "x31795221",
                "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": 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:乘车人支付，代叫单时有效
cityId	string	否	出发地城市编码
bonusSn	string	否	优惠券码
isFixedPrice	int	否	是否一口价：0、否；1､是；
saasCode	string	否	saas服务商扫码信息
orderSourceType	int	否	下单类型，0普通线上下单，1司机码下单，2门店码下单
newTravelUser	int	否	是否是服务商带来的腾讯新用户
serviceProviderCompanyId	string	否	代驾公司id
channelInfo	object	否	下单渠道信息，主要用于渠道区分，以及分渠道催缴短信下发

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	是	查看订单指引文案, 如: 微信搜“腾讯出行服务”小程序，点右下角“我的-订单”，或进入代驾首页—行程订单

请求示例

{
    "estimateId": "161795221",
    "orderId": "6949013848087461896",
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "userPhone": "15800000000",
    "contactPhone": "15800000000",
    "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",
    "saasCode": "xzx3sas*MP",
    "orderSourceType": 2,
    "newTravelUser": 0,
    "serviceProviderCompanyId": "aaasa12"
}

响应数据

参数名称	类型	必须	说明
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订单状态模型 定义）
driverInfo	object	否	司机信息
serviceProvider	string	是	接单代驾公司名
serviceProviderLogoUrl	string	是	接单代驾公司logo的url
serviceProviderSlogan	string	是	接单代驾公司slogan
serviceProviderCompanyId	string	是	接单代驾公司id
serviceProviderPhone	string	是	接单代驾公司客服电话
orderSourceType	int	是	订单类型

driverInfo 数据结构

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

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "orderStatus": 401,
        "serviceProvider": "xx代驾",
        "serviceProviderLogoUrl": "https://xx.com/xxx",
        "serviceProviderCompanyId": "1qweras"
        "serviceProviderSlogan": "xx代驾，老司机的选择",
        "serviceProviderPhone": "400xxx",
        "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	是	费用明细列表

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

参数名称	类型	必须	说明
feeName	string	是	费用名称（英文），例如: wait_fee,start_fee
feeNameShow	string	是	费用名称（中文，用户可见），例如:等候费,时长费。注意数据信息分开传，不要传类似时长费(共3分钟,封顶30元)
feeDesc	string	否	费用描述,（用户可见）,例如: 春节调整
amount	int	是	金额（用户可见）
unit	string	是	费用单位，例：元
op	int	是	费用增减描述：1､收款；-1､减免；
feeCap	int	否	费用封顶（用户可见），单位：分，例如: 3000
mile	int	否	费用路程信息（用户可见），单位：米，例如: 1000
time	int	否	费用时长信息（用户可见），单位：秒，例如: 180

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "settleAmount": 1741,
        "totalAmount": 1741,
        "discountAmount": 0,
        "couponId": "adddd",
        "chargeInfoList": [
            {
                "amount": 30,
                "unit": "元",
                "feeName": "start_fee",
                "feeDesc": "",
                "op": 1,
                "feeNameShow": "起步价",
                "feeCap": 2000,
                "mile": 1000,
                "time": 0
            },
            {
                "amount": 44,
                "unit": "元",
                "feeName": "time_fee",
                "feeDesc": "",
                "op": 1,
                "feeNameShow": "时长费",
                "feeCap": 10000,
                "mile": 0,
                "time": 3600
            },
            {
                "amount": 10,
                "unit": "元",
                "feeName": "dynamic_fee",
                "feeDesc": " 晚高峰间，临时调价",
                "op": 1,
                "feeNameShow": "固定调价",
                "feeCap": 10000,
                "mile": 0,
                "time": 0
            }
        ]
    }
}

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 司机评分

接口说明

• 用户完成订单后，对司机的评价通知服务商

请求地址

• /dd/open/v1/driver/score

请求参数

参数名称	类型	必填	说明
userCode	string	是	用户标识
userPhone	string	是	手机号
spOrderId	string	是	服务商订单号
score	int	是	评分，1星对应1分，最大5分
labelInfo	string	否	司机标签，逗号分隔，老司机,驾驶技术好

响应示例

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

2.13 获取扫码运力信息

接口说明

• 本接口用于获取Saas服务商具体运力名称、h5资质链接以及具体司机信息

请求地址

• /dd/open/v1/ride/info

请求参数

参数名称	类型	必填	说明
saasCode	string	是	码信息
orderSourceType	int	否	下单类型，0普通线上下单，1司机码下单，2门店码下单

响应数据

参数名称	类型	必填	说明
rideName	string	是	运力名
serviceProviderCompanyId	string	是	代驾公司id
rideAptitudeUrl	string	否	资质链接
servicePhone	string	否	运力电话
driverInfo	object	否	司机信息

其中driverInfo的数据格式为：

参数名称	类型	必填	说明
driverId	string	是	司机ID
driverPhone	string	是	司机手机号
driverName	string	是	司机名称
pictureUrl	string	是	司机头像地址
orderNumber	int	是	司机服务单数
newLevel	int	是	司机星级
year	int	是	司机驾龄
labels	string	是	司机评价标签，以逗号分割，例:已打疫苗,礼貌道别,服务 热情

2.14 一键下单接口

接口说明

• 本接口用于扫司机码之后，向服务商一键下单

请求地址

• /dd/open/v1/order/fastCreate

请求参数

参数名称	类型	必填	说明
fastCreateOrderId	string	是	快速订单ID，腾讯和服务商均可以此为唯一id
userCode	string	是	用户标识
userPhone	string	是	用户手机号
originInfo	object	是	出发地信息
publishInfo	object	否	发单地信息
cityId	string	否	出发地城市编码
saasCode	string	否	saas服务商扫码信息
orderSourceType	int	否	下单类型，0普通线上下单，1司机码下单，2门店码下单
serviceProviderCompanyId	string	否	代驾公司id

originInfo、publishInfo数据结构：

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

响应示例

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

2.15 查询一键下单预估详情

接口说明

• 本接口用于一键下单后，向服务商查询预估详情

请求地址

• /dd/open/v1/order/queryFastCreateEstimate

请求参数

参数名称	类型	必填	说明
fastCreateOrderId	string	是	快速订单ID，腾讯和服务商均可以此为唯一id
userCode	string	是	用户标识
userPhone	string	是	用户手机号
estimateId	string	是	预估id

响应参数

参数名称	类型	必须	说明
serviceProvider	string	是	代驾公司名
serviceProviderLogoUrl	string	是	代驾公司logo的url
serviceProviderSlogan	string	是	代驾公司slogan
serviceProviderCompanyId	string	是	代驾公司id
serviceProviderPhone	string	是	代驾公司客服电话
fastCreateOrderId	string	是	快速订单ID，腾讯和服务商均可以此为唯一id
estimateId	string	是	预估ID，关联当次预估信息
estimateAmount	int	是	预估金额（优惠后金额），单位：分
totalAmount	int	是	预估总额，单位：分
discountAmount	int	否	优惠金额，单位：分
feeDetailList	array	是	预估费用明细
originInfo	object	是	出发地信息
destinationInfo	object	是	目的地信息

originInfo、destinationInfo 数据结构

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

2.16 一键下单修改预估目的地

接口说明

• 本接口用于客户看到一键下单的预估结果后，请求修改目的地

请求地址

• /dd/open/v1/order/modifyFastCreate

请求参数

参数名称	类型	必填	说明
estimateId	string	是	预估ID
fastCreateOrderId	string	是	一键下单ID，腾讯和服务商均可以此为唯一id
userCode	string	是	用户标识
userPhone	string	是	用户手机号

响应示例

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

2.17 一键下单确认下单

接口说明

• 本接口用于客户看到一键下单的预估结果后，确认下单

请求地址

• /dd/open/v1/order/confirmFastCreate

请求参数

参数名称	类型	必填	说明
estimateId	string	是	预估ID
orderId	string	是	腾讯侧订单号
fastCreateOrderId	string	是	一键下单ID，腾讯和服务商均可以此为唯一id
userCode	string	是	用户标识
userPhone	string	是	用户手机号

响应数据

参数名称	类型	必须	说明
spOrderId	String	是	服务商订单号
timeout	int	否	派单超时时间

响应示例

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

2.18 取消一键下单

接口说明

• 本接口用于客户取消一键下单，在预估产生之前和产生之后，都会取消

请求地址

• /dd/open/v1/order/cancelFastCreate

请求参数

参数名称	类型	必填	说明
fastCreateOrderId	string	是	快速订单ID，腾讯和服务商均可以此为唯一id
userCode	string	是	用户标识
userPhone	string	是	用户手机号

响应示例

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

3. 被调接口

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

3.1 订单状态回调

接口说明

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

请求地址

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

请求参数

参数名称	类型	必选	说明
userCode	string	是	用户标识
spId	int	是	服务商ID
spOrderId	string	是	服务商订单号
orderId	string	是	腾讯侧订单号
timestamp	long	是	订单状态变更时间，单位：秒
orderStatus	int	是	订单状态（参考 订单状态模型 定义）
hasWaitFee	boolean	否	当orderStatus=920时，该字段有效。表示司机取消时是否产生等候费，false、未产生 true、产生
mile	int	否	行驶里程数，单位：米，当行程结束后，orderStatus>=601，该字段有效
waitTime	int	否	用户总等待时间，单位：秒，当行程结束后，orderStatus>=601时，该字段有效，（行程回顾数据）

请求示例

{
    "userCode": "a0c1b41b7e425574e0416d0777c5f533",
    "spId": 1000,
    "spOrderId": "6a6b8239b4ee66",
    "orderId": "6949013848087461896",
    "timestamp": 1617953971,
    "orderStatus": 501,
    "hasWaitFee": false
}

响应数据

响应示例

{
    "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 改派司机通知

接口说明

• 本接口用于通知腾讯出行平台代驾司机变更，腾讯收到该通知后，会请求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.6 查询订单在腾讯侧的状态

接口说明

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

请求地址

• /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.7 回调一键下单预估结果

接口说明

• 本接口用于Saas服务商的司机输入目的地后，再回调预估价格id

请求地址

• /dd/gateway/v1/callback/std/fastCreateEstimateResult

请求参数

参数名称	类型	必填	说明
spId	int	是	服务商ID
fastCreateOrderId	string	是	快速订单ID，腾讯和服务商均可以此为唯一id
estimateId	string	是	saas服务商生成的预估id

响应示例

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

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	订单完成（已支付）

订单状态机