跳到主要内容

商品 (Product)

Product 对象是 GStable 系统中的基础库存单位。

在使用 Payment Link (无代码模式) 时，你必须先创建商品，因为 Payment Link 本质上是指向一个或多个商品的永久收款链接。而在使用 Checkout Session (低代码模式) 时，商品是可选的，你可以选择传入现有的 productId，也可以直接在 Session 中定义一次性的行项目（Line Items）。

商品对象​

核心属性​

属性类型描述
productIdString商品的唯一标识符（如 prd_TLEGL1FK...）。
nameString商品名称。
descriptionString商品描述。
imageUrlString商品图片的 URL。GStable 会自动下载并托管此图片。
statusString状态。active (活跃) 或 archived (归档)。
commonPricesArray常用价格列表（单位：Micro-USD）。
attributesArray自定义属性列表（如尺码、颜色）。

价格单位说明 (Micro-USD)​

GStable 的商品价格统一使用 Micro-USD（百万分之一美元）作为整数存储，以避免浮点数精度问题。

  • 1000000 = $1.00 USD
  • 2000000 = $2.00 USD

创建商品​

创建商品时，你可以提供外部图片链接，GStable 会自动将其下载并转存到内部文件服务中，以保证图片在收银台的加载速度和稳定性。

POST /product/create

请求参数​

参数类型必填描述
nameString✅商品名称（最大 100 字符）。
commonPricesInteger[]✅常用价格列表。至少 1 个，最多 5 个。用于在 Dashboard 创建 Payment Link 时快速选择定价。
descriptionString❌商品描述（最大 1000 字符）。
imageUrlString❌必须是 HTTPS URL（最大 500 字符）。系统会自动转存。如果下载失败，商品仍会创建成功，但无法显示图片。
attributesObject[]❌商品属性（最大 10 个）。包含 name 和 value。

请求示例​

{
  "name": "高级会员",
  "description": "解锁所有高级功能",
  "imageUrl": "https://yoursite.com/product_01.png",
  "attributes": [
    { "name": "时长", "value": "1个月" },
    { "name": "等级", "value": "VIP" }
  ],
  "commonPrices": [1000000, 2000000, 5000000]
}

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "productId": "prd_TLEGL1FKzZt9hqWu",
    "name": "高级会员",
    "description": "解锁所有高级功能",
    "imageUrl": "https://files.gstable.io/product/prd_TLEGL1FKzZt9hqWu/image.png", // 注意：这是转存后的 URL
    "status": "active",
    "attributes": [
      { "name": "时长", "value": "1个月" },
      { "name": "等级", "value": "VIP" }
    ],
    "commonPrices": [1000000, 2000000, 5000000]
  }
}

更新商品​

POST /product/update

全量更新

更新接口采用全量替换策略。调用此接口时，必须传递商品的所有字段（包括那些不想修改的字段）。未包含在请求中的可选字段可能会被重置。

特殊行为说明​

  • 图片更新：如果你提供了新的 imageUrl，系统会重新下载并覆盖旧图片。接口返回时不包含新的图片 URL，但后续查询会返回更新后的地址。

请求示例​

{
  "productId": "prd_TLEGL1FKzZt9hqWu", // 必填
  "name": "高级会员 (已更新)",
  "description": "解锁所有高级功能",
  "imageUrl": "https://example.com/new-image.png",
  "attributes": [
    { "name": "时长", "value": "1个月" }
  ],
  "commonPrices": [1000000]
}

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

获取商品列表​

GET /product/list/:page/:size

该接口支持分页查询。分页参数直接通过 URL 路径 传递。

  • page: 页码，从 1 开始。
  • size: 每页条数，最大 100。

请求示例​

GET /product/list/1/10

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 6,
    "page": "1",
    "size": "10",
    "products": [
      {
        "productId": "prd_6syzYz_j4WRqs-jOaji6SA",
        "name": "高级会员",
        "status": "active",
        "createAt": "2025-12-25 01:58:29",
        ...
      }
    ]
  }
}

批量获取商品​

POST /product/list/by/ids

此接口常配合创建 Payment Link 使用。如果你有一组 ID，想验证它们是否存在并获取详细信息，请使用此接口。

  • 如果请求的 ID 中包含不存在的商品，响应列表只会返回存在的那些，不会报错。

请求示例​

{
  "productIds": [
    "prd_6syzYz_j4WRqs-jOaji6SA",
    "prd_invalid_id_example"
  ]
}

响应示例​

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "productId": "prd_6syzYz_j4WRqs-jOaji6SA",
      "name": "高级会员",
      ...
    }
    // 注意：prd_invalid_id_example 未返回
  ]
}

归档与解归档​

管理商品的生命周期状态。

级联禁用逻辑

归档操作具有级联效应：

  1. 归档时：一旦商品被归档，所有关联该商品的 Payment Link 将被自动禁用 (Disable)。这是为了防止用户向已下架的商品付款。
  2. 解归档时：商品恢复活跃状态后，关联的 Payment Link 不会自动恢复。你需要通过 API 或 Dashboard 手动重新启用 (Enable) 相应的 Payment Link。

归档​

POST /product/archive

解归档​

POST /product/unarchive

请求示例​

{
  "productId": "prd_TLEGL1FKzZt9hqWu"
}

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

删除商品​

POST /product/remove

删除操作具有严格的业务限制，以保证历史数据的完整性。

删除限制​

  • 未使用：只有从未被任何 Payment Link 关联过的商品才能被删除。
  • 已使用：一旦商品被任何 Payment Link（包括已禁用或删除的 Link）引用过，该商品将永久无法删除。对于此类商品，建议使用 归档 功能。

请求示例​

{
  "productId": "prd_TLEGL1FKzZt9hqWu"
}

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}