淘宝开放平台

登录
文档中心 > API类目 > 商品API

koubei.catering.item.create (口碑餐饮行业商品创建接口)

isv为口碑餐饮商户创建商品

公共参数

请求地址：
环境 HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do
公共请求参数：
参数 类型 是否必填 最大长度 描述 示例值
app_id String 是 32 支付宝分配给开发者的应用ID 2014072300007148
method String 是 128 接口名称 koubei.catering.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
app_auth_token String 否 40 详见应用授权概述
biz_content String 是 - 请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
operator_type String 必须 20 操作人员身份类型。如果是isv代操作，请传入ISV；如果是商户操作请传入MERCHANT；如果是商户员工则传入M_STAFF MERCHANT
request_id String 必须 64 支持英文字母和数字，由开发者自行定义（不允许重复），在商品notify消息中也会带有该参数，以此标明本次notify消息是对哪个请求的回应 2016102903214476899999999
original_price Price 必须 20 商品原价。字符串类型，单位元，2位小数。最高价格49998元 120.12
price Price 必须 20 商品现价（优惠价）。字符串类型，单位元，2位小数。最高价格49998元 119.99
cover String 必须 100 商品首图。支持bmp,png,jpeg,jpg,gif格式的图片，建议宽高比16:9，建议宽高：1242*698px 图片大小≤5M。图片大小超过5M,接口会报错。若图片尺寸不对，口碑服务器自身不会做压缩，但是口碑把这些图片放到客户端上展现时，自己会做性能优化(等比缩放，以图片中心为基准裁剪) VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD
shop_ids String [] 必须 50000 商品需要关联的门店id列表，即传入一个或多个shop_id。 2015100300077000000001860010, 2015100300077000000001860011
item_packages ItemPackageInfo [] 必须 - 商品详情-商品套餐内容
  • └ title
  • String
  • 必填
  • 30
  • 商品详情-套餐标题。最多不超过15个汉字，30个字符
  • 鱼香肉丝套餐
  • item_units
  • ItemUnitInfo []
  • 必填
  • 500
  • 商品详情-套餐内菜品信息列表
  • └ title
  • String
  • 必填
  • 40
  • 商品详情-商品套餐内容-菜品名称。不得超过40个字符
  • 宫保鸡丁
  • └ price
  • Price
  • 必填
  • 20
  • 商品详情-商品套餐内容-菜品价格。字符串，单位元，两位小数
  • 88.12
  • └ amount
  • Number
  • 必填
  • 20
  • 商品详情-商品套餐内容-菜品数量
  • 100
  • └ unit
  • String
  • 必填
  • 20
  • 商品详情-商品套餐内容-菜品数量单位
  • 份
  • └ spec
  • String
  • 可选
  • 20
  • 商品详情-商品套餐内容-菜品规格
  • 大份
item_dishes ItemDishInfo [] 必须 - 商品详情-菜品图文详情
  • └ title
  • String
  • 必填
  • 40
  • 详情图片中，菜品标题。请勿超过20个汉字，40个字符
  • 鱼香肉丝
  • └ image_urls
  • String []
  • 必填
  • 500
  • 详情图片中，菜品图片。支持bmp,png,jpeg,jpg,gif格式的图片，建议宽高比16:9，建议宽高：1242*698px 图片大小≤5M。图片大小超过5M,接口会报错。若图片尺寸不对，口碑服务器自身不会做压缩，但是口碑把这些图片放到客户端上展现时，自己会做性能优化(等比缩放，以图片中心为基准裁剪)。
  • 0yaPA96AQPqJDIju28pvAgAAACMAAQEC,0yaPA96AQPqJDIju28pvAgAAACMAAQEC
  • └ desc
  • String
  • 可选
  • 100
  • 商品详情-菜品图片中的图片描述
  • 鱼香肉丝盖浇饭
