腾讯出行服务·开放平台

# 打车

# 通用说明

  1. 接口传输协议

采用 HTTPS（超文本传输安全协议）协议

  1. 字符编码

字符编码统一为 UTF-8

  1. 请求方法

请求方法统一为 POST

  1. 数据格式

请求及返回内容类型（Content-Type）统一为 application/json; charset=utf-8 请求及返回数据格式采用 JSON 格式

  1. 城市编码 参考附录 7
  2. 坐标系

地图坐标系采用 GCJ-02 坐标系。

  1. 日期时间格式 参考附录 8。
  2. 消息通知

微信服务通知、手机短信通知，全部由腾讯出行完成，无需运力商向用户发送。

# 接口调用说明

  1. 请求地址

运力商提供的接口地址，可以自定义域名以及路径前缀，即文档中的<sp_url_prefix>，示 例：

仅域名的方式：https://api.example.com

包含路径前缀的方式：https://api.example.com/path/to/prefix

  1. 通用入参
参数名 类型 长度 必选 说明
version string 10 Y 接口版本，统一为 1.0.0
appId string 32 Y 运力方标识，由腾讯出行提供
timestamp long 20 Y 请求的 Unix时间戳（毫秒），有效期 1 分钟
nonce string 32 Y 随机字符串，需保证 1 分钟内唯一
sign string 40 Y 签名，采用 HMAC-SHA1算法
data object N 业务参数对象
  1. 通用出参
参数名 类型 长度 必选 说明
code int 10 Y 参考附录 5
message string 64 N 参考附录 5
data object N 业务参数对象
requestId string 64 N 请求 ID
  1. 签名算法
    1. 将 appId，timestamp，nonce，version 以及 data 中的所有参数（不包括 object、list、 及值为 null 的参数）按照字母顺序升序排列
    2. 依次将升序排列后的 key, value 使用 "=" 和 "&" 符号连接起来，生成新的字符串 key1=value1&key2=value2&key3=value3....&keyn=valuen
    3. 使用 appSecret 作为 key，计算 2 中生成字符串的 HMAC-SHA1散列值，转换为 16 进 制小写字符串，作为 sign
    4. 将 sign 作为参数加入到入参中，访问接口。
  2. 签名算法示例

假如访问订单详情接口，appSecret 为 "test_123456"，请求体为：

{ 

  "version": "1.0.0", 
  "appId": "test", 
  "timestamp": 1658973463326, 
  "nonce": "toUPcjOB6+tLwQ", 
  "data": { 
    "orderId": "123456789",
    "spOrderId": "987654321" 
  } 
}

则 sign 计算方法如下：

  1. 将 data 中的参数以及 version，appId，timestamp，nonce 按照字母顺序升序排列，使 用“=”，“&”符号连接起来生成新的字符串（data 中的 object, array 及值为 null 的 参数不参与签名）：
appId=test&nonce=toUPcjOB6+tLwQ&orderId=123456789&spOrderId=987654321 &timestamp=1658973463326&version=1.0.0
  1. 将 appSecret 作为 key，计算如上字符串的 HMAC-SHA1值，转换为 16 进制小写字符 串，作为 sign
sign = HMAC-SHA1("appId=test&nonce=toUPcjOB6+tLwQ&orderId=123456789&spOrderId=987 654321&timestamp=1658973463326&version=1.0.0", "test\_123456")

结果为：

curl -XPOST \
-H "Content-Type: application/json; charset=utf-8" \ <sp_url_prefix>/api/order/detail \ 
-d '{ 
    "version": "1.0.0", 
    "appId": "test", 
    "timestamp": 1658973463326,
    "nonce": "toUPcjOB6+tLwQ", 
    "sign": "143f2a38bdf192524b916a73bd48c96e5a200b12", 
    "data": { 
      "orderId": "123456789", 
      "spOrderId": "987654321" 
    } 
  }'

# 运力商提供接口文档

  1. 开城列表

  • 接口说明 运力商提供，腾讯出行向运力商调用，获取开城列表及每个城市支持的运力类型，服务类型

  • 请求地址 <sp_url_prefix>/api/city/open

  • 请求参数(data)

