淘宝开放平台 - 文档中心

请求地址：

环境	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。

名称	类型	是否必须	示例值	更多限制	描述
voucher_dto	VoucherDTO	可选			同步卡券实例
└ business_unit Number 可选 0 所属商业单元，0 未分组 └ buyer_id Number 可选 1231 买家ID，获得券的人的ID coupon_feature CouponFeature 可选券的扩展属性 └ supplier_logo String 可选 koubei.net/pinpai.png 商户Logo或品牌Logo └ detail_instruction_url String 可选 taobao.com/detail 详细说明URL coupon_function CouponFunction 可选卡券权益信息 └ amount Number 可选 100 券面额，单位分 └ start_fee Number 可选 101 使用门槛，单位分 └ discount String 可选 0.95 折扣信息 └ coupon_type Number 可选 258 卡券类型，如口碑券-258 instance_feature InstanceFeature 可选券实例扩展属性 └ instruction2_url String 可选 koubei.net/mendian.h5 口碑门店h5链接 └ action_point_url String 可选 koubei.net/using 行动点URL └ instruction1_title String 可选 koubei 扩展使用说明1 标题 └ instruction2_title String 可选 koubei 扩展使用说明2 标题 └ instruction3_title String 可选 koubei 扩展使用说明3 标题 └ instruction1 String 可选 taobao 扩展使用说明1 内容 └ instruction2 String 可选 taobao 扩展使用说明2 内容 └ instruction3 String 可选 taobao 扩展使用说明3 内容 └ instruction1_url String 可选 taobao.net/using 扩展使用说明1 图片地址 └ instruction3_url String 可选 taobao.net/using 扩展使用说明3 图片地址 └ instruction String 可选使用说明使用说明 └ memo String 可选备注备注 └ out_coupon_type Number 可选 1 外部卡券类型，自定义 └ out_instance_id String 可选 ABx21 外部实例id，自定义，唯一 └ out_instance_type Number 可选 58 外部实例类型，如口碑券-58 └ status Number 可选 1 卡券实例状态，1-可使用，0-冻结中，-1-已删除，-2-已使用 └ store_num Number 可选 1 门店数量 └ supplier_id Number 可选 110 商户id，自定义 └ supplier_type Number 可选 1 商户类型，天猫/淘宝-1 └ support_store Boolean 可选 true 是否支持门店 └ title String 可选自定义卡券包展示标题 └ voucher_end_time Date 可选 2017-09-28 18:00:00 卡券失效时间，活动结束 └ voucher_start_time Date 可选 2017-09-28 18:00:00 卡券生效时间，活动开始 └ instance_count Number 可选 1 电子凭证数量必填 └ out_coupon_id String 可选 0 外部卡券类型ID └ pictures String 可选 taobao.net/using.png 图片地址，多张图片";"隔开 └ skin String 可选 taobao.net/using.png 凭证皮肤 └ coupon_tag String 可选 koubei 卡券属性标志

