koubei.catering.item.modify (口碑餐饮行业商品修改接口)

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

公共参数

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

请求参数

参数 类型 是否必填 最大长度 描述 示例值
operator_type String 可选 64 操作人员身份类型。如果是isv代操作,请传入ISV;如果是商户操作请传入MERCHANT;如果是商户员工则传入M_STAFF MERCHANT
request_id String 必须 64 请求id。支持英文字母和数字,由开发者自行定义(不允许重复)。比如2016102903214476899999999 2016102903214476899999999
item_id String 必须 64 口碑体系内部商品的唯一标识 2015090300006123123213213
subject String 必须 60 商品名称,请勿超过60个字符 鱼香肉丝杨梅汁套餐
category_id String 必须 64 口碑商品所属的后台类目id,ISV可通过开放接口koubei.item.category.children.batchquery来获得后台类目树,并选择叶子类目,作为该值传入 2017081400178386
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,接口会报错。若图片尺寸不对,口碑服务器自身不会做压缩,但是口碑把这些图片放到客户端上展现时,自己会做性能优化(等比缩放,以图片中心为基准裁剪)。 0yaPA96AQPqJDIju28pvAgAAACMAAQEC
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失效。商品购买后,没有在有效期内核销,则自动退款给用户。举例:买了一个鱼香肉丝杨梅汁套餐的商品,有效期一个月,如果一个月之后,用户没有消费该套餐,则自动退款给用户 300
ticket_display_mode String 必须 20 商品购买凭证核销方式。枚举值为:USER_PAY_CODE代表付款码核销方式,如果选择付款码核销,则sku_id必填。TICKET_CODE代表券码核销方式,如果选择券码核销,则sku_id必须为空 USER_PAY_CODE
weight String 可选 10 商品顺序权重,必须是整数,不传默认为0,权重数值越大排序越靠前 2
auth_code String 可选 64 服务商、服务商员工、商户、商户员工等口碑角色操作时必填,对应为《koubei.member.data.oauth.query》中的auth_code,默认有效期24小时;isv自身角色操作的时候,无需传该参数 6a8713a414da4a2dafdb7c24e597TX80
picture_details String [] 可选 500 商品详情图片列表。尺寸大小与商品首图一致,最多5张。C端上展现时,自己会做性能优化(等比缩放,以图片中心为基准裁剪) [0yaPA96AQPqJDIju28pvAgAAACMAAQEC, VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD]
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个中文字符
  • 小标题下方的描述文案
latest_notice String 可选 200 商家公告,最多不超过200个字符 本店周五休息不上班
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 支持英文字母和数字,由开发者自行定义(不允许重复) yyyymmddhhmmssSSS99999999,比如2016102903214476899999999

请求示例

  • 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");
KoubeiCateringItemModifyRequest request = new KoubeiCateringItemModifyRequest();
request.setBizContent("{" +
"\"operator_type\":\"MERCHANT\"," +
"\"request_id\":\"2016102903214476899999999\"," +
"\"item_id\":\"2015090300006123123213213\"," +
"\"subject\":\"鱼香肉丝杨梅汁套餐\"," +
"\"category_id\":\"2017081400178386\"," +
"\"original_price\":120.12," +
"\"price\":119.99," +
"\"cover\":\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"," +
"      \"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\":300," +
"\"ticket_display_mode\":\"USER_PAY_CODE\"," +
"\"weight\":\"2\"," +
"\"auth_code\":\"6a8713a414da4a2dafdb7c24e597TX80\"," +
"      \"picture_details\":[" +
"        \"[0yaPA96AQPqJDIju28pvAgAAACMAAQEC\",\" VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD]\"" +
"      ]," +
"\"sku_id\":\"2017071013300001\"," +
"      \"package_notes\":[" +
"        \"补充说明:套餐可以叠加使用\"" +
"      ]," +
"\"merchant_introduction\":{" +
"\"title\":\"肯德基(蚂蚁金服店)店内环境。不得超过15个中文字符\"," +
"        \"image_urls\":[" +
"          \"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\",\"0yaPA96AQPqJDIju28pvAgAAACMAAQEC\"" +
"        ]" +
"    }," +
"\"buyer_notes\":{" +
"\"title\":\"小标题\"," +
"        \"details\":[" +
"          \"小标题下方的描述文案\"" +
"        ]" +
"    }," +
"\"latest_notice\":\"本店周五休息不上班\"," +
"\"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\"" +
"  }");
KoubeiCateringItemModifyResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

  • JSON示例
{
	"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
	"koubei_catering_item_modify_response":{
		"msg":"Success",
		"code":"10000",
		"item_id":"2015090300006123123213213",
		"request_id":"yyyymmddhhmmssSSS99999999,比如2016102903214476899999999"
	}
}

异常示例

  • JSON示例
{
	"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
	"koubei_catering_item_modify_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_LOCKED 商品已参加平台活动被锁定,只允许修改部分信息 联系客服将商品踢出活动后修改
ITEM_SPECIAL_CHAR 商品操作包含特殊字符 检查并修改商品操作中特殊字符
ITEM_ALIPASS 创建Alipass券模板失败 联系客服解决
INVALID_PARAMETER 参数有误 校验入参是否正正确
SYSTEM_UPDATE 系统升级中,请稍后再试 请稍后再试,或联系客服询问具体原因
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格式错误 检查入参后重新请求

公共错误码

返回
顶部