inventory Number 必须 20 发布商品库存数量 1000
gmt_start Date 必须 50 商品生效时间，商品状态有效并且到达生效时间后才可在客户端（消费者端）展示出来，如果商品生效时间小于当前时间，则立即生效。
说明：商品的生效时间不能早于创建当天的0点		 2016-10-07 11:30:24
validity_period Number 必须 16 购买有效期：商品自购买起多长时间内有效，取值范围 7-360，单位天。举例，如果是7的话，是到第七天晚上23:59:59失效。商品购买后，没有在有效期内核销，则自动退款给用户。举例：买了一个鱼香肉丝杨梅汁套餐的商品，有效期一个月，如果一个月之后，用户没有消费该套餐，则自动退款给用户 360
subject String 必须 60 商品名称，请勿超过60个字符 鱼香肉丝杨梅汁套餐
ticket_display_mode String 必须 20 商品购买凭证核销方式。枚举值为：USER_PAY_CODE代表付款码核销方式，如果选择付款码核销，则sku_id必填。TICKET_CODE代表券码核销方式，如果选择券码核销，则sku_id必须为空 USER_PAY_CODE
latest_notice String 可选 200 商家公告，最多不超过200个字符 本店周五休息不上班
category_id String 必须 64 口碑商品所属的后台类目id，ISV可通过开放接口koubei.item.category.children.batchquery来获得后台类目树，并选择叶子类目，作为该值传入 2017081400178386
picture_details String [] 可选 500 商品详情图片列表。尺寸大小与商品首图一致，最多5张。C端上展现时，自己会做性能优化(等比缩放，以图片中心为基准裁剪) 0yaPA96AQPqJDIju28pvAgAAACMAAQEC, 0yaPA96AQPqJDIju28pvAgAAACMAAQEC
weight String 可选 10 商品顺序权重，必须是整数，不传默认为0，权重数值越大排序越靠前 2
auth_code String 可选 64 服务商、服务商员工、商户、商户员工等口碑角色操作时必填，对应为《koubei.member.data.oauth.query》中的auth_code，默认有效期24小时；isv自身角色操作的时候，无需传该参数 6a8713a414da4a2dafdb7c24e597TX80
sku_id String 可选 64 商品编码，由商家自定义，不可重复，用于商品核销。如果ticket_display_mode选择付款码核销方式(USER_PAY_CODE)，则sku_id必填。如果ticket_display_mode选择券码核销方式(TICKET_CODE)，则sku_id必须为空 2017071013300001
package_notes String [] 可选 1000 商品详情-套餐补充说明列表 补充说明：套餐可以叠加使用
merchant_introduction IntroductionInfo 可选 - 商品详情-商家介绍图文详情
  • └ title
  • String
  • 可选
  • 30
  • 商品详情-商家介绍标题
  • 肯德基（蚂蚁金服店）店内环境。不得超过15个中文字符
  • └ image_urls
  • String []
  • 可选
  • 500
  • 商品详情-商家介绍图片地址列表
  • 0yaPA96AQPqJDIju28pvAgAAACMAAQEC,0yaPA96AQPqJDIju28pvAgAAACMAAQEC
buyer_notes BuyerNotesInfo 可选 - 商品购买须知
  • └ title
  • String
  • 必填
  • 30
  • 描述标题，不得超过15个中文字符
  • 小标题
  • └ details
  • String []
  • 可选
  • 5200
  • 标题下的描述列表，列表类型，每项不得为空,最多10项，总长度不能超过2600个中文字符
  • 小标题下方的描述文案
memo String 可选 100 商品备注信息。用于商户内部管理，用户页面不露出。 备注：肯德基（蚂蚁金服店）首推新品
available_periods AvailablePeriodInfo [] 可选 - 商品可用时段列表。最多添加三条规则。该内容仅用于展示，不影响实际核销。
  • └ time_start
  • String
  • 必填
  • 50
  • 可用时段开始时间。格式为HH:mm，如08:30
  • 08:30
  • └ time_end
  • String
  • 必填
  • 50
  • 商品可用时段结束时间。格式HH:mm，如22:30
  • 22:30
  • └ available_week_days
  • String
  • 必填
  • 50
  • 每周可用天列表。格式为星期几并用逗号分隔。如周一周二可用则为“1,2”，周五周六可用则为"5,6"
  • "1,2"
unavailable_periods UnavailablePeriodInfo [] 可选 - 商品不可用日期区间。该内容仅用于展示，不影响实际核销。
  • └ start_day
  • String
  • 必填
  • 50
  • 商品不可用时段开始日期。格式为YYYY-MM-DD，如2017-05-01
  • 2017-05-01
  • └ end_day
  • String
  • 必填
  • 50
  • 商品不可用时段结束日期。格式为YYYY-MM-DD，如2017-05-03
  • 2017-05-03
taobao_cover_image String 可选 100 商品首图(1:1)版本，作为商品在淘宝渠道露出的首图。支持bmp，png，jpeg，jpg，gif格式的图片。如果某个商品的本字段为空，则该商品无法再淘宝渠道露出 VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD

公共响应参数

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

响应参数

参数 类型 是否必填 最大长度 描述 示例值
item_id String 必填 64 口碑体系内部商品的唯一标识 2015090300006123123213213
request_id String 必填 64 支持英文字母和数字，由开发者自行定义（不允许重复），在商品notify消息中也会带有该参数，以此标明本次notify消息是对哪个请求的回应 2016102903214476899999999

请求示例

  • 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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
