V1 Products API

商品管理模块提供商品查询、四步创建、审核提交和上下架能力。V1 商品固定使用多规格模式，每个商品至少包含一个 SKU。

概述

所有接口需要 Access Token，通过 Authorization: Bearer <access_token> 传递。
数据按 Token 绑定的卖家租户隔离。
V1 商品默认且固定为多规格，调用方只需提交 SKU；内部规格结构由服务端自动生成。
商品售价固定为 TWD 主单位；请求和响应均使用 decimal string。
海关资料由平台根据商品类目维护。
商品提交审核前，必须完成基本信息、媒体和完整 SKU 组合配置。

Base Path: /openapi/v1/products

商品创建流程

创建基本信息：创建商品草稿，取得商品 ID。
上传媒体：取得预签名上传 URL，将文件上传到对象存储。
配置 SKU 与详情：设置商品图片、详情图片和 SKU。
提交审核：校验完整资料并进入 pending_review。

[Step 1] POST /openapi/v1/products                     → product
[Step 2] POST /openapi/v1/products/{id}/media/upload   → upload_url + file_url
[Step 3] POST /openapi/v1/products/{id}                → product
[Step 4] POST /openapi/v1/products/{id}/submit         → pending_review

商品列表

GET /openapi/v1/products

Authentication: Required (Access Token)

返回当前租户的商品摘要，固定按 created_at DESC, id DESC 排列。id 是创建时间相同时的稳定第二排序键；V1 不提供自定义排序参数。

Query Parameters

字段	类型	必填	说明
`limit`	number	否	每页数量，默认 20，最大 100
`offset`	number	否	偏移量，默认 0
`q`	string	否	搜索商品名称、露天商品编号、SKU 或卖家自定义编号
`status`	string	否	商品状态，见V1 状态附录
`review_status`	string	否	审核状态：`draft`、`pending`、`approved`、`rejected`
`min_price`	string	否	SKU 最低售价，TWD 主单位 decimal string，必须大于 0
`max_price`	string	否	SKU 最高售价，TWD 主单位 decimal string，必须大于 0
`min_qty`	number	否	最低总库存，非负整数
`max_qty`	number	否	最高总库存，非负整数

Response

字段	类型	说明
`products`	ProductSummary[]	当前页商品摘要
`count`	number	符合条件的商品总数
`limit`	number	分页大小
`offset`	number	偏移量

Response Example

json

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "a7b3c8df-bb08-46f0-9ca2-5597a32e0404",
        "status": "migrated",
        "review_status": "approved",
        "name": "轻量防泼水通勤背包",
        "class_id": "00110001",
        "images": [
          "https://static.sugumart.com/products/backpack-front.jpg"
        ],
        "sku_count": 4,
        "active_sku_count": 4,
        "total_quantity": 75,
        "ruten_item_id": "22408041234567",
        "created_at": "2026-08-01T03:00:00.000Z",
        "updated_at": "2026-08-04T07:20:00.000Z"
      }
    ],
    "count": 1,
    "limit": 20,
    "offset": 0
  }
}

Error Responses

Status	message	code	说明
400	Invalid query parameters	`validation_error`	查询参数格式或范围错误
401	Invalid or expired token	`unauthorized`	Access Token 无效或已过期

商品详情

GET /openapi/v1/products/{id}

Authentication: Required (Access Token)

Path Parameters

字段	类型	必填	说明
`id`	string(uuid)	是	商品 ID

Response

字段	类型	说明
`product`	Product	商品完整详情，包含 SKU

Response Example

json

