koubei.catering.item.query (口碑餐饮行业商品详情查询接口)

isv查询口碑餐饮商品详情

公共参数

请求地址:
环境 HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do
公共请求参数:
参数 类型 是否必填 最大长度 描述 示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 koubei.catering.item.query
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 请求id。支持英文字母和数字,由开发者自行定义(不允许重复)。比如2016102903214476899999999 2016102903214476899999999
item_id String 必须 64 口碑体系内部商品的唯一标识 2015090300006123123213213
auth_code String 可选 64 服务商、服务商员工、商户、商户员工等口碑角色操作时必填,对应为《koubei.member.data.oauth.query》中的auth_code,默认有效期24小时;isv自身角色操作的时候,无需传该参数 6a8713a414da4a2dafdb7c24e597TX80

公共响应参数

参数 类型 是否必填 最大长度 描述 示例值
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 请求id。支持英文字母和数字,由开发者自行定义(不允许重复)。比如2016102903214476899999999 2016102903214476899999999
item_id String 必填 64 口碑体系内部商品的唯一标识 2015090300006123123213213
ticket_display_mode String 必填 20 商品购买凭证核销方式。枚举值为:USER_PAY_CODE代表付款码核销方式,如果选择付款码核销,则sku_id必填。TICKET_CODE代表券码核销方式,如果选择券码核销,则sku_id必须为空 USER_PAY_CODE
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,接口会报错。若图片尺寸不对,口碑服务器自身不会做压缩,但是口碑把这些图片放到客户端上展现时,自己会做性能优化(等比缩放,以图片中心为基准裁剪)。 VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD
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
shop_ids String [] 必填 50000 商品关联门店id列表,即传入一个或多个shop_id。 [2015100300077000000001860010, 2015100300077000000001860011]
item_status String 必填 20 该商品当前的状态,共有5个状态:INIT(初始状态)EFFECTIVE(生效)PAUSE(暂停)FREEZE(冻结)INVALID(失效) EFFECTIVE
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 商品详情-补充说明列表 补充说明:套餐可以叠加使用
buyer_notes BuyerNotesInfo [] 选填 - 商品购买须知列表
  • └ title
  • String
  • 必填
  • 30
  • 描述标题,不得超过15个中文字符
  • 小标题
  • └ details
  • String []
  • 选填
  • 5200
  • 标题下的描述列表,列表类型,每项不得为空,最多10项,总长度不能超过2600个中文字符
  • 小标题下方的描述文案
latest_notice String 选填 200 商家公告,最多不超过200个字符 本店周五休息不上班
memo String 选填 100 商品备注信息。用于商户内部管理,用户页面不露出。 备注:肯德基(蚂蚁金服店)首推新品
merchant_introduction IntroductionInfo 选填 - 商品详情-商家介绍图文详情
  • └ title
  • String
  • 选填
  • 30
  • 商品详情-商家介绍标题
  • 肯德基(蚂蚁金服店)店内环境。不得超过15个中文字符
  • └ image_urls
  • String []
  • 选填
  • 500
  • 商品详情-商家介绍图片地址列表
  • 0yaPA96AQPqJDIju28pvAgAAACMAAQEC,0yaPA96AQPqJDIju28pvAgAAACMAAQEC
weight String 选填 10 商品顺序权重,必须是整数,不传默认为0,权重数值越大排序越靠前 2
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

请求示例

  • 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");
KoubeiCateringItemQueryRequest request = new KoubeiCateringItemQueryRequest();
request.setBizContent("{" +
"\"operator_type\":\"MERCHANT\"," +
"\"request_id\":\"2016102903214476899999999\"," +
"\"item_id\":\"2015090300006123123213213\"," +
"\"auth_code\":\"6a8713a414da4a2dafdb7c24e597TX80\"" +
"  }");
KoubeiCateringItemQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

  • JSON示例
{
	"koubei_catering_item_query_response":{
		"msg":"Success",
		"original_price":120.12,
		"taobao_cover_image":"VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD",
		"picture_details":[
			"[0yaPA96AQPqJDIju28pvAgAAACMAAQEC",
			" VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD]"
		],
		"code":"10000",
		"buyer_notes":[
			{
				"details":[
					"小标题下方的描述文案"
				],
				"title":"小标题"
			}
		],
		"subject":"鱼香肉丝杨梅汁套餐",
		"merchant_introduction":{
			"image_urls":[
				"0yaPA96AQPqJDIju28pvAgAAACMAAQEC",
				"0yaPA96AQPqJDIju28pvAgAAACMAAQEC"
			],
			"title":"肯德基(蚂蚁金服店)店内环境。不得超过15个中文字符"
		},
		"package_notes":[
			"补充说明:套餐可以叠加使用"
		],
		"memo":"备注:肯德基(蚂蚁金服店)首推新品",
		"inventory":1000,
		"cover":"VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD",
		"gmt_start":"2016-10-07 11:30:24",
		"category_id":"2017081400178386",
		"price":119.99,
		"unavailable_periods":[
			{
				"end_day":"2017-05-03",
				"start_day":"2017-05-01"
			}
		],
		"shop_ids":[
			"[2015100300077000000001860010",
			" 2015100300077000000001860011]"
		],
		"item_id":"2015090300006123123213213",
		"validity_period":300,
		"weight":"2",
		"sku_id":"2017071013300001",
		"item_status":"EFFECTIVE",
		"available_periods":[
			{
				"time_start":"08:30",
				"available_week_days":"\"1,2\"",
				"time_end":"22:30"
			}
		],
		"item_dishes":[
			{
				"image_urls":[
					"0yaPA96AQPqJDIju28pvAgAAACMAAQEC",
					"0yaPA96AQPqJDIju28pvAgAAACMAAQEC"
				],
				"title":"鱼香肉丝",
				"desc":"鱼香肉丝盖浇饭"
			}
		],
		"ticket_display_mode":"USER_PAY_CODE",
		"item_packages":[
			{
				"item_units":[
					{
						"amount":100,
						"unit":"份",
						"price":88.12,
						"title":"宫保鸡丁",
						"spec":"大份"
					}
				],
				"title":"鱼香肉丝套餐"
			}
		],
		"request_id":"2016102903214476899999999",
		"latest_notice":"本店周五休息不上班"
	},
	"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

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

业务错误码

错误码 错误描述 解决方案
ITEM_OPERATION_ERROR 商品操作异常 检查商品信息是否录入正确
SYSTEM_ERROR 系统繁忙 联系口碑商品开放技术人员进行问题排查
ITEM_ILLEGAL_PARAMS 商品操作参数异常 检查调用商品操作接口时入参
ITEM_FROBIDDEN_WORD 商品操作包含违禁词 检查并修改违禁词
ITEM_SPECIAL_CHAR 商品操作包含特殊字符 检查并修改商品操作中特殊字符
QUERY_NO_DATA 查询无相关商品数据 检查查询入参是否正确
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格式错误 检查入参后重新请求

公共错误码

返回
顶部