营销中台

更新时间：2024-04-22 13:06:50

商家券接口

调用时序图

image.png

1.0 新增商家券

  • URL:coupon/marketing/createmchstock
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
inst_no String 8 Y 机构编号，扫呗分配
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
channel String 16 Y 渠道类型WECHAT：微信 ALIPAY：支付宝 ,多个以逗号分隔
stock_type String 16 Y 券类型 NORMAL:满减券 DISCOUNT:折扣券
stock_name String 20 Y 券名称
coupon_code_mode String 16 N 券code模式
LC_MODE：系统分配券code（固定19位纯数字）；
MERCHANT_API：商户发放时接口指定券code；
MERCHANT_UPLOAD：商户上传自定义code，发券时系统随机选取上传的券code。
不传默认LC_MODE
use_rule String 1024 Y 券核销相关规则
send_rule String 1024 Y 券发放相关规则
wx_custom_entrance String 1024 N 微信卡详情页面，可选择多种入口引导用户。
ali_custom_entrance String 1024 N 支付宝卡详情页面，可选择多种入口引导用户。
wx_display_pattern_info String 1024 N 微信创建批次时的样式信息。
ali_display_pattern_info String 1024 N 支付宝创建批次时的样式信息。预留字段,暂未开放
wx_extra_params String 1024 N 微信额外参数
ali_extra_params String 1024 N 支付宝额外参数,预留字段,暂未开放
upload_image String 1 N 是否上传过图片 0否 1是（传1 后面得图片地址请调用接口2.3得返回地址，该字段仅针对微信使用）
notify_url String 255 N 接收用户领券/核券通知地址
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换

券使用规则use_rule字段如下

参数名称 类型 长度 必填 说明
description String 1000 N 使用须知，channel包含支付宝时必传
coupon_available_time Object 1024 Y 日期区间内可以使用优惠。
fixed_normal_coupon Object 1024 N stock_type为NORMAL时必填。
└discount_amount string 16 Y 优惠金额，单位：分。
└transaction_minimum string 16 Y 消费门槛，单位：分。
特殊规则：取值范围 1 ≤ value ≤ 10000000
示例值：100
discount_coupon Object 1024 N stock_type为DISCOUNT时必填。
└discount_percent string 16 Y 折扣百分比，例如：86为八六折。
示例值：86
└transaction_minimum string 16 Y 消费门槛，单位：分。
特殊规则：取值范围 1 ≤ value ≤ 10000000
示例值：100
goods_name String 12 N 商品名称，支付宝创建单品券时填入

coupon_available_time如下

参数名称 类型 长度 必填 说明
available_begin_time String 19 Y 批次开始时间,格式为yyyy-MM-dd HH:mm:ss
available_end_time String 19 Y 批次结束时间,格式为yyyy-MM-dd HH:mm:ss
available_day_after_receive string 32 N 生效后N天内有效,可配合wait_days_after_receive一同填写，也可单独填写。单独填写时，有效期内领券后立即生效，生效后x天内有效。
wait_days_after_receive string 1 N 需配合available_day_after_receive一同填写，不可单独填写。
available_week Object 1024 N 固定周期有效时间段(仅微信生效)
└week_day array[int] 16 N 可用星期数,0代表周日，1代表周一，以此类推
当填写available_day_time时，week_day必填
示例值：1, 2
└time_period string 32 N 当天可用时间段,格式：HH:mm-HH:mm,可以填写多个时间段，最多不超过2个。
示例值：08:00-12:00, 15:00-18:00

send_rule如下

参数名称 类型 长度 必填 说明
max_coupons String 11 Y 批次最大可发放个数限制
max_coupons_per_user String 11 Y 用户最大可领个数
max_coupons_by_day String 11 N 单天发放上限个数(仅微信生效)
natural_person_limit bool 1 N 不填默认否，枚举值：
true：是
false：否
注：自然人防刷即同证件号下的所有账户合并计算的限领次数（限领次数指的是参数字段“用户最大领取个数”填写的值）
示例值：false

wx_custom_entrance如下

参数名称 类型 长度 必填 说明
mini_programs_info Object 11 N 批次最大可发放个数限制
└mini_programs_appid string 16 Y 商家小程序appid
└mini_programs_path String 32 Y 商家小程序path
示例值：/path/index/index
└entrance_words String 32 Y 入口文案，字数上限为5个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：欢迎选购
└guiding_words String 32 N 小程序入口引导文案，用户自定义字段。字数上限为6个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：获取更多优惠
appid String 32 N 商户公众号appid
hall_id String 32 N 填写微信支付营销馆的馆id，用户自定义字段。 营销馆需在服务商平台创建。
示例值：233455656
store_id String 32 N 填写代金券可用门店id，用户自定义字段。
示例值：233554655
code_display_mode String 32 N 枚举值：
NOT_SHOW：不展示code
BARCODE：一维码
QRCODE：二维码
示例值：BARCODE

ali_custom_entrance如下

参数名称 类型 长度 必填 说明
store_ids String 1024 N 券可使用的门店列表。多个逗号分隔（支付宝侧门店id）
real_shop_ids string 1024 N 代运营商业关系门店列表，列表中的门店id是调用接口alipay.business.relation.shop.create创建门店返回的real_shop_id,多个逗号分隔
mini_app_id String 32 N 卡包详情页可跳转的小程序appId。 限制： 该appId归属的pid必须和当前商户保持一致。 目前mini_app_id、store_ids、real_shop_ids必须三选一。
mini_app_path String 32 N 指定跳转到mini_app_id时的具体页面路径。 限制： 该小程序路径是相对路径。
offlineCodeUseGuide String 8 N 控制是否展示线下核销 true：展示线下核销 false：不展示线下核销 (字符串格式，不传默认 true)

wx_display_pattern_info如下

参数名称 类型 长度 必填 说明
merchant_logo_url String 255 N 商户logo的URL地址
1、商户logo大小需为120像素*120像素。
2、支持JPG/JPEG/PNG格式，且图片小于1M。
merchant_name String 16 N 商户名称
background_color String 32 N 券的背景颜色，可设置10种颜色，色值请参考卡券背景颜色图 https://pay.weixin.qq.com/wiki/doc/apiv3_partner/apis/chapter9_2_1.shtml#part-01
。颜色取值为颜色图中的颜色名称。
示例值：Color020
coupon_image_url String 255 N 券详情图片，850像素*350像素，且图片大小不超过2M，支持JPG/PNG格式

wx_extra_params如下
+

参数名称 类型 长度 必填 说明
use_method String 16 N 微信枚举值：
OFF_LINE：线下滴码核销，点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS：线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序appid和path）。
PAYMENT_CODE：微信支付付款码核销，点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME：用户自助核销，点击券“立即使用”跳转至用户自助操作核销界面（当前暂不支持用户自助核销）。
示例值：OFF_LINE
mini_programs_appid String 19 N 小程序appid
示例值：wx23232232323
mini_programs_path String 13 N 小程序path
示例值：/path/index/index
notify_appid string 32 N 事件通知appid。用于回调通知时，计算返回操作用户的openid（诸如领券用户），支持小程序or公众号的APPID；如该字段不填写，则回调通知中涉及到用户身份信息的openid与unionid都将为空
subsidy bool 1 N 是否允许营销补贴
枚举值：
true：是
false：否
默认为false

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
stock_no String 32 N 券批次编号,result_code为01时返回

