腾讯出行服务·开放平台

# SP优惠券

  • 名称解释
名词 描述 备注
SP ServiceProvider 服务提供商
⼩程序插件 被添加到微信⼩程序内直接使⽤的功能组件 SP 提供的⼩程序插件
返回地址 从车联⼩程序跳到插件页⾯，最后流程结束，返回车联的⼩程序地址
  • 注意事项

接口分为“优惠券接入协议接口”和“接入方回调腾讯出行服务同步信息接口”两部分；

1）优惠券接入协议接口：需要接入方根据接口定义实现 server 端逻辑，以供腾讯出行服务调用；

2）接入方回调腾讯出行服务同步信息接口：需要腾讯出行服务实现 server 端逻辑，以供接入方在相应时机回调腾讯出行服务；

  • 调用时序
uml diagram

# 查询批次信息

  • 接口说明 本接口用于查询优惠券批次信息，包括批次券类型、批次有效期、批次券金额等

  • 请求地址 接入方提供

  • 请求方式 POST

  • 请求参数 通用参数 + 业务参数

参数名称 类型 最大长度 必选 说明
stock_id string 30 是 批次 ID（唯一）
extra string 128 否 扩展参数
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
app_channel_id int 10 是 多租户渠道 ID 0:出行服务 11:手图
app_id string 32 是 小程序 AppId
stock_id string 30 是 批次 ID
stock_name string 20 是 批次名称
instructions string 1024 是 批次券使用说明
coupon_name string 20 是 优惠券名称
coupon_desc string 50 是 优惠券描述
coupon_type int 4 是 优惠券类型 1：满减券 2：减至券 3：折扣券
fixed_normal_coupon object - 否 满减券信息
fixed_normal_coupon.coupon_amount long 20 是 优惠券面额（单位：分）
fixed_normal_coupon.transaction_minimum long 20 是 优惠券使用门槛（单位：分）
discount_coupon object - 否 折扣券信息
discount_coupon.discount_amount_max long 20 是 最高折扣金额（单位：分）
discount_coupon.discount_percent Int 11 是 折扣百分比，例如 88-八八折
discount_coupon.transaction_minimum long 20 是 使用券金额门槛（单位：分）
max_coupons int 11 是 总发券数量
max_coupons_per_user int 11 是 单个用户可领个数
available_begin_time string 32 是 可用开始时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
available_end_time string 32 是 可用结束时间，格式 yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
create_time string 32 是 创建时间 yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
stock_status int 4 是 批次状态 1：未激活 2：审核中 3：运行中 4：已停止 5：暂停发放
province_name string 2000 否 优惠券适用省份名称，多个名称之间使用逗号隔开
province_code string 2000 否 优惠券适用省份code，多个名称之间使用逗号隔开
city_name string 5000 否 优惠券适用城市名称，多个名称之间使用逗号隔开
city_code string 5000 否 优惠券适用城市code，多个code之间使用逗号隔开
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "stock_id": "test001",
  "extra": "extra info"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful",
  "data": {
    "app_channel_id":1,
    "app_id": "wx1111111111",
    "stock_id": "test001",
    "stock_name": "代驾10元代金券",
    "instructions": "优惠券使用简介",
    "coupon_name": "代驾代金券",
    "coupon_desc": "消费满100元可用，仅限深圳使用",
    "coupon_type": 1,
    "fixed_normal_coupon": {
      "coupon_amount": 1000,
      "transaction_minimum": 10000
    },
    "discount_coupon": {
      "discount_amount_max": 1000,
      "discount_percent": 88,
      "transaction_minimum": 10000
    },
    "max_coupons": 20000,
    "max_coupons_per_user": 1,
    "available_begin_time": "2020-07-20T13:29:35.120+08:00",
    "available_end_time": "2020-08-20T13:29:35.120+08:00",
    "create_time": "2020-07-20T13:29:35.120+08:00",
    "stock_status": 3,
    "province_name": "广东省",
    "province_code": "516324",
    "city_name": "深圳市",
    "city_code": "44030000"
  }
}

# 领券

  • 接口说明 本接口用于腾讯出行服务调用接入方领券接口发券。

  • 请求地址 接入方提供

  • 请求方式 POST

  • 请求参数 通用参数 + 业务参数

