淘宝开放平台

请求地址：

环境	HTTP请求地址	HTTPS请求地址
正式环境	http://gw.api.taobao.com/router/rest	https://eco.taobao.com/router/rest

公共请求参数：

名称	类型	是否必须	描述
method	String	是	API接口名称。
app_key	String	是	TOP分配给应用的AppKey。
target_app_key	String	否	被调用的目标AppKey，仅当被调用的API为第三方ISV提供时有效。
sign_method	String	是	签名的摘要算法，可选值为：hmac，md5。
sign	String	是	API输入参数签名结果，签名算法介绍请点击这里。
session	String	否	用户登录授权成功后，TOP颁发给应用的授权信息，详细介绍请点击这里。当此API的标签上注明：“需要授权”，则此参数必传；“不需要授权”，则此参数不需要传；“可选授权”，则此参数为可选。
timestamp	String	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8，例如：2015-01-01 12:00:00。淘宝API服务端允许客户端请求最大时间误差为10分钟。
format	String	否	响应格式。默认为xml格式，可选值：xml，json。
v	String	是	API协议版本，可选值：2.0。
partner_id	String	否	合作伙伴身份标识。
simplify	Boolean	否	是否采用精简JSON返回格式，仅当format=json时有效，默认值为：false。

名称	类型	是否必须	示例值	更多限制	描述
use_request	ExternalTicketUseRequest	必须			外部券使用请求
└ quantity String 可选 2 特殊可选核销份数，次卡业务必填、非次卡业务选填，非次卡场景表示核销同一订单下的同类凭证的个数 └ ticket_request_id String 可选 2016102903214476899999999 外部请求号，支持英文字母和数字，由开发者自行定义（不允许重复） └ shop_id String 可选 671505495 核销的口碑门店id(门店同步API中的alsc_store_id)，目前是必填。只有加白的合作方法可以不填写 └ shop_type String 可选 INTERNAL_SHOP 门店id类型,INTERNAL_SHOP(内部店铺id),EXTERNAL_SHOP(外部店铺id),默认INTERNAL_SHOP └ ticket_code String 可选 016569843362 凭证码，包括内部凭证码和外部凭证码，内部凭证码为12位，纯数字，且唯一不重复 └ gmt_biz Date 可选 2017-09-09 12:12:12 业务发生时间，默认为接口调用时间 └ ticket_id String 可选 xxxx 本地侧凭证id，如果是三方码值核销传参ticketId,则该参数必须 ticket_infos TicketInfo [] 可选 [{"quantity":"","ticket_code":"","ticket_id":""}] 需要发送的码列表，其中code表示串码码值，num表示码的可核销份数 └ quantity String 可选 1 码的可核销份数 └ ticket_code String 可选 GAL358309629 凭证码值，必填 └ ticket_id String 可选 xxxxx 本地生活凭证id(奇门发码通知中的ticketId)，必填

