koubei.item.create (创建口碑商品)

提供给ISV创建口碑商品

公共参数

请求地址:
环境 HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do
公共请求参数:
参数 类型 是否必填 最大长度 描述 示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 koubei.item.create
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_type String 必须 20 商品类型为交易凭证类型:TRADE_VOUCHER TRADE_VOUCHER
subject String 必须 80 商品名称,请勿超过40汉字,80个字符 美发美甲套餐
weight String 可选 10 商品顺序权重,必须是整数,不传默认为0,权重数值越大排序越靠前 2
descriptions KoubeiItemDescription [] 可选 - 商品描述,列表类型,最多10项,每一项的key,value的描述见下面两行
  • └ title
  • String
  • 必填
  • 80
  • 描述标题,不得超过40个中文字符
  • 小标题
  • └ details
  • String []
  • 必填
  • 5200
  • 标题下的描述列表,列表类型,每项不得为空,最多10项,总长度不能超过2600个中文字符
  • 小标题下方的描述文案
price_mode String 必须 16 标准商品:FIX;非标准商品:FLOAT FIX
inventory Number 可选 20 商品库存数量,标准商品必填;非标准商品不需要填写,不填写则默认为:99999999 1000
shop_ids String 必须 50000 上架门店id列表,即传入一个或多个shop_id。多个ID则以英文分隔 2015100300077000000001860010,2015100100077000000001855137
gmt_start Date 必须 50 商品生效时间,商品状态有效并且到达生效时间后才可在客户端(消费者端)展示出来,如果商品生效时间小于当前时间,则立即生效。
说明:商品的生效时间不能早于创建当天的0点
2016-10-07 11:30:24
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.alipay.net/atinterface/receive_notify.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角色操作时必填。其他角色不需填写,不填时以auth_code为准。
  • └ 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小时;isv自身角色操作的时候,无需传该参数 6a8713a414da4a2dafdb7c24e597TX80
memo String 可选 3000 备注 备注

公共响应参数

参数 类型 是否必填 最大长度 描述 示例值
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请求源码
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
KoubeiItemCreateRequest request = new KoubeiItemCreateRequest();
request.setBizContent("{" +
"\"request_id\":\"2016102903214476899999999\"," +
"\"item_type\":\"TRADE_VOUCHER\"," +
"\"subject\":\"美发美甲套餐\"," +
"\"weight\":\"2\"," +
"      \"descriptions\":[{" +
"        \"title\":\"小标题\"," +
"          \"details\":[" +
"            \"小标题下方的描述文案\"" +
"          ]" +
"        }]," +
"\"price_mode\":\"FIX\"," +
"\"inventory\":1000," +
"\"shop_ids\":\"2015100300077000000001860010,2015100100077000000001855137\"," +
"\"gmt_start\":\"2016-10-07 11:30:24\"," +
"\"cover\":\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"," +
"\"tb_cover\":\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"," +
"\"picture_details\":\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"," +
"\"price\":50.00," +
"\"original_price\":100.00," +
"\"item_detail_url\":\"http://api.test.alipay.net/atinterface/receive_notify.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\":\"备注\"" +
"  }");
KoubeiItemCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

  • JSON示例
{
	"koubei_item_create_response":{
		"msg":"Success",
		"code":"10000",
		"item_id":"2015090300006123123213213",
		"request_id":"2016102903214476899999999"
	},
	"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

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

业务错误码

错误码 错误描述 解决方案
SYSTEM_ERROR 系统繁忙 重试或等待mnotify通知
BIZ_ERROR 业务异常。底层业务错误 重试或等待异步通知
INVALID_PARAMETER 参数有误。 对照接口文档以及请求参数用例,修改请求参数
ITEM_UNIQUE_VIOLATION 唯一性约束报错,重复请求 当前request_id的请求已经被受理,如果是新请求,需更换request_id
ITEM_BIZ_ALREADY_SUCCESS 商品已经创建成功 业务已经成功,本次请求为重复请求
ITEM_HAS_NO_PRIVILEGE 无权限操作商品 根据错误文案调整参数。检查商户和门店关系
ITEM_EXIST_FORBIDDEN_URL 商品操作请求中存在非法的URL 去掉或替换请求中的不合法的URL
ITEM_EXIST_FORBIDDEN_WORD 业务异常。商品操作请求中存在违禁词 去掉请求中的非法关键字
ITEM_ILLEGAL_SHOP_INFO 业务异常。商品操作请求中门店信息有误,适用门店非法 检查创建商品时门店列表是否有误,例如错误的店铺id,店铺不存在,店铺不是open状态,店铺无证照,店铺不归属当前商户
ITEM_BIZ_ALREADY_FAIL 商品创建已经失败 业务已经失败,本次为重复请求
AUTH_CODE_VALIDATE_FAIL authcode检查失败 可能不存在或已失效 根据文案提示自查 是否为合法authcode 且 authcode授权是否已失效
ITEM_NO_CONTRACT 商户签约检查失败 商户签约检查未通过 请自查签约是否正常
ITEM_SHOP_HAS_NO_PRIVILEGE 商户对门店无权限 检查商户是否拥有该门店
SHOP_HAS_NO_CERTIFY 店铺需要补齐证照后才能发布商品 店铺需要补齐证照
STANDARD_CATEGORY_NOT_EXIST 后台类目不存在 确认后台类目是否存在
CATOGORY_NOT_LEAF_NODE 类目不是叶子类目或者不可发布商品 查询类目是否是叶子类目,并确认是否可发布商品
ITEM_CONTAIN_SPECIAL_CHARACTER 商品中有特殊字符 去掉请求中的非法字符

公共错误码

触发通知类型

通知类型 描述 默认开启
item_result 业务通知类型 商品操作相关的通知 1

触发通知字段

参数 类型 是否必填 最大长度 描述 示例值
item_id String 必填 - 口碑体系内部商品的唯一标识
request_id String 必填 - 如果是对ISV调用某次接口的响应消息,会带上这个参数,以表示对ISV哪条消息的回应
item_status String 必填 - 商品当前的状态EFFECTIVE(生效)PAUSE(暂停)FREEZE(冻结)INVALID(失效)
gmt_modified String 必填 - 本次请求商品的操作时间,格式:yyyy-MM-dd hh:mm:ss
biz_type String 必填 - 商品通知传参值范围:ITEM_CREATE(有新建商品)
notify_id String 必填 - 本次通知ID,技术参数,唯一标识一次通知
notify_type String 必填 - 通知类型,商品的通知统一为item_result
ext_info 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&item_status=null&gmt_modified=null&biz_type=null&notify_id=null&notify_type=null&ext_info=null&merchant_pid=2088211521646673

异步通知验签方式

返回
顶部