1.1 投放活动

  • URL:coupon/marketing/deliveryactivity
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
inst_no String 8 Y 机构编号，扫呗分配
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
activity_type String 16 Y 活动类型枚举:
PAY:微信支付有礼,
DELIVERY:支付宝自运营活动
brand_id String 11 N 品牌id
upload_image String 1 N 是否上传过图片 0否 1是（传1 后面得图片地址请调用接口2.3得返回地址，该字段仅针对微信使用）
activity_info String 1024 Y 活动基本信息,支付宝为数组
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换

支付宝活动activity_info如下,支持传数组；例："{\"delivery_config_list\":[{\"booth_code\":\"XXX\",\"stock_no\":\"XXX\"}]}

参数名称 类型 长度 必填 说明
delivery_config_list String
Y 活动信息
delivery_merchant_infos String
N 品牌id不传时 必填，都传则品牌id生效

delivery_config_list参数

参数名称 类型 长度 必填 说明
stock_no String 32 Y 批次号
booth_code String 20 Y _展位码:booth_code表达的是具体渠道所属的展位码。例如：支付有礼 PAY_RESULT_

delivery_merchant_infos参数

参数名称 类型 长度 必填 说明
merchant_id String 16 Y 支付宝商户号
merchant_id_type String 16 Y 传固定值SMID

微信活动activity_info如下

参数名称 类型 长度 必填 说明
activity_base_info Object 1024 N 活动基本信息
award_send_rule Object 1024 N 活动奖品发放规则

activity_base_info如下

参数名称 类型 长度 必填 说明
activity_name String 10 Y 活动名称
activity_second_title String 1024 N 活动副标题
merchant_logo_url String 255 N 商户logo，送出优惠券时展示
background_color String 8 N 代金券的背景颜色，可设置10种颜色，颜色取值请参见色卡图，默认为微信支付绿色， 颜色取值为颜色图中的颜色名称。
示例值：COLOR020
begin_time String 19 Y 活动开始时间yyyy-MM-dd HH:mm:ss
end_time String 19 Y 活动结束时间yyyy-MM-dd HH:mm:ss
available_periods Object 1024 N 可自定义活动有效时间内可用的多个时间段以及每天可用的时间点。
└available_time String 32 N 可用时间，可选择多个时间段，在可用时间段内会发放优惠券。当传入available_periods（可用时间段）后，该字段必填。yyyyMMddHHmmss-yyyyMMddHHmmss。多个逗号分隔
└available_day_time String 32 N 每日可用时间，基于“可用时间（available_time）”范围内，可再设置每日可用时间，取两者的交集时间段发券。无限制填 00:00-23:59 即可。当传入available_periods（可用时间段）后，该字段必填。多个逗号分隔
delivery_purpose String 16 Y 枚举值：
OFF_LINE_PAY：拉用户回店消费
JUMP_MINI_APP：引导用户前往小程序消费
示例值：OFF_LINE_PAY
mini_programs_appid String 32 N 商家小程序appid,投放目的为JUMP_MINI_APP时必填。
示例值：wx23232232323
mini_programs_path String 127 N 商家小程序path

award_send_rule如下

参数名称 类型 长度 必填 说明
transaction_amount_minimum String 10 Y 消费金额门槛，单位：分。
注：该字段金额指订单金额
示例值：100
send_content String 1024 Y 发放内容，可选单张券或礼包，选礼包时奖品限定3-5个。
枚举值：
SINGLE_COUPON：单张券
GIFT_PACKAGE：礼包
示例值：SINGLE_COUPON
award_type String 255 Y 奖品类型，暂时只支持商家券。枚举值：
BUSIFAVOR：商家券
示例值：BUSIFAVOR
award_list Array - Y 奖品基本信息列表，当send_content（发放内容）选择GIFT_PACKAGE（礼包）时，奖品信息必须是3-5个，与send_content（发放内容）中礼包的个数保持一致。
条目个数限制：[1，5]
注：创建活动时，作为奖品的券包，券包里的券核销时间需要一致
└stock_no String 32 Y 批次id
└original_image_url String 255 Y 奖品原始图（大图）
└thumbnail_url String 255 N 奖品缩略图（小图）

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
activity_no String 32 N 活动编号,result_code为01时返回

1.2 停止活动

  • URL:coupon/open/activitystop
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
inst_no String 8 Y 机构编号，扫呗分配
activity_no String 32 Y 活动编号 activity_no和acceptance_no二选一，都传时以activity_no为准
acceptance_no String 11 N 受理流水号 activity_no和acceptance_no二选一，都传时以activity_no为准
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换


返回参数

result String 2 Y 返回json字符串

result类型

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号

1.3 微信小程序插件发券

  • URL:coupon/marketing/minisend
  • Method: POST
  • ContentType: application/json

注：支付宝的请使用官方小程序插件
请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
inst_no String 8 Y 机构编号，扫呗分配
merchant_no String 15 Y 扫呗商户号
pay_type String 10 Y 发券类型 010微信
stock_params String 1024 Y 发券批次数组
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换


stock_params如下

参数名称 类型 长度 必填 说明
out_coupon_no String 32 N 外部券码code。当券批次券code模式为”商户发放时接口指定券code“时传
out_request_no String 32 Y 发券凭证，可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号，需在单个批次单个用户下确保唯一性
stock_no String 32 Y 券批次编号


返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
send_coupon_params String 32 N 发券参数
sign String 32 N 签名
send_coupon_merchant String 32 N 发券商户号 示例值：10016226


注意：

请求完这个接口得到的返回参数直接去调微信小程序发券插件API，参数值不用做变化

https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter9_3_1.shtml

1.4 查询用户已领取的可用的券

  • 返回的券只包含当前时间（发起查询的时间）可用的券。

  • URL:coupon/open/queryusercoupons

  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
user_id_type String 10 Y 用户标识类型
PHONE：手机号
OPENID：微信open_id
USERID：支付宝user_id
UNIONID：微信union_id
PAYCODE：付款码
CARDNO：会员卡号
user_id String 32 Y 用户标识。
user_id_type为PHONE时传手机号
user_id_type为OPENID时传微信open_id
user_id_type为USERID时传支付宝user_id
user_id_type为UNIONID时传微信union_id
user_id_type为PAYCODE时传微信/支付宝付款码
user_id_type为CARDNO时传会员卡号
channel_type String 10 N 通道类型 LC：利楚 WECHAT：微信 ALIPAY：支付宝 MALLCOO：猫酷
amount String 11 N 参与优惠金额（分）,该字段有值时返回满足该用券金额门槛的可用券
coupon_type String 10 N 券类型 0:满减券 1:折扣券 2.兑换 3.停车 4.团购 5:优惠券。4、5只在channel_type为MALLCOO时存在
,多个类型,号分割
start_time String 19 N 券有效期开始时间 yyyy-MM-dd HH:mm:ss，channel_type为LC、WECHAT、ALIPAY时该字段生效
end_time String 19 N 券有效期结束时间 yyyy-MM-dd HH:mm:ss，channel_type为LC、WECHAT、ALIPAY时该字段生效
page_size String 11 N 页面大小，最大20。不传默认每页返回10条数据
previou_id String 11 N 上一页最后一条数据id，不填查询第一页
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_info String - N 会员信息,JSON字符串,需要转义
coupons String - N 可用券列表,JSON字符串,需要转义
sence_no String 32 N 请求支付宝流水号,result_code为01时返回

member_info字段如下

参数名称 类型 长度 必填 说明
nick_name String 32 Y 昵称
phone String 11 Y 手机号
card_no String 32 Y 卡号