参数名称 类型 最大长度 必选 说明
app_channel_id int 10 是 多租户渠道ID 0:出行服务 11:手图
user_code string 32 是 用户标识
mobile_phone string 11 否 手机号码
stock_id string 30 是 批次 ID
request_id string 32 是 请求 ID（业务唯一，根据 request_id 做幂等处理）
extra string 128 否 扩展信息
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态码，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
app_id string 32 是 小程序 appId
stock_id string 30 是 批次 ID
coupon_id string 20 是 优惠券 ID
coupon_type int 4 是 优惠券类型 1：满减券 2：减至券 3：折扣券
fixed_normal_coupon object - 否 满减券信息
fixed_normal_coupon.coupon_amount long 20 是 优惠券面额（单位：分）
fixed_normal_coupon.transaction_minimum long 20 是 优惠券使用门槛（单位：分）
discount_coupon object - 否 折扣券信息
discount_coupon.discount_amount_max long 20 是 最高折扣金额（单位：分）
discount_coupon.discount_percent int 11 是 折扣百分比，例如 88-八八折
discount_coupon.transaction_minimum long 20 是 使用券金额门槛（单位：分）
available_begin_time string 32 是 可用开始时间，格式： yyyy-MM-ddTHH:mm:ss: SSS+TIMEZONE
available_end_time string 32 是 可用结束时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
receive_time string 32 是 领券时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
coupon_status int - 是 优惠券状态 1：可用 2：已使用 3：已过期
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "app_channel_id":1,
  "user_code": "udxbxd",
  "mobile_phone": "13911112222",
  "stock_id": "test001",
  "request_id": "123456789",
  "extra": "extra info"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful",
  "data": {
    "app_id": "wx1111111111",
    "stock_id": "test001",
    "coupon_id": "123456789",
    "coupon_type": 1,
    "fixed_normal_coupon": {
      "coupon_amount": 1000,
      "transaction_minimum": 10000
    },
    "discount_coupon": {
      "discount_amount_max": 1000,
      "discount_percent": 88,
      "transaction_minimum": 10000
    },
    "available_begin_time": "2020-07-05T13:29:35.120+08:00",
    "available_end_time": "2020-07-30T23:59:59.120+08:00",
    "receive_time": "2020-07-30T23:59:59.120+08:00",
    "stock_status": 1
  }
}

# 设置可用优惠券过期/失效

  • 接口说明 本接口用于出行服务调用服务商将可用的优惠券设置为过期或无效/失效状态

  • 请求地址 接入方提供

  • 请求方式 POST

  • 请求参数 通用参数 + 业务参数

参数名称 类型 最大长度 必选 说明
app_channel_id int 10 是 多租户渠道ID 0:出行服务 11:手图
user_code string 32 是 用户标识
mobile_phone string 11 否 手机号码
stock_id string 30 是 批次 ID
coupon_id string 32 是 优惠券 ID
coupon_status int 11 是 优惠券状态3：已过期4：无效/失效
reason string 15 否 原因
extra string 128 否 扩展信息
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态码，参见附录一
message string 64 是 服务响应状态说明，参见附录一
data object 否
deactivate_time string 32 否 无效时间；格式：yyyy-MM-ddTHH:mm:ss.SSS+TIMEZONE
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce":"157234207",
  "sign":"8A983278E5366EB93FEB0D4143E1C522",
  "app_channel_id":1,
  "user_code": "udxbxd",
  "mobile_phone":"13911112222",
  "stock_id":"test001",
  "coupon_id": "123456789",
  "coupon_status":3,
  "reason": "用户申请退款",
  "extra": "extra**** info"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful",
  "data": {
    "deactivate_time": "2020-07-05T13:29:35.120+08:00"
  }
}

# 批量设置可用优惠券过期/失效

  • 接口说明 本接口用于出行服务调用服务商批量将可用的优惠券设置为过期或无效/失效状态

  • 注意事项 仅当优惠券当前状态不是可用时，才认为此优惠券不满足设置条件；优惠券已过期和已无效/失效都认为是满足条件的。

如果存在任何一张不满足条件的优惠券，即认为不满足执行条件，批量操作中的所有优惠券状态都不可更新，此时把不满足条件的优惠券信息放到 illegal_coupons中放回即可。

  • 请求地址 接入方提供

  • 请求方式 POST

  • 请求参数 通用参数 + 业务参数