参数名称 类型 长度 必选 说明
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y
message string 64 N
data object
-.cities array object Y
---.cityCode string 10 Y 城市编码，参考附录 7
---.cityName string 30 Y 城市名称，参考附录 7
---.rideTypes array object Y
-----.id int Y 参考附录 3
-----.name string 10 Y
-----.serviceTypes array int Y 支持的服务类型，参考附录 2
requestId string 64 N 请求 ID
  1. 预估价格
  • 接口说明 运力商提供，腾讯出行向运力商调用，获取预估价格
  • 请求地址 <sp_url_prefix>/api/estimate/price
  • 请求参数(data)
参数名称 类型 长度 必选 说明
cityCode string 10 Y 出发地城市编码
startLat double Y 出发地纬度
startLng double Y 出发地经度
startName string 50 Y 出发地名称
startAddress string 100 Y 出发地详细地址
endLat double Y 目的地纬度
endLng double Y 目的地经度
endName string 50 Y 目的地名称
endAddress string 100 Y 目的地详细地址
serviceType int Y 服务类型，参考附录 2
rideType string 100 N 运力类型，多个运力类型使用逗号分 隔，参考附录 3
departureTime string 20 N 出发时间，日期时间格式，比如： 2022-08-01 15:00:00， 默认为当前时 间，参考附录 8
flightNo string 10 N 航班号，比如：CA1564
flightDate string 10 N 航班起飞日期，比如：2022-08-01，参 考附录 8
delayTime int N 落地后多长时间出发，单位为秒，接机 单必传
airportCode string 10 N 到达机场 IATA三字码，接机单必传
  • 返回数据
参数名称 类型 长度 必选 说明
code
int Y
message string 64 N
data object
-.distance int Y 行驶距离，单位：米
-.duration int Y 预计行驶时间，单位：秒
-.prices array object Y
---.rideType int Y 运力类型
---.estimatePrice int Y 预估价格，单位：分
---.estimateId string 40 Y 预估价格标识，创建订单时腾讯出行需提供该参数，由运力商进行校 验，过期则下单失败，如果 estimateId 过期或行程有变化，必 须重新预估价格
---.dynamicRate double N 动态调价倍率
---.chargeType int N 计价类型，默认为 1-普通计费，参 考附录 4
---.details array object N 价格明细
-----.name string 30 Y 明细项名称
-----.amount int Y 明细项金额，单位：分
requestId string 64 N 请求 ID
  1. 创建订单
  • 接口说明 运力商提供，腾讯出行向运力商调用，创建订单。
  • 请求地址 <sp_domain>/api/order/create
  • 请求参数（data）
参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单号，防止重复创建订单
cityCode string 10 Y 城市编码，参考附录 7
startLat double Y 出发地纬度
startLng double Y 出发地经度
startName string 50 Y 出发地名称
startAddress string 100 Y 出发地详细地址
endLat double Y 目的地纬度
endLng double Y 目的地经度
endName string 50 Y 目的地名称
endAddress string 100 Y 目的地详细地址
serviceType int Y 服务类型，参考附录 2
estimateIds string 500 Y 预估价格标志，多个 estimateId 使用逗 号分隔，每个 estimateId 对应一个车 型，不再单独提供运力类型参数，若 estimateId 过期（建议有效期：10 分 钟）或者行程有变化则无法创建订单， 需要重新预估价格获取 estimateId
departureTime string 20 N 乘车时间，日期时间格式，比如 2022- 08-01 14:00:00，默认为当前时间，参考 附录 8
userId string 20 Y 叫车人用户 ID
userMobile string 20 Y 叫车人手机
passengerMobile string 20 Y 乘车人手机
passengerName string 20 Y 乘车人姓名
message string 50 N 乘客给司机留言，最长 50 个字符
flightNo string 10 N 航班号
flightDate string 10 N 航班起飞日期，比如：2022-08-01，参 考附录 8
delayTime int N 落地后多长时间用车，单位（S），接机 单必传
airportCode string 10 N 到达机场 IATA三字码，接机单必传
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y
message string 64 N
data object
-.orderId string 32 Y 腾讯出行订单 ID
-.spOrderId string 32 Y 运力商订单 ID
requestId string 64 N 请求 ID
  1. 订单详情

  • 接口说明 运力商提供，腾讯出行向运力商调用，查询订单详情，任何订单状态都可能会发起查询。

  • 请求地址 <sp_url_prefix>/api/order/detail

  • 请求参数(data)

