顺风车

1. 版本历史

版本	日期	修订人	修改内容	审核人
V0.1	2023.07.25		初稿
V0.2	2023.12.27		主调接口更新

2. 基础说明

2.1 接口协议

除非特殊指定，默认请求方式均为 HTTPS/POST 方式。

2.2 返回数据格式

除非特殊指定，默认返回数据格式均为 JSON 格式。

2.3 字符编码

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

2.4 请求格式

接口内如果没有特殊说明的，请求格式一律统一为 application/json 。

2.5 重试机制

调⽤出行服务接口时，返回码 Code 不成功，要有重试机制（具体见错误码表）。

2.6 通用参数

字段名	字段类型	最大长度	必填	说明
accessKey	String	32	是	腾讯出行服务分配给服务商调用的 accessKey
seqId	String	36	是	请求流水号,调用方自动生成一个随机 ID，建议使用 uuid
timestamp	Long	20	是	请求发送时的时间戳(unix 时间戳) 毫秒
nonce	String	10	是	10 位随机字符串
sign	String	32	是	验证签名参数

2.7 通用返回值

字段名	字段类型	最大长度	必填	说明
code	Integer	11	是	服务响应状态，参见错误码表
message	String	64	是	服务响应状态说明，参见错误码表
data	Object	-	否	具体的接口对应不同的对象详见具体的接口

2.8 鉴权说明

步骤 1 从请求串中获得 accessKey、seqId、timestamp, nonce 通用字段以及其他的业务段和鉴权结果字段 sign。

步骤 2 根据签名算法，对参与签名的内容进行签名； 按照除 sign 外参数名称排序(字典升序排列)成”key1=value1&key2=value2&....”的原始字符串 src1；参数值为 null 不参与签名。 将原始字符串+分配给调用方的 apiSercret 形成字符串 src2； 将 src2 进行 md5 后转成大写形成签名内容 dest

步骤 3 将步骤 2 中得到的签名内容 dest 与请求中的 sign 字段内容做比较，如果相同则验证成功，否则判定请求非法。

举例： 假设/order/status 接口文档中业务字段为[slon, slat]，分配的 apiSercret=DZaslH9B9ycqRrE77laCPB2Om， 请求参数如下: accessKey=PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y, seqId=b8b4f0b8-01fb-4c06-80b9-3ab895a8c616, timestamp=1554695343, slat=39.998299, slon=116.285561 则需要签名的内容: accessKey=PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y&seqId=b8b4f0b8-01fb-4c06-80b9-3ab895a8c616&slat=39.998299&slon=116.285561&timestamp=1554695343&apiSercret=DZaslH9B9ycqRrE77laCPB2Om

步骤 4 计算的 MD5 值为 8a983278e5366eb93feb0d4143e1c522，大写值为 8A983278E5366EB93FEB0D4143E1C522。

步骤 5 将步骤 4 中得到的 MD5 值，与请求中 sign 字段的值比较。两者相同请求合法。

2.9 注意事项

1、需要签名的字段与请求串中字段先后顺序没有关系，只与进行签名的内容有关，必须按照文档中的顺序拼接。
2、apiSercret 内容为双方保密内容，不在请求中传输，严禁公开。
3、通用字段 accessKey，seqId，timestamp，nonce 参与所有接口的签名。
4、字段值是 JSON 类型的，把字段值 json 串参与签名, 不用拆分里面字段。

2.10 服务环境

服务正式环境 https://sp.wecar.map.qq.com/hitchride/

服务测试环境 https://test.tai.qq.com/hitchride/

2.11 数据加密

在双方进行HTTP接口交互时，为保证数据安全，须对请求参数和响应数据中的敏感数据（如手机号）加密传输，接收数据后解密使用。双方联调时提供具体加密策略。

2.12 坐标系

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

2.13 城市编码

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

• 参见中华人民共和国民政部链接 (opens new window)
• 或 参见腾讯位置服务链接 (opens new window)

2.14 单位

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

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

2.15 重试机制

调⽤出行服务接口时，返回码 Code 不成功，要有重试机制（具体见错误码表）。

2.16 接口分类

• 接口分为主调接口、被调接口、数据解密接口。
• 主调接口（调用方：腾讯出行，被调方：各服务商，如哈啰、嘀嗒、同程、拇指、T3），主调接口由服务商实现。
• 被调接口（调用方：各服务商，如哈啰、嘀嗒、同程、拇指、T3，被调方：腾讯出行），被调接口由腾讯实现。
• 数据解密接口（调用方：各服务商，如哈啰、嘀嗒、同程、拇指、T3，被调方：腾讯出行），数据解密接口由腾讯实现。

3. 业务接口列表

3.1 业务主调接口

说明：

1. 请求参数：腾讯侧可提供的参数
2. 返回值：服务商需要返给腾讯侧的数据

通用结构

Position

参数名	必传	类型	描述	备注
lon	Y	String	经度
lat	Y	String	纬度
shortAddr	Y	String	地点名称	如"腾讯北京总部大楼"
longAddr	Y	String	详细地址	如"北京市海淀区西北旺东路10号"
cityCode	Y	String	城市编码
cityName	Y	String	城市名称
provinceName	N	String	省份名称
countyCode	N	String	区县编码
phoneAreaCode	N	String	手机区号

DriverInfo

参数名	必传	类型	描述	备注
nickName	Y	String	司机昵称
phone	Y	String	司机手机号/虚拟号	接单后必传
gender	Y	Integer	性别	1-男 2-女
rating	N	String	司机评分	均为五分制
logoUrl	N	String	头像url
orderCounts	N	String	接单量
carPlate	Y	String	车牌号
carModel	Y	String	车型名称
carColorName	Y	String	车辆颜色名称	eg.白色,红色,黑色...carColor枚举可以不传, 优先取该字段
carColor	N	Integer	车辆颜色	Integer枚举：1-白色,2-红色,3-黑色,4-银灰色,6-蓝色,7-黄色,8-绿色,9-金色,10-棕色,5-其他（非必填，可以不传，直接传颜色中文描述）
carImage	N	String	车辆图片链接

3.1.1 查询开城列表

请求地址

• /city/list

请求参数

参数名	必传	类型	描述	备注
-	-	-	-	-

请求示例

{
  "accessKey": "11111111111111111111111111111111",
  "nonce": "oHEMA6JwRB",
  "seqId": "1715671012587876725",
  "sign": "2222222222222222222222222222222222",
  "spId": 60774,
  "timestamp": 1715671012763
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	Array	返回数据
data.openCities[]	Y	CityInfo[]	开城列表

CityInfo

参数名	必传	类型	描述
cityCode	Y	string	城市代码
cityName	Y	string	城市名称
provinceName	Y	string	省份名称
phoneAreaCode	N	string	所属市（市级）区号

响应示例

{
  "code": 0,
  "message": "成功",
  "data": [
      {
        "cityCode": "440400",
        "phoneAreaCode": null,
        "cityName": "珠海市",
        "provinceName": "广东省"
      }
  ]
}

3.1.2 询价

请求地址

• /estimate/price

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	用户标识
startPosition	Y	Position	出发点信息
endPosition	Y	Position	目的地信息
earliestDepartureTime	Y	Long	最早出发时	单位：秒
latestDepartureTime	Y	Long	最晚出发时间	单位：秒
passengerNum	Y	Integer	乘客人数
userPhone	N	String	用户手机号	加密后传输，某些场景无手机号
poolType	N	Integer	拼车类型	1-独享 2-拼车

请求示例

{
  "accessKey": "111111111111111111111111111111",
  "earliestDepartureTime": 1715736600,
  "endPosition": {
      "cityCode": "440600",
      "cityName": "",
      "countyCode": "440607",
      "lat": "23.274389",
      "lon": "112.924052",
      "longAddr": "广东省佛山市三水区X521",
      "phoneAreaCode": "0757",
      "provinceName": "",
      "shortAddr": "广东碧海蓝天环保科技有限公司-北门"
  },
  "latestDepartureTime": 1715736600,
  "nonce": "NUU7cw8Wgm",
  "passengerNum": 2,
  "poolType": 0,
  "seqId": "1715732930866897133",
  "sign": "222222222222222222222222222",
  "spId": 60774,
  "startPosition": {
      "cityCode": "440100",
      "cityName": "",
      "countyCode": "440111",
      "lat": "23.25677483976827",
      "lon": "113.25562513576975",
      "longAddr": "广东省广州市白云区虎石西街",
      "phoneAreaCode": "020",
      "provinceName": "",
      "shortAddr": "兴隆开料行"
  },
  "timestamp": 1715732928040,
  "userCode": "33333333333333333333333333333",
  "userPhone": "Auhn/oyP2+kbB8wN9kRXFA=="
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	Object	返回数据
data.multiPrice	Y	Integer	拼车未拼成价	单位：分
data.poolPrice	Y	Integer	拼车价	单位：分
data.notPoolPrice	Y	Integer	独享价	单位：分
data.distance	Y	Integer	行程规划路径	单位：米

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
      "multiPrice": 11824,
      "poolPrice": 11824,
      "notPoolPrice": 16554,
      "distance": 45830
  }
}