名称	类型	示例值	描述
order_no	String	20170301011040030100490000189223	口碑子订单号, 即alsc_sub_order_no //**** 20220922后对接的服务商，不支持该字段 ****
original_price	String	100.00	用户购买时商品的原价，单位为元，精确到小数点后两位 //**** 20220922后对接的服务商，不支持该字段 ****
biz_code	String	TICKET_ALREADY_USED	该字段用于描述本次返回中的业务属性，现有：TICKET_ALREADY_USED（幂等业务码）
current_price	String	50.00	用户购买时商品的现价，单位为元，精确到小数点后两位 //**** 20220922后对接的服务商，不支持该字段 ****
discount_amount	String	1.00	商家优惠金额，单位为元，精确到小数点后两位，一次性核销多份券场景，返回总商家优惠金额 //**** 20220922后对接的服务商，不支持该字段 ****
invoice_amount	String	45.00	交易中可给用户开具发票的金额，单位为元，精确到小数点后两位，一次性核销多份券场景，返回总开票金额 //**** 20220922后对接的服务商，不支持该字段 ****
use_shop_id	String	2015100300077000000001860010	券核销门店ID //**** 20220922后对接的服务商，不支持该字段 ****
item_alias	String	2019060100076000000000002845	凭证对应商品别名，在口碑商品创建时候设置 //**** 20220922后对接的服务商，不支持该字段 ****
use_shop_name	String	烘培世家	券核销门店名称 //**** 20220922后对接的服务商，不支持该字段 ****
item_id	String	2015060400076000000000012100	口碑商品ID //**** 20220922后对接的服务商，不支持该字段 ****
receipt_amount	String	49.00	商家实收金额，单位为元，精确到小数点后两位，一次性核销多份券场景，返回总商家实收金额 //**** 20220922后对接的服务商，不支持该字段 ****
item_name	String	暑期超值洗剪吹套餐	用户购买时商品的名称 //**** 20220922后对接的服务商，不支持该字段 ****
ticket_trans_id	String	20170809001640040200080000032365	核销流水号 //**** 20220922后对接的服务商，不支持该字段 ****
use_date	String	2016-10-07 11:30:24	券核销时间
voucher_id	String	20170818000730023147007LT3RE	凭证码对应的凭证资产id //**** 20220922后对接的服务商，不支持该字段 ****
ticket_request_id	String	2016102903214476899999999	外部请求号，支持英文字母和数字，由开发者自行定义（不允许重复）
buyer_pay_amount	String	45.00	用户购买券的时候实际支付的金额，单位为元，精确到小数点后两位，一次性核销多份券场景，返回总实际支付金额 //**** 20220922后对接的服务商，不支持该字段 ****
ticket_use_details	MerchantTicketUseDetail []	[]	一次性核销多份场景，被核销的凭证明细信息
└ ticket_trans_id String 20170809001640040200080000032365 券核销流水号 └ ticket_code String 016569843362 核销的券码 └ buyer_pay_amount String 45.00 用户购买券的时候实际支付的金额，单位为元，精确到小数点后两位 //**** 20220922后对接的服务商，不支持该字段 ** └ receipt_amount String 49.00 商家实收金额，单位为元，精确到小数点后两位 //** 20220922后对接的服务商，不支持该字段 ** └ discount_amount String 1 商家优惠金额，单位为元，精确到小数点后两位 //** 20220922后对接的服务商，不支持该字段 ** └ merchant_subsidy_amount String 20 口碑补贴金额，单位为元，精确到小数点后两位 //** 20220922后对接的服务商，不支持该字段 ** └ invoice_amount String 45.00 交易中可给用户开具发票的金额，单位为元，精确到小数点后两位 //** 20220922后对接的服务商，不支持该字段 **** └ ticket_id String 123456789 对应的凭证id
merchant_subsidy_amount	String	4.00	口碑补贴金额，单位为元，精确到小数点后两位，一次性核销多份券场景，返回总口碑补贴金额 //**** 20220922后对接的服务商，不支持该字段 ****
ticket_code	String	016569843362	12位的券码，券码为纯数字，且唯一不重复 //**** 20220922后对接的服务商，不支持该字段 ****