coupons字段如下

参数名称 类型 长度 必填 说明
id String 11 Y id
channel_type String 10 Y 通道类型 LC：利楚 WECHAT：微信
ALIPAY：支付宝
MALLCOO：猫酷
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
apply_scope String 1 Y 适用范围 0：全场 1：单品
coupon_type String 1 Y 券类型 0:满减券 1:折扣券 2:兑换券 3:停车券 4:团购券 5:优惠券。4、5只在channel_type为MALLCOO时存在
get_time String 19 N 领取时间 yyyy-MM-dd HH:mm:ss
start_time String 19 Y 券有效期开始时间 yyyy-MM-dd HH:mm:ss
end_time String 19 Y 券有效期结束时间 yyyy-MM-dd HH:mm:ss
discount_amt String 11 N 优惠金额（分），根据amount计算出来的优惠金额，amount有值时返回
actual_amt String 11 N 实付金额（分）（优惠后金额），amount有值时返回
discount_rule Object Y 优惠规则
use_rule Object Y 券使用规则

优惠规则discount_rule字段如下

参数名称 类型 长度 必填 说明
discount_threshold String 11 Y 消费门槛（分)，0代表没门槛
discount_amt String 8 N 优惠金额（分）。coupon_type为0或2时必传
rebate String 3 N 折扣，1~100的整数（eg：70表示七折）。coupon_type为1时必传
discount_top String 8 Y 单笔优惠封顶金额，0代表不封顶
park_special_tag String 1 N 停车券特殊优惠标记 0.普通优惠 1.特殊优惠 coupon_type为3时必传
deduction_amt String 11 N 抵用金额(分) coupon_type为3时选传
deduction_time String 11 N 抵消时常(分钟) coupon_type为3时选传

券使用规则use_rule字段如下

参数名称 类型 长度 必填 说明
use_time_type String 1 Y 券可用时间类型 0:用户领券后N天内可用 1:固定可用时间段 2:规则日期可用
limit_days String 4 N 用户领券多少天内有效。use_time_type为0时必传
wait_days String 4 N 领取后N天开始生效,最大值90。use_time_type为0时非必传
use_start_time String 19 N 固定可用时间段开始时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
use_end_time String 19 N 固定可用时间段结束时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
days_period String 13 N 规则日期可用星期，1代表周日，2代表周一，以此类推，多个,分隔。示例值：1,2。use_time_type为2时传，为空代表没有可用时间
time_period String 11 N 规则日期可用时间段，格式：HH:mm-HH:mm。use_time_type为2时选传，days_period不为空时和days_period搭配使用，为空代表不限制。days_period为空该字段无意义。
use_note String 144 Y 使用需知

1.5 查询用户已领取的可用的券最优解

  • URL:coupon/open/querybestcoupons
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
user_id_type String 10 Y 用户标识类型
PHONE：手机号
OPENID：微信open_id
USERID：支付宝user_id
UNIONID：微信union_id
PAYCODE：付款码
CARDNO：会员卡号
user_id String 32 Y 用户标识。
user_id_type为PHONE时传手机号
user_id_type为OPENID时传微信open_id
user_id_type为USERID时传支付宝user_id
user_id_type为UNIONID时传微信union_id
user_id_type为PAYCODE时传微信/支付宝付款码
user_id_type为CARDNO时传会员卡号
amount String 11 Y 参与优惠金额（分）
freeze_flag String 1 N 是否需要同时冻结查出的最优券 0：不冻结 1：冻结 ，该字段为空不冻结
freeze_time String 11 N 冻结时长（秒）。freeze_flag为1时选填，不可小于300秒，不传默认冻结2小时
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_info String - N 会员信息,JSON字符串,需要转义
coupon String - N 券信息,JSON字符串,需要转义
, result_code为01时返回
sence_no String 32 N 请求支付宝流水号,result_code为01时返回

member_info字段如下

参数名称 类型 长度 必填 说明
nick_name String 32 Y 昵称
phone String 11 Y 手机号
card_no String 32 Y 卡号

coupon字段如下

参数名称 类型 长度 必填 说明
coupon_credential String 128 N 优惠券凭据，调用支付接口时用，freeze_flag为1时返回
channel_type String 10 Y 通道类型 LC：利楚 WECHAT：微信
ALIPAY：支付宝
MALLCOO：猫酷
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
apply_scope String 1 Y 适用范围 0：全场 1：单品
coupon_type String 1 Y 券类型 0:满减券 1:折扣券 2:兑换券 3:停车券 4:团购券 5:优惠券。4、5只在channel_type为MALLCOO时存在
get_time String 19 N 领取时间 yyyy-MM-dd HH:mm:ss
start_time String 19 Y 券有效期开始时间 yyyy-MM-dd HH:mm:ss
end_time String 19 Y 券有效期结束时间 yyyy-MM-dd HH:mm:ss
discount_amt String 11 Y 优惠金额（分），根据amount计算出来的优惠金额
actual_amt String 11 Y 实付金额（分）（优惠后金额)
discount_rule Object Y 优惠规则
use_rule Object Y 券使用规则

优惠规则discount_rule字段如下

参数名称 类型 长度 必填 说明
discount_threshold String 11 Y 消费门槛（分)，0代表没门槛
discount_amt String 8 N 优惠金额（分）。coupon_type为0时必传
rebate String 3 N 折扣，1~100的整数（eg：70表示七折）。coupon_type为1时必传
discount_top String 8 Y 单笔优惠封顶金额，0代表不封顶
deduction_amt String 11 N 抵用金额(分) coupon_type为3时选传
deduction_time String 11 N 抵消时常(分钟) coupon_type为3时选传

券使用规则use_rule字段如下

参数名称 类型 长度 必填 说明
use_time_type String 1 Y 券可用时间类型 0:用户领券后N天内可用 1:固定可用时间段 2:规则日期可用
limit_days String 4 N 用户领券多少天内有效。use_time_type为0时必传
wait_days String 4 N 领取后N天开始生效,最大值90。use_time_type为0时非必传
use_start_time String 19 N 固定可用时间段开始时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
use_end_time String 19 N 固定可用时间段结束时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
days_period String 13 N 规则日期可用星期，1代表周日，2代表周一，以此类推，多个,分隔。示例值：1,2。use_time_type为2时传，为空代表没有可用时间
time_period String 11 N 规则日期可用时间段，格式：HH:mm-HH:mm。use_time_type为2时选传，days_period不为空时和days_period搭配使用，为空代表不限制。days_period为空该字段无意义。
use_note String 144 Y 使用需知

1.6 查询单个券信息

  • URL:coupon/open/getcoupon
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
支持100、110、200
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 O 券码，版本号110选填，其他版本必填
merchant_trade_no String 64 O 商户订单号,商户测保证唯一(与coupon_no字段二选一) 版本号110选填，其他版本不填
channel_type String 3 O 券通道类型：如
LC：利楚券
MT：美团券
DY：抖音券；
版本号200时必填
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_info String - N 会员信息,JSON字符串,需要转义
coupon String - N 券信息,JSON字符串,需要转义
, result_code为01时返回，110版本返回集合

member_info字段如下

参数名称 类型 长度 必填 说明
nick_name String 32 Y 昵称
phone String 11 Y 手机号
card_no String 32 Y 卡号

coupon字段如下