3.1.3 创建订单

请求地址

• /order/create

请求参数

参数名	必传	类型	描述	备注
startPosition	Y	Position	出发点信息
endPosition	Y	Position	目的地信息
earliestDepartureTime	Y	Integer	最早出发时	单位：秒
latestDepartureTime	Y	Integer	最晚出发时间	单位：秒
userCode	Y	String	用户标识
userPhone	Y	String	用户手机	加密后传输
partnerOrderId	N	String	腾讯侧订单ID
passengerCount	Y	Integer	乘客人数
poolType	Y	Integer	拼车类型	1-独享 2-拼车
bearHighwayFeeType	Y	Integer	高速费承担方式	1-愿意承担高速费 2-不愿承担高速费 3-愿意分摊高速费
orderComment	N	String	备注信息	多个备注信息以,间隔
reassignTimes	N	Integer	改派次数
couponInfoList	N	CouponInfo[]	优惠券信息

CouponInfo

参数名	必传	类型	描述	备注
couponId	Y	String	优惠券id
couponAmount	Y	Integer	优惠券金额，折扣券为计算好的折扣金额	单位：分
couponType	Y	String	优惠券类型
couponName	Y	String	优惠券名称

请求示例

{
  "accessKey": "11111111111111111111111111111",
  "bearHighwayFeeType": 2,
  "earliestDepartureTime": 1715736000,
  "endPosition": {
      "cityCode": "440600",
      "cityName": "佛山市",
      "countyCode": "440606",
      "lat": "22.831816",
      "lon": "113.259104",
      "longAddr": "广东省佛山市顺德区大良保健路3号",
      "phoneAreaCode": "0757",
      "provinceName": "",
      "shortAddr": "广东医科大学顺德妇女儿童医院妇产科楼附近"
  },
  "latestDepartureTime": 1715736900,
  "nonce": "uIcCsNg3F8",
  "orderComment": "",
  "orderPrice": 0,
  "partnerOrderId": "444444444444444444",
  "passengerCount": 1,
  "poolType": 2,
  "reassignTimes": 0,
  "seqId": "1715735041112835855",
  "sign": "2222222222222222222222222222222",
  "spId": 60774,
  "startPosition": {
      "cityCode": "440600",
      "cityName": "佛山市",
      "countyCode": "440606",
      "lat": "22.871088772496893",
      "lon": "113.08224762068926",
      "longAddr": "广东省佛山市顺德区东华路23号",
      "phoneAreaCode": "0757",
      "provinceName": "",
      "shortAddr": "保利上城-南门"
  },
  "timestamp": 1715735042163,
  "userCode": "3333333333333333333333",
  "userPhone": "Qy1yje/rPYBu0Ns58LFm7w=="
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	Object
data.orderId	Y	String	服务商订单ID
data.passengerProPayPrice	Y	Integer	下单价格
data.passengerPoolPayPrice	N	Integer	拼车价格

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
      "orderId": "965580978fc64b80845ba8e2a49d3502",
      "passengerProPayPrice": 3339,
      "passengerPoolPayPrice": null
  }
}

3.1.4 取消订单

请求地址

• /order/cancel

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	用户标识
orderId	Y	String	服务商订单 ID
userPhone	N	String	乘客手机号	加密后传输
reason	N	String	取消原因

请求示例