参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
  • 返回数据
参数名称 类型 长度 必选 说明
code int
message string 64
data object
-.orderId string 32 Y 腾讯出行订单 ID
-.spOrderId string 32 Y 运力商订单 ID
-.status int Y 订单状态，参考附录 1.1
-.cancelType int N 取消编码，参考附录 6
-.serviceType int Y 服务类型，参考附录 2 服务类型
-.rideType int Y 运力类型，参考附录 3 运力类型
-.chargeType int Y 计价类型，参考附录 4 计价类型
-.distance int N 实际行程距离，单位为米， status=8,9 必选
-.duration int N 实际行程时长，单位为秒， status=8,9 必选
-.estimatePrice int Y 预估价格，单位为分
-.estimateDistance int N 预估行驶里程，单位为米
-.estimateDuration int N 预估行驶时长，单位为秒
-.flightNo string 10 N 航班号
-.flightDate string 10 N 航班起飞日期，比如： 2022-08- 01，参考附录 8
-.delayTime int N 落地后多长时间用车，单位为秒，接 机单必传
-.airportCode string 10 N 到达机场三字码，接机单必选
-.acceptTime string 20 N 司机接单时间，日期时间格式，参考 附录 8
-.setOutTime string 20 N 司机出发时间，日期时间格式，参考 附录 8
-.arriveTime string 20 N 司机到达上车点时间 ，日期时间格 式，参考附录 8
-.startTime string 20 N 服务开始时间，开始计费时间，日期 时间格式，参考附录 8
-.endTime string 20 N 服务结束时间，结束计费时间，日期 时间格式，参考附录 8
-.cancelTime string 20 N 取消时间，日期时间格式，参考附录 8
-.checkTime string 20 Y 账单确认的时间，status 为 8 时必填
-.passenger object N 乘客信息
-.driver object N 司机车辆信息
-.vehicle object N 车辆信息
-.cost object N 费用信息
-.position object N 位置信息
requestId string 64 N 请求 ID

passenger

参数名称** 类型 长度 必选** 说明**
mobile string 20 Y 乘车人手机
name string 20 Y 乘车人姓名
message string 50 N 乘客给司机留言，最长 50 个字符

position

参数名称 类型 长度 必选 说明
startName string 50 Y 出发地名称
startAddress string 100 Y 出发详细地址
startLat double Y 出发地纬度
startLng double Y 出发地经度
endName string 50 Y 目的地名称
endAddress string 100 Y 目的详细地址
endLat double Y 目的地纬度
endLng double Y 目的地经度
factStartLat double N 实际上车纬度
factStartLng double N 实际上车经度
factStartAddr string 100 N 实际出发详细地址
factEndLat double N 实际到达纬度
factEndLng double N 实际到达经度
factEndAddr string 100 N 实际到达详细地址

driver

参数名称 类型 长度 必选 说明
id string 32 Y 司机 ID
name string 32 Y 司机姓名
avatar string 300 N 司机头像 URL
phone string 20 N 司机真实手机号码
virtualPhone string 20 Y 司机虚拟手机号码
rate string 10 N 司机评分
acceptCount int N 司机接单数

vehicle

参数名称 类型 长度 必 选 说明
plate string 10 Y 车牌号
color string 10 Y 汽车颜色
brand string 30 Y 汽车品牌
model string 30 Y 汽车型号
picture string 300 Y 汽车图片的 URL

cost

参数名称 类型 长度 必选 说明
totalAmount int Y

实际总费用，单位为分

总费用由 2 部分组成：行程费用+附加 费用

