商品基础信息修改接口

最后更新于

接口说明

接口名称:alipay.aipay.nowpay.product.modify

修改商品基础信息,包括商品名称、简短描述、图标地址和商品详情地址。通过外部平台商品所有者标识与商品或应用标识定位商品。

适用场景

  • 商品名称或简短描述调整后,同步商品基础信息。
  • 商品图标或详情页地址变更后,更新对应地址。

注意事项

  • external_owner_id、out_product_id 为必选字段;其余四个商品信息字段为可选字段。
  • 原文未说明可选字段省略、传空字符串或传 null 时的更新语义,也未说明是否必须至少传入一个修改字段;接入时需核对这些规则。
  • 请求需按 接口 规则签名;修改请求体或参与签名的请求信息后,应重新生成签名。

公共请求参数

参数 类型 是否必选 最大长度 描述 示例值
app_id String 必选 32 支付宝分配给开发者的应用ID YOUR_APP_ID
method String 必选 128 接口名称 alipay.aipay.nowpay.product.modify
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_id String 必选 128 外部平台商品/应用标识 - gc_1001002
product_name String 可选 128 新商品名称 - 写作助手
product_description String 可选 4096 新简短描述 - 智能提示
product_icon_url String 可选 4096 新图标地址 - https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original
product_url String 可选 4096 新商品详情地址 - https://aipay.alipay.com/community/events/payathon-2026

常见请求示例

以下沿用原文商品信息示例。发送前需准备实际应用 ID、时间戳、随机串、请求标识及签名;签名需基于本次实际请求生成。授权令牌按实际调用场景配置。

biz_content='{
  "external_owner_id": "usr_01",
  "out_product_id": "gc_1001002",
  "product_name": "写作助手",
  "product_description": "智能提示",
  "product_icon_url": "https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original",
  "product_url": "https://aipay.alipay.com/community/events/payathon-2026"
}'

# 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.modify' \
  --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.AlipayAipayNowpayProductModifyRequest;
import com.alipay.api.response.AlipayAipayNowpayProductModifyResponse;

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);

        AlipayAipayNowpayProductModifyRequest request = new AlipayAipayNowpayProductModifyRequest();
        request.setBizContent("{\"external_owner_id\":\"usr_01\",\"out_product_id\":\"gc_1001002\",\"product_name\":\"写作助手\",\"product_description\":\"智能提示\",\"product_icon_url\":\"https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original\",\"product_url\":\"https://aipay.alipay.com/community/events/payathon-2026\"}");
        // 仅在已获授权的第三方代调用场景设置 app_auth_token。
        String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN");
        if (appAuthToken != null && !appAuthToken.isEmpty()) {
            request.putOtherTextParam("app_auth_token", appAuthToken);
        }
        AlipayAipayNowpayProductModifyResponse 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_modify_response。先完成验签并判断 code,再读取业务结果。

业务响应参数

参数 类型 是否必选 最大长度 描述 示例值
product_name String 必选 128 新商品名称 写作助手
product_description String 必选 4096 新简短描述 智能提示
product_icon_url String 必选 4096 新图标地址 https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original
product_url String 必选 4096 新商品详情地址 https://aipay.alipay.com/community/events/payathon-2026

结果处理

  • 调用成功:读取响应中的四个商品基础信息字段,更新平台侧展示。
  • 返回 INVALID_PARAMETER:根据具体错误信息修正参数后重试。
  • 返回 SYSTEM_ERROR:原文允许使用同样的请求重试。重新发送时,应按实际请求重新生成认证签名。
  • 其他失败:结合 HTTP 状态和 接口 公共错误码处理,并保留请求标识以便排查。

响应示例

{
  "product_name": "写作助手",
  "product_description": "智能提示",
  "product_icon_url": "https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original",
  "product_url": "https://aipay.alipay.com/community/events/payathon-2026"
}
{
  "alipay_aipay_nowpay_product_modify_response": {
    "code": "20000",
    "msg": "Service Currently Unavailable",
    "sub_code": "isp.unknow-error",
    "sub_msg": "系统繁忙"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

公共错误码

参见支付宝公共错误码。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。

业务错误码

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