{
  "accessKey": "1111111111111111111111",
  "nonce": "v4JgDY45Qr",
  "orderId": "3333333333333333333",
  "reason": "系统取消",
  "seqId": "9aff9e7a-7b3d-4466-931d-3e84d47e6285",
  "sign": "222222222222222222222222222222",
  "spId": 60774,
  "timestamp": 1715735193543,
  "userCode": "df732a5f4dd20c3802097e37f3f89053",
  "userPhone": "0ygUFDNzWFg6LhhXTxHA4Q=="
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息

响应示例

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

3.1.5 查询可邀请司机列表

请求地址

• /driver/list

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	用户标识
userPhone	N	String	乘客手机号
orderId	Y	String	服务商订单 ID

请求示例

{
  "accessKey": "1111111111111111111111111",
  "nonce": "kqlFpV1yVm",
  "orderId": "333333333333333333333333",
  "seqId": "1715735275150877610",
  "sign": "2222222222222222222222222",
  "spId": 60774,
  "timestamp": 1715735274826,
  "userCode": "44444444444444444444",
  "userPhone": "pUIvhNvy92lmxPnJUE7syQ=="
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	InvitableDriver[]

InvitableDriver

参数名	必传	类型	描述	备注
orderId	Y	String	服务商订单ID
price	Y	String	订单金额	单位：分
driverInfo	Y	DriverInfo	车主信息
driverStartPosition	Y	Position	车主起点
driverEndPosition	Y	Position	车主终点
startDistance	Y	Integer	车主起点距离客户起点的距离	单位：米
endDistance	Y	Integer	车主终点距离客户终点的距离	单位：米
isInvite	Y	Boolean	是否已经邀请过
hitchPercent	Y	String	顺路度	如"0.85"
journeyLineId	N	String	车主路线ID	用于邀请车主接单，与车主订单ID二选一
driverOrderId	N	String	车主订单ID	用于邀请车主接单，与车主路线ID二选一
driverUserId	Y	String	车主ID
planDepartureTime	Y	Integer	车主计划出发时间	单位：秒
availableSeats	Y	Integer	可用座位数
poolPassengerNum	Y	Integer	已拼乘客数

响应示例

{
    "code": 0,
    "message": "成功",
    "data": [
        {
            "orderId": "333333333333333333333333",
            "price": null,
            "driverInfo": {
                "nickName": "梁师傅",
                "phone": "1234567890",
                "gender": 1,
                "rating": "0",
                "logoUrl": null,
                "orderCounts": "2",
                "carPlate": "粤A88888",
                "carModel": "埃安牌GAM7000BEVA0Q",
                "carColor": 1,
                "carImage": null,
                "carColorName": "白色"
            },
            "driverStartPosition": {
                "lon": "113.567",
                "lat": "23.197",
                "shortAddr": "广东省广州市黄埔区布岭路",
                "longAddr": "万科里享家蔚来-南门-南侧",
                "cityCode": "440100",
                "cityName": "广州市",
                "provinceName": null,
                "countyCode": null,
                "phoneAreaCode": null
            },
            "driverEndPosition": {
                "lon": "113.328",
                "lat": "23.1253",
                "shortAddr": "广东省广州市天河区",
                "longAddr": "冼村[地铁站](G口)",
                "cityCode": "440100",
                "cityName": "广州市",
                "provinceName": null,
                "countyCode": null,
                "phoneAreaCode": null
            },
            "startDistance": 9818,
            "endDistance": 410694,
            "isInvite": false,
            "hitchPercent": "0.5",
            "driverUserId": "55555555555555555",
            "planDepartureTime": 1715977020000,
            "availableSeats": 0,
            "poolPassengerNum": 4,
            "driverOrderId": "66666666666666666666"
        }
    ]
}

3.1.6 乘客邀请车主

请求地址

• /driver/invite

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	用户标识
driverUserId	Y	Integer	司机 userId
partnerOrderId	Y	String	服务商订单号
driverOrderId	Y	String	司机订单 ID	与司机路线ID二选一
journeyLineId/routeId	Y	String	司机路线 ID	与司机订单ID二选一
userPhone	N	String	用户手机号	加密后传输

请求示例

{
    "accessKey": "111111111111111111111111111",
    "driverOrderId": "3333333333333333333333333",
    "driverUserId": "444444444444444444444",
    "journeyLineId": "",
    "nonce": "2g43nVtWN0",
    "partnerOrderId": "5555555555555555555555",
    "seqId": "1715735202507831416",
    "sign": "222222222222222222222222222222",
    "spId": 60774,
    "timestamp": 1715735202561,
    "userCode": "66666666666666666",
    "userPhone": "kNKtYPar/zerZEJVEw/aOA=="
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息

响应示例

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

3.1.7 查询订单详情

请求地址

• /order/detail

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	用户标识
orderId	Y	String	订单id
userPhone	N	String	用户手机号	加密后传输

请求示例

{
  "accessKey": "1111111111111111111",
  "nonce": "yWpEvqXKO0",
  "orderId": "333333333333333333333",
  "seqId": "7493d914-9567-4139-8848-96b0b7c6b34f",
  "sign": "22222222222222222",
  "spId": 60774,
  "timestamp": 1715735593153,
  "userPhone": "kVitWEsDPN4VtRbma6vrFg=="
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	Object	详见返回数据

• 返回数据

参数名	必传	类型	描述
orderStatus	Y	Integer	订单状态
poolStatus/poolType	Y	Integer	拼单状态	1-不拼座，2-拼座中,3-未拼成,4-已拼成
acceptedTime	Y	Long	接单时间
planDepartureTime	Y	Long	计划出发时间
earliestDepartureTime	Y	Long	最早出发时间
latestDepartureTime	Y	Long	最晚出发时间
creatTime	Y	Long	订单创建时间
cancelTime	Y	Long	订单取消时间
getOnTime	Y	Long	乘客上车时间
getOffTime	Y	Long	乘客下车时间
cancelType	Y	Integer	取消类型	1：乘客，2：司机，3：系统，4：客服
cancelReason	Y	String	取消原因	具体原因
comments	Y	String	订单备注
passengerNum	Y	Integer	乘客人数
orderEstimatePrice	Y	Integer	订单价格（预估）	单位：分
orderActualPrice	Y	Integer	乘客实际支付金额	单位：分
payTime	Y	Long	支付时间
driverInfo	Y	DriverInfo	司机信息
driverOrder	Y	DriverOrder	司机订单信息
extInfo	N	String	额外信息
blameInfo	Y	BlameInfo	判责信息
distance	Y	Integer	行程距离	单位：米
discountAmount	N	Integer	优惠金额	单位：分

DriverOrder

参数名	必传	类型	描述	备注
driverOrderId	Y	String	车主订单号
availableSeats	Y	Integer	可用座位数
startPosition	Y	Position	车主订单起点位置
endPosition	Y	Position	车主订单终点位置
planDepartureTime	Y	Long	计划出发时间

BlameInfo

参数名	必传	类型	描述	备注
lateBlame	Y	Integer	最终责任人	0-无 1-乘客有责 2-司机有责
blamed	Y	Boolean	是否已追责
payBlamed	Y	Boolean	已支付处罚金
cancelBlamed	Y	Boolean	是否已取消判责
cancelBlameReason	Y	String	取消追责原因
cancelBlameTime	Y	Long	取消追责时间
initiateBlameTime	Y	Long	发起追责时间
cancelBlameType	Y	Integer	取消追责类型	1-乘客 2-司机 3-客服
blameTimeout	Y	Boolean	是否超过可以追责的时间

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
      "orderStatus": 301,
      "poolStatus": 1,
      "acceptedTime": 1715735593000,
      "planDepartureTime": 1715738520000,
      "earliestDepartureTime": 1715738100000,
      "latestDepartureTime": 1715738940000,
      "creatTime": 1715735592000,
      "cancelTime": null,
      "getOnTime": null,
      "getOffTime": null,
      "cancelType": 3,
      "cancelReason": null,
      "comments": "不愿意承担高速费;",
      "passengerNum": 1,
      "orderEstimatePrice": 5668,
      "orderActualPrice": null,
      "payTime": null,
      "extInfo": null,
      "distance": 41666,
      "discountAmount": null,
      "driverInfo": {
          "nickName": "何师傅",
          "phone": "TNwo5X8QtjGpOXqqobclxw==",
          "gender": 1,
          "rating": "0",
          "logoUrl": null,
          "orderCounts": "7",
          "carPlate": "粤AD88888",
          "carModel": "埃安牌GAM7001BEVA1B",
          "carColor": 5,
          "carImage": null,
          "carColorName": "白色"
      },
      "driverOrderTXDto": {
          "driverOrderId": "55555555555",
          "availableSeats": 1,
          "startPosition": {
              "lon": "113.356",
              "lat": "23.1239",
              "shortAddr": null,
              "longAddr": "广东省广州市天河区黄埔大道中178号110号铺",
              "cityCode": "440100",
              "cityName": "广州市",
              "provinceName": null,
              "countyCode": null,
              "phoneAreaCode": null
          },
          "endPosition": {
              "lon": "113.303",
              "lat": "23.3866",
              "shortAddr": null,
              "longAddr": "广东省广州市花都区机场路888号",
              "cityCode": "440100",
              "cityName": "广州市",
              "provinceName": null,
              "countyCode": null,
              "phoneAreaCode": null
          },
          "planDepartureTime": 1715738520000
      },
      "blameInfoTXDto": null
  }
}

3.1.8 确认上车

请求地址

• /order/geton

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	用户标识
orderId	Y	String	订单 id
currentLocation	N	Position	上车时的当前位置	需确认是否需要上传当前定位

请求示例

{
  "accessKey": "111111111111111111111",
  "nonce": "sTJFGEkZ9O",
  "orderId": "33333333333333333",
  "seqId": "1715708413753840780",
  "sign": "2222222222222222222222",
  "spId": 60774,
  "timestamp": 1715708413952,
  "userCode": "0b27faf4e73e0d07cf06ba9147060885",
  "userPhone": "VuQKGLxXIYWFM/4WXUfg/Q=="
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息

响应示例

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

3.1.9 确认下车

请求地址

• /order/getoff

请求参数

参数名	必须	类型	描述	备注
userCode	Y	String	用户标识
orderId	Y	String	订单 id
currentLocation	N	Position	上车时的当前位置	需确认是否需要上传当前定位

请求示例

{
  "accessKey": "1111111111111111",
  "nonce": "9kwHDpjdKG",
  "orderId": "333333333333333333",
  "seqId": "1715702136040828037",
  "sign": "222222222222222222",
  "spId": 60774,
  "timestamp": 1715702136413,
  "userCode": "9f011b2a92c5b006fad3187a21f84b46",
  "userPhone": "MKCGS66N7kJGf7sxDCGlZg=="
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息

响应示例

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

3.1.10 查询司机虚拟号

请求地址

• /driver/phone

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	userCode
userPhone	N	String	用户手机号
orderId	Y	String	服务商订单号

请求示例

{
  "accessKey": "1111111111111111111",
  "nonce": "yWpEvqXKO0",
  "orderId": "333333333333333333333",
  "seqId": "7493d914-9567-4139-8848-96b0b7c6b34f",
  "sign": "22222222222222222",
  "spId": 60774,
  "timestamp": 1715735593153,
  "userCode": "9f011b2a92c5b006fad3187a21f84b46",
  "userPhone": "kVitWEsDPN4VtRbma6vrFg=="
}

响应数据

参数名	必须	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	Object	订单详情数据
data.driverPhone	Y	String	司机虚拟号码
data.expireTime	N	Long	过期时间	毫秒级时间戳

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "driverPhone": "1234567890",
    "expireTime": 1715753436000
  }
}

3.1.11 乘客变更联系方式

请求地址

• /driver/phone/rebind

请求参数

参数名	必传	类型	描述	备注
userPhone	Y	String	用户手机号
userCode	Y	String	userCode
newUserPhone	Y	String	乘客新手机号
orderId	Y	String	服务商订单号

请求示例

{
  "accessKey": "1111111111111111111",
  "nonce": "yWpEvqXKO0",
  "orderId": "333333333333333333333",
  "seqId": "7493d914-9567-4139-8848-96b0b7c6b34f",
  "sign": "22222222222222222",
  "spId": 60774,
  "timestamp": 1715735593153,
  "userCode": "9f011b2a92c5b006fad3187a21f84b46",
  "userPhone": "kVitWEsDPN4VtRbma6vrFg==",
  "newUserPhone": "vdfkdksdjVtRbma12ed23f3"
}

响应数据

参数名	必须	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	Object	订单详情数据
data.driverPhone	Y	String	司机新虚拟号码
data.expireTime	N	Long	过期时间	毫秒级时间戳

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "driverPhone": "1234567890",
    "expireTime": 1715753436000
  }
}

