﻿
## 接口说明

接口名称：`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 | 商户请求参数的签名串，详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` |
| `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 | 已获授权的第三方代调用场景使用的应用授权令牌，详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - |
| `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",<br>"pro_02"] |
## 常见请求示例

以下账号和商品 ID 均为演示值。Java 使用支付宝服务端 SDK；私钥保存在平台服务端。cURL 签名需基于本次实际请求生成，授权令牌按实际调用场景配置。

::::aipay-tabs{defaultActiveKey="cURL"}

:::aipay-tab{key="cURL" title="cURL"}
```bash
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}"
```
:::

:::aipay-tab{key="Java" title="Java"}
```java
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/<br>huamei_82ubz2/afts/img/<br>vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/<br>original |
| `items[].product_url` | String | 未提供 | 未提供 | 商品详情地址 | https://aipay.alipay.com/<br>community/events/<br>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`：可使用同样的业务参数重试；重新发送时按实际请求生成签名。

## 响应示例

::::aipay-tabs{defaultActiveKey="正常示例"}

:::aipay-tab{key="正常示例" title="正常示例"}
以下沿用来源示例。实际收费模式与周期、额度字段的适用关系以接口返回及完整字段定义为准。

```json
{
  "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"
    }
  ]
}
```
:::

:::aipay-tab{key="异常示例" title="异常示例"}
```json
{
  "alipay_aipay_nowpay_product_batchquery_response": {
    "code": "20000",
    "msg": "Service Currently Unavailable",
    "sub_code": "isp.unknow-error",
    "sub_msg": "系统繁忙"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
```
:::

::::

## 公共错误码

参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时，按原请求查询或重试；写操作不能在结果未确认时更换幂等号。

## 业务错误码

| 错误码 | 错误描述 | 解决方案 |
| --- | --- | --- |
| `SYSTEM_ERROR` | 系统繁忙 | 服务器异常，可能发生了网络或者系统异常，导致服务调用失败；商户可以用同样的请求发起重试 |
| `INVALID_PARAMETER` | 参数有误 | 根据接口返回的参数非法的具体错误信息，修改参数后重试 |