{
  "success": true,
  "data": {
    "product": {
      "id": "a7b3c8df-bb08-46f0-9ca2-5597a32e0404",
      "status": "approved",
      "review_status": "approved",
      "rejected_reason": null,
      "name": "轻量防泼水通勤背包",
      "description": "<p>适合日常通勤使用的轻量背包。</p>",
      "class_id": "00110001",
      "store_class_id": "sc_1024",
      "stock_status": "3DAY",
      "sale_start_time": 1788192000,
      "sale_end_time": 1790783999,
      "images": [
        "https://static.sugumart.com/products/backpack-front.jpg"
      ],
      "content_images": [
        "https://static.sugumart.com/products/backpack-detail-1.jpg"
      ],
      "skus": [
        {
          "id": "0e95a8db-9161-4b39-b77a-2bd796f27715",
          "sku": "BAG-BLK-20",
          "spec_name": "黑色",
          "item_name": "20L",
          "taiwan_sale_price": "1280.00",
          "ruten_managed_distribution": true,
          "supply_price": "900.00",
          "qty": 30,
          "status": true,
          "weight": "650.00"
        }
      ],
      "sku_count": 4,
      "active_sku_count": 4,
      "total_quantity": 75,
      "ruten_item_id": null,
      "created_at": "2026-08-01T03:00:00.000Z",
      "updated_at": "2026-08-04T07:20:00.000Z"
    }
  }
}

Error Responses

Status	message	code	说明
401	Invalid or expired token	`unauthorized`	Access Token 无效或已过期
404	Product not found	`not_found`	商品不存在或不属于当前租户

创建商品（第一步：基本信息）

POST /openapi/v1/products

Authentication: Required (Access Token)

创建多规格商品草稿。本接口不接收媒体和 SKU；成功后使用返回的商品 ID继续后续步骤。

Request Body

字段	类型	必填	说明
`name`	string	是	商品名称，1-130 字符，不得包含反斜线
`description`	string	是	商品详情 HTML，最长 60,000 字符
`class_id`	string	是	平台类目代码，必须来自 `GET /openapi/v1/categories`
`store_class_id`	string	否	店铺商品分类 ID，必须来自当前店铺的商品分类列表
`stock_status`	string	否	`3DAY` 或 `PRE_ORDER`；默认 `3DAY`
`pre_order_ship_date`	string	条件必填	`stock_status=PRE_ORDER` 时必填，格式 `YYMMDD`
`sale_start_time`	number	否	指定销售开始时间，Unix 时间戳（秒，UTC 时间点）；必须与 `sale_end_time` 一起提交
`sale_end_time`	number	否	指定销售结束时间，Unix 时间戳（秒，UTC 时间点），必须晚于 `sale_start_time`；必须与开始时间一起提交

Request Example

json

{
  "name": "轻量防泼水通勤背包",
  "description": "<p>适合日常通勤使用的轻量背包。</p>",
  "class_id": "00110001",
  "store_class_id": "sc_1024",
  "stock_status": "3DAY",
  "sale_start_time": 1788192000,
  "sale_end_time": 1790783999
}

sale_start_time 和 sale_end_time 均省略时，商品不指定销售时间。提交任一销售时间时必须同时提交另一字段，服务端会同步开启商品的指定销售时间状态。

Response (201 Created)

字段	类型	说明
`product`	Product	创建后的商品草稿，`status=draft`、`skus=[]`

Response Example

json

{
  "success": true,
  "data": {
    "product": {
      "id": "a7b3c8df-bb08-46f0-9ca2-5597a32e0404",
      "status": "draft",
      "review_status": "draft",
      "name": "轻量防泼水通勤背包",
      "class_id": "00110001",
      "store_class_id": "sc_1024",
      "skus": [],
      "created_at": "2026-08-04T08:30:00.000Z",
      "updated_at": "2026-08-04T08:30:00.000Z"
    }
  }
}

Error Responses

Status	message	code	说明
400	Invalid request body	`validation_error`	字段格式、长度或预购日期校验失败
400	Category is not selectable	`category_not_selectable`	`class_id` 是中间类目或仍有启用子节点，不能用于商品发布
401	Invalid or expired token	`unauthorized`	Access Token 无效或已过期
404	Product category not found	`category_not_found`	`class_id` 不存在或已停用
404	Store class not found	`store_class_not_found`	`store_class_id` 不属于当前店铺

