koubei.trade.ticket.ticketcode.use(口碑凭证码核销) 在线调试(沙箱环境)

根据凭证码和门店id核销口碑凭证

公共参数

请求地址

环境HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do

公共请求参数

参数 类型 是否必填最大长度描述示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 koubei.trade.ticket.ticketcode.use
format String 40 仅支持JSON JSON
charset String 10 请求使用的编码格式,如utf-8,gbk,gb2312等 utf-8
sign_type String 10 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2
sign String 344 商户请求参数的签名串,详见签名 详见示例
timestamp String 19 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" 2014-07-24 03:07:50
version String 3 调用的接口版本,固定为:1.0 1.0
notify_url String 256 支付宝服务器主动通知商户服务器里指定的页面http/https路径。 http://api.test.alipay.net/atinterface/receive_notify.htm
app_auth_token String 40 详见应用授权概述
biz_content String 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
request_id String 必选 32 外部请求号,支持英文字母和数字,由开发者自行定义(不允许重复) 2016102903214476899999999
ticket_code String 必选 32 凭证码,包括内部凭证码和外部凭证码,内部凭证码为12位,纯数字,且唯一不重复 016569843362
shop_id String 必选 64 口碑门店id 2017071200077000000039734370
shop_type String 可选 16 门店id类型,INTERNAL_SHOP(内部店铺id),EXTERNAL_SHOP(外部店铺id),默认INTERNAL_SHOP INTERNAL_SHOP
quantity String 特殊可选 4 核销份数,次卡业务必填、非次卡业务选填, 非次卡场景表示核销同一订单下的同类凭证的个数 2
order_no String 特殊可选 32 口碑订单号,使用外部凭证码核销时必填 20180404111040030100130500594477
code_type String 特殊可选 16 凭证码类型,INTERNAL_CODE(内部凭证码),EXTERNAL_CODE(外部凭证码),默认INTERNAL_CODE,外部券场景必填 INTERNAL_CODE
gmt_biz Date 可选 32 业务发生时间,默认为接口调用时间 2017-09-09 12:12:12

响应参数