3.1.12 查询IM信息列表

请求地址

• /im/list

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	userCode
userPhone	Y	String	用户手机号
driverId	Y	String	服务商侧司机ID
orderId	N	String	服务商订单号
driverOrderId	N	String	服务商侧司机订单ID

请求示例

{
  "accessKey": "1111111111111111111",
  "nonce": "yWpEvqXKO0",
  "orderId": "333333333333333333333",
  "seqId": "7493d914-9567-4139-8848-96b0b7c6b34f",
  "sign": "22222222222222222",
  "spId": 60774,
  "timestamp": 1715735593153,
  "userCode": "3333333333333333333333",
  "userPhone": "kVitWEsDPN4VtRbma6vrFg==",
  "driverId": "5555555555555",
  "driverOrderId": "4444444444444"
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	Object	订单详情数据
data.timestamp	Y	Long	消息更新时间戳	单位：毫秒
data.imPageUrl	N	String	IM会话跳转页面	前端无法直接跳转必传
data.unReadCount	Y	Integer	未读消息数

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
     "timestamp": 1715735593153,
     "imPageUrl": "/pages/x/y/z",
     "unReadCount": 3
  }
}

3.1.13 查询行程ETA信息

请求地址

• /driver/eta

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	userCode
userPhone	Y	String	用户手机号
orderId	Y	String	服务商订单号
driverId	N	String	服务商侧司机ID
driverOrderId	N	String	服务商侧司机订单ID

请求示例

{
  "accessKey": "1111111111111111",
  "driverId": "3333333333333333",
  "driverOrderId": "",
  "nonce": "EP9CpoqMYC",
  "orderId": "4444444444444444",
  "seqId": "1715748160641878743",
  "sign": "22222222222222222",
  "spId": 60774,
  "timestamp": 1715748162164,
  "userCode": "55555555555555",
  "userPhone": "2rE0aMfyTMSGc6zFS+5KhA=="
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	Object	ETA数据
data.driverLat	Y	String	车主实时位置的纬度
data.driverLng	Y	String	车主实时位置的经度
data.etaType	Y	Integer	eta 类型	1-接驾，2-送驾
data.duration	Y	Integer	接驾时距离乘客起点还剩余的时间，或者送驾时距离乘客终点还剩余时间	以秒为单位，例如值为 300 时表示 5 分钟后到达
data.distance	Y	Integer	接驾时距离乘客起点还剩余的里程，或者送驾时距离乘客终点还剩余的里程	以米为单位，例如值为5000 时表示5公里

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "agentAccount": null,
    "sign": "77777777777",
    "action": null,
    "userCode": "55555555555555",
    "userPhone": "2rE0aMfyTMSGc6zFS+5KhA==",
    "orderId": "4444444444444444",
    "driverId": "3333333333333333",
    "driverOrderId": "",
    "driverLat": "22.999959581163193",
    "driverLng": "113.39350179036458",
    "etaType": 1,
    "duration": 24,
    "distance": 54
  }
}

3.1.14 支付通知

• 该接口用于腾讯侧将订单支付结果同步给服务商，含行程费用支付结果、高速费支付结果、爽约金支付结果、感谢费支付结果的通知。

• 该接口需要保持幂等。

请求地址

• /order/notify/payment

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	userCode
orderId	Y	String	服务商订单号
partnerOrderId	Y	String	腾讯侧订单号
notifyType	Y	Integer	通知类型	1、行程费用支付结果通知；2、爽约金支付结果通知；3、高速费支付结果通知
price	N	Integer	行程费用	单位：分
discountAmount	N	Integer	优惠金额，notifyType=1 且有使用优惠券时有值	单位：分
paidAmount	N	Integer	优惠后支付金额， paidAmount = price - discountAmount	单位：分
blameAmount	N	Integer	优惠金额，notifyType=2 时有值	单位：分
highwayFeeAmount	N	Integer	高速费金额，notifyType=3 时有值	单位：分
couponId	N	String	优惠券id，notifyType=1 且 有使用优惠券时有值	单位：分

请求示例

{
  "accessKey": "1111111111111111111",
  "nonce": "yWpEvqXKO0",
  "orderId": "333333333333333333333",
  "seqId": "7493d914-9567-4139-8848-96b0b7c6b34f",
  "sign": "22222222222222222",
  "spId": 60774,
  "timestamp": 1715735593153,
  "userPhone": "kVitWEsDPN4VtRbma6vrFg==",
  "userCode": "55555555555555",
  "partnerOrderId": "66666666666666",
  "notifyType": 1,
  "price": 10000,
  "discountAmount": 1200,
  "paidAmount": 8800,
  "blameAmount": 0,
  "highwayFeeAmount": 0,
  "couponId": "99999999999999"
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息

响应示例

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

3.1.15 退款通知

• 该接口用于腾讯侧将订单退款结果同步给服务商。

• 该接口需要保持幂等。

请求地址

• /order/notify/refund

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	userCode
orderId	Y	String	服务商订单号
partnerOrderId	Y	String	腾讯侧订单号
refundAmount	Y	Integer	退款金额	单位：分

请求示例

{
  "accessKey": "1111111111111111111",
  "nonce": "yWpEvqXKO0",
  "orderId": "333333333333333333333",
  "seqId": "7493d914-9567-4139-8848-96b0b7c6b34f",
  "sign": "22222222222222222",
  "spId": 60774,
  "timestamp": 1715735593153,
  "userCode": "55555555555555",
  "partnerOrderId": "66666666666666",
  "refundAmount": 6000
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息

响应示例

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

3.1.16 查询订单可退款信息

• 该接口用于腾讯侧查询订单是否可退款，以及可退款金额信息（通常会在车主接单后用户取消订单时调用）。

请求地址

• /order/refund/info

请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	userCode
orderId	Y	String	服务商订单号
partnerOrderId	Y	String	腾讯侧订单号
userPhone	Y	String	用户手机号

请求示例

{
  "accessKey": "1111111111111111111",
  "nonce": "yWpEvqXKO0",
  "orderId": "333333333333333333333",
  "seqId": "7493d914-9567-4139-8848-96b0b7c6b34f",
  "sign": "22222222222222222",
  "spId": 60774,
  "timestamp": 1715735593153,
  "userCode": "55555555555555",
  "partnerOrderId": "66666666666666",
  "userPhone": "kVitWEsDPN4VtRbma6vrFg=="
}

响应数据

参数名	必传	类型	描述	备注
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	Object	返回数据
data.canRefund	Y	Boolean	是否可以退款	true: 可以退款，false：不可以退款
data.refundAmount	N	Integer	可以退款的金额，canRefund为true时必须有值	单位: 分

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "canRefund": true,
    "refundAmount": 6000
  }
}

