淘宝开放平台

请求地址：

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

公共请求参数：

参数	类型	是否必填	最大长度	描述	示例值
app_id	String	是	32	支付宝分配给开发者的应用ID	2014072300007148
method	String	是	128	接口名称	koubei.item.modify
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	必须	64	支持英文字母和数字，由开发者自行定义（不允许重复），在商品notify消息中也会带有该参数，以此标明本次notify消息是对哪个请求的回应	2016102903214476899999999
item_id	String	必须	64	口碑体系内部商品的唯一标识，后续的增删改查接口都使用该ID作为主键	2015090300006123123213213
subject	String	必须	80	商品名称，请勿超过40汉字，80个字符	美发美甲套餐
inventory	Number	可选	20	商品库存数量，标准商品必填，非标准商品，不需要填写	1000
weight	String	可选	10	商品顺序权重，必须是整数，不传默认为0，权重数值越大排序越靠前	2
descriptions	KoubeiItemDescription []	可选	-	商品描述，列表类型，每一项的key，value的描述见下面两行
└ title String 必填 80 描述标题，不得超过40个中文字符小标题 └ details String [] 必填 5200 标题下的描述列表，列表类型，每项不得为空,最多10项，总长度不能超过2600个中文字符小标题下方的描述文案
gmt_start	Date	必须	50	商品生效时间，商品状态有效并且到达生效时间后才可在客户端（消费者端）展示出来，如果商品生效时间小于当前时间，则立即生效。说明：商品的生效时间不能早于创建当天的0点	2016-10-07 11:30:24
shop_ids	String	必须	50000	上架门店id列表，即传入一个或多个shop_id。多个ID则以英文分隔	2015100300077000000001860010,2015100100077000000001855137
cover	String	必须	100	商品首图。支持bmp,png,jpeg,jpg,gif格式的图片，建议宽高比16:9，建议宽高：1242*698px 图片大小≤5M。图片大小超过5M,接口会报错。若图片尺寸不对，口碑服务器自身不会做压缩，但是口碑把这些图片放到客户端上展现时，自己会做性能优化(等比缩放，以图片中心为基准裁剪)。	0yaPA96AQPqJDIju28pvAgAAACMAAQEC
tb_cover	String	可选	100	商品1:1首图，该封面图将展示在淘抢购、聚划算等商品售卖渠道。支持bmp、png、jpeg、jpg、gif格式，建议宽高比1:1，建议宽高1500*1500px，图片大小≤5M。图片大小超过5M，接口会报错。若图片尺寸不符，口碑服务器自身不会做压缩，但在口碑客户端展现时，会自动做性能优化（等比缩放，以图片中心为基准裁剪）。	0yaPA96AQPqJDIju28pvAgAAACMAAQEC
picture_details	String	可选	500	商品详情图。尺寸大小与cover一致，最多5张，以英文逗号分隔	0yaPA96AQPqJDIju28pvAgAAACMAAQEC
price	Price	可选	20	标准商品为现价,必填。非标准商品为最小价格（非标商品为xx元起）必填。价格单位为元。如果标准商品现价不填写，则以原价进行售卖；如果现价与原价相等时，则会以原价售卖，并且客户端只展示一个价格（原价）	50.00
original_price	Price	可选	20	标准商品为原价，必填。非标准商品请勿填写，填写无效。价格单位为元	100.00
item_detail_url	String	可选	200	非标准商品详情页url，用户通过此url跳转到非标准商品的商品详情页，非标准商品必填	http://api.test.aliapy.net/dfsaf.htm
trade_voucher_item_template	KoubeiTradeVoucherItemTemplete	必须	-	交易凭证类商品模板信息
└ validity_period String 可选 16 购买有效期：商品自购买起多长时间内有效，取值范围 7-360，单位天。举例，如果是7的话，是到第七天晚上23:59:59失效。商品购买后，没有在有效期内核销，则自动退款给用户。举例：买了一个高级造型师洗剪吹的商品，有效期一个月，如果一个月之后，用户没有使用商品来进行洗剪吹的服务，则自动退款给用户。 200 buyer_notes KoubeiItemDescription [] 可选 3000 购买须知，列表类型，最多10项 └ title String 必填 80 描述标题，不得超过40个中文字符小标题 └ details String [] 必填 5200 标题下的描述列表，列表类型，每项不得为空,最多10项，总长度不能超过2600个中文字符小标题下方的描述文案 └ support_book String 可选 2 表示是否支持预定，支持“T”, 不支持“F” T
category_id	String	可选	64	口碑商品所属的后台类目id，ISV可通过开放接口koubei.item.category.children.batchquery来获得后台类目树，并选择叶子类目，作为该值传入	2017042500132112
operation_context	KoubeiOperationContext	可选	-	操作上下文。isv角色操作时必填。其他角色不需填写。
└ op_role String 可选 20 如果是isv代操作，请传入ISV；如果是其他角色（商户MERCHANT、服务商PROVIDER、服务商员工S_STAFF、商户员工M_STAFF）操作，不用填写。 MERCHANT
auth_code	String	可选	64	服务商、服务商员工、商户、商户员工等口碑角色操作时必填，对应为《koubei.member.data.oauth.query》中的auth_code，有效期24小时；	6a8713a414da4a2dafdb7c24e597TX80
memo	String	可选	40	备注	备注