参数 类型 是否必填 最大长度 描述 示例值
request_id String 必填 64 外部请求号,支持英文字母和数字,由开发者自行定义(不允许重复) 2016102903214476899999999
ticket_code String 必填 64 12位的券码,券码为纯数字,且唯一不重复 016569843362
item_name String 必填 500 用户购买时商品的名称 暑期超值洗剪吹套餐
ticket_trans_id String 必填 60 核销流水号 20170809001640040200080000032365
item_id String 必填 64 口碑商品ID 2015060400076000000000012100
original_price String 必填 20 用户购买时商品的原价,单位为元,精确到小数点后两位 100.00
current_price String 必填 20 用户购买时商品的现价,单位为元,精确到小数点后两位 50.00
use_date String 必填 50 券核销时间 2016-10-07 11:30:24
use_shop_id String 必填 64 券核销门店ID 2015100300077000000001860010
use_shop_name String 必填 100 券核销门店名称 烘培世家
buyer_pay_amount String 必填 20 用户购买券的时候实际支付的金额,单位为元,精确到小数点后两位,一次性核销多份券场景,返回总实际支付金额 45.00
receipt_amount String 必填 20 商家实收金额,单位为元,精确到小数点后两位,一次性核销多份券场景,返回总商家实收金额 49.00
discount_amount String 必填 20 商家优惠金额,单位为元,精确到小数点后两位,一次性核销多份券场景,返回总商家优惠金额 1.00
koubei_subsidy_amount String 必填 20 口碑补贴金额,单位为元,精确到小数点后两位,一次性核销多份券场景,返回总口碑补贴金额 4.00
invoice_amount String 必填 20 交易中可给用户开具发票的金额,单位为元,精确到小数点后两位,一次性核销多份券场景,返回总开票金额 45.00
order_no String 必填 64 凭证码所属的订单id 20170301011040030100490000189223
voucher_id String 必填 64 凭证码对应的凭证资产id 20170818000730023147007LT3RE
biz_code String 选填 32 该字段用于描述本次返回中的业务属性,现有:BIZ_ALREADY_SUCCESS(幂等业务码) BIZ_ALREADY_SUCCESS
item_alias String 选填 256 凭证对应商品别名,在口碑商品创建时候设置 2019060100076000000000002845
ticket_use_details KbTicketUseDetail 选填 500 非次卡一次性核销多份场景,被核销的凭证明细信息
ticket_code String 必填 64 核销的券码 016569843362
ticket_trans_id String 必填 60 券核销流水号 20170809001640040200080000032365
buyer_pay_amount String 必填 20 用户购买券的时候实际支付的金额,单位为元,精确到小数点后两位 45.00
receipt_amount String 必填 20 商家实收金额,单位为元,精确到小数点后两位 49.00
discount_amount String 必填 20 商家优惠金额,单位为元,精确到小数点后两位 1
koubei_subsidy_amount String 必填 20 口碑补贴金额,单位为元,精确到小数点后两位 20
invoice_amount String 必填 20 交易中可给用户开具发票的金额,单位为元,精确到小数点后两位 45.00

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
KoubeiTradeTicketTicketcodeUseRequest request = new KoubeiTradeTicketTicketcodeUseRequest();
request.setBizContent("{" +
"\"request_id\":\"2016102903214476899999999\"," +
"\"ticket_code\":\"016569843362\"," +
"\"shop_id\":\"2017071200077000000039734370\"," +
"\"shop_type\":\"INTERNAL_SHOP\"," +
"\"quantity\":\"2\"," +
"\"order_no\":\"20180404111040030100130500594477\"," +
"\"code_type\":\"INTERNAL_CODE\"," +
"\"gmt_biz\":\"2017-09-09 12:12:12\"" +
"  }");
KoubeiTradeTicketTicketcodeUseResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "koubei_trade_ticket_ticketcode_use_response": {
        "code": "10000",
        "msg": "Success",
        "request_id": "2016102903214476899999999",
        "ticket_code": "016569843362",
        "item_name": "暑期超值洗剪吹套餐",
        "ticket_trans_id": "20170809001640040200080000032365",
        "item_id": "2015060400076000000000012100",
        "original_price": "100.00",
        "current_price": "50.00",
        "use_date": "2016-10-07 11:30:24",
        "use_shop_id": "2015100300077000000001860010",
        "use_shop_name": "烘培世家",
        "buyer_pay_amount": "45.00",
        "receipt_amount": "49.00",
        "discount_amount": "1.00",
        "koubei_subsidy_amount": "4.00",
        "invoice_amount": "45.00",
        "order_no": "20170301011040030100490000189223",
        "voucher_id": "20170818000730023147007LT3RE",
        "biz_code": "BIZ_ALREADY_SUCCESS",
        "item_alias": "2019060100076000000000002845",
        "ticket_use_details": [
            {
                "ticket_code": "016569843362",
                "ticket_trans_id": "20170809001640040200080000032365",
                "buyer_pay_amount": "45.00",
                "receipt_amount": "49.00",
                "discount_amount": "1",
                "koubei_subsidy_amount": "20",
                "invoice_amount": "45.00"
            }
        ]
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

{
    "koubei_trade_ticket_ticketcode_use_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "系统繁忙"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

业务错误码

公共错误码

错误码错误描述解决方案
SYSTEM_ERROR 系统繁忙 重试
INVALID_PARAMETER 参数有误 对照接口文档以及请求参数用例,修改请求参数
TICKET_CODE_NOT_EXIST 凭证码不存在 凭证码不存在,需要核实
TICKET_CODE_INVALID 凭证码不合法 凭证码不合法,仔细检查凭证码格式,如长度是否为12位
NOT_SAME_MERCHANT_PID 非当前商家的凭证码,无法使用 只能查询当前商家的凭证码,确认该凭证码是否属于本商家
TICKET_STATUS_ILLEGAL 券已使用或已退款 检查券的状态
TICKET_PROCESSING 券已经在处理中 券已经在处理中,稍后查看券的最新状态
OUT_OF_SHOP_LIMIT 券码不能在当前门店使用 该券不可在当前门店使用,请切换对应门店后使用
TICKET_NOT_UNDER_VALID_DATE 券不在有效期内,无法使用 券不在有效期内,无法使用,确认券的使用时间
REQUEST_ID_REPEAT 券核销流水号重复,但核销参数不一致 券核销流水号重复,但核销参数不一致,流水号生成存在重复,检查流水号生成规则
SHOP_HAS_RISK 本交易存在风险,无法在当前门店核销 联系口碑客服小二(400-826-7710)
USE_SHOP_NOT_EXIST 核销门店不存在 核销门店不存在,请检查门店id和门店类型是否正确
TICKET_QUALITY_NOT_ENOUGH 券码可用份数不足 确认可用核销份数后重新发起请求
USE_PAYEE_INVALID_STATUS 门店收款账号异常 排查收款账号是否正常

触发通知类型

通知类型描述默认开启
koubei_ticket_openapi_use_notify 业务通知类型 口碑开放平台券核销通知 1

触发通知示例

https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync&notify_id=91722adff935e8cfa58b3aabf4dead6ibe&notify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&request_id=2016102903214476899999999&notify_id=2015060400076000000000012100&notify_type=koubei_ticket_openapi_use_notify&ticket_trans_id=20170809001640040200080000032365&biz_type=TICKET_USE&ticket_code=016569843362&item_name=暑期超值洗剪吹套餐&item_id=2015060400076000000000012100&original_price=100.00&current_price=50.00&use_date=2016-10-07 11:30:24&use_shop_id=2015100300077000000001860010&use_shop_name=烘培世家&buyer_pay_amount=45.00&receipt_amount=49.00&discount_amount=1.00&koubei_subsidy_amount=4.00&invoice_amount=45.00&order_no=20170301011040030100490000189223&voucher_id=20170818000730023147007LT3RE
onlineServer