1、如果订单有责取消，totalAmount

应该等于取消费

未支付改价，

totalAmount 同步更新

orderAmount int Y 行程费用 行程费用作为优惠计算、分佣的基数 未支付改价，orderAmount 同步更新
extraAmount int Y

总费用中的附加费用

如路桥、停车等非司机提供服务的费 用

未支付改价，extraAmount 同步更新

details array object N 明细
-.name string 30 Y 明细项名称
-.amount int Y 明细项金额，单位为分
refundAmount int N 累计退款金额，支付后退款的金额
  1. 决策通知

  • 接口说明 运力商提供，腾讯出行发起，调用运力商，通知运力商选择该司机

  • 请求地址 <sp_url_prefix>/api/order/confirm

  • 请求参数（data）

参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
confirmTime string 20 Y

决策选用的时间，日期时间格式，比 如：2022-08-01 15:27:03，参考附录

8

  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 响应状态编码，附录 5
message string 64 N 响应状态说明，附录 5
requestId string 64 N 请求 ID
  1. 查询司机位置

  • 接口说明 运力商提供，腾讯出行调用运力商接口查询司机当前位置，限订单服务中（司机接单到服务完 成)。

  • 请求地址 <sp_url_prefix>/api/order/driver/location

  • 请求参数（data)

参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 响应状态编码，附录 5
message string 64 N 响应状态说明，附录 5
data object
-.lng double Y 经度
-.lat double Y 纬度
-.direction double Y 车头方向 0-360
-.status int Y 订单状态
-.time string 20 Y

司机位置时间，日期时间格式，比如： 2022-08-01 15:27:03，参考附录

8

requestId string 64 N 请求 ID
  1. 取消订单
  • 接口说明

运力商提供，腾讯出行调用运力方接口取消订单 行程开始前（即订单状态在 6 之前），腾讯出行可以发起取消。 行程开始后，腾讯出行不会再发起取消。

  • 请求地址 <sp_url_prefix>/api/order/cancel
  • 请求参数(data)
参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
cancelSource int Y 取消来源 附录 6
cancelType int Y 取消原因 附录 6
cancelReason string 100 Y 取消原因
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 响应状态编码，附录 5
message string 64 N 响应状态说明，附录 5
data object
-.cancelAmount int Y

取消费（默认为 0）,单位：分

同时更新到订单详情的 totalAmount

requestId string 64 N 请求 ID

  1. 查询取消费
  • 接口说明

运力商提供，用户取消前，腾讯出行调用运力商接口查询取消费

  • 请求地址

<sp_url_prefix>/api/order/precancel

  • 请求参数(data)
参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 响应状态编码，附录 5
message string 64 N 响应状态说明，附录 5
data object
-.cancelAmount int Y 取消费，单位：分
requestId string 64 N 请求 ID
  1. 支付通知

  • 接口说明 运力商提供，用户支付完成后，腾讯出行通知运力商

  • 请求地址 <sp_url_prefix>/api/order/pay/notify

  • 请求参数（data）

参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
totalAmount int Y 订单总金额（单位：分）
payAmount int Y 订单应付金额（单位：分）
paidAmount int Y 用户已付金额（单位：分）
couponId string 32 N 使用的优惠券 ID
couponAmount int N 对应优惠券减免的优惠金额
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 响应状态编码，附录 5
message string 64 响应状态说明，附录 5
requestId string 64 N 请求 ID
  1. 行程轨迹
  • 接口说明 运力商提供，接口数据在服务结束可查询
  • 请求地址 <sp_url_prefix>/api/order/tracks
  • 请求参数(data)
参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
  • 返回参数
参数名称 类型 长度 必选 说明
code int Y 响应状态编码，附录 5
message string 64 N 响应状态说明，附录 5
data
-.distance int Y 行程距离，单位米
-.duration int Y 行程时长，单位秒
-.tracks array object Y 经纬度集合，建议采用道格拉斯普克算法压缩
-.lat double Y 纬度，最多保留 6 位小数
-.lng double Y 经度，最多保留 6 位小数
-.ts int N Unix时间戳，单位秒
requestId string 64 N 请求 ID
  1. 申请发票
  • 接口说明