上传商品媒体（第二步）

POST /openapi/v1/products/{id}/media/upload

Authentication: Required (Access Token)

取得一个图片预签名上传 URL。调用方随后使用返回的上传方法和 Headers 将文件直接传至对象存储；对象存储请求不属于 V1 API。上传完成后，将 file_url 写入第三步对应的主图、详情图、海报图或 SKU 图片字段。

商品视频不使用本接口上传；video_link 只接受平台支持的视频页面 URL。

Path Parameters

字段	类型	必填	说明
`id`	string(uuid)	是	商品 ID

Request Body

字段	类型	必填	说明
`file_name`	string	是	原始文件名，1-255 字符
`content_type`	string	是	图片 MIME type，必须符合对应 `purpose` 的格式限制
`purpose`	string	是	图片用途：`main`、`detail`、`poster` 或 `sku`
`file_size`	number	是	文件大小，单位 byte，正整数且不得超过对应用途上限
`width`	number	是	原始图片宽度，单位 px，正整数
`height`	number	是	原始图片高度，单位 px，正整数

Request Example

json

{
  "file_name": "backpack-front.jpg",
  "content_type": "image/jpeg",
  "purpose": "main",
  "file_size": 1536000,
  "width": 1200,
  "height": 1200
}

图片限制

用途	数量限制	格式	单张大小	原始尺寸	建议尺寸
主图 `main`	提交审核时至少 1 张，最多 9 张	JPEG、PNG	最大 2 MiB（2,097,152 bytes）	宽、高均为 300-6000 px	800 × 800 px；平台发布到露天前会将最长边超过 800 px 的图片等比缩小
详情图 `detail`	最多 30 张，可为空	JPEG、PNG、WebP	最大 5 MiB（5,242,880 bytes）	宽 600-2000 px，高 600-10000 px	宽 1000 px，高度按内容决定
海报图 `poster`	最多 3 张，可为空	JPEG、PNG、WebP	最大 5 MiB（5,242,880 bytes）	宽、高均为 600-3000 px	1200 × 1200 px
SKU 图 `sku`	每个 SKU 最多 1 张，可为空	JPEG、PNG	最大 2 MiB（2,097,152 bytes）	宽、高均为 300-6000 px	800 × 800 px

补充规则：

content_type 必须与实际文件内容一致，不能只修改扩展名或请求 Header。
GIF、SVG、AVIF、HEIC 和动画图片不属于 V1 支持格式。
平台会在商品保存或提交审核时验证对象存储中的实际文件；实际格式、大小或尺寸与声明不一致时拒绝保存或送审。
图片不得包含外部跳转、脚本或非图片内容；图片 URL 必须来自本接口返回的 file_url。
主图按数组顺序展示，第 1 张为商品封面图；详情图和海报图同样保留请求顺序。
已完成上传的图片通常会长期保留，平台不会因为图片尚未关联商品、后来从商品移除或商品下架而自动清理。V1 不提供图片删除接口；调用方应只为确定需要使用的文件申请上传并完成 PUT，避免上传无用或重复文件。

Response

字段	类型	说明
`upload_url`	string	临时对象存储上传 URL
`file_url`	string	上传完成后的公开文件 URL
`upload_method`	string	固定为 `PUT`
`upload_headers`	object	上传对象存储时必须原样携带的 Headers
`expires_at`	string	上传 URL 过期时间，ISO 8601 UTC

Response Example

json

{
  "success": true,
  "data": {
    "upload_url": "https://upload.sugumart.com/presigned/products/backpack-front.jpg?signature=example",
    "file_url": "https://static.sugumart.com/products/backpack-front.jpg",
    "upload_method": "PUT",
    "upload_headers": {
      "Content-Type": "image/jpeg"
    },
    "expires_at": "2026-08-04T08:45:00.000Z"
  }
}

