淘宝开放平台

请求地址：

环境	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	必须	12	12位的券码，券码为纯数字，且唯一不重复	016569843362
shop_id	String	必须	64	口碑门店id	2017071200077000000039734370

参数	类型	是否必填	最大长度	描述	示例值
code	String	是	-	网关返回码,详见文档	40004
msg	String	是	-	网关返回码描述,详见文档	Business Failed
sub_code	String	否	-	业务返回码,详见文档	ACQ.TRADE_HAS_SUCCESS
sub_msg	String	否	-	业务返回码描述,详见文档	交易已被支付
sign	String	是	-	签名,详见文档	DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=

参数	类型	是否必填	最大长度	描述	示例值
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

JAVA
.NET
PHP
HTTP请求源码

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\"" +
"  }");
KoubeiTradeTicketTicketcodeUseResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

IAopClient client = new DefaultAopClient("https://openapi.alipay.com/gateway.do", "app_id", "merchant_private_key", "json", "1.0", "RSA2", "alipay_public_key", "GBK", false);
KoubeiTradeTicketTicketcodeUseRequest  request= new KoubeiTradeTicketTicketcodeUseRequest() ;
request.BizContent="{" +
"\"request_id\":\"2016102903214476899999999\"," +
"\"ticket_code\":\"016569843362\"," +
"\"shop_id\":\"2017071200077000000039734370\"" +
"  }";
KoubeiTradeTicketTicketcodeUseResponse response=client.execute(request);
Console.WriteLine(response.Body);

$aop = new AopClient ();
$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
$aop->appId = 'your app_id';
$aop->rsaPrivateKey = '请填写开发者私钥去头去尾去回车，一行字符串';
$aop->alipayrsaPublicKey='请填写支付宝公钥，一行字符串';
$aop->apiVersion = '1.0';
$aop->signType = 'RSA2';
$aop->postCharset='GBK';
$aop->format='json';
$request = new KoubeiTradeTicketTicketcodeUseRequest ();
$request->setBizContent("{" .
"\"request_id\":\"2016102903214476899999999\"," .
"\"ticket_code\":\"016569843362\"," .
"\"shop_id\":\"2017071200077000000039734370\"" .
"  }");
$result = $aop->execute ( $request); 

$responseNode = str_replace(".", "_", $request->getApiMethodName()) . "_response";
$resultCode = $result->$responseNode->code;
if(!empty($resultCode)&&$resultCode == 10000){
echo "成功";
} else {
echo "失败";
}

https://openapi.alipay.com/gateway.do?timestamp=2013-01-01 08:08:08&method=koubei.trade.ticket.ticketcode.use&app_id=5236&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&biz_content=
  {
"request_id":"2016102903214476899999999",
"ticket_code":"016569843362",
"shop_id":"2017071200077000000039734370"
  }

//为确保安全通信，需自行验证响应示例中的sign值是否为蚂蚁金服所提供。

JSON示例

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

JSON示例

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

错误码	错误描述	解决方案
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）

公共错误码

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

参数	类型	是否必填	最大长度	描述	示例值
request_id	String	必填	64	如果是对ISV调用某次接口的响应消息，会带上这个参数，以表示对ISV哪条消息的回应	2016102903214476899999999
notify_id	String	必填	200	本次通知ID，技术参数，唯一标识一次通知	2015060400076000000000012100
notify_type	String	必填	50	通知类型，口碑券操作通知统一为koubei_ticket_openapi_use_notify	koubei_ticket_openapi_use_notify
ticket_trans_id	String []	必填	60	核销流水号	20170809001640040200080000032365
biz_type	String	必填	50	业务类型，比如券码核销：TICKET_USE	TICKET_USE
ticket_code	String	必填	64	12位的券码，券码为纯数字，且唯一不重复	016569843362
item_name	String	必填	500	用户购买时商品的名称	暑期超值洗剪吹套餐
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

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

异步通知验签方式

营销API

koubei.trade.ticket.ticketcode.use (口碑凭证码核销)

公共参数

请求参数

公共响应参数

响应参数

请求示例

响应示例

异常示例

业务错误码

公共错误码

触发通知类型

触发通知字段

触发通知示例

异步通知验签方式