参数名称 类型 最大长度 必选 说明
app_channel_id int 10 是 多租户渠道ID 0:出行服务 11:手图
user_code string 32 是 用户标识
mobile_phone string 11 否 手机号码
coupons list<object> 是 优惠券数组（一次最多 10个）
coupons[0].stock_id string 30 是 批次 ID
coupons[0].coupon_id string 32 是 优惠券 ID
coupon_status int 11 是 优惠券状态3：已过期4：无效/失效
reason string 15 否 原因
extra string 128 否 扩展信息
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态码，参见附录一
message string 64 是 服务响应状态说明，参见附录一
data object 否
expire_coupons list<object> 否 已过期的优惠券列表
expire_coupons[0].stock_id string 30 是 批次 ID
expire_coupons[0].coupon_id string 32 是 优惠券 ID
expire_coupons[0].expire_time string 32 是 过期时间，格式：yyyy-MM-ddTHH:mm:ss.SSS+TIMEZONE
deactivate_coupons list<object> 否 无效/失效的优惠券列表
deactivate_coupons[0].stock_id string 30 是 批次 ID
deactivate_coupons[0].coupon_id string 32 是 优惠券 ID
deactivate_coupons[0].deactivate_time string 32 是 无效时间，格式：yyyy-MM-ddTHH:mm:ss.SSS+TIMEZONE
illegal_coupons list<object> 否 不满足条件的优惠券数组（优惠券状态不是可用）
illegal_coupons[0].stock_id string 30 是 批次 ID
illegal_coupons[0].coupon_id string 32 是 优惠券 ID
illegal_coupons[0].coupon_status int 11 是 优惠券状态1：可用2：已使用3：已过期4：无效/失效
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "app_channel_id ": 1,
  "user_code": "udxbxd",
  "mobile_phone": "13911112222",
  "coupons": [{
    "stock_id": "test001",
    "coupon_id": "123456789"
  }],
  "coupon_status": 3,
  "reason": "用户申请退款",
  "extra": "extrainfo"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful",
  "data": {
    "expire_coupons": [{
      "stock_id": "test001",
      "coupon_id": "123456789",
      "expire_time": "2020-07-05T13:29:35.120+08:00"
    }],
    "deactivate_coupons": [{
    "stock_id": "test001",
    }],
    "coupon_id": "123456789",
    "deactivate_time": "2020-07-05T13:29:35.120+08:00",
    "illegal_coupons": [{
      "stock_id": "test001",
      "coupon_id": "123456789",
      "coupon_status": 2
    }]
  }
}

# 同步批次信息

  • 接口说明 本接口用于接入方回调腾讯出行服务同步优惠券批次信息。

  • 请求地址 /stock/rsync

  • 请求方式 POST

  • 请求参数 通用参数 + 业务参数

参数名称 类型 最大长度 必选 说明
app_channel_id int 10 是 多租户渠道ID 0:出行服务 11:手图
app_id string 32 是 小程序 appId
buss_classify int 10 否 业务类型
stock_id string 30 是 批次 ID
stock_name string 20 是 批次名称
instructions string 1024 是 使用说明
coupon_name string 20 是 券名称
coupon_desc string 50 是 券描述
coupon_type int 4 是 优惠券类型 1：满减券 2：减至券 3：折扣券
fixed_normal_coupon object - 否 满减券信息
fixed_normal_coupon.coupon_amount long 20 是 优惠券面额（单位：分）
fixed_normal_coupon.transaction_minimum long 20 是 优惠券使用门槛（单位：分）
discount_coupon object - 否 折扣券信息
discount_coupon.discount_amount_max long 20 是 最高折扣金额（单位：分）
discount_coupon.discount_percent int 11 是 折扣百分比，例如 88-八八折
discount_coupon.transaction_minimum long 20 - 使用券金额门槛（单位：分）
max_coupons int 11 是 总发券数量
max_coupons_per_user int 11 是 单个用户可领个数
available_begin_time string 32 是 可用开始时间，格式：yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
available_end_time string 32 是 可用结束时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
create_time string 32 是 创建时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
stock_status int 4 是 批次状态 1：未激活 2：审核中 3：运行中 4：已停止 5：暂停发放
province_name string 2000 否 优惠券适用省份名称，多个名称之间使用逗号隔开
province_code string 2000 否 优惠券适用省份code，多个名称之间使用逗号隔开
city_name string 5000 否 优惠券适用城市名称，多个名称之间使用逗号隔开
city_code string 5000 否 优惠券适用城市code，多个code之间使用逗号隔开
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "app_channel_id":1,
  "app_id": "wx11111111",
  "stock_id": "test001",
  "stock_name": "代驾代金券",
  "instructions": "详细的券使用说明",
  "coupon_name ": "代驾代金券",
  "coupon_desc ": "满10元可用，仅限深圳地区使用",
  "coupon_type ": 1,
  "fixed_normal_coupon": {
    "coupon_amount": 1000,
    "transaction_minimum": 10000
  },
  "discount_coupon": {
    "discount_amount_max": 1000,
    "discount_percent": 88,
    "transaction_minimum": 10000
  },
  "max_coupons ": 20000,
  "max_coupons_per_user ": 1,
  "available_begin_time": "2020-07-05T13:29:35.120+08:00",
  "available_end_time": "2020-07-30T23:59:59.120+08:00",
  "create_time": "2020-07-30T23:59:59.120+08:00",
  "stock_status": 3,
  "province_name": "广东省",
  "province_code": "516324",
  "city_name": "深圳市",
  "city_code": "44030000"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful"
}