3.2 业务被调接口

被调接口通用参数

字段名	字段类型	最大长度	必填	说明
accessKey	String	32	是	腾讯出行服务分配给服务商调用 accessKey
spId	Integer	11	是	腾讯出行服务分配给服务商的 id
seqId	String	36	是	请求流水号,调用方自动生成一个随机 ID，建议使用 uuid
timestamp	Long	20	是	请求发送时的时间戳(unix 时间戳) 毫秒
nonce	String	10	是	10 位随机字符串
sign	String	32	是	验证签名参数
eventType	Integer	11	是	事件类型
orderId	String	32	是	腾讯订单号
spOrderId	String	32	是	服务商订单号
status	Integer	11	是	订单状态
driverOrderId	String	32	是	车主订单号
driverId	String	32	否	车主 id
userId	String	32	否	腾讯用户id（即将下线）
userCode	String	32	是	腾讯用户Code

3.2.1 状态变更通知

请求地址

• /v1/callback/order/status

请求参数

参数名称	类型	说明	必须
mobilePhone	String	车主手机号。需加密，腾讯收到后解密	否。车主接单回调时必传
departStartLat	String	车主出发时纬度
departStartLon	String	车主出发时经度
driverDepartureTime	Long	车主实际出发时间
driverExpectDepartureTime	Long	车主预计到达乘客起点时间	eventType=3司机接单时传递
finishType	Integer	完单类型	1-乘客 2-客服 3-系统 4-跨状态(订单状态从401或501直接流转到901时) 5-车主
driverEffectiveStartLat	String	车主有效开始时纬度	eventType=9 && finishType=3/4/5 时有值
driverEffectiveStartLon	String	车主有效开始时经度	eventType=9 && finishType=3/4/5 时有值
driverEffectiveEndLat	String	车主有效结束时纬度	eventType=9 && finishType=3/4/5 时有值
driverEffectiveEndLon	String	车主有效结束时经度	eventType=9 && finishType=3/4/5 时有值
driverEffectiveStartTime	Long	车主有效开始时间	eventType=9 && finishType=3/4/5 时有值
driverEffectiveEndTime	Long	车主有效结束时间	eventType=9 && finishType=3/4/5 时有值
cancelType	Integer	取消类型	1-乘客取消 2-车主取消 3-客服取消（服务商客服回调通知腾讯侧取消） 4-车主未接单取消（乘客预计出发时间30分钟后还没有车主接单，腾讯侧会自动取消。服务商也会有自动取消逻辑，一般也是乘客出发时间前后会触发车主未接单自动取消回调） 5-超时未支付取消（服务商回调腾讯侧通知超时未支付取消订单） 6-系统取消（一家服务商接单了，取消其他服务商的订单，由腾讯侧主动发起取消请求）
cancelTime	Long	取消时间
cancelReason	String	取消原因
blameAmount	Integer	爽约金金额
hasAcceptedPassengerNum	Integer	已拼成人数	status=301时传递
totalAmount	integer	订单总金额(单位：分)	eventType=6时有值
paidAmount	integer	实际支付金额(单位：分)	eventType=6时有值
discountAmount	integer	优惠金额(单位：分)	eventType=6时有值
couponId	string	优惠券id	eventType=6且使用了优惠券时有值

请求示例

{
  "spId": 60708,
  "eventType": 48,
  "orderId": "7206194011589672964",
  "spOrderId": "166808204900408",
  "status": 501,
  "driverOrderId": "166808204",
  "driverId": "hl-111111"
}

响应数据

参数名称	类型	说明	必须
-	-	-	-

响应示例

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

3.2.2 返款(含退款)通知

使用场景:

• 用户支付时以未拼成价支付，实际拼车成功，在完单后需要给用户返款。
• 客服需要给用户部分退款，如司乘有纠纷。

请求地址

• /v1/callback/order/refund

请求参数

参数名称	类型	说明	必须
refundType	Integer	退款类型.1-未拼成退款, 2-客服退款	是
refundPrice	Integer	返款金额，单位:分	是
multiPrice	Integer	接受合拼价(未拼成)，单位:分	refundType 为 1 时必传
multiSuccessPrice	Integer	合拼成功价，单位:分	refundType 为 1 时必传

请求示例

{
  "multiPrice": 4200,
  "multiSuccessPrice": 3800,
  "refundPrice": 400,
  "refundType": 1
}

响应数据

参数名称	类型	说明	必须
-	-	-	-

响应示例

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

3.2.3 车主eta信息变更通知（计划下线）

请求地址

• /v1/callback/driver/eta

请求参数

参数名称	类型	说明	必须
etaType	Integer	eta 类型. 1-接驾, 2-送驾	是
duration	Integer	接驾时距离乘客起点还剩余的时间，或者 送驾时距离乘客终点还剩余时间，以秒为单位。例如值为 300 时表示 5 分钟后到达	是
distance	Integer	接驾时距离乘客起点还剩余的里程，或者 送驾时距离乘客终点还剩余的历程，以米为单位。例如值为 5000 时表示 5 公里	否

请求示例

{
  "etaType": 1,
  "duration": 300,
  "distance": 4000
}

响应数据

参数名称	类型	说明	必须
-	-	-	-

响应示例

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

3.2.4 IM消息通知

该接口适用于司乘通过IM沟通时，服务商将用户维度的未读的车主消息数量同步给腾讯。

请求地址

• /v1/callback/im/info

请求参数

参数名称	类型	说明	必须
unReadCount	Integer	未读消息数量	是
imPageUrl	String	im页面链接	否
lastMessage	String	最后一条消息内容	否
messageType	Integer	消息类型，1-车主文字消息，2-车主Message消息，3-乘客文字消息，4-乘客Message消息，5-未读数同步	是
messageTitle	String	消息标题(特殊的message消息如红包、卡片消息等传入标题)	否
driverName	String	昵称	是
driverSex	Integer	1-男，2-女	否
driverAvatar	String	头像ID	否
vehicleModelName	String	车型	是
vehiclePlateNum	String	车牌	是
vehicleColor	String	颜色	是

请求示例

{
  "unReadCount": 3,
  "imPageUrl": "xxx/xxx",
  "lastMessage": "最新消息",
  "messageType": 1,
  "messageTitle": "",
  "driverName": "尾号XXXX",
  "driverSex": 1,
  "driverAvatar": "https://xxxxxx",
  "vehicleModelName": "特斯拉",
  "vehiclePlateNum": "黑A12345",
  "vehicleColor": "白色"
}

响应数据

参数名称	类型	说明	必须
-	-	-	-

响应示例

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

3.2.5 高速费支付回调