运力商提供，腾讯出行调用运力商接口申请发票，发票由腾讯出行负责将发票发送给用户，如 果合同有特殊约定的按照约定处理。

目前仅支持按照订单开票，发票仅支持电子发票，支持一年内的订单开具发票，附加费用不支 持开具发票，每次最多 30 个订单。

  • 请求地址 <sp_url_prefix>/api/invoice/create
  • 请求参数（data）
参数名称 类型 长度 必 选 说明
spOrders array object Y 每次最多 30 个订单
-.spOrderId string 32 Y 运力订单 ID
-.amount int Y 订单对应的开票金额，单位：分
invoiceAmount int Y 订单总开票金额
buyerType int Y 开票所属类型， 1-企业，2-个人
invoiceType int Y 发票类型：0. 电子发票，仅支持电子发票
invoiceTitle string 80 N 发票抬头，开票所属类型为 2 时必选
taxNum string 20 N 纳税人识别号，开票所属类型为 1 时必选
sender int Y 发送方，1.腾讯出行 2. 运力方，需和腾讯出行约定发送方，没有特殊约定的应当由 腾讯出行发送
receiverName string 20 Y 发票接收人姓名
receiverPhone string 20 Y 发票接收人手机号
receiverEmail string 50 Y 发票接收人邮箱
bankName String 50 N 开户行
bankAccount String 100 N 开户行帐号
regAddress String 100 N 注册地址
regTel String 20 N 注册电话
remark string 50 N 备注
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 响应状态编码，附录 5
message string 64 Y 响应状态说明，附录 5
data object
-.invoices array object
-.invoiceId string 32 Y 发票 ID
-.amount int Y 发票金额
-.invoiceSpOrderIds array string Y

该发票 id 对应的运力商订单号

注：与上面 2 个同级

（invoiceId,amount)

-.invalidSpOrderIds array string N 全部无效的运力商订单号列表
requestId string 64 N 请求 ID
  1. 开票状态查询

  • 接口说明 运力商提供，腾讯出行调用运力商接口查询开票状态

  • 请求地址 <sp_url_prefix/api/invoice/status

  • 请求参数（data）

参数名称 类型 长度 必选 说明
invoiceId string 32 Y 发票 ID
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 响应状态编码，附录 5
message string 64 Y 响应状态说明，附录 5
data object
-.invoiceId string 32 Y 发票 ID
-.status int Y 开票状态 1-开票中 2-已开票 3-开票失败 4-已取消 5-已作废
-.invoiceTitle string 80 N 发票抬头，status=2 时必选
-.invoiceContent string 50 N 发票内容，status=2 时必选
-.taxNum string 20 N 纳税人识别号，status=2 时必选
-.invoiceUrl string 300 N 发票下载地址，status=2 时必选
requestId string 64 N 请求 ID
  1. 查询司机虚拟手机号码

  • 接口说明 运力商提供，腾讯出行调用运力商接口查询司机虚拟手机号码

  • 接口地址 <sp_url_prefix/api/order/driver/phone

  • 请求参数（data）

参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 参考附录 5
message string 64 N
data object
-.orderId string 32 Y 腾讯出行订单 ID
-.spOrderId string 32 Y 运力商订单 ID
-.driverVirtualPhone string 20 Y 司机虚拟手机号码
requestId string 64 N 请求 ID

# 腾讯出行提供接口文档

  1. 状态回调
  • 接口说明

腾讯出行提供，运力商通知腾讯出行订单状态的变更，包括司机接单、完结、 改价、退款 等。

  • 请求地址 <tmscx_url_prefix>/spapi/order/callback
  • 请求参数（data)