调用方必须在 expires_at 前完成 PUT，请求体为原始文件二进制，并原样携带 upload_headers。对象存储返回 200 或 204 才表示上传成功；取得预签名 URL 本身不代表文件已上传。

Error Responses

Status	message	code	说明
400	Invalid media type	`invalid_media_type`	`content_type` 不是对应用途允许的图片类型
400	Image file is too large	`image_file_too_large`	`file_size` 超过对应用途限制
400	Invalid image dimensions	`invalid_image_dimensions`	`width` 或 `height` 不符合对应用途限制
401	Invalid or expired token	`unauthorized`	Access Token 无效或已过期
404	Product not found	`not_found`	商品不存在或不属于当前租户
503	Upload service unavailable	`upload_service_unavailable`	对象存储暂时不可用

更新商品（第三步：配置 SKU 与详情）

POST /openapi/v1/products/{id}

Authentication: Required (Access Token)

更新商品公开资料、媒体和 SKU。请求体只需传需要变更的商品字段；传入 skus 时必须提交更新后的完整 SKU 列表。服务端根据 SKU 的 spec_name 和 item_name 自动生成商品规格结构。

SKU 更新以 SKU UUID id 为准，不以 SKU 编号 sku 定位。新 SKU 省略 id；已有 SKU 必须提交商品详情返回的 id。SKU 编号由平台生成并维护，即使请求中提交 sku，服务端也会忽略该值：新 SKU 生成新编号，已有 SKU 保留平台当前编号。

更新字段采用以下语义：

请求体省略普通字段时保持当前值不变。
对允许为空的字段提交 null 时清空当前值；各字段是否接受 null 以 Request Body 表为准。
poster_images、images、content_images 和 skus 只要出现在请求中，就会完整替换对应当前列表；调用方应先读取商品详情并提交需要保留的完整内容。
空图片数组表示清空对应图片列表；skus 至少保留一个项目，不接受空数组。

Path Parameters

字段	类型	必填	说明
`id`	string(uuid)	是	商品 ID

Request Body

字段	类型	必填	说明
`name`	string	否	商品名称，1-130 字符
`description`	string	否	商品详情 HTML，最长 60,000 字符
`class_id`	string	否	平台类目代码
`store_class_id`	string \| null	否	店铺商品分类 ID；`null` 表示移出商品分类
`stock_status`	string	否	`3DAY` 或 `PRE_ORDER`
`pre_order_ship_date`	string \| null	条件必填	预购时为 `YYMMDD`；取消预购时传 `null` 或省略
`sale_start_time`	number \| null	否	指定销售开始时间，Unix 时间戳（秒，UTC 时间点）；与结束时间一起传 `null` 可取消指定销售时间
`sale_end_time`	number \| null	否	指定销售结束时间，Unix 时间戳（秒，UTC 时间点），必须晚于开始时间；与开始时间一起传 `null` 可取消指定销售时间
`poster_images`	string[]	否	商品海报图 URL，最多 3 张；传入时替换当前完整海报图列表，限制见“图片限制”
`images`	string[]	否	商品主图 URL，1-9 张；传入时替换当前完整主图列表，限制见“图片限制”
`content_images`	string[]	否	商品详情图 URL，最多 30 张；传入时替换当前完整详情图列表，限制见“图片限制”
`video_link`	string \| null	否	商品视频 URL，露天用youtube url link
`skus`	SkuInput[]	否	完整 SKU 列表，1-30 项

SkuInput

