# 顺风车

顺风车

# 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 不成功，要有重试机制（具体见错误码表）。

注意：当调用腾讯侧接口返回状态码为22, 23, 26时，无需重试。

# 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 城市编码

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

城市编码说明

# 2.14 单位

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

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

# 2.15 重试机制

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

# 2.16 接口分类

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

# 3.1 业务主调接口

说明：

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

# 通用结构

# 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	车辆图片链接

注意：车辆颜色统一格式为: X色，如"白色"，"黑色"，"蓝色"等，不要直接传"白"、"黑"、"蓝"。

# 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	行程规划路径	单位：米
data.spEstimateId	N	String	询价id，和本次询价结果一一对应	如果返回该值，该值需要具有唯一性, 长度128以下
data.notPoolPriceDiscount	N	Integer	独享价优惠金额	单位：分
data.poolPriceDiscount	N	Integer	拼车成功价优惠金额	单位：分
data.multiPriceDiscount	N	Integer	愿拼未拼成价优惠金额	单位：分
data.categoryInfoList[]	N	List	多品类询价结果
data.priceInfoList[]	N	List	非多品类价格信息(包含默勾调价信息)

# CategoryInfo 结构

参数名	必传	类型	描述	备注
categoryCode	Y	Integer	服务商品类Code	由服务商自定义即可
poolType	Y	Integer	对应腾讯侧拼车类型	取值：1-独享, 2-拼车
categoryPrice	Y	Integer	品类拼车价	单位：分
multiPrice	Y	Integer	品类拼车未拼成价	单位：分
categoryPriceDiscount	N	Integer	拼车成功价优惠金额	单位：分
multiPriceDiscount	N	Integer	拼车未拼成价服务商优惠金额	单位：分
minPrice	N	Integer	最低价格	单位：分
priceSelectPolicy	N	Integer	价格调整策略 0.不调价，1.降到默勾价格，2.降倒最低价格	单位：分

默勾调价相关字段说明：对于需要接入默勾调价的服务商（通过调整价格进入默勾），询价时需返回minPrice和priceSelectPolicy这两个字段。腾讯侧通过这两个字段调整价格，使服务商的价格尽量可进入默勾。调整后的价格会通过下单接口告知服务商，服务商需根据调整后的价格进行定价。对于接入多品类的服务商，minPrice、priceSelectPolicy放在categoryInfoList中，和品类价格一起返回，对于未接入多品类的服务商，minPrice、priceSelectPolicy放在priceInfoList中。不同类型价格可分别控制调价策略。示例数据如下

响应示例（带默勾调价，非多品类）

{
  "code": 0,
  "message": "成功",
  "data": {
      "multiPrice": 2000,
      "poolPrice": 2000,
      "notPoolPrice": 3000,
      "distance": 45830,
      "spEstimateId": "b3c51d2e6133d514d9",
      "priceInfoList": [
        {
          "poolType": 1,  // 1:独享，2：拼座
          "categoryCode": 1,  // 非多品类，categoryCode取值和poolType一致即可
          "minPrice": 2500,
          "priceSelectPolicy": 1
        },
        {
          "poolType": 2,
          "categoryCode": 2,
          "minPrice": 1800,
          "priceSelectPolicy": 2
        }
      ]
  }
}

响应示例（带默勾调价，多品类）

{
  "code": 0,
  "message": "成功",
  "data": {
      "multiPrice": 2000,
      "poolPrice": 2000,
      "notPoolPrice": 3000,
      "distance": 45830,
      "spEstimateId": "b3c51d2e6133d514d9",
      "categoryInfoList": [
        {
          "categoryCode": 1,
          "poolType": 1,
          "multiPrice": 11824,
          "poolPrice": 11824,
          "notPoolPrice": 16554,
          "minPrice": 2500,
          "priceSelectPolicy": 1
        },
        {
          "categoryCode": 2,
          "poolType": 2,
          "multiPrice": 11824,
          "poolPrice": 11824,
          "notPoolPrice": 16554,
          "minPrice": 2500,
          "priceSelectPolicy": 1
        }
      ]
  }
}

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
      "multiPrice": 11824,
      "poolPrice": 11824,
      "notPoolPrice": 16554,
      "distance": 45830,
      "spEstimateId": "b3c51d2e6133d514d9",
      "categoryInfoList": [
        {
          "categoryCode": 1,
          "poolType": 1,
          "multiPrice": 11824,
          "poolPrice": 11824,
          "notPoolPrice": 16554
        },
        {
          "categoryCode": 2,
          "poolType": 2,
          "multiPrice": 11824,
          "poolPrice": 11824,
          "notPoolPrice": 16554
        }
      ]
  }
}

# 3.1.3 创建订单

请求地址
/order/create
请求参数

参数名	必传	类型	描述	备注
startPosition	Y	Position	出发点信息
endPosition	Y	Position	目的地信息
earliestDepartureTime	Y	Integer	最早出发时	单位：秒
latestDepartureTime	Y	Integer	最晚出发时间	单位：秒
userCode	Y	String	用户标识
userPhone	Y	String	用户手机	加密后传输
partnerOrderId	Y	String	腾讯侧订单ID
passengerCount	Y	Integer	乘客人数
poolType	Y	Integer	拼车类型	1-独享 2-拼车
bearHighwayFeeType	Y	Integer	高速费承担方式	0-用户未选择或不途径高速路段 1-愿意承担高速费 2-不愿承担高速费 3-愿意分摊高速费
orderComment	N	String	备注信息	多个备注信息以,间隔
reassignTimes	N	Integer	改派次数	只有改派下单该参数值才会大于等于1
couponInfoList	N	List	优惠券信息
spEstimateId	N	String	询价接口返回的spEstimateId
categoryList	N	List	下单勾选的品类列表
adjustedResult	N	Object	默勾调价结果(未调价的没有此字段)
adjustedResult.categoryPriceList	N	List	不同品类调价结果
adjustedResult.categoryPriceList[0].categoryCode	N	Integer	服务商品类Code
adjustedResult.categoryPriceList[0].poolType	N	Integer	对应腾讯侧拼车类型：1-独享, 2-拼车
adjustedResult.categoryPriceList[0].adjustedPrice	N	Integer	调整后的价格，单位分
payType	Y	Integer	0半屏支付，1普通支付，2支付分	此字段代表预期的支付类型，不代表最终支付类型

CouponInfo