名称	类型	示例值	描述
is_success	Boolean	true	success
result_code	String	PARAMETER_INVALID	resultCode
error_msg	String	parameter is invalid	errorMsg

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
PromotionVoucherSyncRequest req = new PromotionVoucherSyncRequest();
PromotionVoucherSyncRequest.VoucherDTO obj1 = new PromotionVoucherSyncRequest.VoucherDTO();
obj1.setBusinessUnit(0L);
obj1.setBuyerId(1231L);
PromotionVoucherSyncRequest.CouponFeature obj2 = new PromotionVoucherSyncRequest.CouponFeature();
obj2.setSupplierLogo("koubei.net/pinpai.png");
obj2.setDetailInstructionUrl("taobao.com/detail");
obj1.setCouponFeature(obj2);
PromotionVoucherSyncRequest.CouponFunction obj3 = new PromotionVoucherSyncRequest.CouponFunction();
obj3.setAmount(100L);
obj3.setStartFee(101L);
obj3.setDiscount("0.95");
obj1.setCouponFunction(obj3);
obj1.setCouponType(258L);
PromotionVoucherSyncRequest.InstanceFeature obj4 = new PromotionVoucherSyncRequest.InstanceFeature();
obj4.setInstruction2Url("koubei.net/mendian.h5");
obj4.setActionPointUrl("koubei.net/using");
obj4.setInstruction1Title("koubei");
obj4.setInstruction2Title("koubei");
obj4.setInstruction3Title("koubei");
obj4.setInstruction1("taobao");
obj4.setInstruction2("taobao");
obj4.setInstruction3("taobao");
obj4.setInstruction1Url("taobao.net/using");
obj4.setInstruction3Url("taobao.net/using");
obj1.setInstanceFeature(obj4);
obj1.setInstruction("使用说明");
obj1.setMemo("备注");
obj1.setOutCouponType(1L);
obj1.setOutInstanceId("ABx21");
obj1.setOutInstanceType(58L);
obj1.setStatus(1L);
obj1.setStoreNum(1L);
obj1.setSupplierId(110L);
obj1.setSupplierType(1L);
obj1.setSupportStore(true);
obj1.setTitle("自定义");
obj1.setVoucherEndTime(StringUtils.parseDateTime("2017-09-28 18:00:00"));
obj1.setVoucherStartTime(StringUtils.parseDateTime("2017-09-28 18:00:00"));
obj1.setInstanceCount(1L);
obj1.setOutCouponId("0");
obj1.setPictures("taobao.net/using.png");
obj1.setSkin("taobao.net/using.png");
obj1.setCouponTag("koubei");
req.setVoucherDto(obj1);
PromotionVoucherSyncResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
PromotionVoucherSyncRequest req = new PromotionVoucherSyncRequest();
PromotionVoucherSyncRequest.VoucherDTODomain obj1 = new PromotionVoucherSyncRequest.VoucherDTODomain();
obj1.BusinessUnit = 0L;
obj1.BuyerId = 1231L;
PromotionVoucherSyncRequest.CouponFeatureDomain obj2 = new PromotionVoucherSyncRequest.CouponFeatureDomain();
obj2.SupplierLogo = "koubei.net/pinpai.png";
obj2.DetailInstructionUrl = "taobao.com/detail";
obj1.CouponFeature= obj2;
PromotionVoucherSyncRequest.CouponFunctionDomain obj3 = new PromotionVoucherSyncRequest.CouponFunctionDomain();
obj3.Amount = 100L;
obj3.StartFee = 101L;
obj3.Discount = "0.95";
obj1.CouponFunction= obj3;
obj1.CouponType = 258L;
PromotionVoucherSyncRequest.InstanceFeatureDomain obj4 = new PromotionVoucherSyncRequest.InstanceFeatureDomain();
obj4.Instruction2Url = "koubei.net/mendian.h5";
obj4.ActionPointUrl = "koubei.net/using";
obj4.Instruction1Title = "koubei";
obj4.Instruction2Title = "koubei";
obj4.Instruction3Title = "koubei";
obj4.Instruction1 = "taobao";
obj4.Instruction2 = "taobao";
obj4.Instruction3 = "taobao";
obj4.Instruction1Url = "taobao.net/using";
obj4.Instruction3Url = "taobao.net/using";
obj1.InstanceFeature= obj4;
obj1.Instruction = "使用说明";
obj1.Memo = "备注";
obj1.OutCouponType = 1L;
obj1.OutInstanceId = "ABx21";
obj1.OutInstanceType = 58L;
obj1.Status = 1L;
obj1.StoreNum = 1L;
obj1.SupplierId = 110L;
obj1.SupplierType = 1L;
obj1.SupportStore = true;
obj1.Title = "自定义";
obj1.VoucherEndTime = DateTime.Parse(2017-09-28 18:00:00");
obj1.VoucherStartTime = DateTime.Parse(2017-09-28 18:00:00");
obj1.InstanceCount = 1L;
obj1.OutCouponId = "0";
obj1.Pictures = "taobao.net/using.png";
obj1.Skin = "taobao.net/using.png";
obj1.CouponTag = "koubei";
req.VoucherDto_ = obj1;
PromotionVoucherSyncResponse rsp = client.Execute(req);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new PromotionVoucherSyncRequest;
$voucher_dto = new VoucherDTO;
$voucher_dto->business_unit="0";
$voucher_dto->buyer_id="1231";
$coupon_feature = new CouponFeature;
$coupon_feature->supplier_logo="koubei.net/pinpai.png";
$coupon_feature->detail_instruction_url="taobao.com/detail";
$voucher_dto->coupon_feature = $coupon_feature;
$coupon_function = new CouponFunction;
$coupon_function->amount="100";
$coupon_function->start_fee="101";
$coupon_function->discount="0.95";
$voucher_dto->coupon_function = $coupon_function;
$voucher_dto->coupon_type="258";
$instance_feature = new InstanceFeature;
$instance_feature->instruction2_url="koubei.net/mendian.h5";
$instance_feature->action_point_url="koubei.net/using";
$instance_feature->instruction1_title="koubei";
$instance_feature->instruction2_title="koubei";
$instance_feature->instruction3_title="koubei";
$instance_feature->instruction1="taobao";
$instance_feature->instruction2="taobao";
$instance_feature->instruction3="taobao";
$instance_feature->instruction1_url="taobao.net/using";
$instance_feature->instruction3_url="taobao.net/using";
$voucher_dto->instance_feature = $instance_feature;
$voucher_dto->instruction="使用说明";
$voucher_dto->memo="备注";
$voucher_dto->out_coupon_type="1";
$voucher_dto->out_instance_id="ABx21";
$voucher_dto->out_instance_type="58";
$voucher_dto->status="1";
$voucher_dto->store_num="1";
$voucher_dto->supplier_id="110";
$voucher_dto->supplier_type="1";
$voucher_dto->support_store="true";
$voucher_dto->title="自定义";
$voucher_dto->voucher_end_time="2017-09-28 18:00:00";
$voucher_dto->voucher_start_time="2017-09-28 18:00:00";
$voucher_dto->instance_count="1";
$voucher_dto->out_coupon_id="0";
$voucher_dto->pictures="taobao.net/using.png";
$voucher_dto->skin="taobao.net/using.png";
$voucher_dto->coupon_tag="koubei";
$req->setVoucherDto(json_encode($voucher_dto));
$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=taobao.promotion.voucher.sync' \
-d 'partner_id=apidoc' \
-d 'sign=224AE0CBD0DAEF4117E064207B76B45C' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-05-02+22%3A21%3A34' \
-d 'v=2.0' \
-d 'voucher_dto=null'

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

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

req.voucher_dto=""
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,"taobao.promotion.voucher.sync");
add_param(pRequest,"voucher_dto","数据结构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('taobao.promotion.voucher.sync', {
	'voucher_dto':'数据结构JSON示例'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<promotion_voucher_sync_response>
    <is_success>true</is_success>
    <result_code>PARAMETER_INVALID</result_code>
    <error_msg>parameter is invalid</error_msg>
</promotion_voucher_sync_response>

{
    "promotion_voucher_sync_response":{
        "is_success":true,
        "result_code":"PARAMETER_INVALID",
        "error_msg":"parameter is invalid"
    }
}

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

taobao.promotion.voucher.sync (电子凭证同步)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