字段	类型	必填	说明
`id`	string(uuid)	条件必填	更新已有 SKU 时必填；创建新 SKU 时省略。必须属于当前商品且不得重复
`spec_name`	string	是	第一规格值，1-20 字符；服务端据此生成第一规格组
`item_name`	string	否	第二规格值，1-20 字符；使用双规格时，每个 SKU 均须提交，服务端据此生成第二规格组
`sku`	string \| null	否	兼容输入字段，服务端忽略。SKU 编号始终由平台生成；调用方不得依赖请求中的值
`custom_no`	string	否	卖家自定义编号，最长 100 字符
`taiwan_sale_price`	string	是	TWD 主单位 decimal string，固定 2 位小数，必须大于 0
`ruten_managed_distribution`	boolean	否	是否支持露天全托管，默认 `false`
`supply_price`	string \| null	条件必填	`ruten_managed_distribution=true` 时必填；TWD 主单位 decimal string，固定 2 位小数，必须大于 0；不支持全托管时传 `null` 或省略
`qty`	number	是	可售库存，0-99,999 的整数
`status`	boolean	否	是否启用，默认 `true`
`image`	string \| null	否	SKU 图片 URL；每个 SKU 最多 1 张，限制见“图片限制”
`length`	string \| null	否	包裹长度，单位 cm，正数 decimal string，最多 2 位小数
`width`	string \| null	否	包裹宽度，单位 cm，正数 decimal string，最多 2 位小数
`height`	string \| null	否	包裹高度，单位 cm，正数 decimal string，最多 2 位小数
`weight`	string	是	单件包裹重量，单位 g，正数 decimal string，最多 2 位小数

同一商品内，spec_name 与 item_name 的组合不得重复。服务端会将 spec_name 的去重值生成为“规格”组，将 item_name 的去重值生成为“款式”组；调用方无需提交规格组。当任一 SKU 的 ruten_managed_distribution=true 时，服务端会同步开启商品的全托管标记，调用方无需提交商品级开关。

skus 是完整替换列表，处理规则如下：

带 id 的项目更新对应已有 SKU；id 不存在、不属于当前商品或在列表中重复时请求失败。
不带 id 的项目创建新 SKU，并由平台生成 SKU 编号。
从未上架的已有 SKU 未出现在列表中时会被删除。
任何曾经上架过的 SKU 均不得删除，即使商品或 SKU 当前已经下架。调用方必须继续提交其 id；不再销售时将 status 设置为 false。
平台根据历史发布记录判断 SKU 是否曾经上架，调用方不能仅根据当前 status 或商品当前上下架状态判断。

Request Example

json

{
  "poster_images": [
    "https://static.sugumart.com/products/backpack-poster.jpg"
  ],
  "images": [
    "https://static.sugumart.com/products/backpack-front.jpg",
    "https://static.sugumart.com/products/backpack-side.jpg"
  ],
  "content_images": [
    "https://static.sugumart.com/products/backpack-detail-1.jpg"
  ],
  "skus": [
    {
      "spec_name": "黑色",
      "item_name": "20L",
      "taiwan_sale_price": "1280.00",
      "ruten_managed_distribution": true,
      "supply_price": "900.00",
      "qty": 30,
      "status": true,
      "weight": "650.00"
    },
    {
      "spec_name": "黑色",
      "item_name": "28L",
      "taiwan_sale_price": "1580.00",
      "ruten_managed_distribution": true,
      "supply_price": "1100.00",
      "qty": 20,
      "status": true,
      "weight": "780.00"
    },
    {
      "spec_name": "卡其色",
      "item_name": "20L",
      "taiwan_sale_price": "1280.00",
      "ruten_managed_distribution": false,
      "qty": 15,
      "status": true,
      "weight": "650.00"
    },
    {
      "spec_name": "卡其色",
      "item_name": "28L",
      "taiwan_sale_price": "1580.00",
      "ruten_managed_distribution": false,
      "qty": 10,
      "status": true,
      "weight": "780.00"
    }
  ]
}

上例为首次配置 SKU，因此各项均省略 id。修改已有 SKU 时应使用商品详情返回的 UUID；例如将一个曾经上架的 SKU 停用：

json

{
  "skus": [
    {
      "id": "0e95a8db-9161-4b39-b77a-2bd796f27715",
      "spec_name": "黑色",
      "item_name": "20L",
      "taiwan_sale_price": "1280.00",
      "ruten_managed_distribution": true,
      "supply_price": "900.00",
      "qty": 30,
      "status": false,
      "weight": "650.00"
    }
  ]
}

