koubei.trade.ticket.ticketcode.query(口碑凭证码查询)

根据凭证码查询口碑凭证核销状态、核销明细、价格、有效期等信息; 仅允许查询本商户下的凭证

公共参数

请求地址

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

公共请求参数

参数 类型 是否必填最大长度描述示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 koubei.trade.ticket.ticketcode.query
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
app_auth_token String 40 详见应用授权概述
biz_content String 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
ticket_code String 必选 12 12位的券码,券码为纯数字,且唯一不重复 016569843362
shop_id String 必选 64 口碑门店id 2017071200077000000039734370

响应参数

参数 类型 是否必填 最大长度 描述 示例值
ticket_code String 必填 12 12位的券码,券码为纯数字,且唯一不重复 016569843362
ticket_status String 必填 50 券状态
1. USED:该券已经被消费,无法核销
2. EFFECTIVE:未核销,且可以在当前门店核销
3. UN_EFFECTIVE:未核销,但不可以在当前门店核销
4. REFUNDED:该券已经退款,无法核销
5. USING:核销处理中,无法核销
6. REFUNDING:退款处理中,无法核销
EFFECTIVE
ticket_status_desc String 必填 50 券状态描述
1. 该券已经被消费,无法核销
2. 未核销,且可以在当前门店核销
3. 未核销,但不可以在当前门店核销
4. 该券已经退款,无法核销
5. 该券正在核销处理中,无法核销
6. 该券正在退款处理中,无法核销
该券已经被消费,无法核销
item_name String 必填 500 商品名称 暑期超值洗剪吹套餐
item_id String 必填 64 口碑商品ID 2015060400076000000000012100
original_price String 必填 20 用户购买时商品的原价 100.00
current_price String 必填 20 用户购买时商品的现价 50.0
effect_date String 必填 50 券生效时间 2016-10-07 11:30:24
expire_date String 必填 50 券失效时间 2017-07-04 23:12:45
voucher_id String 必填 64 券码对应的凭证资产id 20170818000730023147007LT3RE
order_no String 必填 64 凭证对应的订单号 20170819011040030100490000189333
available_quantity String 选填 6 非次卡场景,表示同一订单下同类凭证的可核销份数; 次卡场景,表示可用核销份数。 10
total_quantity String 选填 6 非次卡场景,表示同一订单下同类凭证的总份数;次卡场景,表示次卡原始总份数 10
time_cards String 必填 6 是否次卡。是次卡场景值为true,反之为false true
ticket_trans_info_list TicketTransInfo 选填 凭证的流水记录
ticket_trans_id String 必填 60 凭证流水id 20170809001640040200080000032365
ticket_trans_type String 必填 20 流水类型 核销流水:USE; 退款流水:REFUND; 售后退流水:USED_REFUND
create_time Date 必填 30 流水创建时间 2017-08-09 14:28:52
last_modify_time Date 必填 60 最后修改时间,也就是流水状态更新为成功的时间 2017-08-09 14:28:52

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
KoubeiTradeTicketTicketcodeQueryRequest request = new KoubeiTradeTicketTicketcodeQueryRequest();
request.setBizContent("{" +
"\"ticket_code\":\"016569843362\"," +
"\"shop_id\":\"2017071200077000000039734370\"" +
"  }");
KoubeiTradeTicketTicketcodeQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "koubei_trade_ticket_ticketcode_query_response": {
        "code": "10000",
        "msg": "Success",
        "ticket_code": "016569843362",
        "ticket_status": "EFFECTIVE",
        "ticket_status_desc": "该券已经被消费,无法核销",
        "item_name": "暑期超值洗剪吹套餐",
        "item_id": "2015060400076000000000012100",
        "original_price": "100.00",
        "current_price": "50.0",
        "effect_date": "2016-10-07 11:30:24",
        "expire_date": "2017-07-04 23:12:45",
        "voucher_id": "20170818000730023147007LT3RE",
        "order_no": "20170819011040030100490000189333",
        "available_quantity": "10",
        "total_quantity": "10",
        "time_cards": "true",
        "ticket_trans_info_list": [
            {
                "ticket_trans_id": "20170809001640040200080000032365",
                "ticket_trans_type": "核销流水:USE;\r\n退款流水:REFUND;\r\n售后退流水:USED_REFUND",
                "create_time": "2017-08-09 14:28:52",
                "last_modify_time": "2017-08-09 14:28:52"
            }
        ]
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

{
    "koubei_trade_ticket_ticketcode_query_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 非当前商家的凭证码,无法查询 只能查询当前商家的凭证码,确认该凭证码是否属于本商家
onlineServer