参数	类型	是否必填	最大长度	描述	示例值
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	即入参中的request_id	2016102903214476899999999
item_id	String	必填	64	口碑体系内部商品的唯一标识，后续的增删改查接口都使用该ID作为主键	2015090300006123123213213

JAVA
.NET
PHP
HTTP请求源码

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
KoubeiItemModifyRequest request = new KoubeiItemModifyRequest();
request.setBizContent("{" +
"\"request_id\":\"2016102903214476899999999\"," +
"\"item_id\":\"2015090300006123123213213\"," +
"\"subject\":\"美发美甲套餐\"," +
"\"inventory\":1000," +
"\"weight\":\"2\"," +
"      \"descriptions\":[{" +
"        \"title\":\"小标题\"," +
"          \"details\":[" +
"            \"小标题下方的描述文案\"" +
"          ]" +
"        }]," +
"\"gmt_start\":\"2016-10-07 11:30:24\"," +
"\"shop_ids\":\"2015100300077000000001860010,2015100100077000000001855137\"," +
"\"cover\":\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"," +
"\"tb_cover\":\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"," +
"\"picture_details\":\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"," +
"\"price\":50.00," +
"\"original_price\":100.00," +
"\"item_detail_url\":\"http://api.test.aliapy.net/dfsaf.htm\"," +
"\"trade_voucher_item_template\":{" +
"\"validity_period\":\"200\"," +
"        \"buyer_notes\":[{" +
"          \"title\":\"小标题\"," +
"            \"details\":[" +
"              \"小标题下方的描述文案\"" +
"            ]" +
"          }]," +
"\"support_book\":\"T\"" +
"    }," +
"\"category_id\":\"2017042500132112\"," +
"\"operation_context\":{" +
"\"op_role\":\"MERCHANT\"" +
"    }," +
"\"auth_code\":\"6a8713a414da4a2dafdb7c24e597TX80\"," +
"\"memo\":\"备注\"" +
"  }");
KoubeiItemModifyResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

$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 KoubeiItemModifyRequest ();
$request->setBizContent("{" .
"\"request_id\":\"2016102903214476899999999\"," .
"\"item_id\":\"2015090300006123123213213\"," .
"\"subject\":\"美发美甲套餐\"," .
"\"inventory\":1000," .
"\"weight\":\"2\"," .
"      \"descriptions\":[{" .
"        \"title\":\"小标题\"," .
"          \"details\":[" .
"            \"小标题下方的描述文案\"" .
"          ]" .
"        }]," .
"\"gmt_start\":\"2016-10-07 11:30:24\"," .
"\"shop_ids\":\"2015100300077000000001860010,2015100100077000000001855137\"," .
"\"cover\":\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"," .
"\"tb_cover\":\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"," .
"\"picture_details\":\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"," .
"\"price\":50.00," .
"\"original_price\":100.00," .
"\"item_detail_url\":\"http://api.test.aliapy.net/dfsaf.htm\"," .
"\"trade_voucher_item_template\":{" .
"\"validity_period\":\"200\"," .
"        \"buyer_notes\":[{" .
"          \"title\":\"小标题\"," .
"            \"details\":[" .
"              \"小标题下方的描述文案\"" .
"            ]" .
"          }]," .
"\"support_book\":\"T\"" .
"    }," .
"\"category_id\":\"2017042500132112\"," .
"\"operation_context\":{" .
"\"op_role\":\"MERCHANT\"" .
"    }," .
"\"auth_code\":\"6a8713a414da4a2dafdb7c24e597TX80\"," .
"\"memo\":\"备注\"" .
"  }");
$result = $aop->execute ( $request); 
 