JAVA
.NET
PHP
CURL
Python
C/C++
NodeJS

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
AlibabaAlscMerchantExtTicketcodeUseRequest req = new AlibabaAlscMerchantExtTicketcodeUseRequest();
AlibabaAlscMerchantExtTicketcodeUseRequest.ExternalTicketUseRequest obj1 = new AlibabaAlscMerchantExtTicketcodeUseRequest.ExternalTicketUseRequest();
obj1.setQuantity("2");
obj1.setTicketRequestId("2016102903214476899999999");
obj1.setShopId("671505495");
obj1.setShopType("INTERNAL_SHOP");
obj1.setTicketCode("016569843362");
obj1.setGmtBiz(StringUtils.parseDateTime("2017-09-09 12:12:12"));
obj1.setTicketId("xxxx");
List<AlibabaAlscMerchantExtTicketcodeUseRequest.TicketInfo> list3 = new ArrayList<AlibabaAlscMerchantExtTicketcodeUseRequest.TicketInfo>();
AlibabaAlscMerchantExtTicketcodeUseRequest.TicketInfo obj4 = new AlibabaAlscMerchantExtTicketcodeUseRequest.TicketInfo();
list3.add(obj4);
obj4.setQuantity("1");
obj4.setTicketCode("GAL358309629");
obj4.setTicketId("xxxxx");
obj1.setTicketInfos(list3);
req.setUseRequest(obj1);
AlibabaAlscMerchantExtTicketcodeUseResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
AlibabaAlscMerchantExtTicketcodeUseRequest req = new AlibabaAlscMerchantExtTicketcodeUseRequest();
AlibabaAlscMerchantExtTicketcodeUseRequest.ExternalTicketUseRequestDomain obj1 = new AlibabaAlscMerchantExtTicketcodeUseRequest.ExternalTicketUseRequestDomain();
obj1.Quantity = "2";
obj1.TicketRequestId = "2016102903214476899999999";
obj1.ShopId = "671505495";
obj1.ShopType = "INTERNAL_SHOP";
obj1.TicketCode = "016569843362";
obj1.GmtBiz = DateTime.Parse(2017-09-09 12:12:12");
obj1.TicketId = "xxxx";
List<AlibabaAlscMerchantExtTicketcodeUseRequest.TicketInfoDomain> list3 = new List<AlibabaAlscMerchantExtTicketcodeUseRequest.TicketInfoDomain>();
AlibabaAlscMerchantExtTicketcodeUseRequest.TicketInfoDomain obj4 = new AlibabaAlscMerchantExtTicketcodeUseRequest.TicketInfoDomain();
list3.Add(obj4);
obj4.Quantity = "1";
obj4.TicketCode = "GAL358309629";
obj4.TicketId = "xxxxx";
obj1.TicketInfos= list3;
req.UseRequest_ = obj1;
AlibabaAlscMerchantExtTicketcodeUseResponse rsp = client.Execute(req);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new AlibabaAlscMerchantExtTicketcodeUseRequest;
$use_request = new ExternalTicketUseRequest;
$use_request->quantity="2";
$use_request->ticket_request_id="2016102903214476899999999";
$use_request->shop_id="671505495";
$use_request->shop_type="INTERNAL_SHOP";
$use_request->ticket_code="016569843362";
$use_request->gmt_biz="2017-09-09 12:12:12";
$use_request->ticket_id="xxxx";
$ticket_infos = new TicketInfo;
$ticket_infos->quantity="1";
$ticket_infos->ticket_code="GAL358309629";
$ticket_infos->ticket_id="xxxxx";
$use_request->ticket_infos = $ticket_infos;
$req->setUseRequest(json_encode($use_request));
$resp = $c->execute($req);

curl -X POST 'http://gw.api.taobao.com/router/rest' \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'app_key=12129701' \
-d 'format=json' \
-d 'method=alibaba.alsc.merchant.ext.ticketcode.use' \
-d 'partner_id=apidoc' \
-d 'sign=D85959A95CD6FCF09FD44E456717893E' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-05-05+18%3A58%3A35' \
-d 'v=2.0' \
-d 'use_request=null'

# -*- coding: utf-8 -*-
import top.api

req=top.api.AlibabaAlscMerchantExtTicketcodeUseRequest(url,port)
req.set_app_info(top.appinfo(appkey,secret))

req.use_request=""
try:
	resp= req.getResponse()
	print(resp)
except Exception,e:
	print(e)

pTopRequest pRequest = alloc_top_request();
pTopResponse pResponse = NULL;
pTaobaoClient pClient = alloc_taobao_client(url, appkey, appsecret);
set_api_name(pRequest,"alibaba.alsc.merchant.ext.ticketcode.use");
add_param(pRequest,"use_request","数据结构JSON示例");
pResponse = top_execute(pClient,pRequest,NULL);
printf("ret code:%d\n",pResponse->code);
if(pResponse->code == 0){
	pTopResponseIterator ite = init_response_iterator(pResponse);
	pResultItem pResultItem = alloc_result_item();
	while(parseNext(ite, pResultItem) == 0){
		printf("%s:%s\n",pResultItem->key,pResultItem->value);
	}
	destroy_response_iterator(ite);
	destroy_result_item(pResultItem);
}
destroy_top_request(pRequest);
destroy_top_response(pResponse);
destroy_taobao_client(pClient);

TopClient = require('./topClient').TopClient;
var client = new TopClient({
	'appkey': 'appkey',
	'appsecret': 'secret',
	'REST_URL': 'http://gw.api.taobao.com/router/rest'
});

client.execute('alibaba.alsc.merchant.ext.ticketcode.use', {
	'use_request':'数据结构JSON示例'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<alibaba_alsc_merchant_ext_ticketcode_use_response>
    <order_no>20170301011040030100490000189223</order_no>
    <original_price>100.00</original_price>
    <biz_code>TICKET_ALREADY_USED</biz_code>
    <current_price>50.00</current_price>
    <discount_amount>1.00</discount_amount>
    <invoice_amount>45.00</invoice_amount>
    <use_shop_id>2015100300077000000001860010</use_shop_id>
    <item_alias>2019060100076000000000002845</item_alias>
    <use_shop_name>烘培世家</use_shop_name>
    <item_id>2015060400076000000000012100</item_id>
    <receipt_amount>49.00</receipt_amount>
    <item_name>暑期超值洗剪吹套餐</item_name>
    <ticket_trans_id>20170809001640040200080000032365</ticket_trans_id>
    <use_date>2016-10-07 11:30:24</use_date>
    <voucher_id>20170818000730023147007LT3RE</voucher_id>
    <ticket_request_id>2016102903214476899999999</ticket_request_id>
    <buyer_pay_amount>45.00</buyer_pay_amount>
    <ticket_use_details>
        <merchant_ticket_use_detail>
            <ticket_trans_id>20170809001640040200080000032365</ticket_trans_id>
            <ticket_code>016569843362</ticket_code>
            <buyer_pay_amount>45.00</buyer_pay_amount>
            <receipt_amount>49.00</receipt_amount>
            <discount_amount>1</discount_amount>
            <merchant_subsidy_amount>20</merchant_subsidy_amount>
            <invoice_amount>45.00</invoice_amount>
            <ticket_id>123456789</ticket_id>
        </merchant_ticket_use_detail>
    </ticket_use_details>
    <merchant_subsidy_amount>4.00</merchant_subsidy_amount>
    <ticket_code>016569843362</ticket_code>
</alibaba_alsc_merchant_ext_ticketcode_use_response>

{
    "alibaba_alsc_merchant_ext_ticketcode_use_response":{
        "order_no":"20170301011040030100490000189223",
        "original_price":"100.00",
        "biz_code":"TICKET_ALREADY_USED",
        "current_price":"50.00",
        "discount_amount":"1.00",
        "invoice_amount":"45.00",
        "use_shop_id":"2015100300077000000001860010",
        "item_alias":"2019060100076000000000002845",
        "use_shop_name":"烘培世家",
        "item_id":"2015060400076000000000012100",
        "receipt_amount":"49.00",
        "item_name":"暑期超值洗剪吹套餐",
        "ticket_trans_id":"20170809001640040200080000032365",
        "use_date":"2016-10-07 11:30:24",
        "voucher_id":"20170818000730023147007LT3RE",
        "ticket_request_id":"2016102903214476899999999",
        "buyer_pay_amount":"45.00",
        "ticket_use_details":{
            "merchant_ticket_use_detail":[
                {
                    "ticket_trans_id":"20170809001640040200080000032365",
                    "ticket_code":"016569843362",
                    "buyer_pay_amount":"45.00",
                    "receipt_amount":"49.00",
                    "discount_amount":"1",
                    "merchant_subsidy_amount":"20",
                    "invoice_amount":"45.00",
                    "ticket_id":"123456789"
                }
            ]
        },
        "merchant_subsidy_amount":"4.00",
        "ticket_code":"016569843362"
    }
}

XML示例
JSON示例

<error_response>
    <code>50</code>
    <msg>Remote service error</msg>
    <sub_code>isv.invalid-parameter</sub_code>
    <sub_msg>非法参数</sub_msg>
</error_response>

{
	"error_response":{
		"msg":"Remote service error",
		"code":50,
		"sub_msg":"非法参数",
		"sub_code":"isv.invalid-parameter"
	}
}

错误码	错误描述	解决方案

API测试工具错误码查询工具 SDK下载

本地生活商户基础API

alibaba.alsc.merchant.ext.ticketcode.use (外部核销服务)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