示例为简化展示。实际请求的 skus 必须包含商品更新后需要保留的全部 SKU；不得遗漏任何曾经上架过的 SKU。

Response

字段	类型	说明
`product`	Product	更新后的商品

Response Example

json

{
  "success": true,
  "data": {
    "product": {
      "id": "a7b3c8df-bb08-46f0-9ca2-5597a32e0404",
      "status": "draft",
      "review_status": "draft",
      "name": "轻量防泼水通勤背包",
      "images": [
        "https://static.sugumart.com/products/backpack-front.jpg"
      ],
      "content_images": [
        "https://static.sugumart.com/products/backpack-detail-1.jpg"
      ],
      "skus": [
        {
          "id": "0e95a8db-9161-4b39-b77a-2bd796f27715",
          "sku": "BAG-BLK-20",
          "spec_name": "黑色",
          "item_name": "20L",
          "taiwan_sale_price": "1280.00",
          "ruten_managed_distribution": true,
          "supply_price": "900.00",
          "qty": 30,
          "status": true,
          "weight": "650.00"
        }
      ],
      "updated_at": "2026-08-04T08:40:00.000Z"
    }
  }
}

Error Responses

Status	message	code	说明
400	Invalid product or SKU data	`validation_error`	字段、规格组合、价格、库存或尺寸校验失败
400	Category is not selectable	`category_not_selectable`	`class_id` 是中间类目或仍有启用子节点，不能用于商品发布
400	SKU structure is locked	`sku_structure_locked`	已发布商品不允许破坏已有露天规格结构
400	Published SKU cannot be deleted	`cannot_delete_published_sku`	尝试删除任何曾经上架过的 SKU；应保留其 `id` 并将 `status` 设置为 `false`
400	Invalid SKU ID	`invalid_sku_id`	SKU `id` 不存在、不属于当前商品或在请求列表中重复
401	Invalid or expired token	`unauthorized`	Access Token 无效或已过期
404	Product not found	`not_found`	商品不存在或不属于当前租户
409	Product review state changed	`product_review_state_changed`	保存期间审核状态已变化，应重新查询后再提交

提交商品审核（第四步）

POST /openapi/v1/products/{id}/submit

Authentication: Required (Access Token)

提交商品进入平台审核。服务端会校验基本信息、类目、媒体、SKU 组合、价格、库存和重量。内部规格及发布字段由平台补齐，不要求调用方提交。

提交成功后会向店铺唯一回调 URL 发送 product.review.submitted；平台作出审核决定后发送 product.review.approved 或 product.review.rejected。回调仅作为异步状态提示，最新结果以商品详情接口为准，详见回调通知。

Path Parameters

字段	类型	必填	说明
`id`	string(uuid)	是	商品 ID

Request Body

无。

Response

字段	类型	说明
`product`	Product	已提交审核的商品，`status=pending_review`、`review_status=pending`
`submitted_at`	string	提交审核时间，ISO 8601 UTC

Response Example

json

{
  "success": true,
  "data": {
    "product": {
      "id": "a7b3c8df-bb08-46f0-9ca2-5597a32e0404",
      "status": "pending_review",
      "review_status": "pending",
      "name": "轻量防泼水通勤背包"
    },
    "submitted_at": "2026-08-04T08:45:00.000Z"
  }
}

Error Responses

Status	message	code	说明
400	Product information is incomplete	`product_incomplete`	基本信息、媒体、规格或 SKU 不完整
400	Product cannot be submitted	`invalid_state`	当前商品状态不允许提交
401	Invalid or expired token	`unauthorized`	Access Token 无效或已过期
404	Product not found	`not_found`	商品不存在或不属于当前租户

上架商品

POST /openapi/v1/products/{id}/online

Authentication: Required (Access Token)

将审核通过的商品恢复至线上销售。

Path Parameters

