koubei.item.batchquery (口碑商品查询)

查询商户录入的所有商品ID接口和商品详情接口,两个接口合并为一个接口,koubei.item.batchquery 商品信息查询

公共参数

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

请求参数

参数 类型 是否必填 最大长度 描述 示例值
page_no String 可选 9 页码,留空标示第一页,默认10个结果为一页 1
page_size Number 可选 30 每页记录数,默认10,最大20 10
item_ids String 可选 32 商品Id,多个用,分割,最多支持传5个,如果不传递则查询商户下所有商品,但是不返回适用门店字段,使用了该参数,则无需填写page_no和page_size 2015052100077000000000120773
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

公共响应参数

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

响应参数

参数 类型 是否必填 最大长度 描述 示例值
page_size String 必填 3 每页记录数 20
current_page_no String 必填 9 当前页码 1
total_page_no String 必填 9 总页码数目 3
total_items String 必填 9 总共商品数目 50
item_infos ItemQueryResponse [] 必填 - 商品信息
  • └ item_id
  • String
  • 必填
  • 32
  • 商品ID
  • 20161011111111111111113
  • └ item_type
  • String
  • 必填
  • 20
  • 商品类型,交易凭证类:TRADE_VOUCHER
  • TRADE_VOUCHER
  • └ subject
  • String
  • 必填
  • 40
  • 商品名称,不超过20汉字,40个字符
  • 商品A
  • └ item_status
  • String
  • 必填
  • 20
  • 该商品当前的状态,共有5个状态:INIT(初始状态)EFFECTIVE(生效)PAUSE(暂停)FREEZE(冻结)INVALID(失效);详见状态变更图
  • EFFECTIVE
  • descriptions
  • KoubeiItemDescription []
  • 选填
  • 9999999
  • 商品描述,列表类型,每一项的key,value的描述见下面两行
  • └ title
  • String
  • 必填
  • 80
  • 描述标题,不得超过40个中文字符
  • 小标题
  • └ details
  • String []
  • 必填
  • 5200
  • 标题下的描述列表,列表类型,每项不得为空,最多10项,总长度不能超过2600个中文字符
  • 小标题下方的描述文案
  • └ inventory
  • Number
  • 必填
  • 10
  • 当前库存
  • 1000
  • └ cover
  • String
  • 必填
  • 100
  • 首图
  • 0yaPA96AQPqJDIju28pvAgAAACMAAQEC
  • └ tb_cover
  • String
  • 必填
  • 100
  • 淘宝首图
  • r3xDgvHISgKTRZ9QKmdVZQAAACMAAQED
  • └ weight
  • Number
  • 必填
  • 10
  • 商品顺序权重
  • 1
  • └ picture_details
  • String
  • 选填
  • 500
  • 商品详情图,多张图片以英文逗号分隔
  • 商品图片
  • └ shop_ids
  • String
  • 必填
  • 3000
  • 适用门店列表
  • 2015100300077000000001860010,2015100100077000000001855137
  • └ gmt_start
  • String
  • 必填
  • 50
  • 商品生效时间,商品状态有效并且到达生效时间后才可在客户端(消费者端)展示出来,如果商品生效时间小于当前时间,则立即生效。
    说明: 商品的生效时间不能早于创建当天的0点
  • 2016-10-07 11:30:24
  • └ pic_coll
  • String []
  • 选填
  • 3000
  • 图片集,本商品所有图片id和URL的对应关系数组
  • {"IUFIDASFIEUIOFKSFIUFE83IEI":"http://object.alipay.com/getpic.do?kjkdjkjj"}
  • └ price_mode
  • String
  • 必填
  • 16
  • 标准商品:FIX;非标准商品:FLOAT ,根据该字段判断商品是标准商品或非标商品。
  • FIX
  • └ original_price
  • Price
  • 选填
  • 20
  • 标准商品为原价,必填。非标准商品请勿填写,填写无效。价格单位为元
  • 100.00
  • └ price
  • Price
  • 选填
  • 20
  • 标准商品为现价,选填。非标准商品为最小价格(非标商品为xx元起)必填。价格单位为元。如果标准商品现价不填写,则以原价进行售卖;如果现价与原价相等时,则会以原价售卖,并且客户端只展示一个价格(原价)
  • 50.00
  • └ category_id
  • String
  • 选填
  • 64
  • 口碑商品所属的后台类目id,后台类目数据来源:开放接口koubei.item.category.children.batchquery(查询后台类目树接口)
  • 2017042500132112
  • trade_voucher_item_template
  • KoubeiTradeVoucherItemTemplete
  • 必填
  • 50000
  • 交易凭证类商品模板信息
  • └ 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
  • └ memo
  • String
  • 必填
  • 3000
  • 备注
  • 备注

请求示例

  • 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");
KoubeiItemBatchqueryRequest request = new KoubeiItemBatchqueryRequest();
request.setBizContent("{" +
"\"page_no\":\"1\"," +
"\"page_size\":10," +
"\"item_ids\":\"2015052100077000000000120773\"," +
"\"operation_context\":{" +
"\"op_role\":\"MERCHANT\"" +
"    }," +
"\"auth_code\":\"6a8713a414da4a2dafdb7c24e597TX80\"" +
"  }");
KoubeiItemBatchqueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

  • JSON示例
{
	"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
	"koubei_item_batchquery_response":{
		"msg":"Success",
		"code":"10000",
		"total_page_no":"3",
		"current_page_no":"1",
		"total_items":"50",
		"item_infos":[
			{
				"original_price":100.00,
				"picture_details":"商品图片",
				"item_id":"20161011111111111111113",
				"item_type":"TRADE_VOUCHER",
				"subject":"商品A",
				"tb_cover":"r3xDgvHISgKTRZ9QKmdVZQAAACMAAQED",
				"weight":1,
				"memo":"备注",
				"pic_coll":[
					"{\"IUFIDASFIEUIOFKSFIUFE83IEI\":\"http://object.alipay.com/getpic.do?kjkdjkjj\"}"
				],
				"item_status":"EFFECTIVE",
				"inventory":1000,
				"descriptions":[
					{
						"details":[
							"小标题下方的描述文案"
						],
						"title":"小标题"
					}
				],
				"cover":"0yaPA96AQPqJDIju28pvAgAAACMAAQEC",
				"gmt_start":"2016-10-07 11:30:24",
				"category_id":"2017042500132112",
				"price":50.00,
				"trade_voucher_item_template":{
					"support_book":"T",
					"buyer_notes":[
						{
							"details":[
								"小标题下方的描述文案"
							],
							"title":"小标题"
						}
					],
					"validity_period":"200"
				},
				"shop_ids":"2015100300077000000001860010,2015100100077000000001855137",
				"price_mode":"FIX"
			}
		],
		"page_size":"20"
	}
}

异常示例

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

业务错误码

错误码 错误描述 解决方案
SYSTEM_ERROR 系统繁忙 发生系统异常,请稍后重试
INVALID_PARAMETER 非法参数 请参考接口文档,检查入参是否满足要求。
AUTH_CODE_VALIDATE_FAIL auth code验证失败 传入正确的auth code
BIZ_ERROR 业务异常底层业务错误,请参考返回信息处理 底层业务错误,请参考返回信息处理

公共错误码

返回
顶部