KoubeiCateringItemCreateRequest request = new KoubeiCateringItemCreateRequest();
request.setBizContent("{" +
"\"operator_type\":\"MERCHANT\"," +
"\"request_id\":\"2016102903214476899999999\"," +
"\"original_price\":120.12," +
"\"price\":119.99," +
"\"cover\":\"VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD\"," +
"      \"shop_ids\":[" +
"        \"2015100300077000000001860010\",\" 2015100300077000000001860011\"" +
"      ]," +
"      \"item_packages\":[{" +
"        \"title\":\"鱼香肉丝套餐\"," +
"          \"item_units\":[{" +
"            \"title\":\"宫保鸡丁\"," +
"\"price\":88.12," +
"\"amount\":100," +
"\"unit\":\"份\"," +
"\"spec\":\"大份\"" +
"            }]" +
"        }]," +
"      \"item_dishes\":[{" +
"        \"title\":\"鱼香肉丝\"," +
"          \"image_urls\":[" +
"            \"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\",\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"" +
"          ]," +
"\"desc\":\"鱼香肉丝盖浇饭\"" +
"        }]," +
"\"inventory\":1000," +
"\"gmt_start\":\"2016-10-07 11:30:24\"," +
"\"validity_period\":360," +
"\"subject\":\"鱼香肉丝杨梅汁套餐\"," +
"\"ticket_display_mode\":\"USER_PAY_CODE\"," +
"\"latest_notice\":\"本店周五休息不上班\"," +
"\"category_id\":\"2017081400178386\"," +
"      \"picture_details\":[" +
"        \"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\",\" 0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"" +
"      ]," +
"\"weight\":\"2\"," +
"\"auth_code\":\"6a8713a414da4a2dafdb7c24e597TX80\"," +
"\"sku_id\":\"2017071013300001\"," +
"      \"package_notes\":[" +
"        \"补充说明：套餐可以叠加使用\"" +
"      ]," +
"\"merchant_introduction\":{" +
"\"title\":\"肯德基（蚂蚁金服店）店内环境。不得超过15个中文字符\"," +
"        \"image_urls\":[" +
"          \"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\",\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"" +
"        ]" +
"    }," +
"\"buyer_notes\":{" +
"\"title\":\"小标题\"," +
"        \"details\":[" +
"          \"小标题下方的描述文案\"" +
"        ]" +
"    }," +
"\"memo\":\"备注：肯德基（蚂蚁金服店）首推新品\"," +
"      \"available_periods\":[{" +
"        \"time_start\":\"08:30\"," +
"\"time_end\":\"22:30\"," +
"\"available_week_days\":\"\\\"1,2\\\"\"" +
"        }]," +
"      \"unavailable_periods\":[{" +
"        \"start_day\":\"2017-05-01\"," +
"\"end_day\":\"2017-05-03\"" +
"        }]," +
"\"taobao_cover_image\":\"VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD\"" +
"  }");
KoubeiCateringItemCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

  • JSON示例
1
2
3
4
5
6
7
8
9
{
    "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
    "koubei_catering_item_create_response":{
        "msg":"Success",
        "code":"10000",
        "item_id":"2015090300006123123213213",
        "request_id":"2016102903214476899999999"
    }
}

异常示例

  • JSON示例
1
2
3
4
5
6
7
8
9
{
    "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
    "koubei_catering_item_create_response":{
        "msg":"Service Currently Unavailable",
        "code":"20000",
        "sub_msg":"系统繁忙",
        "sub_code":"isp.unknow-error"
    }
}

业务错误码

错误码 错误描述 解决方案
ITEM_OPERATION_ERROR 商品操作发生异常 重试或等待异步通知
SYSTEM_ERROR 系统繁忙 重试或联系技术人员协助
ITEM_ILLEGAL_PARAMS 商品操作参数异常 对照接口文档以及请求参数用例，修改请求参数
ITEM_NO_LICENSE 商品关联无证门店 去除商品包含的无证门店或上传门店相关证照
ITEM_FROBIDDEN_WORD 商品操作包含违禁词 去掉请求中的非法关键字
ITEM_SPECIAL_CHAR 商品操作包含特殊字符 检查并修改商品操作中特殊字符
ITEM_ALIPASS 创建Alipass券模板失败 联系客服解决
SYSTEM_UPDATE 系统升级中，请稍后再试 请稍后再试，或联系客服询问具体原因
INVALID_PARAMETER 参数有误 对照接口文档以及请求参数用例，修改请求参数
AUTH_CODE_VALIDATE_FAIL authcode检查失败 可能不存在或已失效 根据文案提示自查 是否为合法authcode 且 authcode授权是否已失效
ITEM_UNIQUE_VIOLATION 唯一性约束报错，重复请求 当前request_id的请求已经被受理，如果是新请求，需更换request_id
SYSTEM_ERROR 系统繁忙 重试或联系技术人员协助
NO_PERMISSION 无调用接口权限 请联系业务人员添加相应权限
BIZ_ERROR 业务异常 根据错误码提示排查原因
INVALID_PARAMETER 参数有误biz_content的json格式错误 检查入参后重新请求

公共错误码

公共错误码
有用(0)
我要提问
返回
顶部