字段	类型	必填	说明
`id`	string(uuid)	是	商品 ID

Response

字段	类型	说明
`product`	Product	上架后的商品，`status=migrated`

Response Example

json

{
  "success": true,
  "data": {
    "product": {
      "id": "a7b3c8df-bb08-46f0-9ca2-5597a32e0404",
      "status": "migrated",
      "review_status": "approved",
      "ruten_item_id": "22408041234567",
      "updated_at": "2026-08-05T02:10:00.000Z"
    }
  }
}

Error Responses

Status	message	code	说明
400	Product is not approved	`invalid_state`	商品尚未审核通过或当前状态不可上架
401	Invalid or expired token	`unauthorized`	Access Token 无效或已过期
404	Product not found	`not_found`	商品不存在
502	Ruten publish failed	`ruten_provider_error`	露天拒绝发布或响应不可用

下架商品

POST /openapi/v1/products/{id}/offline

Authentication: Required (Access Token)

将线上商品下架。

Path Parameters

字段	类型	必填	说明
`id`	string(uuid)	是	商品 ID

Response

字段	类型	说明
`product`	Product	下架后的商品，`status=offline`

Response Example

json

{
  "success": true,
  "data": {
    "product": {
      "id": "a7b3c8df-bb08-46f0-9ca2-5597a32e0404",
      "status": "offline",
      "review_status": "approved",
      "ruten_item_id": "22408041234567",
      "updated_at": "2026-08-06T04:30:00.000Z"
    }
  }
}

Error Responses

Status	message	code	说明
400	Product is not online	`invalid_state`	商品当前不在线
401	Invalid or expired token	`unauthorized`	Access Token 无效或已过期
404	Product not found	`not_found`	商品不存在
502	Ruten offline request failed	`ruten_provider_error`	露天拒绝下架或响应不可用

公共响应字段

ProductSummary

商品列表返回摘要对象，不包含 description、完整媒体列表和 skus。需要完整资料时调用商品详情接口。

字段	类型	说明
`id`	string(uuid)	商品 ID
`status`	string	V1 商品生命周期状态
`review_status`	string	审核状态：`draft`、`pending`、`approved`、`rejected`
`name`	string	商品名称
`class_id`	string	平台类目代码
`images`	string[]	商品主图；列表响应只保证包含首张主图，暂无图片时为空数组
`sku_count`	number	未删除 SKU 总数，非负整数
`active_sku_count`	number	已启用 SKU 数量，非负整数
`total_quantity`	number	已启用 SKU 的可售库存合计，非负整数
`ruten_item_id`	string \| null	露天商品编号；尚未发布时为 `null`
`created_at`	string	创建时间，ISO 8601 UTC
`updated_at`	string	更新时间，ISO 8601 UTC

Product

字段	类型	说明
`id`	string(uuid)	商品 ID
`status`	string	V1 商品生命周期状态
`review_status`	string	审核状态：`draft`、`pending`、`approved`、`rejected`
`rejected_reason`	string \| null	审核拒绝原因
`name`	string	商品名称
`description`	string \| null	商品详情 HTML
`class_id`	string	平台类目代码
`store_class_id`	string \| null	店铺商品分类 ID
`stock_status`	string	`3DAY` 或 `PRE_ORDER`
`pre_order_ship_date`	string \| null	预购出货日期，格式 `YYMMDD`
`sale_start_time`	number \| null	指定销售开始时间，Unix 时间戳（秒，UTC 时间点）；未指定时为 `null`
`sale_end_time`	number \| null	指定销售结束时间，Unix 时间戳（秒，UTC 时间点）；未指定时为 `null`
`poster_images`	string[]	商品海报图，最多 3 张；格式、大小和尺寸限制见“图片限制”
`images`	string[]	商品主图，最多 9 张；提交审核时至少 1 张
`content_images`	string[]	商品详情图，最多 30 张；格式、大小和尺寸限制见“图片限制”
`video_link`	string \| null	商品视频 URL
`skus`	Sku[]	SKU 列表
`sku_count`	number	未删除 SKU 总数
`active_sku_count`	number	已启用 SKU 数量
`total_quantity`	number	已启用 SKU 的可售库存合计
`ruten_item_id`	string \| null	露天商品编号；尚未发布时为 `null`
`submitted_at`	string \| null	最近提交审核时间，ISO 8601 UTC
`approved_at`	string \| null	最近审核通过时间，ISO 8601 UTC
`created_at`	string	创建时间，ISO 8601 UTC
`updated_at`	string	更新时间，ISO 8601 UTC