参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
event int Y 回调事件 ID，参考附录 1.2
eventTime string 20 Y 事件发生时间，日期时间格式，比如：2022- 08-01 15:37:20，参考附录 8
cancelType int N event=12 时必传 ，参考附录 6
rideType int N 运力类型，参考附录 3
distance int N 实际行程里程，event=8 时必传， 单位为米
duration int N 实际行程时长，event=8 时必传， 单位为秒
driver object N 司机信息，event=3、31 时必传（3-司机接 单、31-改派）
vehicle object N 车辆信息，event=3、31 时必传（3-司机接 单、31-改派）
driverLocation object N 司机位置信息，event=3、31、4、5、6、7 时必传
position object N 实际上下车地点信息，event=6、7 时必传
cost object N 账单信息，event=8,81,91 时必传 ，

driver

参数名称 类型 长度 必选 说明
id string 32 Y 司机 id（需要保证唯一即可）
name string 32 Y 司机姓名
avatar string 300 N 司机头像
phone string 20 N 司机真实手机号码
virtualPhone string 20 Y 司机虚拟手机号码
rate string 10 Y 司机评级（例 5.0）
acceptCount int N 司机接单数

vehicle

参数名称 类型 长度 必 选 说明
plate string 10 Y 车牌号
color string 10 Y 汽车颜色
brand string 20 Y 汽车品牌
model string 20 Y 汽车型号
picture string 300 Y 汽车图片的 URL

driverLocation

参数名称 类型 长度 必选 说明
lat double Y 纬度
lng double Y 经度

position

参数名称 类型 长度 必选 说明
startName string 50 Y 预约出发地名称
startAddress string 100 Y 预约出发详细地址
startLat double Y 预约出发地纬度
startLng double Y 预约出发地经度
endName string 50 Y 预约目的地名称
endAddress string 100 Y 预约目的详细地址
endLat double Y 预约目的地纬度
endLng double Y 预约目的地经度
factStartLat double N 实际上车纬度
factStartLng double N 实际上车经度
factStartAddr string 100 N 实际出发详细地址
factEndLat double N 实际到达纬度
factEndLng double N 实际到达经度
factEndAddr string 100 N 实际到达详细地址

cost

参数名称 类型 长度 必选 说明
totalAmount int Y

实际总费用，单位为分

总费用由 2 部分组成：行程费用+附加 费用

2、如果订单有责取消，totalAmount

应该等于取消费

未支付改价，totalAmount 同步更新

orderAmount int Y 行程费用 行程费用作为优惠计算、分佣的基数 未支付改价，orderAmount 同步更新
extraAmount int Y

总费用中的附加费用

如路桥、停车等非司机提供服务的费 用

未支付改价，extraAmount 同步更新

details array object N 明细
-.name string 30 Y 明细项名称
-.amount int Y 明细项金额，单位为分
refundAmount int N 累计退款金额，支付后退款的金额
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 响应状态编码，附录 5
message string 64 N 响应状态说明，附录 5
requestId string 64 N 请求 ID
  1. 查询订单支付状态
  • 接口说明 腾讯出行提供，运力商查询腾讯出行的订单支付状态。
  • 请求地址 <tmscx_url_prefix>/spapi/order/status
  • 请求参数（data）
参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y
message string 64 N
data object
-.orderId string 32 Y 腾讯出行订单 ID
-.spOrderId string 32 Y 运力商订单 ID
-.status int Y 订单状态，附录 1.1
-.payStatus int Y 支付状态，附录 1.2
-.paidAmount int N 用户已付的金额，单位为分
-.couponId string 32 N 使用的优惠券
-.couponAmount int N 优惠券减免的金额，单位为分
-.transactionId string 32 N 微信支付流水号
-.payTime string 20 N 支付时间
requestId string 64 N 请求 ID
  1. 司机位置
  • 接口说明

腾讯出行提供，订单状态更新为“司机已出发”之后，运力商应当以每 10 秒 1 次的频率向优 本出行推送司机位置信息。

备注：如果不提供订单轨迹接口，需要回调腾讯出行司机位置数据。

  • 请求地址 <tmscx_url_prefix>/spapi/driver/location

  • 请求参数（data)