参数名称 类型 长度 必填 说明
channel_type String 10 Y 通道类型 LC：利楚 WECHAT：微信 ALIPAY：支付宝 MALLCOO：猫酷
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
apply_scope String 1 Y 适用范围 0：全场 1：单品
coupon_type String 1 Y 券类型 0:满减券 1:折扣券 2:兑换券 3:停车券 4:团购券 5:优惠券。4、5只在channel_type为MALLCOO时存在
activity_no String 32 N 所属活动编号
stock_no String 32 N 所属券批次编号
get_time String 19 Y 领取时间 yyyy-MM-dd HH:mm:ss
use_status String 1 Y 状态 1.可用 2.已失效 3.已核销 4.已过期
out_trade_no String 32 N 核销关联订单号，use_status为2时返回
use_time String 19 N 核销时间 use_status为2时返回
discount_rule Object Y 优惠规则
use_rule Object Y 券使用规则

优惠规则discount_rule字段如下

参数名称 类型 长度 必填 说明
discount_threshold String 11 Y 消费门槛（分)，0代表没门槛
discount_amt String 8 N 优惠金额（分）。coupon_type为0时必传
rebate String 3 N 折扣，1~100的整数（eg：70表示七折）。coupon_type为1时必传
discount_top String 8 Y 单笔优惠封顶金额，0代表不封顶
park_special_tag String 1 N 停车券特殊优惠标记 0.普通优惠 1.特殊优惠 coupon_type为3时必传
deduction_amt String 11 N 抵用金额(分) coupon_type为3时选传
deduction_time String 11 N 抵消时常(分钟) coupon_type为3时选传

券使用规则use_rule字段如下

参数名称 类型 长度 必填 说明
use_time_type String 1 Y 券可用时间类型 0:用户领券后N天内可用 1:固定可用时间段 2:规则日期可用
limit_days String 4 N 用户领券多少天内有效。use_time_type为0时必传
wait_days String 4 N 领取后N天开始生效,最大值90。use_time_type为0时非必传
use_start_time String 19 N 固定可用时间段开始时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
use_end_time String 19 N 固定可用时间段结束时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
days_period String 13 N 规则日期可用星期，1代表周日，2代表周一，以此类推，多个,分隔。示例值：1,2。use_time_type为2时传，为空代表没有可用时间
time_period String 11 N 规则日期可用时间段，格式：HH:mm-HH:mm。use_time_type为2时选传，days_period不为空时和days_period搭配使用，为空代表不限制。days_period为空该字段无意义。
use_note String 144 Y 使用需知

1.7 券冻结

  • URL:coupon/open/freeze
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 Y 券码
freeze_time String 11 N 冻结时长（秒），不可小于300秒，不传默认冻结2小时
goods_ids String - N 商品编号，多个商品编号,分割
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_credential String 128 N 优惠券凭据，调用支付接口时用
verify_warn_msg String 32 N 核销预警信息，result_code为01时若有值，表示用户用券次数达到了设置的优惠示警值

1.8 券解冻

  • URL:coupon/open/unfreeze
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 Y 券码
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号

1.9 券核销

  • URL:coupon/open/use
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100；
支持100，200
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 Y 券码
order_amt String 11 N 订单金额（优惠前的金额，单位分），券通道为支付宝时必传
channel_type String 3 O 券通道类型：如
LC：利楚券
MT：美团券
DY：抖音券；
版本号200时必填
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
verify_warn_msg String 32 N 核销预警信息，result_code为01时若有值，表示用户用券次数达到了设置的优惠示警值
channel_type String 3 Y 券通道类型：如
LC：利楚券
MT：美团券
DY：抖音券;
版本号200时返回
tail_amount String - N 尾款金额，等于订单总金额减去券抵扣金额;
版本号200时返回

1.10 券核销撤销

  • URL:coupon/open/canceluse
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100；
支持100，110，200
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 O 券码110版本选填，其他版本必填
merchant_trade_no String 64 O 商户订单号,商户测保证唯一(与coupon_no字段二选一)110版本支持，其他版本不填
channel_type String 3 O 券通道类型：如
LC：利楚券
MT：美团券
DY：抖音券；
版本号200必填
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
channel_type String 3 O 券通道类型：如
LC：利楚券
MT：美团券
DY：抖音券；200版本返回

1.11 券失效

  • URL:coupon/open/deactivate
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 Y 券码
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号

1.12 领券/券核销/券核销撤销通知

  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
inst_no String 8 Y 机构编号，扫呗分配
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 N 终端号
event_type String 15 Y 事件类型 USED：核销券 SEND：领券 CANCEL：核销撤销
activity_no String 32 Y 活动编号
stock_no String 32 Y 券批次编号
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
coupon_type String 1 Y 券类型 0:满减券 1:折扣券 2:兑换券 3:团购券 4:停车券 5:优惠券
phone String 20 Y 手机号
open_id String 32 Y 用户标识（微信openid，支付宝userid）
union_id String 32 N 微信开发平台UnionID，event_type为COUPON.SEND时返回
out_trade_no String 32 N 关联交易流水号，
event_type为COUPON.USE时代表支付交易订单号，
event_type为COUPON.CANCEL时代表退款/撤销交易流水号，
time String 19 Y 时间 yyyy-MM-dd HH:mm:ss，
event_type为COUPON.SEND时代表领取时间，
event_type为COUPON.USE时代表核销时间，
event_type为COUPON.CANCEL时代表核销撤销时间，
verify_merchant_no String 15 N 核券/撤销券商户号（该商户号不一定为发券商户号），event_type为USED或CANCEL时返回
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败
return_msg String 128 Y 返回信息提示

1.13 通过用户标识查询用户会员信息

  • URL:coupon/open/querymemberinfo
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
user_id_type String 10 Y 用户标识类型
PHONE：手机号
OPENID：微信open_id
USERID：支付宝user_id
UNIONID：微信union_id
CARDNO：会员卡号
user_id String 32 Y 用户标识。
user_id_type为PHONE时传手机号
user_id_type为OPENID时传微信open_id
user_id_type为USERID时传支付宝user_id
user_id_type为UNIONID时传微信union_id
user_id_type为CARDNO时传会员卡号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_info String - N 会员信息，result_code为01时有值,JSON字符串,需要转义

member_info字段如下

参数名称 类型 长度 必填 说明
nick_name String 32 Y 昵称
phone String 11 Y 手机号
card_no String 32 Y 卡号
register_time String 32 Y 注册时间 yyyy-MM-dd HH:mm:ss
balance String 11 Y 会员余额（分）
score String 11 Y 会员积分
real_name String 9 N 真实姓名
level_desc String 32 N 会员等级中文描述

1.14 微信关联订单信息

  • 将有效态（未核销）的商家券与订单信息关联，用于后续参返佣的统计。

  • 注意：订单交易时间和券核销时间间隔不可超过2分钟。

  • URL:coupon/open/associate

  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
inst_no String 8 Y 机构号
merchant_no String 15 Y 扫呗商户号
coupon_no String 32 Y 券码
out_trade_no String 128 Y 关联的商户订单号。
若商户支付是通过调用扫呗的支付接口处理的，该字段传支付接口的out_trade_no即可；
若商户支付不是通过扫呗的支付接口处理的，该字段传微信支付下单时的商户订单号。
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号

1.15 取消关联订单信息

  • URL:coupon/open/disassociate
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
inst_no String 8 Y 机构号
merchant_no String 15 Y 扫呗商户号
coupon_no String 32 Y 券码
out_trade_no String 128 Y 关联的商户订单号。
若商户支付是通过调用扫呗的支付接口处理的，该字段传支付接口的out_trade_no即可；
若商户支付不是通过扫呗的支付接口处理的，该字段传微信支付下单时的商户订单号。
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号

