批量查询商品接口
最后更新于
接口说明
接口名称:alipay.aipay.nowpay.product.batchquery
批量查询指定外部平台资源归属账号下的商品,返回命中的商品列表;无命中时返回空数组。
适用场景
- 根据多个外部商品 ID,批量获取商品信息。
- 在商品列表页集中展示商品基础信息和收费配置。
- 查询指定商品的记录状态及创建、修改时间。
注意事项
external_owner_id、out_product_ids均为必选字段。out_product_ids的列表范围为 0~100;原文同时标注长度范围为 1~4096,但未明确该长度约束的适用对象,接入时需核对。- 无命中时
items为空数组。按每个元素的out_product_id关联平台商品,不依赖返回顺序。 - 原文未展开
NowpayProduct及收费配置子字段的完整定义。下文子字段根据响应示例整理,未提供的必选性、长度和完整枚举不作推定。
公共请求参数
| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
|---|---|---|---|---|---|
app_id |
String | 必选 | 32 | 支付宝分配给开发者的应用ID | YOUR_APP_ID |
method |
String | 必选 | 128 | 接口名称 | alipay.aipay.nowpay.product.batchquery |
format |
String | 可选 | 40 | 仅支持JSON | JSON |
charset |
String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | utf-8 |
sign_type |
String | 必选 | 10 | 请求签名算法,推荐 RSA2 | RSA2 |
sign |
String | 必选 | 344 | 商户请求参数的签名串,详见签名 | 详见示例 |
timestamp |
String | 必选 | 19 | 发送请求的时间,格式”yyyy-MM-dd HH:mm:ss” | 2026-09-07 10:00:00 |
version |
String | 必选 | 3 | 调用的接口版本,固定为:1.0 | 1.0 |
app_auth_token |
String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见应用授权概述 | - |
biz_content |
String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - |
业务请求参数
业务字段统一放入 biz_content。下表数组子字段使用 [] 表示元素路径。
| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 |
|---|---|---|---|---|---|---|
external_owner_id |
String | 必选 | 128 | 外部平台资源归属账号 | - | usr_01 |
out_product_ids |
String[] | 必选 | 4096 | 外部商品 ID 列表 | 列表范围:0~100 | [“pro_01”,“pro_02”] |
常见请求示例
以下账号和商品 ID 均为演示值。Java 使用支付宝服务端 SDK;私钥保存在平台服务端。cURL 签名需基于本次实际请求生成,授权令牌按实际调用场景配置。
biz_content='{
"external_owner_id": "usr_01",
"out_product_ids": [
"pro_01",
"pro_02"
]
}'
# app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。
curl --request POST 'https://openapi.alipay.com/gateway.do' \
--data-urlencode "app_id=${app_id}" \
--data-urlencode 'method=alipay.aipay.nowpay.product.batchquery' \
--data-urlencode 'format=json' \
--data-urlencode 'charset=UTF-8' \
--data-urlencode 'sign_type=RSA2' \
--data-urlencode "timestamp=${timestamp}" \
--data-urlencode 'version=1.0' \
--data-urlencode "biz_content=${biz_content}" \
--data-urlencode "sign=${sign}"import com.alipay.api.AlipayConfig;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.request.AlipayAipayNowpayProductBatchqueryRequest;
import com.alipay.api.response.AlipayAipayNowpayProductBatchqueryResponse;
public class NowpayExample {
public static void main(String[] args) throws Exception {
AlipayConfig config = new AlipayConfig();
config.setServerUrl("https://openapi.alipay.com/gateway.do");
config.setAppId(System.getenv("ALIPAY_APP_ID"));
config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY"));
config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY"));
config.setFormat("json");
config.setCharset("UTF-8");
config.setSignType("RSA2");
AlipayClient client = new DefaultAlipayClient(config);
AlipayAipayNowpayProductBatchqueryRequest request = new AlipayAipayNowpayProductBatchqueryRequest();
request.setBizContent("{\"external_owner_id\":\"usr_01\",\"out_product_ids\":[\"pro_01\",\"pro_02\"]}");
// 仅在已获授权的第三方代调用场景设置 app_auth_token。
String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN");
if (appAuthToken != null && !appAuthToken.isEmpty()) {
request.putOtherTextParam("app_auth_token", appAuthToken);
}
AlipayAipayNowpayProductBatchqueryResponse response = client.execute(request);
if (!response.isSuccess()) {
// 按 code/sub_code 处理;结果未知时保留原业务请求号。
System.out.println(response.getCode() + ":" + response.getSubCode());
return;
}
// 网关成功后,按本页“结果处理”读取业务字段。
System.out.println(response.getBody());
}
}公共响应参数
| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
|---|---|---|---|---|---|
code |
String | 必选 | - | 网关返回码;10000 表示接口调用成功 | 10000 |
msg |
String | 必选 | - | 网关返回码说明 | Success |
sub_code |
String | 可选 | - | 业务错误码;仅用于接口失败处理 | - |
sub_msg |
String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - |
sign |
String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - |
响应业务对象名为 alipay_aipay_nowpay_product_batchquery_response。先完成验签并判断 code,再读取业务结果。
业务响应参数
下表数组子字段使用 [] 表示元素路径。“未提供”表示来源未展开字段定义,字段名称和示例值来自正常响应示例。
| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
|---|---|---|---|---|---|
items |
NowpayProduct[] | 必选 | - | 命中的商品列表;无命中时为空数组 | [] |
items[].out_product_id |
String | 未提供 | 未提供 | 外部商品 ID | gc_1001002 |
items[].product_id |
String | 未提供 | 未提供 | 商品 ID | P0806000200867536 |
items[].product_name |
String | 未提供 | 未提供 | 商品名称 | 写作助手 |
items[].product_icon_url |
String | 未提供 | 未提供 | 商品图标地址 | https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original |
items[].product_url |
String | 未提供 | 未提供 | 商品详情地址 | https://aipay.alipay.com/community/events/payathon-2026 |
items[].product_description |
String | 未提供 | 未提供 | 商品描述 | 描述 |
items[].record_status |
String | 未提供 | 未提供 | 商品记录状态;完整枚举未提供 | INIT |
items[].pricing_mode_list |
Object[] | 未提供 | 未提供 | 收费配置列表 | 见响应示例 |
items[].pricing_mode_list[].billing_mode |
String | 未提供 | 未提供 | 收费模式 | ONE_TIME |
items[].pricing_mode_list[].price |
String | 未提供 | 未提供 | 价格 | 0.01 |
items[].pricing_mode_list[].display_name |
String | 未提供 | 未提供 | 收费配置展示名称 | 一次性买断 |
items[].pricing_mode_list[].currency |
String | 未提供 | 未提供 | 币种 | CNY |
items[].pricing_mode_list[].duration_period |
String | 未提供 | 未提供 | 时长周期 | WEEK |
items[].pricing_mode_list[].quota_unit |
String | 未提供 | 未提供 | 额度单位 | COUNT |
items[].pricing_mode_list[].quota_amount |
Number | 未提供 | 未提供 | 额度数量 | 10 |
items[].gmt_create |
String | 未提供 | 未提供 | 创建时间 | 2026-10-10 10:10:10 |
items[].gmt_modified |
String | 未提供 | 未提供 | 修改时间 | 2026-10-10 10:10:10 |
结果处理
- 调用成功:遍历
items,根据out_product_id关联并更新对应商品信息。 items为空数组:本次查询无命中商品。- 返回
INVALID_PARAMETER:根据具体错误信息检查归属账号、商品 ID 列表及数量,修正后重试。 - 返回
SYSTEM_ERROR:可使用同样的业务参数重试;重新发送时按实际请求生成签名。
响应示例
以下沿用来源示例。实际收费模式与周期、额度字段的适用关系以接口返回及完整字段定义为准。
{
"items": [
{
"out_product_id": "gc_1001002",
"product_id": "P0806000200867536",
"product_name": "写作助手",
"product_icon_url": "https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original",
"product_url": "https://aipay.alipay.com/community/events/payathon-2026",
"product_description": "描述",
"record_status": "INIT",
"pricing_mode_list": [
{
"billing_mode": "ONE_TIME",
"price": "0.01",
"display_name": "一次性买断",
"currency": "CNY",
"duration_period": "WEEK",
"quota_unit": "COUNT",
"quota_amount": 10
}
],
"gmt_create": "2026-10-10 10:10:10",
"gmt_modified": "2026-10-10 10:10:10"
}
]
}{
"alipay_aipay_nowpay_product_batchquery_response": {
"code": "20000",
"msg": "Service Currently Unavailable",
"sub_code": "isp.unknow-error",
"sub_msg": "系统繁忙"
},
"sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}公共错误码
参见支付宝公共错误码。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。
业务错误码
| 错误码 | 错误描述 | 解决方案 |
|---|---|---|
SYSTEM_ERROR |
系统繁忙 | 服务器异常,可能发生了网络或者系统异常,导致服务调用失败;商户可以用同样的请求发起重试 |
INVALID_PARAMETER |
参数有误 | 根据接口返回的参数非法的具体错误信息,修改参数后重试 |