该接口适用于司机在行程中或行程结束后发起高速费支付，将支付金额和支付状态同步给腾讯侧。

请求地址

• /v1/callback/highwayfee/pay

请求参数

参数名称	类型	说明	必须
operationTime	Long	实际发起操作的毫秒级时间戳，不同于公共参数请求时间戳	是
highwayFee	Integer	高速费金额，单位：分	是
payStatus	Integer	支付状态（0-无高速费、1-发起支付（未支付）、2-已撤销、3-已支付）	是

请求示例

{
  "operationTime": 111111111111,
  "highwayFee": 100,
  "payStatus": 0
}

响应数据

参数名称	类型	说明	必须
-	-	-	-

响应示例

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

3.2.6 合拼信息回调

该接口适用于同步订单合拼是否成功的信息。通用参数中eventType=83

请求地址

• /v1/callback/order/multi/detail

请求参数

参数名称	类型	说明	必须
multiSuccess	Integer	0:否，1:是	是
multiOrderNum	Integer	合拼拼成订单数	是
multiPassengerNum	Integer	合拼拼成总人数	是
multiRefundAmount	Integer	合拼返款金额，单位：分	否

请求示例

{
  "multiSuccess": 1,
  "multiOrderNum": 2,
  "multiPeopleNum": 4,
  "multiRefundAmount": 100
}

响应数据

参数名称	类型	说明	必须
-	-	-	-

响应示例

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

3.2.7 同步订单财务信息字段

使用场景:

• 订单财务信息同步接口，同步「车主收入」、「车主收入到账时间」、「完单后退款金额」、「退款类型」、「完单后退款时间」

请求地址

• /v1/callback/order/bill/sync

请求参数

参数名称	类型	说明	必须
syncId	String	同步流水号	是
syncType	Integer	同步类型：0-全同步，1-收入信息，2-退款信息	是
driverIncome	Integer	车主收入金额，单位：分	非退款时必须
incomeType	Integer	车主收入类型，1-车费，2-高速费，3-违约金	非退款时必须
driverIncomeArrivalTime	Long	车主收入到账时间，毫秒级时间戳	非退款时必须
refundPrice	Integer	完单后退款金额，单位：分	存在退款必填
refundType	Integer	退款类型，1-合拼返款，2-预留	存在退款必填
refundTime	Long	完单后退款时间，毫秒级时间戳	存在退款必填

请求示例

{
  "syncId": "12345",
  "syncType": 0,
  "driverIncome": 1000,
  "incomeType": 1,
  "driverIncomeArrivalTime": 1111111111,
  "refundPrice": 1000,
  "refundType": 1,
  "refundTime": 1111111111
}

响应数据

参数名称	类型	说明	必须
-	-	-	-

响应示例

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

3.2.8 查询订单财务信息

使用场景: 确认信息同步状况，通过订单号或流水号查询订单财务信息列表

请求地址

• /v1/callback/order/bill/info

请求参数

参数名称	类型	说明	必须
type	Integer	查询类型.1-订单号, 2-订单号&流水号	是
syncId	String	查询流水号	查询类型为2时必传

请求示例

{
  "type": 2,
  "syncId": "12345678"
}

响应数据

参数名称	类型	说明	必须
billInfoList	Object	订单财务信息列表	是
billInfoList[].userCode	String	userCode	是
billInfoList[].orderId	String	订单号	是
billInfoList[].spOrderId	String	服务商订单号	是
billInfoList[].orderStatus	Integer	订单状态	是
billInfoList[].syncId	Long	同步流水号	是
billInfoList[].syncTime	Long	同步请求时间，毫秒级时间戳	是
billInfoList[].syncType	Integer	同步类型：0-全同步，1-收入信息，2-退款信息	是
billInfoList[].driverIncome	Integer	车主收入金额，单位：分	存在即返回
billInfoList[].incomeType	Integer	收入类型，1-车费，2-高速费，3-违约金	存在即返回
billInfoList[].driverIncomeArrivalTime	Long	车主收入到账时间，毫秒级时间戳	存在即返回
billInfoList[].refundPrice	Integer	完单后退款金额，单位：分	存在即返回
billInfoList[].refundType	Integer	退款类型，1-合拼返款，2-预留	存在即返回
billInfoList[].refundTime	Long	完单后退款时间，毫秒级时间戳	存在即返回
billInfoList[].extInfo	String	额外信息	存在即返回

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
      "billInfoList": [
          {
            "orderId": "12345",
            "spOrderId": "12345",
            "userCode": "12345",
            "orderStatus": 901,
            "syncId": "12345",
            "syncTime": 1111111111,
            "syncType": 0,
            "driverIncome": 1000,
            "incomeType": 1,
            "driverIncomeArrivalTime": 1111111111,
            "refundPrice": 1000,
            "refundType": 1,
            "refundTime": 1111111111,
            "extInfo": "{\"ext1\": \"extInfo1\"}"
          },
          {
            "orderId": "12345",
            "spOrderId": "12345",
            "userCode": "12345",
            "orderStatus": 901,
            "syncId": "12345",
            "syncTime": 1111111111,
            "syncType": 0,
            "driverIncome": 1000,
            "incomeType": 1,
            "driverIncomeArrivalTime": 1111111111,
            "refundPrice": 1000,
            "refundType": 1,
            "refundTime": 1111111111,
            "extInfo": "{\"ext1\": \"extInfo1\"}"
          }
      ]
  }
}

4. 数据解密接口

仅针对非原生接入方式时需要关注。

接入方根据请求中传入的 userCode 作为用户唯一标识，并在系统中建立关联关系； 如接入方原系统中使用手机号做唯一标识，则根据插件中传入的 userCode 和 mobile 进行融合关联用户； userCode 相对用户固定不变，mobile 可能会变更。

• 接口说明

本接口用于小程序参数明文获取，本接口签名方式同“基础说明”。

• 请求地址

  正式环境 https://sp.wecar.map.qq.com/open/v1/param/decode

  测试环境 https://test.tai.qq.com/open/v1/param/decode

• 请求方式 POST

• 请求参数

参数名称	类型	最大长度	必选	说明
api_key	string	32	是	腾讯出行服务分配给服务商调用的api_key
seq_id	string	36	是	请求流水号,调用方自动生成一个随机ID，建议使用uuid
timestamp	int	11	是	请求发送时的时间戳(unix时间戳) 秒
nonce	string	10	是	10位随机字符串
sign	string	32	是	验证签名参数
encrypt_data	string	-	是	加密数据
encrypt_id	string	18	否	加密流水号

• 返回数据

参数名称	类型	最大长度	必选	说明
code	int	11	是	服务响应状态，参见错误码表
message	string	64	是	服务响应状态说明，参见错误码表
data	object	-	是	-
json_string	string	-	是	解密后的json字符串

• 请求数据示例

{
  "encrypt_data": "PSYDQHwWw+0H2l/NFUoLNrnhUFn9Jf0k6nkkZTSAIF8=",
  "encrypt_id": "1611844898010850820"
}

• 返回数据示例

{
  "code": 0,
  "message": "successful",
  "data": {
    "json_string": "{\"openId\":\"b0b15a758bac280fb110aa8985b1902e\",\"mobile\":\"13800138000\"}"
  }
}

5. 工单接口列表

5.1 主调接口

5.1.1 创建工单

发起创建客服工单。

请求地址

• /spapi/work/create

请求参数