支付券接口

调用时序图

image.png

2.0 新增支付券

  • URL:coupon/marketing/createpaystock
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
inst_no String 8 Y 机构编号，扫呗分配
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
channel String 16 Y 渠道类型WECHAT：微信 ALIPAY：支付宝 ,多个以逗号分隔
stock_type String 16 Y 批次类型，仅支持：
NORMAL：固定面额满减券批次
stock_name String 20 Y 券名称
available_begin_time String 19 Y 可用时间-开始时间yyyy-MM-dd HH:mm:ss
available_end_time String 19 Y 可用时间-结束时间yyyy-MM-dd HH:mm:ss
stock_use_rule String 1024 Y 发放规则
pattern_info String 1024 Y 样式设置
coupon_use_rule String 1024 Y 核销规则
budget_info String 1024 Y 营销资金预算
notify_url String 255 N 接收用户核券通知地址
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换

发放规则stock_use_rule

参数名称 类型 长度 必填 说明
max_coupons String 11 Y 最大发券数
校验规则：
1、发放总个数最少5个
2、发放总个数最多1000万个
max_amount String 11 C (微信必传,支付宝不传)最大发券预算，当营销经费no_cash选择预充值false时，激活批次时会从制券商户的余额中扣除预算，请保证账户金额充足，单位：分
max_amount需要等于coupon_amount（面额） * max_coupons（发放总上限）

校验规则：批次总预算最多1000万元 | | max_coupons_per_user | String | 16 | Y | 单个用户可领个数 |

样式设置pattern_info

参数名称 类型 长度 必填 说明
description String 2000 Y 使用说明
merchant_logo String 255 C (微信时生效)商户logo url
merchant_name String 128 N 品牌名称
background_color String 16 C (微信时生效)券的背景颜色，可设置10种颜色，色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。可选枚举字段不用则不传，不可以传空值
coupon_image String 255 N 微信券详情图片 url,支付宝传resource_id
ali_coupon_image String 255 C (支付宝时生效)券详情页封面图，支付宝resource_id，resource_id调用2.3 上传营销图片获取，限制:1.指定可核销商品(available_items)时必传
ali_voucher_detail_images String 255 C (支付宝时生效)支付宝券详细图列表，支付宝resource_id，多个resource_id以逗号分隔 ，resource_id调用2.3 上传营销图片获取，限制：1.ali_coupon_image填入，该值才能填入； 2.最多3张；
customer_service_mobile String 20 C (支付宝必传)商家客服电话，会展示在支付宝卡包券详情页。

核销规则coupon_use_rule

参数名称 类型 长度 必填 说明
coupon_amount String 11 Y 面额，单位：分。
transaction_minimum String 11 Y 使用券金额门槛，单位：分。
若指定可核销商品编码，门槛则为可核销商品部分的消费金额，而不是订单的消费金额。
goods_tag array 1024 C (微信时生效)订单优惠标记，按json格式。
商户下单时需要传入相同的标记(goods_tag)，用户同时符合其他规则才能享受优惠
校验规则：
1、最多允许录入50个
2、每个订单优惠标记支持字母/数字/下划线，不超过128个UTF8字符。
available_items array 1024 N (限制:
1、available_items与
unavailable_items只能二选一或者同时为空)
可核销商品编码,包含指定SKU商品编码的交易才可核销/使用代金券：活动商户在交易下单时，需传入用户购买的所有SKU商品编码，当命中代金券中设置的商品编码时可享受优惠。
校验规则：
1、单个商品编码的字符长度为【1，128】
2、条目个数限制为【1，50】
示例值：['123321','456654']
unavailable_items array 1024 N (限制:
1、available_items与
unavailable_items只能二选一或者同时为空)包含指定SKU商品编码的交易不可核销/使用代金券。
校验规则：
1、单个商品编码的字符长度为【1，128】
2、条目个数限制为【1，50】

示例值：['123321','456654'] | | ali_available_merchants | Object | 1024 | N | 优惠券可核销的直连商户PID,优惠券可核销的间连商户SMID | | └available_pids | array | 84000 | C | 优惠券可核销的直连商户PID

限制：
1、available_pids和available_smids至少二选一。 | | └available_smids | array | 84000 | C | 优惠券可核销的间连商户SMID

限制：
1、available_pids和available_smids至少二选一。 | | wx_available_merchants | array | 1024 | N | 微信可核销商户号 |

营销资金预算budget_info

参数名称 类型 长度 必填 说明
budget_type String 11 Y 营销资金预算类型
枚举值:
NO_CASH 免充值
RECHARGE 预充值
max_amount String 11 C (微信必传,支付宝不传)最大发券预算，当营销经费no_cash选择预充值false时，激活批次时会从制券商户的余额中扣除预算，请保证账户金额充足，单位：分
max_amount需要等于coupon_amount（面额） * max_coupons（发放总上限）

校验规则：批次总预算最多1000万元 | | amount | String | 16 | c | (支付宝预充值必传)营销资金预算,单位元。
总预算=优惠金额*总发券张数 | | logon_id | String | 16 | C | (支付宝预充值必传)出资的支付宝登录账号
限制:
1、登录账号和用户ID必须且只能二选一
username@gmail.com | | user_id | String | 16 | C | (支付宝预充值必传)出资的支付宝用户id
2088512417841101
限制:
1、登录账号和用户ID必须且只能二选一 |

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
stock_no String 32 N 券批次编号,result_code为01时返回

2.1 激活支付券

  • URL:coupon/marketing/publish
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
inst_no String 8 Y 机构编号，扫呗分配
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
pay_type String 10 Y 支付类型 010微信 020支付宝
stock_no String 16 Y 券批次编号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
recharge_url String 32 N 预充值链接(支付宝返回)
限制:
1、有效时间3天

2.2 发放支付券

  • URL:coupon/marketing/send
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
inst_no String 8 Y 机构编号，扫呗分配
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
stock_no String 16 Y 券批次编号
pay_type String 10 Y 支付类型 010微信 020支付宝
openid String 32 Y 微信用户openid,支付宝user_id账号( 单个用户 )
appid String 32 C (微信必传)公众账号ID校验规则：
1、该appid需要与接口传入中的openid有对应关系；
2、该appid需要与调用接口的商户号（即请求头中的商户号）有绑定关系，若未绑定，可参考该指引完成绑定（商家商户号与AppID账号关联管理）
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
coupon_no String 32 Y 券码
receive_url String 32 N (支付宝返回)支付宝插卡包URL

2.3 上传营销图片

  • URL:coupon/marketing/uploadimage
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
inst_no String 8 Y 机构编号，扫呗分配
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
type String 10 Y 类型 010微信 020支付宝
image_url String 32 Y 图片地址
image_type String 32 Y 图片类型
券详情页封面图：PROMO_VOUCHER_IMAGE
券详细图列表：PROMO_VOUCHER_DETAIL_IMAGE
推广计划图片素材:PUBLIC_UNION_CHANNEL_PIC、DELIVERY_CHANNEL_PIC
文件业务标识。