参数名	必传	类型	描述	备注
couponId	Y	String	优惠券id
couponAmount	Y	Integer	优惠券金额，折扣券为计算好的折扣金额	单位：分
couponType	Y	String	优惠券类型
couponName	Y	String	优惠券名称
categoryCode	N	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==",
  "spEstimateId": "b3c51d2e6133d514d9",
  "categoryList": [
        {
          "categoryCode": 1,
          "poolType": 1,
          "multiPrice": 11824,
          "poolPrice": 11824,
          "notPoolPrice": 16554
        },
        {
          "categoryCode": 2,
          "poolType": 2,
          "multiPrice": 11824,
          "poolPrice": 11824,
          "notPoolPrice": 16554
        }
  ],
  "adjustedResult": {
    "categoryPriceList": [
      {
        "categoryCode": 1,
        "poolType": 1,
        "adjustedPrice": 1000
      }
    ]

  }
}

响应数据

参数名	必传	类型	描述
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	业务消息
data	N	Object	业务数据
data.blameAmount	N	Integer	爽约金	单位分

响应示例

{
  "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.5 查询可邀请司机列表（新）

请求地址
/driver/list/v2
请求参数

参数名	必传	类型	描述
userCode	Y	String	用户标识
userPhone	N	String	乘客手机号
orderId	Y	String	服务商订单 ID
pageNo	Y	Integer	页码
pageSize	Y	Integer	每页查询条数

请求示例

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

响应数据

参数名	必传	类型	描述
code	Y	Integer	业务状态码
message	Y	String	业务消息
data	Y	Object
data.total	Y	Integer
data.list	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": {
        "total": 23,
        "list": [
            {
                "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	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	优惠金额	单位：分
thanksFee	N	Integer	感谢费	单位：分
spDiscountAmount	N	Integer	服务商优惠总金额	单位：分
spDiscountDetails	N	List	服务商优惠明细
spDiscountDetails[0].amount	N	Integer	优惠金额	单位：分
spDiscountDetails[0].desc	N	String	优惠描述
highwayFeeDetail	N	HighwayFeeDetail	高速费信息

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	是否超过可以追责的时间

HighwayFeeDetail

参数名	必传	类型	描述	备注
highwayFee	N	Integer	高速费金额	单位：分
payStatus	N	Integer	高速费支付状态	0-无高速费、1-发起支付（未支付）、2-已撤销、3-已支付

响应示例

{
  "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": "白色"
      },
      "driverOrder": {
          "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
      },
      "blameInfo": 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 支付通知

该接口用于腾讯侧将订单支付结果同步给服务商，含行程费用支付结果、高速费支付结果、爽约金支付结果、感谢费支付结果的通知。
该接口需要保持幂等。
行程费用通知中包含感谢费的，会在感谢费字段中体现。优惠前行程费用=totalAmount-thanksFee。
请求地址
/order/notify/payment
请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	userCode
orderId	Y	String	服务商订单号
partnerOrderId	Y	String	腾讯侧订单号
notifyType	Y	Integer	通知类型	1、行程费用支付结果通知；2、爽约金支付结果通知；3、高速费支付结果通知
totalAmount	N	Integer	总费用	单位：分
discountAmount	N	Integer	优惠金额，有使用优惠券时有值	单位：分
paidAmount	N	Integer	优惠后支付金额	单位：分
thanksFee	N	Integer	感谢费	单位：分
couponId	N	String	优惠券id，有使用优惠券时有值
stockId	N	String	优惠券批次id，有使用优惠券时有值
stockUsage	N	Integer	优惠券批次使用场景，1:腾讯内部营销，2:服务商客服发券
transactionId	N	String	交易流水号
outTradeNo	N	String	商户订单号
subMchId	N	String	支付到的子商户号	对于内部户支付，此值为空
payType	Y	Integer	支付类型	1：普通支付，2：支付分，3：内部户支付

请求示例

{
  "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,
  "totalAmount": 10000,
  "discountAmount": 1200,
  "paidAmount": 8800,
  "thanksFee": 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	腾讯侧订单号
refundSource	Y	Integer	退款来源，1.合拼返款，2.客服退款
refundSerialId	Y	String	退款流水号
refundBillType	Y	Integer	退款类型，60.部分退款，70.全额退款
refundType	Y	Integer	退款费用类型	1.行程费用，2感谢费，3.高速费，4.违约金
refundAmount	Y	Integer	退款金额	单位：分
refundTransactionId	N	String	微信退款交易流水号

请求示例

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

响应数据

参数名	必传	类型	描述	备注
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.1.17 添加感谢费

通过添加感谢费，激励车主接单。
请求地址
/order/thanksFee/update
请求参数

参数名	必传	类型	描述
userCode	Y	String	用户标识
orderId	Y	String	服务商订单号
thanksFee	Y	Integer	感谢费金额

请求示例

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

响应数据

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

响应示例

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

# 3.1.18 同步订单评价信息

用户对订单进行评价后，将评价内容同步给服务商
请求地址
/order/comment/sync
请求参数

参数名	必传	类型	描述
userCode	Y	String	用户标识
orderId	Y	String	服务商订单号
score	Y	Integer	评分(1-5星)
labelComments	N	String	选择的评价标签，json字符串
commentContent	N	String	自定义评价内容

请求示例

{
  "orderId": "333333333333333333333",
  "userCode": "55555555555555",
  "score": 5,
  "labelComments": "[\"认路准送达快\",\"车主态度好\", \"主动提供帮助\"]",
  "commentContent": "很满意"
}

响应数据

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

响应示例

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

# 3.1.19 支付分创单成功通知

司机接单以后，创建支付分订单并通知服务商
请求地址
/payscore/bill/create

参数名	必传	类型	描述	备注
orderId	Y	String	服务商订单号
partnerOrderId	Y	String	腾讯侧订单号
payScoreBillList	Y	Array	创单账单信息
payScoreBillList[].spMerchantPackage	Y	String	服务商商户数据包
payScoreBillList[].billFeeType	Y	Integer	账单金额类型，1.订单金额，2感谢费，3.高速费，4.违约金
payScoreBillList[].billFee	Y	Integer	账单金额
spSubMchId	N	String	支付分完单扣款使用的商户号	当服务商有多个商户号时，可通过此值区分完单扣款的商户号

请求示例

{
  "spOrderId": "333333333333333333333",
  "billList": [
    "spMerchantPackage": "xxx",
    "billFeeType": 1,
    "billFee": 500
  ]
}

响应数据

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

响应示例

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

# 3.1.20 发起扣款通知

乘客下车以后，发起扣款通知
请求地址
/payscore/bill/complete

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

请求示例

{
  "spOrderId": "333333333333333333333"
}

响应数据

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

响应示例

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

# 3.1.21 乘客发送消息通知服务商

请求地址
/im/passenger/send
请求参数

参数名称	类型	说明	必须
userCode	String	腾讯侧userCode	是
spDriverId	String	服务商司机ID	是
orderId	String	会话关联的服务商订单ID	是
partnerOrderId	String	会话关联的腾讯侧订单ID	是
messageType	Integer	消息类型文字0/图片1/定位2	是
messageBody	MessageBody	消息内容	是
messageBody.text	String	文本消息	否
messageBody.url	String	图片/语音URL	否
messageBody.duration	Integer	语音时长	否
messageBody.location	Location	定位信息	否
messageBody.location.address	String	定位地址详情	否
messageBody.location.name	String	定位地址名	否
messageBody.location.latitude	String	纬度	否
messageBody.location.longitude	String	经度	否
messageId	String	腾讯侧消息ID	是

请求示例

{
  "seqId": "vwx234",
  "timestamp": 1234567891080,
  "spId": 60933,
  "userCode": "usercode123456",
  "spDriverId": "driver123456",
  "orderId": "trip123456",
  "partnerOrderId": "1234567890",
  "messageType": 0,
  "messageBody": {
    "text": "你好",
    "url": "图片URL/语音URL（duration记录语音时长）",
    "duration": 0
  },
  "messageId": "message123456",
  "tipType": 0
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是
data	SendImMessageResData	响应数据	是
data.spMessageId	String	服务商侧消息ID	是

响应示例

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

# 3.1.22 乘客单会话或部分消息已读通知服务商

接口说明

该接口有两种使用方式，优先使用方式一

会话已读：服务商通过腾讯侧userCode、订单ID、车主ID 参数确定会话，将该会话下所有消息进行已读。
部分消息已读：服务商若支持根据消息ID已读部分消息，腾讯侧传入spMessageIdList，服务商根据该部分ID进行已读操作。

请求地址
/im/passenger/read/session
请求参数

参数名称	类型	说明	必须
userCode	String	腾讯侧参与会话的用户userCode	是
orderId	String	会话关联的服务商订单ID	是
partnerOrderId	String	会话关联的腾讯侧订单ID	是
spDriverId	String	服务商车主ID	是
messageIdList	List<String>	腾讯侧消息ID列表	否
spMessageIdList	List<String>	服务商消息ID列表	否

请求示例

{
  "seqId": "yz1234",
  "timestamp": 1234567891090,
  "spId": 60933,
  "orderId": "trip123456",
  "partnerOrderId": "1234567890",
  "driverId": "driver123456",
  "userCode": "usercode123456",
  "messageIdList": ["message123456"],
  "spMessageIdList": ["spMessage123456"]
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是

响应示例

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

# 3.1.23 乘客全部已读通知服务商

接口说明

若服务商只通过腾讯侧userCode即可清除全部未读，则腾讯侧只提供userCode即可
（可选）若服务商支持通过消息ID全部已读，则可与腾讯侧商议传入消息ID列表

请求地址
/im/passenger/read/all
请求参数

参数名称	类型	说明	必须
userCode	String	腾讯侧参与会话的用户userCode	是
messageIdList	List<String>	腾讯侧消息ID列表（可选）	否
spMessageIdList	List<String>	服务商消息ID列表（可选）	否

请求示例

{
  "seqId": "yz1234",
  "timestamp": 1234567891090,
  "spId": 60933,
  "userCode": "usercode123456",
  "messageIdList": ["message123456"],
  "spMessageIdList": ["spMessage123456"]
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是

响应示例

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

# 3.1.24 上报用户经纬度位置

上报当前订单用户的经纬度信息
请求地址
/order/user/location/report
请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	用户标识
orderId	Y	String	服务商订单号
lon	Y	String	经度
lat	Y	String	纬度
orderStatus	Y	Integer	订单状态
reportTime	Y	Long	上报时间	单位ms

请求示例

{
  "orderId": "333333333333333333333",
  "userCode": "55555555555555",
  "lon": "65.12",
  "lat": "31.12",
  "orderStatus": 401,
  "reportTime":1740622672781
}

响应数据

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

响应示例

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

# 3.1.25 支付分关单通知

该接口适用于支付分扣款发起前发生了取消或退款，给服务商发支付分关单通知。

请求地址
/payscore/bill/close
请求参数

参数名称	类型	说明	必须
orderId	String	服务商订单号	是
partnerOrderId	String	腾讯侧订单号	是

请求示例

{
  "orderId": "1234567890",
  "partnerOrderId": "1234567890"
}

响应数据

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

响应示例

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

# 3.1.26 支付类型变更通知

该接口适用于腾讯侧用户在下单后开启或关闭支付分，将最新支付类型同步给服务商，服务商根据该变化为车主动态展示是否“已预付”。

请求地址
/pay/type/update
请求参数

参数名称	类型	说明	必须
orderId	String	服务商订单号	是
partnerOrderId	String	腾讯侧订单号	是
payType	Integer	支付类型 0-半屏支付，1-原生支付，2-支付分支付	是

请求示例

{
  "orderId": "",
  "partnerOrderId": "",
  "payType": 2
}

响应数据

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

响应示例

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

# 3.1.27 转账通知

该接口用于内部户功能，腾讯侧将订单完单转账结果同步给服务商，含行程费用转账结果、感谢费转账结果、高速费转账结果、爽约金转账结果的通知。
该接口需要保持幂等。
行程费用通知中包含感谢费的，会在感谢费字段中体现。优惠前行程费用=totalAmount-thanksFee。
请求地址
/order/notify/transfer
请求参数

参数名	必传	类型	描述	备注
userCode	Y	String	userCode
orderId	Y	String	服务商订单号
partnerOrderId	Y	String	腾讯侧订单号
notifyType	Y	Integer	通知类型	1、行程费用转账结果通知；2、爽约金转账结果通知；3、高速费转账结果通知
totalAmount	N	Integer	总费用	单位：分
discountAmount	N	Integer	优惠金额，有使用优惠券时有值	单位：分
paidAmount	N	Integer	优惠后支付金额	单位：分
thanksFee	N	Integer	感谢费	单位：分
transactionId	N	String	交易流水号
outTradeNo	N	String	商户订单号

请求示例

{
  "accessKey": "1111111111111111111",
  "nonce": "yWpEvqXKO0",
  "orderId": "333333333333333333333",
  "seqId": "7493d914-9567-4139-8848-96b0b7c6b34f",
  "sign": "22222222222222222",
  "spId": 60774,
  "timestamp": 1715735593153,
  "userCode": "55555555555555",
  "partnerOrderId": "66666666666666",
  "notifyType": 1,
  "totalAmount": 10000,
  "discountAmount": 1200,
  "paidAmount": 8800,
  "thanksFee": 0,
  "transactionId": "42000000000000000000111",
  "outTradeNo": ""
}

响应数据

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

响应示例

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

# 3.1.28 默勾结果同步

该接口用于将默勾结果同步给服务商。只有初始价格未进入默勾时才会同步，如果未进入默勾并且进行了调价，会同时设置调价结果。
请求地址
/estimate/price/selectResult
请求参数

参数名	必传	类型	描述
userCode	Y	String	userCode
spEstimateId	Y	String	服务商询价id
selectResult	Y	List	调价结果
selectResult[0].categoryCode	Y	Integer	服务商品类Code
selectResult[0].poolType	Y	Integer	对应腾讯侧拼车类型：1-独享, 2-拼车
selectResult[0].estimatePrice	Y	Integer	服务商询价返回的原始价格
selectResult[0].estimateMultiPrice	Y	Integer	服务商询价返回的原始价格（未拼成）
selectResult[0].priceSelectPolicy	N	Integer	服务商询价返回的价格选择策略
selectResult[0].estimateMinPrice	N	Integer	服务商询价返回的最低价格
selectResult[0].priceInSelect	Y	Integer	初始价格是否进入默勾 0: 否，1: 是
selectResult[0].adjustedPriceInSelect	N	Integer	调价后的价格是否进入默勾 0: 否，1: 是
selectResult[0].adjustedPrice	N	Integer	调整后价格
selectResult[0].maxInSelectPrice	Y	Integer	最高可默勾价格

priceSelectPolicy、estimateMinPrice、adjustedPriceInSelect、adjustedPrice在有调价时才有值

请求示例

{
  "userCode": "usercode123456",
  "spEstimateId": "b3c51d2e6133d514d9",
  "selectResult": [
    {
      "categoryCode": 2,
      "poolType": 2,
      "estimatePrice": 2500,
      "estimateMultiPrice": 2500,
      "priceSelectPolicy": 1,
      "estimateMinPrice": 2000,
      "priceInSelect": 1,
      "adjustedPriceInSelect": 1,
      "adjustedPrice": 2500,
      "maxInSelectPrice": 2800
    }
  ]
}

响应数据

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

响应示例

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

# 3.2 业务被调接口

注意：当调用腾讯侧接口返回状态码为22, 23, 26时，无需重试。

# 被调接口通用参数

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

# 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且使用了优惠券时有值
pkEndTime	Long	车主pk结束时间	eventType=89且status=280时有值，返回值为司机pk结束时刻（类型是秒级时间戳）
acceptCategoryCode	Integer	接单品类编码	司机接单时传，值需要在下单时传递的品类编码列表中

请求示例

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

响应数据

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

响应示例

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

# 3.2.2 返款(含退款)通知

使用场景:

用户支付时以未拼成价支付，实际拼车成功，在完单后需要给用户返款。
客服需要给用户部分退款，如司乘有纠纷。
refundType 为 2 时，eventType需要使用85-88
请求地址
/v1/callback/order/refund
请求参数

参数名称	类型	说明	必须
refundSerialId	String	退款流水号，原生支付部分退款时必填	否
refundType	Integer	退款类型.1-未拼成退款, 2-客服退款	是
refundPrice	Integer	返款金额，单位:分	是
multiPrice	Integer	接受合拼价(未拼成)，单位:分	refundType 为 1 时必传
multiSuccessPrice	Integer	合拼成功价，单位:分	refundType 为 1 时必传
refundDetail	String	退款详情[注意是string类型，json字符串]	行程费用和感谢费同时退款时必传
refundDetail[0].billFeeType	Integer	账单类型 1：行程费用，2：感谢费
refundDetail[0].refundPrice	Integer	退款金额，单位:分

说明：未避免复杂对象字段顺序导致双方签名不一致，refundDetail使用字符串类型，请将refundDetail转成json字符串传参

请求示例

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

请求示例2(行程费用和感谢费同时退)

{
  "refundPrice": 6000,
  "refundType": 2,
  "refundDetail": "[{\"billFeeType\":1,\"refundPrice\":5000},{\"billFeeType\":2,\"refundPrice\":1000}]"
}

响应数据

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

响应示例

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

# 3.2.3 车主eta信息变更通知

已下线

# 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	颜色	是
driverLastName	String	车主姓氏	否

注意：车辆颜色统一格式为: X色，如"白色"，"黑色"，"蓝色"等，不要直接传"白"、"黑"、"蓝"。

请求示例

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

响应数据

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

响应示例

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

# 3.2.5 高速费回调

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

请求地址
/v1/callback/highwayfee/pay
请求参数

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

请求示例

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

响应数据

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

响应示例

{
  "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\"}"
          }
      ]
  }
}

# 3.2.9 服务商支付通知回调

使用场景: 预付回调通知，通用参数中eventType=91

请求地址
/v1/callback/payment/notify
请求参数

参数名称	类型	说明	必须
payAmount	String	支付金额	是
payTime	Long	支付完成时间，秒级时间戳	否
paymentSerialId	String	支付流水号，幂等	是

请求示例

{
    "payAmount": "1016",
    "payTime": 1723552800,
    "paymentSerialId": "1273014402707222528"
}

响应数据

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

响应示例

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

# 3.2.10 原生支付账单查询

使用场景: 原生支付账单查询接口，通过服务商订单id查询订单在腾讯侧的账单信息以及账单状态，通用参数中eventType=92

请求地址
/v1/callback/bill/query
请求参数

参数名称	类型	说明	必须
billFeeType	Integer	账单类型，1.订单金额，2感谢费，3.高速费，4.违约金，为0时，查询所有	是

请求示例

{
    "billFeeType": 0
}

响应数据

参数名称	类型	说明	必须
data.spOrderId	Integer	服务商订单id	是
data.feeTypeList[].billFeeType	Integer	账单类型，1.订单金额，2感谢费，3.高速费，4.违约金	是
data.feeTypeList[].paidFee	Integer	已支付金额，单位：分	是
data.feeTypeList[].refundedFee	Integer	退款金额，单位：分	是
data.feeTypeList[].discountFee	Integer	折扣金额，单位：分	是
data.feeTypeList[].billStatus	Integer	账单状态：10.待支付，20.部分支付，30.已支付，40.支付单关闭，50.待退款，60.部分退款，70.已退款，80.退款关闭	是
data.feeTypeList[].spMerchantPackage	String	服务商商户数据包	是
data.feeTypeList[].records[].amount	Integer	金额	是
data.feeTypeList[].records[].completeTime	Long	完成时间	是
data.feeTypeList[].records[].state	Integer	流水状态：10.待支付，20.部分支付，30.已支付，40.支付单关闭，50.待退款，60.部分退款，70.已退款，80.退款关闭	是
data.feeTypeList[].records[].transactionId	String	微信流水号	是
data.feeTypeList[].records[].type	Integer	流水类型：1.支付记录，2.退款记录，3.补差记录，4补差退款记录	是

响应示例

{
    "code": 0,
    "data": {
        "feeTypeList": [
            {
                "billFeeType": 1,
                "billStatus": 70,
                "discountFee": 500,
                "paidFee": 1746,
                "records": [
                    {
                        "amount": 1746,
                        "completeTime": "1734069789000",
                        "state": 30,
                        "transactionId": "42000024132024121320483251xx",
                        "type": 1
                    },
                    {
                        "amount": 1746,
                        "completeTime": "1734090137000",
                        "state": 70,
                        "transactionId": "503034016320241213017923320xx",
                        "type": 2
                    },
                    {
                        "amount": 500,
                        "completeTime": "0",
                        "state": 10,
                        "transactionId": "",
                        "type": 3
                    }
                ],
                "refundedFee": 1746,
                "spMerchantPackage": "17497186349990543xx"
            }
        ],
        "spOrderId": "1749718626409119748"
    },
    "message": "success"
}

# 3.2.11 原生支付账单下载

使用场景: 原生支付账单下载

请求地址
/v1/callback/bill/download
请求参数

字段名	字段类型	最大长度	必填	说明
accessKey	String	32	是	腾讯出行服务分配给服务商调用 accessKey
spId	Integer	11	是	腾讯出行服务分配给服务商的 id
seqId	String	36	是	请求流水号,调用方自动生成一个随机 ID，建议使用 uuid
timestamp	Long	20	是	请求发送时的时间戳(unix 时间戳) 毫秒
nonce	String	10	是	10 位随机字符串
sign	String	32	是	验证签名参数
billType	Integer	32	是	账单类型 1: 第三方原始交易账单; 2: 第三方原始资金账单; 3 第三方原始二级商户资金账单; 4: 第三方原始交易成功账单; 5: 第三方原始交易退款账单; 6: 第三方原始提现异常账单; 7: 第三方原始分账账单; 8:子商户第三方原始资金账单
billDate	String	32	是	账单时间，时间格式yyyymmdd。这个时间是UTC格式，示例 20010102
subMchId	String	32	否	要下载账单的商户号，此字段不传，默认取spId绑定的顺风车业务的商户号

请求示例

{
    "appVersion": "consequat esse amet deserunt laboris",
    "billDate": "magna mollit",
    "billType": 67050761,
    "spId": 27764943,
    "traceId": "enim",
    "userCode": "ex voluptate Duis"
}

响应数据

参数名称	类型	说明	必须
data.billDownloadInfoList[].downloadUrl	String	账单下载地址	是
data.billDownloadInfoList[].fileName	String	文件名称	是
data.billDownloadInfoList[].hashType	Integer	1，sha1 hash类型；2，md5 hash类型	是
data.billDownloadInfoList[].hashValue	String	哈希值, 文件的摘要值，用于校验文件的完整性	是

响应示例

{
    "code": 15938271,
    "data": {
        "billDownloadInfoList": [
            {
                "downloadUrl": "cupidatat ullamco veniam cillum",
                "fileName": "nostrud cillum irure consequat",
                "hashType": -34850229,
                "hashValue": "eu veniam"
            }
        ]
    },
    "message": "eiusmod reprehenderit"
}

# 3.2.12 通话记录同步接口

该接口用于服务商同步司乘通过电话联系后的通话记录及状态信息。注：该接口driverId必传，eventType=84

请求地址
/v1/callback/call/record/sync
请求参数

参数名称	类型	说明	必须
srcPhone	String	主叫号码	是
destPhone	String	被叫号码	是
caller	Intger	主叫人 1-乘客，2-车主	是
callTime	Long	通话时间，毫秒级时间戳	是
callStatus	Integer	详见"通话状态枚举"	是
callStatusDesc	String	详见"通话状态枚举"	是

请求示例

{
  "srcPhone": "",
  "destPhone": "",
  "caller": 1,
  "callTime": 1720173600000,
  "callStatus": 1,
  "callStatusDesc": "正常接通"
}

响应数据

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

响应示例

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

通话状态枚举

枚举值	枚举描述
1	正常接通
2	关机
3	停机
4	空号
5	主叫提前关机
6	暂时无法接通
7	无人接听
8	被叫忙
9	被叫拒接
10	被叫不可及
11	线路忙
12	无权限呼叫
13	无绑定关系
14	网络忙
15	路由失败
16	中间号状态异常
27	运营商黑名单/超频
-1	其他

# 3.2.13 服务商车主发送IM消息给乘客

接口说明

车主信息用于消息界面的信息展示，其中车主ID、昵称、车型、颜色为必传项，性别和头像建议传递，若不传递腾讯侧使用兜底展示。
若服务商内部的每条消息会对应一个ID，建议将messageId传递到腾讯侧。

请求地址
/v1/callback/im/driver/send
请求参数

参数名称	类型	说明	必须
orderId	String	会话关联的订单ID（腾讯侧）	是
spOrderId	String	会话关联的订单ID（服务商侧）	是
driverInfo	SpDriverInfo	服务商司机信息	是
driverInfo.driverId	String	服务商司机ID	是
driverInfo.nickname	String	由姓氏+称呼构成，eg:李先生	是
driverInfo.gender	Integer	司机性别，1男，2女	否
driverInfo.avatarUrl	String	服务商司机头像URL	否
driverInfo.vehicleModel	String	车型号 eg:特斯拉	是
driverInfo.vehicleColor	String	车颜色	是
messageType	Integer	消息类型文字0/图片1/定位2	是
messageBody	MessageBody	消息内容	是
messageBody.text	String	文本消息	否
messageBody.url	String	图片/语音URL	否
messageBody.duration	Integer	语音时长	否
messageBody.location	Location	定位信息	否
messageBody.location.address	String	定位地址详情	否
messageBody.location.name	String	定位地址名	否
messageBody.location.latitude	String	纬度	否
messageBody.location.longitude	String	经度	否
spMessageId	String	服务商生成的消息ID	否

请求示例

{
  "seqId": "stu234",
  "timestamp": 1234567891023,
  "spId": 60933,
  "userCode": "driverTrip123456",
  "driverInfo": {
    "driverId": "123456",
    "nickname": "李先生",
    "vehicleModel": "特斯拉 Model Y",
    "vehicleColor": "白色"
  },
  "orderId": "trip123456",
  "spOrderId": "sptrip123456",
  "messageType": 0,
  "messageBody": {
    "text": "你好，欢迎上车！"
  },
  "spMessageId": "msg123456"
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是
data	Object	响应数据	是
data.messageId	String	腾讯侧消息ID	是

响应示例

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

# 3.2.14 服务商车主单会话已读

请求地址
/v1/callback/im/driver/read/session
请求参数

参数名称	类型	说明	必须
orderId	String	腾讯侧订单ID	是
spOrderId	String	会话关联的订单ID（服务商侧）	是
spDriverId	String	服务商车主ID	是
userCode	String	腾讯侧参与会话的用户userCode	是
messageIdList	List<String>	腾讯侧消息ID列表（可选支持）	否
spMessageIdList	List<String>	服务商消息ID列表（可选支持）	否

请求示例

{
  "seqId": "stu234",
  "timestamp": 1234567891023,
  "spId": 60933,
  "orderId": "trip123456",
  "spOrderId": "sptrip123456",
  "spDriverId": "driver001",
  "userCode": "driverTrip123456",
  "messageIdList": ["string1", "string2"],
  "spMessageIdList": ["string1", "string2"]
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是

响应示例

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

# 3.2.15 服务商车主全部已读

请求地址
/v1/callback/im/driver/read/all
请求参数

参数名称	类型	说明	必须
spDriverId	String	服务商车主ID	是
messageIdList	List<String>	腾讯侧消息ID列表（可选支持）	否
spMessageIdList	List<String>	服务商消息ID列表（可选支持）	否

请求示例

{
  "seqId": "stu234",
  "timestamp": 1234567891023,
  "spId": 1001,
  "spDriverId": "driver001"
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是

响应示例

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

# 3.2.16 查询订单IM类型

该接口用于原生IM功能灰度放量期间查询该单实际使用的IM类型，避免腾讯侧和SP侧功能不一致。

请求地址
/v1/callback/order/im/type
请求参数

参数名称	类型	说明	必须
userCode	String	腾讯侧参与会话的用户userCode	是
orderId	String	腾讯侧订单ID	是
spOrderId	String	会话关联的订单ID（服务商侧）	否

请求示例

{
  "seqId": "stu234",
  "timestamp": 1234567891023,
  "spId": 60933,
  "orderId": "trip123456",
  "userCode": "user1234456"
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是
data	Object	响应数据	是
data.imType	Integer	IM类型（0-非原生，1-原生）	是

响应示例

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

# 3.2.17 服务商更新车主虚拟号

请求地址
/v1/callback/driver/phone/update
请求参数

参数名称	类型	说明	必须
mobilePhone	String	车主手机号。需加密，腾讯收到后解密	是

请求示例

{
  "seqId": "stu234",
  "timestamp": 1234567891023,
  "mobilePhone":"Mw2313412ssa",
  "spId": 600010,
  "orderId": "orderIdxxxx",
  "spOrderId":"spOrderIdxxxx",
  "userCode": "xxxxx123456",
  "eventType":93,
  "driverOrderId":"xxxxx"
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是

响应示例

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

# 3.2.18 查询订单信息

请求地址
/v1/callback/order/info/query
请求参数

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

请求示例

{
  "spId": 60723,
  "orderId": "7206194011589672964",
  "spOrderId": "166808204900408",
  "userCode": "sghdgdhadggda7236e76763764726377"
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是
data	Object	响应数据	是
data.status	Integer	腾讯订单状态，详见订单状态	是

响应示例

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

# 3.2.19 违约金支付通知

请求地址
/v1/callback/blameAmount/pay
请求参数

参数名称	类型	说明	必须
`eventType`	Integer	事件类型	是
`orderId`	String	腾讯侧订单ID	是
`spOrderId`	String	服务商侧订单ID	是
`operationTime`	Long	爽约金操作时间	是
`blameAmount`	Long	爽约金金额，单位：分	是
`blameStatus`	Integer	1-车主发起追款，2-车主取消追责，3-客服取消追责，4-已支付，5-申诉中，6-申诉成功免责，7-申诉失败	是
`userCode`	String	用户code	是
`paySerialId`	String	支付流水id	是
`appealUrl`	String	申诉链接	是

请求示例

{
    "spId": 60708,
    "traceId": "c46688dc-1054-478c-816a-xxxx",
    "timestamp": "1753079823",
    "eventType": 57,
    "orderId": "xxx",
    "spOrderId": "xxx",
    "operationTime": "1753079822690",
    "blameAmount": 520,
    "blameStatus": 4,
    "userCode": "208137713",
    "appealUrl": "hitch/pages/MyWebView/MyWebView?xxx"
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是

响应示例

{
    "code": 0,
    "message": "success"
}

# 3.2.20 订单ID查询

请求地址
/v1/callback/order/id/query
请求参数

参数名称	类型	说明	必须
`spId`	Integer	服务商ID	是
`traceId`	String	请求唯一标识	是
`transactionId`	String	支付流水号，如果payScoreNo为空则必须传	否
`payScoreNo`	String	服务单号（支付分单号），如果 transactionId 为空则必须传	否

请求示例

{
    "payScoreNo": "",
    "spId": 1234,
    "traceId": "sdfjasdlk-sdfsdf-xxxxx",
    "transactionId": "420000xxxxxxx"
}

响应数据

参数名称	类型	说明	必须
code	Integer	响应状态码	是
message	String	响应信息	是
data	Object	响应数据	是
data.orderId	String	腾讯侧订单ID	是
data.spOrderId	String	服务商订单ID	否

响应示例

{
    "code": 0,
    "data": {
        "orderId": "xxxx",
        "spOrderId": "xxxxx"
    },
    "message": "success"
}

# 3.2.21 同步订单外部支付账单流水

使用场景:

用于在服务商侧支付的订单对账流水信息的同步，同步「支付金额」、「退款金额」
请求地址
/v1/callback/order/spbill/sync
请求参数

参数名称	类型	说明	必须
syncId	String	同步流水号，用以请求幂等	是
billDetailList	List	账单详情列表	是

BillDetailDto

参数名称	类型	说明	必须
feeType	Integer	费用类型：1.行程费用，2感谢费，3.高速费，4.违约金	是
paidAmount	Integer	实际支付金额	是
refundAmount	Integer	实际退款金额	是
spDiscountFee	Integer	服务商侧优惠金额	否
discountFee	Integer	腾讯侧优惠金额	否
operationTime	Integer	账单操作时间，毫秒级时间戳	是

请求示例

{
  "accessKey": "your_access_key_here",
  "spId": 123456,
  "seqId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1741564800000,
  "nonce": "a1b2c3d4e5",
  "sign": "生成的签名字符串",
  "orderId": "TX202603100001",
  "spOrderId": "SP202603100001",
  "userCode": "userCode",
  "status": 901,
  "eventType": 81,
  "syncId": "SYNC202603100001",
  "billDetailList": [
    {
      "feeType": 1,
      "paidAmount": 5000,
      "refundAmount": 0,
      "spDiscountFee": 500,
      "discountFee": 300,
      "operationTime": 1741564800123
    },
    {
      "feeType": 3,
      "paidAmount": 2000,
      "refundAmount": 0,
      "spDiscountFee": 0,
      "discountFee": 200,
      "operationTime": 1741564800456
    }
  ]
}

响应数据

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

响应示例

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

# 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.1.6 创建报警工单

创建报警工单。

请求地址 /work/alarm/create
请求参数

名称	必须	类型	描述	备注
userId	Y	String	用户标识
orderId	Y	String	腾讯侧订单id
spOrderId	Y	String	运力商订单id
userPhone	Y	String	用户手机号	加密传输
workCategoryId	Y	Long	腾讯工单分类 id	固定值 739309137690828806
workCategoryName	Y	String	腾讯工单问题分类	固定值 110报警
address	N	String	用户当前位置	获取不到不传
lon	N	String	用户当前位置经度	获取不到不传
lat	N	String	用户当前位置纬度	获取不到不传

响应数据

名称	类型	描述	备注
code	Integer	业务状态码
message	String	业务消息
data	Object
data.spWorkId	String	运力商工单号	创建成功必须返回

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "spWorkId": "SpAlarm123456789"
  }
}

# 5.1.7 车主黑名单数据同步

同步车主黑名单数据给服务商，服务商需要根据黑名单数据，限制车主接单。车主A被用户B拉黑的表现

A看不到B发布的行程
B在可邀请车主列表看不到A的行程
A无法接B的行程单

其他说明：

车主黑名单以车牌号作为车主标识。
接口通用参数如签名、seqId等请参考其他接口
腾讯侧调用接口如果超时或者服务商返回非0错误码，腾讯侧会进行重试，服务商需要保证接口幂等。可通过plateNo+userCode来作为唯一key来保证幂等，即相同的plateNo+userCode只会有一条数据。

请求地址 /riskcontrol/driver/blacklist/sync
请求参数

名称	是否必须	参数类型	说明	备注
operationType	Y	Integer	操作类型 1: 全量同步 2: 新增(更新) 3: 删除
driverBlacklist	Y	String	车主黑名单列表。	未避免嵌套对象序列化后字段顺序不同，导致签名校验不通过，此字段设计为String类型，实际内容为json列表，服务商需要使用String接收然后自行解析内容。
driverBlacklist[0].plateNo	Y	String	车牌号
driverBlacklist[0].userCode	N	String	只针对单个用户拉黑司机时，此字段有值，若字段为空字符串，表示对所有用户拉黑。	对单用户拉黑，司机不能接此用户的单，但可以接其他用户的单。
driverBlacklist[0].controlReason	Y	String	拉黑原因，中文描述
driverBlacklist[0].expireTime	Y	Long	失效时间，毫秒时间戳 -1 表示一直生效

对operationType的说明：

operationType=1为全量同步，服务商需要确保同步时把所有存量数据都删除，然后插入此次同步的数据。设计此类型是考虑因为一些网络等原因导致有些数据同步失败，长期累积可能导致双方数据出现较多不一致。通过全量同步重新拉通数据。一般情况下不会使用此类型。
operationType=2为增量新增，服务商做新增即可，如果车牌号已经同步过，则需要做更新操作（根据plateNo+userCode作为唯一key更新）。
operationType=3为删除，服务商需要在黑名单库中删除driverBlackList中的车牌号（根据plateNo+userCode作为唯一key删除）。
请求示例

{
  "operationType": 2,
  "driverBlacklist": "[{\"plateNo\":\"京A12345\",\"userCode\":\"ab45b294ac2df29f3e1cddffe7d3f0a\",\"controlReason\":\"车辆信息不符\",\"expireTime\":1715333551000},{\"plateNo\":\"京A12346\",\"userCode\":\"\",\"controlReason\":\"司机拒载\",\"expireTime\":1715333551000}]",
}

响应数据

名称	类型	描述	备注
code	Integer	业务状态码
message	String	业务消息

响应示例

{
  "code": 0,
  "message": "success"
}

# 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"
}

# 5.2.2 回调同步报警工单状态

请求地址 /v1/callback/work/alarm/update
请求参数

参数名称	必须	类型	描述	备注
userId	Y	String	用户标识
spId	Y	Integer	腾讯出行服务分配给服务商的 id
spWorkId	Y	String	运力商工单号
orderId	Y	String	腾讯侧订单id
spOrderId	Y	String	运力商订单id
operator	Y	String	处理人	人工、智能外呼
status	Y	Integer	处理状态	就同步两个状态：3 跟进、4 关闭
optResult	Y	String	处理结果	危险、非危险
optReason	Y	String	处理原因	客服手工输入，通常为“勿点击”、“完单了”等
userPhone	Y	String	用户手机号
address	N	String	位置	获取不到不传
lon	N	String	经度	获取不到不传
lat	N	String	纬度	获取不到不传

请求示例

{
  "userId": "xxxx",
  "spId": 60723,
  "workId": "xxxx",
  "spWorkId": "xxx",
  "orderId": "xxxx",
  "spOrderId": "xxx",
  "operator": "人工",
  "status": 3,
  "optResult": "危险",
  "optReason": "完单了",
  "position": "xxxx",
  "lon": "65.12",
  "lat": "31.12",
  "userPhone": "xxxx"
}

响应数据

名称	类型	描述
code	Integer	业务状态码
message	String	业务消息
data	Object

响应示例

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

# 6. 优惠券

优惠券采用腾讯商家券的形式发放和核销，服务商无需关注。腾讯测会在用户支付环节将订单所用的优惠信息同步给服务商。

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

# 7. 半屏拉起跳转链接

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

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

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

备注

服务商需提供相关页面的链接，以及相关页面所需携带的参数。比如from、orderId等等。
服务商小程序有能承接上述功能的页面即可，不用一一对应。比如"确认支付页"、"行程中页面"可以是一个页面，也可以是两个页面。

# 8. 协议链接

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

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

# 9. 附录

# 9.1 服务商列表

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

# 9.2 订单状态

订单状态码	状态说明
101	创建订单
201	派单中
206	改派中
280	司机pk中
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	合拼信息同步
84	通话记录同步
85	行程费用退款
86	感谢费退款
87	高速费退款
88	违约金退款
89	司机pk举手
90	pk失败，订单流拍
91	行程费用预付
92	原生支付账单查询
93	服务商更新司机虚拟号

# 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	低

# 9.9 签名

以下代码仅为示例，以实际联调过程中双方沟通结论为准。

服务商接收到腾讯侧请求，无需转换对象，直接将这个请求JSON串传入requestSign(String requestStr, String secret)方法计算得到签名sign。注：为保证结果一致，建议使用相同的JSON工具。

import org.apache.commons.lang3.StringUtils;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import java.util.TreeMap;

/**
 * 验签
 */
public class SignUtil {

    private static final String MD5 = "MD5";

    /**
     * 请求签名算法入口
     * @param requestStr
     * @param secret
     * @return
     */
    public static String requestSign(String requestStr, String secret) {
        Map<String, Object> paramsMap = JsonTool.toObj(requestStr, TreeMap.class);
        Map<String, String> params = new HashMap<>();
        String[] keys = paramsMap.keySet().toArray(new String[0]);
        for (String key : keys) {
            if (org.apache.commons.lang3.StringUtils.isNotBlank(key)) {
                String value = paramsMap.get(key).toString();
                if (null != value) {
                    params.put(key.trim(), value);
                }
            }
        }
        params.remove("sign");
        return sign(params, secret);
    }

    /**
     * 签名算法核心
     * @param params
     * @param secret
     * @return
     */
    public static String sign(Map<String, String> params, String secret) {
        // 第一步：检查参数是否已经排序
        String[] keys = params.keySet().toArray(new String[0]);
        Arrays.sort(keys);
        // 第二步：把所有参数名和参数值串在一起
        StringBuilder sb = new StringBuilder();
        for (String key : keys) {
            if (StringUtils.isNotBlank(key)) {
                String value = params.get(key);
                if (null != value) {
                    sb.append(key.concat("="));
                    sb.append(value.concat("&"));
                }
            }
        }
        sb.append("apiSercret=" + secret);
        return toHex(getMd5(sb.toString()));
    }

    private static String toHex(byte[] byteArray) {
        if (null == byteArray) {
            return null;
        }
        StringBuilder md5Str = new StringBuilder();
        for (byte b : byteArray) {
            md5Str.append(String.format("%02x", b));
        }
        return md5Str.toString().toUpperCase();
    }

    private static byte[] getMd5(String str) {
        MessageDigest messageDigest;
        try {
            messageDigest = MessageDigest.getInstance(MD5);
            messageDigest.reset();
            messageDigest.update(str.getBytes(StandardCharsets.UTF_8));
        } catch (NoSuchAlgorithmException e) {
            return new byte[0];
        }
        return messageDigest.digest();
    }
}

JSON工具类：

import com.fasterxml.jackson.annotation.JsonInclude.Include;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.MapperFeature;
import com.fasterxml.jackson.databind.ObjectMapper;

/**
 * json tools
 */
public class JsonTool {

    private static final ObjectMapper objectMapper;

    static {
        objectMapper = new ObjectMapper();
        objectMapper.setDefaultPropertyInclusion(Include.NON_NULL);
        objectMapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
        objectMapper.enable(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY);
    }

    public static String toJson(Object obj) {
        try {
            return objectMapper.writeValueAsString(obj);
        } catch (Exception ex) {
            throw new RuntimeException("序列化异常");
        }
    }

    public static <T> T toObj(String json, Class<T> valueType) {
        try {
            return objectMapper.readValue(json, valueType);
        } catch (Exception ex) {
            throw new RuntimeException("反序列化异常");
        }
    }

}

← 打车代驾 →

# 顺风车

# 1. 版本历史

# 2. 基础说明

# 2.1 接口协议

# 2.2 返回数据格式

# 2.3 字符编码

# 2.4 请求格式

# 2.5 重试机制

# 2.6 通用参数

# 2.7 通用返回值

# 2.8 鉴权说明

# 2.9 注意事项

# 2.10 服务环境

# 2.11 数据加密

# 2.12 坐标系

# 2.13 城市编码

# 2.14 单位

# 2.15 重试机制

# 2.16 接口分类

# 3.1 业务主调接口

# 通用结构

# Position

# DriverInfo

# 3.1.1 查询开城列表

# 3.1.2 询价

# CategoryInfo 结构

# 3.1.3 创建订单

# 3.1.4 取消订单

# 3.1.5 查询可邀请司机列表（旧，即将废弃）

# 3.1.5 查询可邀请司机列表（新）

# 3.1.6 乘客邀请车主

# 3.1.7 查询订单详情

# 3.1.8 确认上车

# 3.1.9 确认下车

# 3.1.10 查询司机虚拟号

# 3.1.11 乘客变更联系方式

# 3.1.12 查询IM信息列表

# 3.1.13 查询行程ETA信息

# 3.1.14 支付通知

# 3.1.15 退款通知

# 3.1.16 查询订单可退款信息

# 3.1.17 添加感谢费

# 3.1.18 同步订单评价信息

# 3.1.19 支付分创单成功通知

# 3.1.20 发起扣款通知

# 3.1.21 乘客发送消息 通知服务商

# 3.1.22 乘客单会话或部分消息已读 通知服务商

# 3.1.23 乘客全部已读 通知服务商

# 3.1.24 上报用户经纬度位置

# 3.1.25 支付分关单通知

# 3.1.26 支付类型变更通知

# 3.1.27 转账通知

# 3.1.28 默勾结果同步

# 3.2 业务被调接口

# 被调接口通用参数

# 3.2.1 状态变更通知

# 3.2.2 返款(含退款)通知

# 3.2.3 车主eta信息变更通知

# 3.2.4 IM消息通知

# 3.2.5 高速费回调

# 3.2.6 合拼信息回调

# 3.2.7 同步订单财务信息字段

# 3.2.8 查询订单财务信息

# 3.2.9 服务商支付通知回调

# 3.2.10 原生支付账单查询

# 3.2.11 原生支付账单下载

# 3.2.12 通话记录同步接口

# 3.2.13 服务商车主发送IM消息给乘客

# 3.2.14 服务商车主单会话已读

# 3.2.15 服务商车主全部已读

# 3.2.16 查询订单IM类型

# 3.2.17 服务商更新车主虚拟号

# 3.2.18 查询订单信息

# 3.2.19 违约金支付通知

# 3.2.20 订单ID查询

# 3.2.21 同步订单外部支付账单流水

# 4. 数据解密接口

# 5. 工单接口列表

# 5.1 主调接口

# 5.1.1 创建工单

# 3.1.21 乘客发送消息通知服务商

# 3.1.22 乘客单会话或部分消息已读通知服务商

# 3.1.23 乘客全部已读通知服务商