参数名称	类型	长度	必选	说明
workId	String	32	Y	腾讯工单号
orderId	String	32	Y	腾讯订单号
spOrderId	String	32	Y	运力商订单号
workCategoryId	Long	20	Y	腾讯工单分类 id，通常取到三级分类 id
workCategoryName	String	255	N	腾讯工单问题分类，参考附录9.7
workTitle	String	255	N	工单标题（如果无原始标题，推荐选择一二三级分类的文字组合传输）
description	String	2048	Y	工单客诉内容描述，（更新客诉问题按累加描述），一般为工单发起方记录。
complaintPhone	String	32	N	投诉手机号，仅做联系用户使用
priority	Integer		Y	工单优先级，参考附录9.8
exInformation	String	2048	N	附加信息(工单补充信息，双方协商，提前定义结构字段开发)
attachments	String	2048	N	客诉时用户上传的附件，json 数组字符串，内容为图片 url 示例：["fileUrl1","fileUrl2"]

请求示例

{
  "workId": "11111111111111111111111111111111",
  "orderId": "12345678901234567890123456789012",
  "spOrderId": "abcdefghabcdefghabcdefghabcdefgh",
  "workCategoryId": 0,
  "workCategoryName": "",
  "workTitle": "无法取消",
  "description": "着急，帮我",
  "complaintPhone": "18810562508",
  "priority": 1,
  "exInformation": "",
  "attachments": "['https://static.img.tai.qq.com/webapp/open/citycode_desc.png']"
}

响应数据

参数名称	类型	长度	必选	说明
code	Integer		Y	参考附录9.4
message	String	64	Y	响应状态说明
data	Object
data.workId	String	32	Y	腾讯工单号
data.spWorkId	String	32	N	运力商工单号
requestId	String	64	N	请求 ID

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "workId": "11111111111111111111111111111111",
    "spWorkId": "22222222222222222222222222222222"
  },
  "requestId": "1704971701130890243"
}

5.1.2 更新工单

更新客服工单。

请求地址

• /spapi/work/update

请求参数

参数名称	类型	长度	必选	说明
workId	String	32	Y	腾讯工单号
spWorkId	String	32	N	运力商工单号
description	String	2048	Y	工单客诉内容描述，（更新客诉问题按累加描述），一般为工单发起方记录。
optResult	String	2048	N	腾讯或运力商，处理方客服处理结果内容。
priority	Integer		Y	工单优先级，参考附录9.8
status	Integer		Y	工单状态，参考附录9.5
solution	Integer		N	工单处理结果，参考附录9.6
detail	Object		N
detail.cancel	Integer		N	当 solution=1 取消订单时，对应结果状态必填。 参考附件 2 工单处理结果类型说明
detail.refundType	Integer		N	当 solution=2 退款时，对应结果状态必填。 参考附件 2 工单处理结果类型说明
detail.refundAmount	Integer		N	当 solution=2 退款时，必填。退款金额，单位：分。
detail.refundAboutExtraCharge	Integer		N	当 solution=2 退款时，必填。退款是否为退附加费，0-否，1-是
detail.isModifyFee	Integer		N	当 solution=3 改价时，对应结果状态必填。 参考附件 2 工单处理结果类型说明
detail.isFreeOrder	Integer		N	当 solution=5 免单时，对应结果状态必填。 参考附件 2 工单处理结果类型说明
exInformation	String	2048	N	附加信息(工单补充信息，双方协商，提前定义结构字段开发)

请求示例

{
  "workId": "11111111111111111111111111111111",
  "orderId": "12345678901234567890123456789012",
  "description": "着急，帮我",
  "optResult": "同意",
  "priority": 1,
  "status": 2,
  "solution": 1,
  "detail": {
    "cancel": 1,
    "refundType": 1,
    "refundAmount": 200,
    "refundAboutExtraCharge": 1,
    "isModifyFee": 1,
    "isFreeOrder": 1
  },
  "exInformation": ""
}

响应数据

参数名称	类型	长度	必选	说明
code	Integer		Y	参考附录9.4
message	String	64	Y	响应状态说明
data	Object
data.workId	String	32	Y	腾讯工单号
data.spWorkId	String	32	N	运力商工单号
requestId	String	64	N	请求 ID

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "workId": "11111111111111111111111111111111",
    "spWorkId": "22222222222222222222222222222222"
  },
  "requestId": "1704971701130890243"
}

5.1.3 查询工单详情

查询工单详情。

请求地址

• /spapi/work/progress

请求参数

参数名称	类型	长度	必选	说明
workId	String	32	Y	腾讯工单号
spWorkId	String	32	N	运力商工单号

请求示例

{
  "workId": "11111111111111111111111111111111",
  "orderId": "12345678901234567890123456789012"
}

响应数据

参数名称	类型	长度	必选	说明
code	Integer		Y	参考附录9.4
message	String	64	Y	响应状态说明
data	Object
data.workId	String	32	Y	腾讯工单号
data.spWorkId	String	32	N	运力商工单号
data.optResult	String	2048	N	腾讯或运力商，处理方客服处理结果内容。
data.status	Integer		Y	工单状态，参考附录9.5
data.solution	Integer		N	工单处理结果，参考附录9.6
data.detail	Object		N
data.detail.cancel	Integer		N	当 solution=1 取消订单时，对应结果状态必填。 参考附件 2 工单处理结果类型说明
data.detail.refundType	Integer		N	当 solution=2 退款时，对应结果状态必填。 参考附件 2 工单处理结果类型说明
data.detail.refundAmount	Integer		N	当 solution=2 退款时，必填。退款金额，单位：分。
data.detail.refundAboutExtraCharge	Integer		N	当 solution=2 退款时，必填。退款是否为退附加费，0-否，1-是
data.detail.isModifyFee	Integer		N	当 solution=3 改价时，对应结果状态必填。 参考附件 2 工单处理结果类型说明
data.detail.isFreeOrder	Integer		N	当 solution=5 免单时，对应结果状态必填。 参考附件 2 工单处理结果类型说明
data.exInformation	String	2048	N	附加信息(工单补充信息，双方协商，提前定义结构字段开发)
requestId	String	64	N	请求 ID

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "workId": "11111111111111111111111111111111",
    "spWorkId": "22222222222222222222222222222222",
    "optResult": "同意",
    "status": 2,
    "solution": 1,
    "description": "着急，帮我",
    "priority": 1,
    "detail": {
      "cancel": 1,
      "refundType": 1,
      "refundAmount": 200,
      "refundAboutExtraCharge": 1,
      "isModifyFee": 1,
      "isFreeOrder": 1
    },
    "exInformation": ""
  },
  "requestId": "1704971701130890243"
}

5.1.4 工单催单

进行工单催单。

请求地址

• /spapi/work/reminder

请求参数

参数名称	类型	长度	必选	说明
workId	String	32	Y	腾讯工单号
description	String	2048	N	催单客服内容描述，一般为催单发起方记录。
attachments	String	2048	N	催单时客服上传的附件，json 数组字符串，内容为图片 url 示例：["fileUrl1","fileUrl2"]

请求示例

{
  "workId": "11111111111111111111111111111111",
  "description": "着急，求加快处理",
  "attachments": "['https://static.img.tai.qq.com/webapp/open/citycode_desc.png']"
}

响应数据

参数名称	类型	长度	必选	说明
code	Integer		Y	参考附录9.4
message	String	64	Y	响应状态说明
data	Object
data.workId	String	32	Y	腾讯工单号
requestId	String	64	N	请求 ID

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "workId": "11111111111111111111111111111111"
  },
  "requestId": "1704971701130890243"
}

5.1.5 工单回复

进行工单回复。

请求地址

• /spapi/work/reply

请求参数

参数名称	类型	长度	必选	说明
workId	String	32	Y	腾讯工单号
description	String	2048	N	回复客服内容描述，一般为回复服务商的处理结果
attachments	String	2048	N	回复工单时客服上传的附件，json数组字符串，内容为图片url 示例：["fileUrl1","fileUrl2"]

请求示例