枚举值
alipay.marketing.activity.delivery.create接口中
delivery_base_info.delivery_material.delivery_single_material.delivery_image
当delivery_booth_code=PUBLIC_UNION，上传图片接口需指定file_key=PUBLIC_UNION_CHANNEL_PIC。上传图片尺寸600600，支持格式：png、jpg、jpeg、bmp，大小不超过200kb；
当delivery_booth_code=PAYMENT_RESULT，上传图片接口需指定file_key=DELIVERY_CHANNEL_PIC。上传图片尺寸600600，支持格式：png、jpg、jpeg、bmp，大小不超过200kb。
上传图片更多要求参考文档： https://render.alipay.com/p/c/18tpirlg12e8?operateFrom=BALIPAY

alipay.marketing.activity.ordervoucher.create接口中
voucher_display_info.brand_logo字段,file_key=PROMO_BRAND_LOGO，上传图片尺寸600600，支持格式：png、jpg、jpeg、bmp，大小不超过2MB
voucher_display_info.voucher_image字段,file_key=PROMO_VOUCHER_IMAGE,上传图片尺寸670335，支持格式：png、jpg、jpeg、bmp，大小不超过2MB（支付宝图片使用该字段） | | key_sign | String | 32 | Y | 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换 |

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
resource_id String 32 N 图片唯一资源ID

2.4 支付宝补传logo

  • URL:coupon/marketing/uploadlogo
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
inst_no String 8 Y 机构编号，扫呗分配
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
logo_url String 32 Y logo图片地址
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
resource_id String 32 N 图片唯一资源ID

2.5 查询通道券批次

  • URL:coupon/marketing/querychannelstock
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
inst_no String 8 Y 机构编号，扫呗分配
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
stock_no String 32 Y 批次号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为key），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
channel_stock_list String 255 N 通道券批次数组

channel_stock_list如下

参数名称 类型 长度 必填 说明
channel_stock_id String 32 Y 上游渠道券批次id
stock_channel int 1 Y 批次通道 1.微信 2.支付宝
use_count int Y 已消耗库存
total_count int Y 总库存

会员接口

3.1 变更记录

日期 接口 内容
2022-10-20 新增接口

3.2 会员注册接口

  • 测试URL : member/terminal/registerMember
  • Method ：POST

请求参数：

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，当前版本100
trace_no String 32 Y 请求流水号
custom_no String 32 O 自定义编号，需在扫呗侧配置关联，否则不能使用
版本号110时选填
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
out_member_no String 32 O 外部会员号,商户自己的会员编号,商户侧保证唯一,选其一
phone String 11 Y 手机号
nick_name String 8 N 会员昵称
sex Integer 1 N 用户性别 0未知 1.男性 2.女性
birthday String 11 N 生日yyyy-MM-dd
user_info String 32 N 身份标识,JSON数组字符串,需要转义
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

user_info字段内容：

pay_type String Y 010微信 020支付宝
appid String O 微信必传的appid
user_id String Y 微信为opneid,支付宝为user_id

返回参数：

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码，01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 N 扫呗商户号
terminal_id String 8 Y 终端号
member_no String 32 N 会员编号
member_card_no String 32 N 会员卡号
register_time String 19 Y 注册时间 yyyy-MM-dd HH:mm:ss
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

3.3 查询会员

  • URL : member/terminal/querymember
  • Method ：POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
merchant_no String 15 Y 商户号
custom_no String 32 O 自定义编号，需在扫呗侧配置关联，否则不能使用
版本号110时选填
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
user_id_type String 3 Y 用户标识类型
AUTO: 自动识别
PAYCODE：付款码
PHONE：手机号
OPENID：微信open_id
USERID：支付宝user_id
UNIONID：微信union_id
CARDNO：会员卡号
MEMBERNO：会员编号
DYNAMICCODE：动态会员code
user_id String 32 Y 用户标识
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码，01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_no String 32 N 会员编号（注册会员才有此字段。注册会员：有录入手机号的会员）
member_card_no String 32 N 会员卡号（注册会员才有此字段。注册会员：有录入手机号的会员）
phone String 11 N 手机号（注册会员才有此字段。注册会员：有录入手机号的会员）
member_status String 2 N 会员状态 0:待激活 1:正常 2:停用 99:删除
nick_name String 8 N 会员昵称
sex String 1 N 用户性别 0未知 1.男性 2.女性
score String 11 N 积分
level String 11 N 会员等级
level_desc String 32 N 会员等级中文描述
balance String 11 N 会员卡余额(分)
birthday String 11 N 生日yyyy-MM-dd
register_time String 19 Y 注册时间 yyyy-MM-dd HH:mm:ss
update_time String 19 N 更新时间 yyyy-MM-dd HH:mm:ss
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

3.4 会员充值活动查询

URL:member/terminal/queryrechargeactivity
Method: POST
ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
terminal_id String 8 Y 终端号
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
recharge_type String 15 Y FIXED固定金额充值 ANY任意额度充值
amount String 11 N 充值任意金额，都优惠固定填写的金额,ANY任意额度充值有效（ amount=5元时 充值100元 实际支付95元 用户会员卡到账100元 ）
fixed_rule String 32 N FIXED固定金额充值规则,JSON数组字符串,最多8组
manual_switch String 1 用户手动输入充值金额开关 0.关闭 1.开启
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

fixed_rule数组字段如下

参数名称 类型 长度 必填 说明
threshold String 11 Y 充值门槛
value String 11 Y 充值赠送金额

3.5 查询用户已领取的可用的券

返回的券只包含当前时间（发起查询的时间）可用的券。
URL:member/terminal/queryusercoupons
Method: POST
ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
user_id_type String 10 Y 用户标识类型
PHONE：手机号
CHANNEL_USER_ID：支付宝/微信用户标识
OUT_USER_ID：外部系统用户标识
user_id String 32 Y 用户标识的值
amount String 11 N 参与优惠金额（分）,该字段有值时返回满足该用券金额门槛的可用券
page_size String 11 Y 页面大小，最大20。
previou_id String 11 N 上一页最后一条数据id，不填查询第一页
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换


返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupons String - N 可用券列表,JSON字符串,需要转义
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换


coupons字段如下

参数名称 类型 长度 必填 说明
id String 11 Y 券id,16进制加密
share_flag String 1 Y 能否与商家活动共享 0:否 1:能
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
apply_scope String 1 Y 适用范围 0：全场 1：单品
coupon_type String 1 Y 券类型 0:满减券 1:折扣券
get_time String 19 N 领取时间 yyyy-MM-dd HH:mm:ss
start_time String 19 Y 券有效期开始时间 yyyy-MM-dd HH:mm:ss
end_time String 19 Y 券有效期结束时间 yyyy-MM-dd HH:mm:ss
discount_rule Object Y 优惠规则
discount_amt String 11 N 优惠金额（分），根据amount计算出来的优惠金额，amount有值时返回
actual_amt String 11 N 实付金额（分）（优惠后金额），amount有值时返回


优惠规则discount_rule字段如下

参数名称 类型 长度 必填 说明
discount_threshold String 11 Y 消费门槛（分)，0代表没门槛
discount_amt String 8 N 优惠金额（分）。coupon_type为0或2时必传
rebate String 3 N 折扣，1~100的整数（eg：70表示七折）。coupon_type为1时必传
discount_top String 8 Y 单笔优惠封顶金额，0代表不封顶

3.6 会员充值(付款码支付)

  • URL：member/terminal/rechargebarcodepay
  • Method：POST
  • ContentType: application/json