Sku

字段	类型	说明
`id`	string(uuid)	SKU ID；更新已有 SKU 时使用的唯一定位依据
`sku`	string	平台生成的只读 SKU 编号；不接受调用方修改
`custom_no`	string \| null	卖家自定义编号
`spec_id`	string \| null	露天规格 ID；尚未发布时为 `null`
`spec_name`	string	第一规格值
`item_name`	string \| null	第二规格值；不使用第二规格时为 `null`
`taiwan_sale_price`	string	TWD 主单位 decimal string，固定 2 位小数
`ruten_managed_distribution`	boolean	是否支持露天全托管
`supply_price`	string \| null	全托管供货价；TWD 主单位 decimal string，固定 2 位小数；不支持全托管时为 `null`
`qty`	number	可售库存，0-99,999
`status`	boolean	SKU 是否启用
`image`	string \| null	SKU 图片 URL；格式、大小和尺寸限制见“图片限制”
`length`	string \| null	包裹长度，单位 cm，最多 2 位小数
`width`	string \| null	包裹宽度，单位 cm，最多 2 位小数
`height`	string \| null	包裹高度，单位 cm，最多 2 位小数
`weight`	string	单件包裹重量，单位 g，最多 2 位小数
`created_at`	string	创建时间，ISO 8601 UTC
`updated_at`	string	更新时间，ISO 8601 UTC

V1 Products API ​

概述 ​

商品创建流程 ​

商品列表 ​

Query Parameters ​

Response ​

Response Example ​

Error Responses ​

商品详情 ​

Path Parameters ​

Response ​

Response Example ​

Error Responses ​

创建商品（第一步：基本信息） ​

Request Body ​

Request Example ​

Response (201 Created) ​

Response Example ​

Error Responses ​

上传商品媒体（第二步） ​

Path Parameters ​

Request Body ​

Request Example ​

图片限制 ​

Response ​

Response Example ​

Error Responses ​

更新商品（第三步：配置 SKU 与详情） ​

Path Parameters ​

Request Body ​

SkuInput ​

Request Example ​

Response ​

Response Example ​

Error Responses ​

提交商品审核（第四步） ​

Path Parameters ​

Request Body ​

Response ​

Response Example ​

Error Responses ​

上架商品 ​

Path Parameters ​

Response ​

Response Example ​

Error Responses ​

下架商品 ​

Path Parameters ​

Response ​

Response Example ​

Error Responses ​

公共响应字段 ​

ProductSummary ​

Product ​

Sku ​

V1 Products API

概述

商品创建流程

商品列表

Query Parameters

Response

Response Example

Error Responses

商品详情

Path Parameters

Response

Response Example

Error Responses

创建商品（第一步：基本信息）

Request Body

Request Example

Response (201 Created)

Response Example

Error Responses

上传商品媒体（第二步）

Path Parameters

Request Body

Request Example

图片限制

Response

Response Example

Error Responses

更新商品（第三步：配置 SKU 与详情）

Path Parameters

Request Body

SkuInput

Request Example

Response

Response Example

Error Responses

提交商品审核（第四步）

Path Parameters

Request Body

Response

Response Example

Error Responses

上架商品

Path Parameters

Response

Response Example

Error Responses

下架商品

Path Parameters

Response

Response Example

Error Responses

公共响应字段

ProductSummary

Product

Sku