{
  "workId": "11111111111111111111111111111111",
  "description": "着急，求加快处理",
  "attachments": "['https://static.img.tai.qq.com/webapp/open/citycode_desc.png']"
}

响应数据

参数名称	类型	长度	必选	说明
code	Integer		Y	参考附录9.4
message	String	64	Y	响应状态说明
data	Object
data.workId	String	32	Y	腾讯工单号
requestId	String	64	N	请求 ID

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "workId": "11111111111111111111111111111111"
  },
  "requestId": "1704971701130890243"
}

5.2 被调接口

5.2.1 工单回调

服务商商工单处理结果变更时通知腾讯出行。

说明： 工单回调主要用于服务商发起创建工单、进行中工单流转和通知。取消、退款、改价、补偿优惠券等操作以订单系统的实际操作为准。

请求地址

• v1/callback/work/notify

请求参数

参数名称	类型	长度	必选	说明
spId	Integer	32	Y	腾讯出行服务分配给服务商的 id
workId	String	32	N	腾讯工单号。如果进行中工单回调，需填写；如果是运力商发起创建工单，则为空。
spWorkId	String	32	Y	运力商工单号
orderId	String	32	Y	腾讯订单号
spOrderId	String	32	Y	运力商订单号
workCategoryId	Long	20	Y	腾讯工单分类 id，通常取到三级分类 id
workCategoryName	String	255	N	腾讯工单分类，参考附录9.7
workTitle	String	255	N	工单标题（如果无原始标题，推荐选择一二三级分类的文字组合传输）
description	String	2048	Y	工单客诉内容描述，（更新客诉问题按累加描述），一般为工单发起方记录。
complaintPhone	String	32	N	投诉手机号，仅做联系用户使用
optResult	String	2048	N	腾讯或运力商，处理方客服处理结果内容。
priority	Integer		Y	工单优先级，参考附录9.8
status	Integer		Y	工单状态，参考附录9.5
solution	Integer		N	工单处理结果类型，参考附录9.6
detail	Object		N
detail.cancel	Integer		N	当 solution=1 取消订单时，对应结果状态必填。对应结果状态必填。 参考附件 2 工单处理结果类型说明
detail.refundType	Integer		N	当 solution=2 退款时，对应结果状态必填。 参考附件 2 工单处理结果类型说明
detail.refundAmount	Integer		N	当 solution=2 退款时，必填。退款金额，单位：分。
detail.refundAboutExtraCharge	Integer		N	当 solution=2 退款时，必填。退款是否为退附加费，0-否，1-是
detail.isModifyFee	Integer		N	当 solution=3 改价时，对应结果状态必填。 参考附件 2 工单处理结果类型说明
detail.isFreeOrder	Integer		N	当 solution=5 免单时，对应结果状态必填。参考附件 2 工单处理结果类型说明
exInformation	String	2048	N	附加信息(工单补充信息，双方协商，提前定义结构字段开发)
attachments	String	2048	N	运力处理完返回结果的附件，json 数组字符串，内容为图片 url 示例：["fileUrl1","fileUrl2"]

请求示例

{
  "spId": 60723,
  "workId": "11111111111111111111111111111111",
  "spWorkId": "22222222222222222222222222222222",
  "orderId": "12345678901234567890123456789012",
  "spOrderId": "166808204900408",
  "workCategoryId": 1,
  "workCategoryName": "功能异常",
  "workTitle": "无法取消",
  "description": "着急，帮我",
  "complaintPhone": "18810562508",
  "optResult": "同意",
  "priority": 1,
  "status": 2,
  "solution": 1,
  "detail": {
    "cancel": 1,
    "refundType": 1,
    "refundAmount": 200,
    "refundAboutExtraCharge": 1,
    "isModifyFee": 1,
    "isFreeOrder": 1
  },
  "exInformation": "",
  "attachments": "['https://static.img.tai.qq.com/webapp/open/citycode_desc.png']"
}

响应数据

参数名称	类型	长度	必选	说明
code	Integer		Y	参考附录9.4
message	String	64	Y	响应状态说明
data	Object
data.workId	String	32	Y	腾讯工单号
requestId	String	64	N	请求 ID

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "workId": "11111111111111111111111111111111",
    "spWorkId": "22222222222222222222222222222222"
  },
  "requestId": "1704971701130890243"
}

6. 优惠券

接入流程如下图：

具体接口信息在接入时提供。

7. 半屏拉起跳转链接

仅针对非原生接入方式时需要关注。

在目前产品形态中，用户需要跳转服务商小程序完成部分功能，因此需要服务商提供部分页面的跳转地址及参数。

所需跳转页面
首 页
确认支付页
行程中页面
支付爽约金页面
支付后取消页面
保险页
客服页面
价格明细页面
IM消息页面
高速费页面

备注

• 服务商需提供相关页面的链接，以及相关页面所需携带的参数。比如from、orderId等等。

• 服务商小程序有能承接上述功能的页面即可，不用一一对应。比如"确认支付页"、"行程中页面"可以是一个页面，也可以是两个页面。

8. 协议链接

以H5页面形式呈现以下协议内容，服务商需提供以下两个协议的跳转链接。

名称
例：《拇指顺风车隐私协议》
例：《拇指顺风车用户协议》

9. 附录

9.1 服务商列表

服务商 id	服务商名称
60708	哈啰
60723	嘀嗒
60729	同程
60774	拇指

9.2 订单状态

订单状态码	状态说明
101	创建订单
201	派单中
206	改派中
301	车主接单
401	用户已支付
501	待车主到达
601	车主到达起点, 待出发
701	乘客上车
801	车主到达终点, 待下车
901	乘客下车
910	订单取消
950	派单失败

9.3 eventType 列表

eventType	对应事件名称
3	车主接单
4	乘客取消
6	支付成功(车主待出发)
48	车主出发
7	车主到达起点
38	车主到达终点
8	乘客已上车
9	行程结束
17	取消行程（司机取消）
18	取消行程（超时未支付自动取消）
19	取消行程（客服取消）
21	取消行程（未接单自动取消）
11	车主发起爽约金追款
13	取消爽约金追款（车主取消追责）
31	取消爽约金追款（客服取消追责）
57	乘客支付爽约金成功
40	返款/退款
78	IM 信息变更推送
79	ETA 信息变更推送
80	高速费信息变更推送
81	同步对账信息
82	查询对账信息
83	合拼信息同步

9.4 状态码

状态码	描述
0	成功
-1	服务内部错误
1	回调请求签名较验不通过
2	回调请求参数错误
20	回调处理失败
21	未知的回调事件类型
22	无效的订单 ID
23	订单状态不匹配
26	服务商不匹配
10001	请求 URL 错误
10002	请求方法错误
10003	appId 错误
10004	时间戳过期或者 nonce 重复
10005	签名验证失败
10009	请求频繁，请稍后重试
2130000	主号为空
2130001	工号为空
2134001	对象不存在
2136001	更新信息不合法
2136002	没有需要修改信息
2136007	工单已经处于结束状态，不能更改状态
2136008	接口调用失败
E002000007	工单标题为空

• 状态码 10000 ~ 19999 表示请求错误或者签名验证失败
• 状态码 2130000 ~ 2139999 表示业务错误

9.5 工单状态

工单状态	描述
1	新建
2	待处理
3	受理中
4	已解决

9.6 工单处理结果类型

类型	描述	说明
-1	未确认处理结果
0	无需处理
1	取消订单
11	订单已取消
111	订单不取消
2	退款
22	不退款
222	已全额退款
2222	部分退款
3	改价
33	订单已改价
333	订单不改价
5	免单
10	其它

9.7 工单问题分类

参见工单问题分类：【腾讯文档】客诉问题分类与运力映射 (opens new window)

9.8 工单优先级

优先级级别	描述
40	紧急
30	高
20	中
10	低