参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
pay_type String 3 Y 支付方式，010微信，020支付宝，060qq钱包，090口碑，100翼支付，140和包支付（仅限和包通道）
000 自动识别类型
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
terminal_trace String 32 Y 终端流水号，填写商户系统的订单号
terminal_time String 14 Y 终端交易时间，yyyyMMddHHmmss，全局统一时间格式
member_no String 32 Y 会员编号
total_fee String 12 Y 金额，单位分
sub_appid String 16 N 子商户绑定的公众号/小程序 appid(服务商模式)
auth_no String 128 Y 授权码，客户的付款码
sence_no String 64 N 支付宝外部业务号,查询会员使用的付款码,该字段必传,传查询会员用的trace_no
operator_id String 11 N 收银员id
order_body String 128 N 订单描述
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
result_code String 2 N 业务结果 01:成功 02:失败
pay_type String 3 Y 支付方式 010:微信 020:支付宝
trace_no String 32 Y 原请求流水号
terminal_id String 8 Y 终端号
merchant_no String 15 Y 扫呗商户号
merchant_name String 40 N 商户名称
terminal_trace String 32 Y 终端流水号，填写商户系统的订单号
terminal_time String 14 Y 终端交易时间，yyyyMMddHHmmss，全局统一时间格式
total_fee String 12 N 金额，单位分
receipt_fee String 12 N 商家应结算金额,单位分
trade_no String 32 N 会员唯一订单号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

3.7 会员余额支付

支持会员满减活动,会员券,积分同时叠加
URL:member/terminal/balancepay
Method: POST
ContentType: application/json

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
pay_type String 3 Y 支付方式 010:微信 020:支付宝
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
terminal_trace String 32 Y 终端流水号，填写商户系统的订单号
terminal_time String 14 Y 终端交易时间，yyyyMMddHHmmss，全局统一时间格式
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
member_no String 32 Y 会员编号。
total_fee String 12 Y 金额，单位分
activity_no String 32 N 会员活动编号
serial_number String 1 N 优惠规则序号，
和activity_no一起传
coupon_no String 32 N 会员券码
score String 32 N 积分
order_body String 128 N 订单描述
operator_id String 11 N 收银员id
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
result_code String 2 N 业务结果 01:成功 02:失败
pay_type String 3 N 支付方式，010微信，020支付宝，060qq钱包，090口碑，100翼支付
merchant_name String 40 N 商户名称
merchant_no String 15 N 商户号
terminal_id String 8 N 终端号
terminal_trace String 32 Y 终端流水号，填写商户系统的订单号
terminal_time String 14 Y 终端交易时间，yyyyMMddHHmmss，全局统一时间格式
total_fee String 12 N 金额，单位分
receipt_fee String 12 N 实付金额，单位分
trade_no String 32 N 唯一订单号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

##

3.8 会员订单查询

URL:member/terminal/queryorder
Method: POST
ContentType: application/json

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
pay_trace String 32 N 传入支付接口中的支付终端流水号（
terminal_trace），与pay_time同时传递
pay_time String 14 N 传入支付接口中的支付终端交易时间（
terminal_time），与pay_trace同时传递
trace_no String 32 N 请求流水号，不带“-”的uuid,商户侧需保证唯一性
trade_no String 32 N 会员唯一订单号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码：01成功 ，02失败，响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示，“支付成功”，“支付中”，“请求受限”等
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
result_code String 2 N 业务结果：01成功 ，02失败 ，03支付中。支付失败和退款成功状态均返回02，具体状态和原因会在return_msg中给出解释
pay_type String 3 Y 支付方式 010:微信 020:支付宝
merchant_name String 40 N 商户名称
merchant_no String 15 N 商户号
terminal_id String 8 N 终端号
terminal_trace String 32 N 终端流水号，商户系统的查询流水号，扫呗系统原样返回
terminal_time String 14 N 终端交易时间，yyyyMMddHHmmss，全局统一时间格式
trade_no String 32 Y 会员唯一订单号
total_fee String 12 N 金额，单位分
trade_type String 10 N 交易订单类型,
BALABCE_PAY:会员余额付
GENERAL_PAY:普通支付（非余额付）
RECHARGE:会员充值
trade_state String 10 N 交易订单状态，SUCCESS支付成功，REFUND转入退款，NOTPAY未支付，CLOSED已关闭，USERPAYING用户支付中，REVOKED已撤销，NOPAY未支付支付超时，PAYERROR支付失败
user_id String 32 N 付款方用户id，“微信openid”、“支付宝账户”、“qq号”等，返回时不参与签名
receipt_fee String 12 N 实收金额，pay_type为010、020、090时必填
trade_time String 14 N 当前支付终端交易时间yyyy-MM-dd HH:mm:ss
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

3.9 查询优惠活动

  • URL : member/terminal/querydiscoutactivitylist
  • Method ：POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
user_pay_type String 1 N 用户支付方式 1.余额支付 2.非余额支付
active_object String 1 N 活动对象 1.新会员 2.老会员
member_no String 32 N 会员编号，若传了该字段，会进行该会员能参与的活动过滤
market_type String 128 N 活动类型：FULL_REDUCTION：会员消费满减 FULL_DISCOUNT：会员消费折扣 CONSUME_REDUCTION：消费立减， 多个,分割
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码，01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
activities String - N 活动列表，JSON字符串,需要转义
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

activities字段如下

参数名称 类型 长度 必填 说明
activity_no String 32 Y 活动编号
activity_name String 20 Y 活动名称
activity_pay_type String 1 Y 支付方式 0.不限 1.余额支付 2.非余额支付
market_type String 20 Y 活动类型：FULL_REDUCTION：会员消费满减 FULL_DISCOUNT：会员消费折扣 CONSUME_REDUCTION：消费立减
discounts Array - Y 优惠规则列表

discounts字段如下

参数名称 类型 长度 必填 说明
discount_threshold String 11 Y 优惠门槛金额（分）
discount_detail String 35 Y 优惠。market_type为FULL_REDUCTION、CONSUME_REDUCTION、RECHANGE_DISCOUNT时表示优惠金额（分），且需小于优惠门槛；
market_type为FULL_DISCOUNT时表示折扣eg:70=7折；多个优惠规则需保持一致。
serial_number String 1 Y 优惠规则序号

3.10 查询积分抵扣规则

  • URL : member/terminal/queryscoredeductrule
  • Method ：POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码，01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
score_use_limit String 1 Y 是否支持积分抵扣 0:不支持 1:支持
use_threshold String 11 N 积分抵扣门槛。
score_use_limit为1时返回
amt_value String 11 N 满足门槛可抵扣金额（分）
。
score_use_limit为1时返回
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

3.11. 查询单笔会员交易

  • URL : member/terminal/querytradeone
  • Method ：POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
member_trade_no String 32 N 交易流水号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码，01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
trade_data String - N 交易详情，JSON字符串,需要转义
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

trade_data字段如下