参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
lat double Y 纬度
lng double Y 经度
direction double Y 车头方向
time string 20 Y 更新位置时间，日期时间格式，比 如：2022-08-01 15:27:32，参考附 件 8
status int Y 订单状态，参考附录 1.1
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 响应状态编码，参考附录 5
message string 64 N 响应状态说明，参考附录 5
requestId string 64 N 请求 ID
  1. 开票回调（暂时无需接入）

  • 接口说明 腾讯出行提供，发票状态变更时运力商通知腾讯出行。

  • 请求地址 <tmscx_url_prefix>/spapi/invoice/callback

  • 请求参数（data）

参数名称 类型 长度 必选 说明
invoiceId string 50 Y 发票 ID
event int Y 发票回调事件，参考附录 9
eventTime string 20 Y 发票回调事件发生时间，日期时间 格式，比如：2022-08-01 15:27:03， 参考附件 8
eventMessage string 100 N 事件说明， event=2、4 时，说明 失败原因
invoiceAmount int N 发票金额，event=1 必选，单位分
invoiceTitle string 80 N 发票抬头，event=1 必选
taxNum string 20 N 纳税人识别号，event=1 必选
invoiceContent string 50 N 发票内容，event=1 必选
invoiceUrl string 300 N 发票下载地址，event=1 必选
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y 参考附录 5
message string 64 N
requestId string 64 N 请求 ID
  1. 查询乘客虚拟号码（接入前联系平台配置）
  • 接口说明

腾讯出行提供，运力商查询用户虚拟号。

在“决策通知”后，可以进行查询。行程结束后虚拟号会解绑。 使用乘客虚拟号码后，下单接口将只传乘客手机后 4 位。 注：如接入此接口，请提前联系平台进行配置。

  • 请求地址 <tmscx_url_prefix>/spapi/order/passenger/phone

  • 请求参数（data）

参数名称 类型 长度 必选 说明
orderId string 32 Y 腾讯出行订单 ID
spOrderId string 32 Y 运力商订单 ID
  • 返回数据
参数名称 类型 长度 必选 说明
code int Y
message string 64 N
data object
-.passengerVirtualPhone string 20 Y 乘客虚拟号
-.orderId string 32 Y 腾讯出行订单 ID
-.spOrderId string 32 Y 运力商订单 ID
requestId string 64 N 请求 ID

# 附录

附录 1.1：订单状态 status

状态码 说明
1 已创建
2 派单中
3 司机已接单
4 司机已出发
5 司机已到达
6 乘客上车，服务中
7 行程结束
8 确认账单
9 已支付 - 完单且支付后为该状态
10 用户取消 - 取消费支付后，依然为 10
11 平台取消
12 运力取消

附录 1.2：订单回调事件 event

事件 说明 对应的腾讯出行订单状态
运力侧成功创建订单，派单中 2-派单中
3 司机已接单 3-司机已接单
31 改派 3-司机已接单
4 司机已出发 4-司机已出发
5 司机已到达 5-司机已到达
6 乘客上车，服务中 6-乘客上车，服务中
7 行程结束 7-行程结束
8 确认账单 8-确认账单
81 改价事件 8-确认账单
91 退款事件 9-支付完结
用户取消 10-用户取消
平台取消 11-平台取消
12 运力取消 12-运力商取消

附录 1.3：支付状态 payStatus

pay_status 说明
0 无需支付
1 待支付
2 支付成功
3 支付失败

附录 1.4：退款状态 refundStatus

pay_status 说明
0 无需退款
1 待退款
2 退款成功
3 退款关闭
4 退款中
5 退款异常

附录 1.5：发票状态 invoiceStatus

发票状态 0 未开票 1：开票中 2：已开票 3：开票失败 4：已取消 5-已作废

pay_status 说明
0 未开票
1 开票中
2 已开票
3 开票失败
4 已取消
5 已作废

附录 2：服务类型 serviceType

编码 说明
1 即时用车
2 接机
3 送机
4 预约用车

附录 3：运力类型 rideType

编码 说明
1 普通经济
2 超惠经济
3 优享型
4 舒适型
5 商务型
6 豪华型
7 出租车