# 同步优惠券信息

  • 接口说明 本接口用于接入方在出行小程序主动发放的优惠券同步至出行服务侧。调用此接口前请确保已经调用同步批次信息接口。

  • 请求地址 /coupon/rsync

  • 请求方式 POST

  • 请求参数 通用参数 + 业务参数

参数名称 类型 最大长度 必选 说明
app_channel_id int 10 是 多租户渠道ID 0:出行服务 11:手图
user_code string 32 是 用户标识
mobile_phone string 11 否 手机号
app_id string 32 是 小程序 AppID
stock_id string 30 是 批次 ID
coupon_id string 20 是 优惠券 ID
coupon_type int 4 是 优惠券类型 1：满减券 2：减至券 3：折扣券
fixed_normal_coupon object - 否 满减券信息
fixed_normal_coupon.coupon_amount long 20 是 优惠券面额（单位：分）
fixed_normal_coupon.transaction_minimum long 20 是 优惠券使用门槛（单位：分）
discount_coupon object - 否 折扣券信息
discount_coupon.discount_amount_max long 20 是 最高折扣金额（单位：分）
discount_coupon.discount_percent int 11 是 折扣百分比，例如 88-八八折
discount_coupon.transaction_minimum long 20 - 使用券金额门槛（单位：分）
available_begin_time string 32 是 可用开始时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
available_end_time string 32 是 可用结束时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
receive_time string 32 是 领取时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
usage_time string 32 否 使用时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
coupon_status int 11 是 优惠券状态 1：可用 2：已使用 3：已过期
extra string 256 否 扩展信息
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "app_channel_id":1,
  "user_code": "udxbxd",
  "mobile_phone": "13911112222",
  "app_id": "wx11111111",
  "stock_id ": "test001",
  "coupon_id": "1572355050",
  "coupon_type": 1,
  "fixed_normal_coupon": {
    "coupon_amount": 1000,
    "transaction_minimum": 10000
  },
  "discount_coupon": {
    "discount_amount_max": 1000,
    "discount_percent": 88,
    "transaction_minimum": 10000
  },
  "available_begin_time ": "2020-07-20T13:29:35.120+08:00",
  "available_end_time ": "2020-08-20T13:29:35.120+08:00",
  "receive_time": "2020-08-20T13:29:35.120+08:00",
  "usage_time": "2020-08-21T13:29:35.120+08:00",
  "coupon_status": 2,
  "extra": "扩展信息"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful"
}

# 同步批次状态

  • 接口说明 本接口用于同步用户邮寄信息。

  • 请求地址 /stock/status/rsync

  • 请求方式 POST

  • 请求参数 通用参数 + 业务参数

参数名称 类型 最大长度 必选 说明
stock_id string 30 是 批次 ID
stock_status int 11 是 批次状态 1：未激活 2：审核中 3：运行中 4：已停止 5：暂停发放
extra string 128 否 扩展信息
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "stock_id": "udxbxd",
  "stock_status": 3
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful"
}

# 同步优惠券状态

  • ** 接口说明** 本接口用于同步优惠券状态信息。

  • 请求地址 /coupon/status/rsync

  • 请求方式 POST

  • 请求参数 通用参数 + 业务参数

参数名称 类型 最大长度 必选 说明
app_channel_id int 10 是 多租户渠道ID 0:出行服务 11:手图
user_code string 32 是 用户标识
mobile_phone string 11 否 手机号码
stock_id string 30 是 批次 ID
coupon_id string 20 是 优惠券 ID
coupon_status int 11 是 优惠券状态 1: 可用 2: 已使用 3: 已过期
usage_time string 32 否 使用时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
event_time string 32 否 事件时间，格式： yyyy-MM-ddTHH:mm:ss. SSS+TIMEZONE
version string 10 否 版本:当前版本:1.0.1
extra string 128 否 扩展信息
  • 返回数据
参数名称 类型 最大长度 必选 说明
code int 11 是 服务响应状态，参见错误码表
message string 64 是 服务响应状态说明，参见错误码表
data object - 否 -
  • 请求数据示例
{
  "api_key": "PSUBZLHOKUO6HV52A5CAUSSE5KSB6Y",
  "seq_id": "38d42bd9-9f5a-415e-89d9-ea4ff9cffdf2",
  "timestamp": "1572342076",
  "nonce": "157234207",
  "sign": "8A983278E5366EB93FEB0D4143E1C522",
  "app_channel_id":1,
  "user_code": "udxbxd",
  "mobile_phone": "12911112222",
  "stock_id": "test001",
  "coupon_id": "1234567",
  "coupon_status": 2,
  "usage_time ": "2020-07-20T13:29:35.120+08:00",
  "event_time ": "2020-07-20T13:29:35.120+08:00",
  "extra": "扩展信息"
}
  • 返回数据示例
{
  "code": 0,
  "message": "successful"
}

← 租车 →