参数名称 类型 长度 必填 说明
id String 11 Y 数据id
trade_type String 1 Y 交易类型 0.会员余额支付 1.会员充值
pay_type String 3 Y 支付方式 010:微信 020:支付宝
total_fee String 11 Y 总金额(单位分)
refund_fee String 11 Y 退款金额(单位分)
balance String 11 Y 交易金额(单位分)
settle_time String 19 Y 交易时间 yyyy-MM-dd HH:mm:ss
createtime String 19 Y 创建时间 yyyy-MM-dd HH:mm:ss
update_time String 19 Y 更新时间 yyyy-MM-dd HH:mm:ss
member_trade_no String 32 Y 交易流水号
storename String 32 Y 门店名称
phone String 32 Y 会员手机号
nick_name String 32 Y 会员昵称
refund_status_code String 1 Y 退款状态，退款成功1，退款失败2
pay_status_code String 1 Y 支付状态，支付成功1，支付失败2，受理成功3， 退款成功5 退款失败6 退款中8
terminal_id String 11 Y 终端号
member_card_no String 11 Y 会员卡号
current_balance String 11 Y 当前余额(单位分)
give_balance String 11 Y 赠送的金额
change_score String 11 Y 变动会员积分
deduct_score String 11 Y 抵扣积分
deduct_amt String 11 Y 抵扣金额
order_body String 11 Y 订单描述
operator_name String 32 Y 操作员名称
out_trade_no String 32 Y 扫呗订单号
out_refund_no String 32 Y 退款的原订单号

3.12 获取优惠凭证

  • URL : member/terminal/getcredential
  • Method ：POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
amount String 11 Y 订单金额（分）
member_no String 32 N 会员号
coupon_no String 32 N 券码，
coupon_no和activity_no不可同时为空，若有传券码，该接口会将券冻结
activity_no String 32 N 消费立减活动编号
serial_number String 1 N 优惠规则序号，
activity_no不为空时必传
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码，01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
discount_credential String 128 N 优惠凭证（直接透传支付接口）
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

3.13 查询最优解

  • URL:member/terminal/queryoptimalsolution
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
trace_no String 32 Y 请求流水号，不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
user_id_type String 3 Y 用户标识类型
AUTO: 自动识别
PAYCODE：付款码
PHONE：手机号
OPENID：微信open_id
USERID：支付宝user_id
UNIONID：微信union_id
CARDNO：会员卡号
MEMBERNO：会员编号
DYNAMICCODE：动态会员code
user_id String 32 Y 用户标识
amount String 11 Y 参与优惠金额（分）
freeze_flag String 1 N 是否需要同时冻结查出的最优券 0：不冻结 1：冻结 ，该字段为空不冻结
freeze_time String 11 N 冻结时长（秒）。freeze_flag为1时选填，不可小于300秒，不传默认冻结2小时
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态，不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
discount_credential String 128 N 优惠凭证（直接透传支付接口）
member_info String - N 会员信息,JSON字符串,需要转义
coupon_info String - N 券信息,JSON字符串,需要转义
activity_info String - N 活动信息,JSON字符串,需要转义

member_info字段如下

参数名称 类型 长度 必填 说明
nick_name String 32 Y 昵称
phone String 11 Y 手机号
member_card_no String 32 Y 卡号

coupon_info字段如下

参数名称 类型 长度 必填 说明
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
coupon_type String 1 Y 券类型 0:满减券 1:折扣券 2:兑换券 3:停车券 4:团购券 5:优惠券。4、5只在channel_type为MALLCOO时存在

活动信息activity_info字段如下

参数名称 类型 长度 必填 说明
activity_no String 32 Y 活动编号
activity_name String 20 Y 活动名称
market_type String 20 Y 活动类型：FULL_REDUCTION：会员消费满减 FULL_DISCOUNT：会员消费折扣 CONSUME_REDUCTION：消费立减
serial_number String 1 Y 优惠规则序号，
activity_no不为空时必传

3.14 会员交易退款

  • URL : member/terminal/refund
  • Method ：POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
member_trade_no String 32 Y 交易流水号
refund_amt String 11 Y 退款金额
operator_id String 11 Y 用户id
auth_code String 11 N 短信验证码，跨终端退款必填
auth_id String 11 N 退款授权手机号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码，01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
refund_trade_no String 32 Y 退款流水号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（终端令牌名称为access_token），32位md5加密转换

3.15 会员信息通知

提供会员信息推送接口标准，合作方按该接口要求编写接收地址，接收推送过去的会员信息，根据自己的业务逻辑做处理。
推送参数：

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，当前版本100
trace_no String 32 Y 请求流水号
inst_no String 15 Y 机构编号，扫呗分配
merchant_no String 15 O 扫呗商户号（与品牌id二选一，查商户下的会员）
brand_id String 11 O 品牌id（与商户号二选一，查品牌下的会员，适用于多商户会员）
event_type String 8 Y 事件类型 新增ADD,更新 UPDATE
member_no String 32 Y 会员编号
member_card_no String 32 Y 会员卡号
out_member_no String 32 N 外部会员号
phone String 11 Y 手机号
nick_name String 8 N 会员昵称
sex Integer 1 N 用户性别 0未知 1.男性 2.女性
score Integer 11 N 积分
level Integer 11 N 会员等级
balance Integer 11 N 会员卡余额(分)
birthday String 11 N 生日yyyy-MM-dd
age Integer 11 N 年龄
register_time String 19 Y 注册时间 yyyy-MM-dd HH:mm:ss
update_time String 19 N 更新时间 yyyy-MM-dd HH:mm:ss
extra_params String 255 N 扩展属性字段，按json格式，如无需要则不填写。
该字段暂未开放
示例值：{'exinfo1':'1234','exinfo2':'3456'}
key_sign String 32 Y 签名串

需返回参数：

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述

3.16 积分通知

用于给合作方推送积分明细
推送参数：

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，当前版本100
trace_no String 32 Y 请求流水号
inst_no String 15 Y 机构编号，扫呗分配
merchant_no String 15 O 扫呗商户号（与品牌id二选一，查商户下的会员）
brand_id String 11 O 品牌id（与商户号二选一，查品牌下的会员，适用于多商户会员）
member_no String 32 O 会员编号
member_card_no String 32 O 会员卡号
out_member_no String 32 O 外部会员号
phone String 11 O 手机号
score_type Integer 4 Y 类型 1.余额支付消费赠送积分 2.储值赠送积分 3.余额支付抵扣扣除 4.积分换券 5.积分过期扣除 6退款扣除 7:会员营销活动赠送 8.会员等级变动赠送 9.券过期未使用退款归还 10.普通支付赠送 11.普通支付扣除 12.手动充值赠送 13.手动核销, 14.生日赠送,15.积分支付
change_type Integer 4 Y 变动类型：0.扣除 1.新增
change_score Integer 11 Y 变动积分
remain_score Integer 11 Y 当前积分
out_trade_no String 32 N 支付系统交易流水号
change_date String 10 Y 变动日期 yyyy-MM-dd
change_time String 19 Y 积分时间 yyyy-MM-dd HH:mm:ss
expire_date String 10 Y 积分有效期 yyyy-MM-dd (在这一天积分就失效了)
remark String 50 N 备注
extra_params String 255 N 扩展属性字段，按json格式，如无需要则不填写。
该字段暂未开放
示例值：{'exinfo1':'1234','exinfo2':'3456'}
key_sign String 32 Y 签名串

需返回参数：

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述

3.17 积分变更

  • URL : member/terminal/score
  • Method ：POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
member_no String 32 Y 会员编号
event_type String 32 Y 事件类型：
ADD新增
REDUCE扣减
event_name String 32 N 事件类型名
change_score String 11 Y 变更的积分
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为access_token），32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码，01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_no String 32 Y 会员编号
current_score String 11 Y 最新的积分
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为access_token），32位md5加密转换

3.18 查询会员小程序二维码地址

  • URL : member/terminal/qrurl
  • Method ：POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号，默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为access_token），32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码，01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码，01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
qr_url String 11 Y 二维码地址
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌（机构令牌名称为access_token），32位md5加密转换

© 利楚商服 2020 All rights reserved.