附录 4：计价类型 chargeType

编码 说明
1 普通计费
2 一口价

附录 5：响应状态编码(code)

成功

编码 说明
0 成功

10000 - 19999 请求错误或者签名验证失败

编码 说明
10001 请求 URL错误
10002 请求方法错误
10003 appId 错误
10004 时间戳过期或者 nonce 重复
10005 签名验证失败
10009 请求频繁，请稍后重试
- -

40000 - 49999 业务错误

编码 说明
40001 数据不存在（订单号不存在，发票不存在）
40002 出发时间错误，超过允许范围
40003 该城市未开通
40004 该城市临时关闭
40005 命中电子围栏，该区域不能下单
40006 航班信息错误
40007 不支持的运力类型
40008 预估价格 ID不存在或者已经失效，请重新获取预估价格
40009 预估价格 ID同订单数据不一致，请重新获取预估价格
40010 该手机号码有进行中的订单，不能再创建订单
40011 腾讯出行订单号已经存在，不能再创建订单
40012 不支持的服务类型
40013 订单取消失败，比如服务已经开始，不能取消订单
40014 参数错误
40015 该订单无司机信息（查询司机位置）
40016 订单已经取消，比如确认接单时运力商已经取消订单
40020 支付费用不一致
40021 退款费用不一致
40030 订单已经开票
49001 该用户健康码异常
49002 取消次数过多，不能再下单

50000 - 59999 服务端错误

50000 系统错误，服务端存在未处理的异常
50001 创建订单失败
50002 开票失败
50003 查询发票失败

回调事件错误代码

0 成功
10001 请求 URL错误
10002 请求方法错误
10003 appId 错误
10004 时间戳过期或者 nonce 重复
10005 签名验证失败
10009 请求频繁，请稍后重试
40001 数据不存在（订单号不存在，发票不存在）
40002 订单回调:事件无效
40003 订单回调:取消事件取消类型不能为空
40004 订单回调:接单改派事件司机车辆信息不能为空
40005 订单回调:当前事件通知司机位置信息不能为空
40006 订单回调:当前事件通知账单信息不能为空
40007 订单回调:当前事件通知行程里程时长不能为空
50000 系统错误，服务端存在未处理的异常

附录 6：取消原因

取消来源：cancelSource 取消类型：cancelType 取消原因：cancelReason

取消来源 取消类型 取消原因 说明
100 客户取消（默认）
101 临时有事，暂不用车
102 选错上车或下车地点
103 与司机协商一致后取消订单
104 联系不上司机
1 105 车辆或司机和订单显示的不一致 用户取消及小程 序侧选择的原因
106 司机要求线下付款或加价
107 司机要求我取消订单
108 司机原地不动或长时间不来接我
109 司机打电话态度不好
110 派了离我太远的司机来接我
111 不是我预期的车型或运力商
112 推荐上车地点不准确
200 派单决策没选用
2 201 用户风控未过 平台取消
299 其他
300 无司机接单
301 司机取消
3 302 客服取消 运力商取消
303 系统取消
304 系统补偿取消（订单异常）

附录 7：城市编码

参考： GB/T 2260

城市编码：https://lbs.qq.com/service/webService/webServiceGuide/webServiceDistrict (opens new window)

附录 8：日期时间格式

日期格式采用 GB/T 7408—2005 标准中"YYYY-MM-DD"格式（示例：2022-08-01），时区统一 采用东八区（即北京时间）。

日期时间格式采用 GB/T 7408—2005 标准中的 "YYYY-MM-DD hh:mm:ss" 格式（示例： 2022-08- 01 19:00:00），时区统一采用东八区（即北京时间）。

Java 中时间格式应为： "yyyy-MM-dd HH:mm:ss"

PHP中时间格式应为： "Y-m-d H:i:s"

Go 中时间格式应为："2006-01-02 15:04:05"

Python 中时间格式应为： "%Y-%m-%d %H:%M:%S"

附录 9：发票回调事件

事件 说明
1 开票成功
2 开票失败
3 作废成功
4 作废失败

← 顺风车 →