$responseNode = str_replace(".", "_", $request->getApiMethodName()) . "_response";
$resultCode = $result->$responseNode->code;
if(!empty($resultCode)&&$resultCode == 10000){
echo "成功";
} else {
echo "失败";
}

JSON示例

{
    "koubei_item_modify_response":{
        "msg":"Success",
        "code":"10000",
        "item_id":"2015090300006123123213213",
        "request_id":"2016102903214476899999999"
    },
    "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

JSON示例

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

错误码	错误描述	解决方案
SYSTEM_ERROR	系统繁忙	重试或等待商户通知
ITEM_BUSINESS_ERROR	统一业务异常	业务失败
INVALID_PARAMETER	参数有误。	对照接口文档以及请求参数用例，修改请求参数
ITEM_UNIQUE_VIOLATION	唯一性约束错误	更换request_id
ITEM_BIZ_ALREADY_SUCCESS	商品处理已经成功	业务已经成功，本次请求为重复请求
AUTH_CODE_VALIDATE_FAIL	auth code验证失败	传入合法的auth code
ITEM_NOT_EXSIT	商品不存在	检查item_id是否正确，是否商品已经创建成功
ITEM_ILLEGAL_STATUS	商品状态非法	查看商品当前状态是否可以执行操作
BUDGET_DECREASE_NOT_ENOUGH	减少库存时库存不足	稍后重试或检查是否有被锁定的库存，导致库存不能减少
ITEM_IS_LOCKED	商品被锁定	商品被锁定，不能修改商品，待商品解锁后重试
CAN_ONLY_MANAGE_OWNED_ITEM	只能管理归属当前ISV的商品	检查修改的商品是否归属当前ISV
ITEM_SHOP_HAS_NO_PRIVILEGE	适用门店必须是当前商户的门店	检查商用门店是否归属当前商户
ITEM_HAS_NO_PRIVILEGE	商户对商品没有操作权限	商品不归属当前商户，没有操作权限。
ITEM_EXIST_FORBIDDEN_WORD	业务异常。商品操作请求中存在违禁词	去掉请求中的非法关键字
ITEM_EXIST_FORBIDDEN_URL	商品操作请求中存在非法的URL	去掉或替换请求中的不合法的URL
ITEM_BIZ_ALREADY_FAIL	商品修改操作已经失败	业务已经失败，本次为重复请求
ITEM_ILLEGAL_SHOP_INFO	业务异常。商品操作请求中门店信息有误，适用门店非法	检查创建商品时门店列表是否有误，例如错误的店铺id，店铺不存在，店铺不是open状态，店铺无证照，店铺不归属当前商户
SHOP_HAS_NO_CERTIFY	店铺需要补齐证照后才能发布商品	店铺需要补齐证照
STANDARD_CATEGORY_NOT_EXIST	后台类目不存在	确认后台类目是否存在
CATOGORY_NOT_LEAF_NODE	类目不是叶子类目或者不可发布商品	查询类目是否是叶子类目，并确认是否可发布商品

公共错误码

通知类型	描述	默认开启
item_result	商品业务结果通知	1

参数	类型	是否必填	最大长度	描述	示例值
item_id	String	必填	-	商品id
request_id	String	必填	-	外部请求流水号
biz_type	String	必填	-	业务类型，比如商品修改：ITEM_MODIFY
item_status	String	必填	-	商品状态
gmt_modified	String	必填	-	申请流水最后修改时间
merchant_pid	String []	必填	64	商户pid	2088211521646673

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=&item_id=null&request_id=null&biz_type=null&item_status=null&gmt_modified=null&merchant_pid=2088211521646673

异步通知验签方式

商品API

koubei.item.modify (修改口碑商品)

公共参数

请求参数

公共响应参数

响应参数

请求示例

响应示例

异常示例

业务错误码

公共错误码

触发通知类型

触发通知字段

触发通知示例

异步通知验签方式