商品庫 API

商品、品牌、分類與資訊範本的介面參數和呼叫範例。

最近更新 2026-10-13

快速接入

商品庫 API 的服務位址為 https://open.musedam.cc/api/product。在此位址後加上接口路徑，例如 /products。

取得 MuseDAM API Key。
請商品庫管理員在「成員設定 → 新增成員」中，將該密鑰新增為 API Key 協作者，並指派所需角色。
從伺服器端呼叫接口，在請求標頭中攜帶 Authorization: Bearer <key>。

權限依密鑰所屬團隊和協作者目前角色驗證，請求參數不能切換商品庫。

新加入的協作者預設為 view_only。依需要選擇角色：

角色	可執行的操作
`view_only`	檢視已發佈商品。
`usable`	檢視、分享和下載已發佈商品。
`editable`	建立和編輯商品、存取草稿、發佈及刪除商品。
`manage`	管理全部資源，包括品牌、分類、資訊範本及活動記錄。

每個角色包含上一級角色的權限。後續範例中的資源 ID 需替換為實際值。

將 your_api_key 替換為已授權的 API Key，查詢商品列表：

bash

curl --request GET 'https://open.musedam.cc/api/product/products?page=1&pageSize=20' \
  --header 'Authorization: Bearer your_api_key'

請求成功時，success 為 true，data 為商品列表，pagination 為分頁資訊。列表為空時，請先確認商品庫中是否有目前角色可見的商品；view_only 和 usable 只能檢視已發佈商品。

請求與回應

所有請求均攜帶 Authorization: Bearer <key>；JSON 請求使用 Content-Type: application/json。介面表中的路徑均相對上述服務地址。

JSON 接口使用以下結構。下載和匯出成功時直接回傳檔案。

回傳內容	讀取方式
操作成功	`success: true`，從 `data` 讀取結果；`code`、`message` 為 `null`。
操作失敗	`success: false`，`data: null`；依 HTTP 狀態碼和 `code` 處理，不依賴 `message` 的文案。
參數驗證失敗	若回應包含 `details`，可依 `details[].field` 和 `details[].message` 修正欄位。
請求追蹤	保留 `requestId` 或回應標頭 `X-Request-Id`，用於排查問題。

一般列表使用 page 和 pageSize，在回應頂層回傳 pagination。其中 totalCount 為總筆數，totalPages 為總頁數：

參數	預設值	範圍
`page`	`1`	從 `1` 開始的整數。
`pageSize`	`20`	正整數，超過 `100` 時以 `100` 處理。

json

{
  "page": 1,
  "pageSize": 20,
  "totalCount": 42,
  "totalPages": 3
}

商品和素材可能在請求期間變為不可見，因此實際回傳筆數可能少於 pageSize，計數仍保留分頁時的結果。單一資源不可見時回傳 404。

需要持續同步商品時，請使用游標同步，不要依靠一般頁碼列表。篩選參數見具體接口；一般查詢會忽略未知參數，JSON 請求主體會拒絕未知欄位。

欄位格式

欄位	使用方式
數值型資源 ID	正整數，最大 `2147483647`。
範本、分組、欄位、版本 ID	字串，原樣保存，不假定為 UUID。
素材 ID	使用素材查詢回傳的 `id`（FilePath ID），不能替換成 AssetObject ID 或商品關聯 ID。
分類 `iconAssetId`	使用分類圖示的識別碼（CategoryIconAsset）。
`size`	十進位字串或 `null`，避免大型檔案位元組數失去精度。
日期	RFC 3339 字串或 `null`；同步時間戳記保留完整六位小數。
商品 SKU	API 欄位名稱為 `spu`。

舊版或無法解析的商品媒體可能回傳 id: null。有效的媒體引用不會被截斷。預覽和下載連結的使用方式見媒體連結。

所有回應攜帶 Cache-Control: private, no-store。JSON 操作和錯誤使用 application/json。請求大小、批次數量等上限見請求限制。

並行更新

讀取品牌、分類、模板或商品時儲存強 ETag（包括引號），更新、狀態變更或刪除時可放入 If-Match。回傳 412 precondition_failed 時重新讀取並核對；省略時後一次寫入覆蓋前一次。分享、歷史和下載記錄不使用 ETag。

建立與下載重試

建立資源可使用 Idempotency-Key。鍵按團隊、API Key 和操作區分，最長 255 個字元，不能為空白或含控制字元。24 小時內以相同鍵和輸入重試；變更輸入回傳 409 idempotency_key_reused。資源建立重播首次非媒體結果，媒體按目前權限重建。下載重試只重用業務記錄，仍重新授權並傳輸目前檔案。

請求限制與錯誤處理

請求本文最多 1 MiB。未知 JSON 欄位會被拒絕；一般查詢忽略未知參數，歷史和同步查詢另有嚴格驗證。

回傳結果	處理方式
401 / 403	檢查密鑰、協作者角色及資源可見性。
404	資源不存在、已刪除或不可存取，核對 ID。
422 `validation_failed`	修正輸入；若有 `details`，讀取 `field` 和 `message`。
409 `sku_in_use` / `name_in_use`	變更衝突的 SKU 或名稱；軟刪除商品的 SKU 仍被占用。
409 `mutation_response_unavailable`	變更已提交或重播，按 `mutationOutcome` 核對；不要盲目重新建立。
503 `write_conflict`	變更已回滾，依 `Retry-After: 1` 等待後重試。
413	縮小請求本文或下載數量／大小。

透過回應標頭 X-Request-Id 或 JSON 中的 requestId 排查請求。下載錯誤含 mutationOutcome 時，記錄已經提交，重試沿用原冪等鍵。

下載 OpenAPI JSON

品牌

Brand 回傳欄位

字段名	類型	描述
id	Integer	資源 ID。正整數 ID，最大 2147483647。
name	String	名稱。
code	String	編碼。
description	String	說明。可為 null
website	String	網站地址。可為 null
sortOrder	Integer	排序值。
isEnabled	Boolean	是否啓用。
createdAt	String	RFC 3339 時間字串；保留完整精度。
updatedAt	String	RFC 3339 時間字串；保留完整精度。

獲取品牌列表

接口路徑：/brands

請求方式：GET

接口描述：返回公開元數據，按 sortOrder 再按 id 排序。不包含原始 logo URL。

所需角色：所有協作者角色。

請求參數：

參數名	類型	必填	描述
page	Integer	否	頁碼，正整數，預設 1
pageSize	Integer	否	每頁筆數，正整數，預設 20，上限 100。

響應參數： 200，data：List<Brand>。欄位說明分頁欄位見請求與回應。

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/brands?page=1&pageSize=20' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": [
    {
      "id": 10,
      "name": "Example brand",
      "code": "example-code",
      "description": null,
      "website": null,
      "sortOrder": 0,
      "isEnabled": true,
      "createdAt": "2026-10-08T10:00:00.000Z",
      "updatedAt": "2026-10-08T10:00:00.000Z"
    }
  ],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111",
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1,
    "totalPages": 1
  }
}

創建品牌

接口路徑：/brands

請求方式：POST

接口描述：創建品牌；允許名稱重復，code 由服務端生成。Logo 地址限制見下方參數表。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
Idempotency-Key	String	否	選填請求標頭；同一鍵和輸入在 24 小時內重試，詳見冪等重試。
-	BrandCreate	是	JSON 請求體：application/json

BrandCreate參數說明：

不接受未定義字段。

字段名	類型	必填	描述
name	String	是	校驗前會去除首尾空白。最短 1 個字符；最長 128 個字符
description	String	否	最長 512 個字符；可為 null
logoUrl	String	否	null/空值表示清除。僅支持 HTTP(S)，不得包含憑據，且須為允許列表中的 MuseDAM CDN 或已配置的存儲主機；存儲前會移除 query 和 fragment。不支持上傳；讀取時不會返回。最長 512 個字符；可為 null

響應參數： 201，data：Brand。欄位說明

響應頭：ETag

請求示例：

bash

curl --request POST \
  'https://open.musedam.cc/api/product/brands' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Example brand"
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": 10,
    "name": "Example brand",
    "code": "example-code",
    "description": null,
    "website": null,
    "sortOrder": 0,
    "isEnabled": true,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z"
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

獲取品牌詳情

接口路徑：/brands/{id}

請求方式：GET

接口描述：回傳指定品牌的公開元資料及目前的強 ETag，不包含原始 logo URL。

所需角色：所有協作者角色。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。

響應參數： 200，data：Brand。欄位說明

響應頭：ETag

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/brands/10' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": {
    "id": 10,
    "name": "Example brand",
    "code": "example-code",
    "description": null,
    "website": null,
    "sortOrder": 0,
    "isEnabled": true,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z"
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

更新品牌

接口路徑：/brands/{id}

請求方式：PATCH

接口描述：更新所提供的元數據字段；未提供的屬性保持不變。不支持文件上傳或通用素材替換。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。
If-Match	String	否	選填請求標頭；使用讀取時的 ETag，詳見並行更新。
-	BrandPatch	是	JSON 請求體：application/json

BrandPatch參數說明：

不接受未定義字段；至少提供字段數：1。

字段名	類型	必填	描述
name	String	否	校驗前會去除首尾空白。最短 1 個字符；最長 128 個字符
description	String	否	最長 512 個字符；可為 null
logoUrl	String	否	null/空值表示清除。僅支持 HTTP(S)，不得包含憑據，且須為允許列表中的 MuseDAM CDN 或已配置的存儲主機；存儲前會移除 query 和 fragment。不支持上傳；讀取時不會返回。最長 512 個字符；可為 null

響應參數： 200，data：Brand。欄位說明

響應頭：ETag

請求示例：

bash

curl --request PATCH \
  'https://open.musedam.cc/api/product/brands/10' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "description": "Updated by API"
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": 10,
    "name": "Example brand",
    "code": "example-code",
    "description": "Updated by API",
    "website": null,
    "sortOrder": 0,
    "isEnabled": true,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:05:00.000Z"
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

刪除品牌

接口路徑：/brands/{id}

請求方式：DELETE

接口描述：僅可刪除沒有有效分類或商品的品牌，否則返回 409；絕不會級聯刪除商品。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。
If-Match	String	否	選填請求標頭；使用讀取時的 ETag，詳見並行更新。

響應參數： 200，data：DeletedId。回傳 data.id，即已刪除的資源 ID。

響應頭：ETag

請求示例：

bash

curl --request DELETE \
  'https://open.musedam.cc/api/product/brands/10' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": {
    "id": 10
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

分類

分類樹與刪除

同級名稱必須唯一，父分類必須屬於同一品牌。分類最多 10 級，每個品牌最多 5000 個未刪除節點。sortOrder 是從零開始的同級位置；建立或移動時省略則附加，同父層更新時省略則保持位置。改名或移動會更新後代路徑。

建立時，只有商品庫預設模板未綁定品牌或已綁定目前品牌，才新增直接模板綁定；否則仍建立成功，按祖先分類、品牌、商品庫預設模板查找。刪除會軟刪除整棵子樹；其中有未刪除商品時回傳 409 category_has_products，不執行刪除。

Category 回傳欄位

字段名	類型	描述
id	Integer	資源 ID。正整數 ID，最大 2147483647。
brandId	Integer	品牌 ID。正整數 ID，最大 2147483647。
parentId	Integer	父分類 ID。正整數 ID，最大 2147483647。；可為 null
name	String	名稱。
pathKey	String	分類路徑。
description	String	說明。可為 null
iconEmoji	String	分類表情圖標。可為 null
iconAssetId	Integer	分類圖標 ID。正整數 ID，最大 2147483647。；可為 null
sortOrder	Integer	排序值。
isEnabled	Boolean	是否啓用。
createdAt	String	RFC 3339 時間字串；保留完整精度。
updatedAt	String	RFC 3339 時間字串；保留完整精度。

獲取分類列表

接口路徑：/categories

請求方式：GET

接口描述：返回扁平的有效分類樹，按 brandId、parentId、sortOrder 和 id 排序。可選按品牌篩選；不會隱式展開子樹。

所需角色：所有協作者角色。

請求參數：

參數名	類型	必填	描述
page	Integer	否	頁碼，正整數，預設 1
pageSize	Integer	否	每頁筆數，正整數，預設 20，上限 100。
brandId	Integer	否	查詢參數。按本商品庫內的品牌 ID 篩選。正整數 ID，最大 2147483647。

響應參數： 200，data：List<Category>。欄位說明分頁欄位見請求與回應。

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/categories?page=1&pageSize=20' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": [
    {
      "id": 20,
      "brandId": 10,
      "parentId": null,
      "name": "Catalog",
      "pathKey": "/Catalog",
      "description": null,
      "iconEmoji": null,
      "iconAssetId": null,
      "sortOrder": 0,
      "isEnabled": true,
      "createdAt": "2026-10-08T10:00:00.000Z",
      "updatedAt": "2026-10-08T10:00:00.000Z"
    }
  ],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111",
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1,
    "totalPages": 1
  }
}

創建分類

接口路徑：/categories

請求方式：POST

接口描述：在指定品牌下創建有效節點。父節點必須是同一品牌/商品庫中的有效節點。最大深度為 10，每個品牌最多 5000 個有效節點。同級名稱必須唯一。僅當商品庫默認模板未綁定任何品牌或已綁定該品牌時，才會添加顯式模板綁定；否則分類仍創建成功，不添加顯式綁定，並保留依次查找祖先分類、品牌和商品庫默認模板的解析順序。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
Idempotency-Key	String	否	選填請求標頭；同一鍵和輸入在 24 小時內重試，詳見冪等重試。
-	CategoryCreate	是	JSON 請求體：application/json

CategoryCreate參數說明：

不接受未定義字段。

字段名	類型	必填	描述
brandId	Integer	是	正整數 ID，最大 2147483647。
name	String	是	精確值，不去除首尾空白。必須包含非空白字符且不含斜槓；在有效同級節點中唯一。最短 1 個字符；最長 64 個字符；須匹配 `^(?=.*\S)[^/]+$`
parentId	Integer	否	正整數 ID，最大 2147483647。；可為 null
sortOrder	Integer	否	同級插入索引，不得大於目標位置的同級節點數。省略時：創建/移動時追加到末尾，父節點不變時保持原位置。最小值：0；最大值：5,000
description	String	否	可為 null
iconEmoji	String	否	最長 16 個字符；可為 null
iconAssetId	Integer	否	同一商品庫中現有的 CategoryIconAsset ID，而非 FilePath ID。正整數 ID，最大 2147483647。；可為 null
isEnabled	Boolean	否	—

響應參數： 201，data：Category。欄位說明

響應頭：ETag

請求示例：

bash

curl --request POST \
  'https://open.musedam.cc/api/product/categories' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Catalog",
  "brandId": 10
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": 20,
    "brandId": 10,
    "parentId": null,
    "name": "Catalog",
    "pathKey": "/Catalog",
    "description": null,
    "iconEmoji": null,
    "iconAssetId": null,
    "sortOrder": 0,
    "isEnabled": true,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z"
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

獲取分類詳情

接口路徑：/categories/{id}

請求方式：GET

接口描述：回傳指定未刪除分類及目前的強 ETag；分類不存在或不屬於目前商品庫時回傳 404。

所需角色：所有協作者角色。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。

響應參數： 200，data：Category。欄位說明

響應頭：ETag

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/categories/20' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": {
    "id": 20,
    "brandId": 10,
    "parentId": null,
    "name": "Catalog",
    "pathKey": "/Catalog",
    "description": null,
    "iconEmoji": null,
    "iconAssetId": null,
    "sortOrder": 0,
    "isEnabled": true,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z"
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

更新分類

接口路徑：/categories/{id}

請求方式：PATCH

接口描述：在其現有品牌內更新或移動節點；brandId 不可變更。會拒絕循環引用、超出深度/節點數限制以及無效的排序索引。以原子方式更新後代路徑。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。
If-Match	String	否	選填請求標頭；使用讀取時的 ETag，詳見並行更新。
-	CategoryPatch	是	JSON 請求體：application/json

CategoryPatch參數說明：

不接受未定義字段；至少提供字段數：1。

字段名	類型	必填	描述
name	String	否	精確值，不去除首尾空白。必須包含非空白字符且不含斜槓；在有效同級節點中唯一。最短 1 個字符；最長 64 個字符；須匹配 `^(?=.*\S)[^/]+$`
parentId	Integer	否	正整數 ID，最大 2147483647。；可為 null
sortOrder	Integer	否	同級插入索引，不得大於目標位置的同級節點數。省略時：創建/移動時追加到末尾，父節點不變時保持原位置。最小值：0；最大值：5,000
description	String	否	可為 null
iconEmoji	String	否	最長 16 個字符；可為 null
iconAssetId	Integer	否	同一商品庫中現有的 CategoryIconAsset ID，而非 FilePath ID。正整數 ID，最大 2147483647。；可為 null
isEnabled	Boolean	否	—

響應參數： 200，data：Category。欄位說明

響應頭：ETag

請求示例：

bash

curl --request PATCH \
  'https://open.musedam.cc/api/product/categories/20' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "description": "Updated by API"
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": 20,
    "brandId": 10,
    "parentId": null,
    "name": "Catalog",
    "pathKey": "/Catalog",
    "description": "Updated by API",
    "iconEmoji": null,
    "iconAssetId": null,
    "sortOrder": 0,
    "isEnabled": true,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:05:00.000Z"
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

刪除分類

接口路徑：/categories/{id}

請求方式：DELETE

接口描述：僅當沒有有效商品引用任何後代分類時，才軟刪除整個分類子樹。不會刪除或降級商品。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。
If-Match	String	否	選填請求標頭；使用讀取時的 ETag，詳見並行更新。

響應參數： 200，data：DeletedId。回傳 data.id，即已刪除的資源 ID。

響應頭：ETag

請求示例：

bash

curl --request DELETE \
  'https://open.musedam.cc/api/product/categories/20' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": {
    "id": 20
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

信息模板

分組 groups

groups 包含 1–200 個分組，一個模板的欄位總數最多為 200。

欄位	類型	說明
`id`	string	現有分組必填，1–128 個字元，必須屬於本模板；新分組不傳。
`name`	string	必填，1–128 個字元，去除首尾空白。
`fields`	array	必填，分組中的欄位，見下表。

現有分組保持原有順序，新分組按提交順序附加。分組不接受 sortOrder 或 isDefault。預設分組由伺服器指定，不能刪除。

欄位 fields

新欄位必須提供 key、name 和 type。更新現有欄位時必須傳 id。類型不變時，省略的屬性保留原值，sortOrder 除外；變更 type 時，config 會按目標類型遷移，必要時須明確提供新設定。

欄位	類型	說明
`id`	string	現有欄位必填，1–128 個字元，必須屬於目前分組；新欄位不傳。
`key`	string	新欄位必填，1–64 個字元，須為唯一的有效識別符；既有欄位不能修改。
`name`	string	新欄位必填，1–128 個字元。
`type`	string	新欄位必填，支援的類型見下方設定表。
`required`	boolean	選填；新欄位預設為 `false`。
`placeholder`	string 或 null	選填，最多 255 個字元；新欄位預設為 `null`。
`sortOrder`	integer	選填，同組內唯一的非負整數；省略時使用欄位在陣列中的位置。
`config`	object	按欄位類型填寫，見下方設定表；新欄位省略時使用 `{}`，但仍須滿足該類型的設定要求。
`typeChangeConfirmed`	boolean	選填；允許但需要確認的類型變更須傳 `true`。

建立時會自動加入名稱、SKU 和主圖三個受保護欄位，因此最多可新增 197 個自訂欄位。第一個分組的自訂欄位排列在這三個欄位之後，傳入的 sortOrder（省略時為陣列位置）會增加 3。替換定義時須保留這些欄位的 id，以及類型、必填標記和設定。欄位不能移到其他分組。

新欄位只能是自訂欄位，不能使用保留的系統 key。isSystemField 和 systemKey 不能用於建立或重新分配系統身分；更新時保留原值。未知的分組或欄位屬性會被拒絕。

欄位設定 config

設定由欄位的 type 決定。例如，文字欄位使用 {}，貨幣和選項欄位需要額外設定。

欄位類型	config 設定
`text`、`textarea`、`email`、`phone`、`url`、`color`、`date`、`dateRange`	使用 `{}`，不接受其他設定。
`number`	選填 `unit`，字串。
`currency`	必填 `code`、`symbol`（非空字串）和 `decimals`（0–4 的整數）。
`richtext`	必填 `mode`，取值為 `html` 或 `delta`。
`select`、`radio`、`checkbox`	必填非空 `options` 陣列。每項見下表，`value` 不得重複。
`image`、`file`	選填 `maxCount`（大於等於 1 的整數）、`maxSizeMB`（大於 0 的數字）和 `accept`（字串陣列）。

每個 options 元素包含：

欄位	類型	說明
`value`	string	必填，非空，選項的唯一值。
`label`	string	必填，非空，顯示名稱。
`sortOrder`	integer	必填，非負整數。
`archived`	boolean	選填，是否封存該選項。

系統欄位的可用設定是 customPlaceholder（選填字串，最多 255 個字元）；品牌、分類系統欄位不接受自訂選項。受保護系統欄位的設定不能變更。

空設定和系統設定拒絕未知屬性；其他設定及選項會移除未知屬性。完整機器可讀定義可下載 OpenAPI JSON。

回傳的模板定義

模板詳情的 groups 和商品的 templateDefinition.groups 均包含分組與欄位。商品回傳的是建立時固定的版本，後續模板修改或刪除不會改變它；未綁定模板時，templateDefinition 可為 null。

分組固定回傳 id、name、fields，以及以下唯讀屬性：

欄位	類型	說明
`isDefault`	boolean	是否為預設分組。
`sortOrder`	integer	分組順序。

每個欄位固定回傳 id、key、name、type、required、placeholder、sortOrder、config，以及以下屬性；不回傳寫入參數 typeChangeConfirmed。

欄位	類型	說明
`isSystemField`	boolean	是否為系統欄位。
`systemKey`	string 或 null	系統身分：`name`、`sku`、`brand`、`category`、`description`、`mainImage`；自訂欄位為 `null`。

placeholder 可為 null。設定中的媒體引用會回傳安全的預覽資訊，不包含儲存路徑或憑證。讀取商品的固定模板定義不需要 templates:read 權限。

Template 回傳欄位

字段名	類型	描述
id	String	資源 ID。最短 1 個字符；最長 128 個字符
name	String	名稱。
description	String	說明。可為 null
enabled	Boolean	是否啓用模板。
isSystemDefault	Boolean	是否為系統默認模板。
isLibraryDefault	Boolean	是否為商品庫默認模板。
createdAt	String	RFC 3339 時間字串；保留完整精度。
updatedAt	String	RFC 3339 時間字串；保留完整精度。
boundBrandIds	List<Integer>	綁定的品牌 ID。每個元素：正整數 ID，最大 2147483647。
boundCategoryIds	List<Integer>	綁定的分類 ID。每個元素：正整數 ID，最大 2147483647。
groups	List<VersionGroup>	模板分組。嵌套字段：範本分組與欄位

獲取模板列表

接口路徑：/product-info-templates

請求方式：GET

接口描述：返回有效模板的元數據、綁定以及有序的分組/字段，包括僅預覽配置。按 createdAt 降序再按 id 排序。

所需角色：所有協作者角色。

請求參數：

參數名	類型	必填	描述
page	Integer	否	頁碼，正整數，預設 1
pageSize	Integer	否	每頁筆數，正整數，預設 20，上限 100。

響應參數： 200，data：List<Template>。欄位說明分頁欄位見請求與回應。

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/product-info-templates?page=1&pageSize=20' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": [
    {
      "id": "template_example",
      "name": "Example template",
      "description": null,
      "enabled": true,
      "isSystemDefault": false,
      "isLibraryDefault": false,
      "createdAt": "2026-10-08T10:00:00.000Z",
      "updatedAt": "2026-10-08T10:00:00.000Z",
      "boundBrandIds": [],
      "boundCategoryIds": [],
      "groups": [
        {
          "id": "group_details",
          "name": "Details",
          "isDefault": true,
          "sortOrder": 0,
          "fields": [
            {
              "id": "field_name",
              "key": "name",
              "name": "商品名称",
              "type": "text",
              "required": true,
              "placeholder": null,
              "sortOrder": 0,
              "isSystemField": true,
              "systemKey": "name",
              "config": {}
            },
            {
              "id": "field_sku",
              "key": "sku",
              "name": "SKU",
              "type": "text",
              "required": true,
              "placeholder": null,
              "sortOrder": 1,
              "isSystemField": true,
              "systemKey": "sku",
              "config": {}
            },
            {
              "id": "field_main_image",
              "key": "mainImage",
              "name": "商品主图",
              "type": "image",
              "required": true,
              "placeholder": null,
              "sortOrder": 2,
              "isSystemField": true,
              "systemKey": "mainImage",
              "config": {}
            },
            {
              "id": "field_color",
              "key": "color",
              "name": "Color",
              "type": "text",
              "required": false,
              "placeholder": null,
              "sortOrder": 3,
              "isSystemField": false,
              "systemKey": null,
              "config": {}
            }
          ]
        }
      ]
    }
  ],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111",
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1,
    "totalPages": 1
  }
}

創建模板

接口路徑：/product-info-templates

請求方式：POST

接口描述：建立模板及不可變版本。syncStrategy 可省略，目前僅支援 newOnly；最多 200 個欄位，不會變更任何既有商品。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
Idempotency-Key	String	否	選填請求標頭；同一鍵和輸入在 24 小時內重試，詳見冪等重試。
-	TemplateCreate	是	JSON 請求體：application/json

TemplateCreate參數說明：

name/description 會去除首尾空白。所有分組合計最多 200 個字段。綁定必須屬於同一商品庫，會替換所提供的綁定集合，並可將綁定從其他模板移過來。當所選品牌非空時，所選分類必須屬於這些品牌。僅支持 newOnly；絕不批量重新固定現有商品的版本。

不接受未定義字段。

字段名	類型	必填	描述
name	String	是	最短 1 個字符；最長 30 個字符
description	String	否	最長 50 個字符；可為 null
enabled	Boolean	否	—
groups	List<TemplateGroupInput>	是	最少 1 項；最多 200 項。嵌套字段：範本分組欄位
boundBrandIds	List<Integer>	否	每個元素：正整數 ID，最大 2147483647。；最多 10,000 項
boundCategoryIds	List<Integer>	否	每個元素：正整數 ID，最大 2147483647。；最多 10,000 項
isLibraryDefault	Boolean	否	—
syncStrategy	String	否	允許值：newOnly；默認值："newOnly"

響應參數： 201，data：Template。欄位說明

響應頭：ETag

請求示例：

bash

curl --request POST \
  'https://open.musedam.cc/api/product/product-info-templates' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Example template",
  "groups": [
    {
      "name": "Details",
      "fields": [
        {
          "key": "color",
          "name": "Color",
          "type": "text",
          "config": {}
        }
      ]
    }
  ]
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": "template_example",
    "name": "Example template",
    "description": null,
    "enabled": true,
    "isSystemDefault": false,
    "isLibraryDefault": false,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z",
    "boundBrandIds": [],
    "boundCategoryIds": [],
    "groups": [
      {
        "id": "group_details",
        "name": "Details",
        "isDefault": true,
        "sortOrder": 0,
        "fields": [
          {
            "id": "field_name",
            "key": "name",
            "name": "商品名称",
            "type": "text",
            "required": true,
            "placeholder": null,
            "sortOrder": 0,
            "isSystemField": true,
            "systemKey": "name",
            "config": {}
          },
          {
            "id": "field_sku",
            "key": "sku",
            "name": "SKU",
            "type": "text",
            "required": true,
            "placeholder": null,
            "sortOrder": 1,
            "isSystemField": true,
            "systemKey": "sku",
            "config": {}
          },
          {
            "id": "field_main_image",
            "key": "mainImage",
            "name": "商品主图",
            "type": "image",
            "required": true,
            "placeholder": null,
            "sortOrder": 2,
            "isSystemField": true,
            "systemKey": "mainImage",
            "config": {}
          },
          {
            "id": "field_color",
            "key": "color",
            "name": "Color",
            "type": "text",
            "required": false,
            "placeholder": null,
            "sortOrder": 3,
            "isSystemField": false,
            "systemKey": null,
            "config": {}
          }
        ]
      }
    ]
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

獲取模板詳情

接口路徑：/product-info-templates/{id}

請求方式：GET

接口描述：回傳指定未刪除模板的元資料、綁定及分組／欄位，包括僅供預覽的設定。分組和欄位按 sortOrder、id 升序排列。回應包含目前的強 ETag，涵蓋有效欄位、分組、綁定集合及預設模板標記。

所需角色：所有協作者角色。

請求參數：

參數名	類型	必填	描述
id	String	是	路徑參數。不透明的模板 ID；請勿假定其為 UUID 格式。最短 1 個字符；最長 128 個字符

響應參數： 200，data：Template。欄位說明

響應頭：ETag

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/product-info-templates/template_example' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": {
    "id": "template_example",
    "name": "Example template",
    "description": null,
    "enabled": true,
    "isSystemDefault": false,
    "isLibraryDefault": false,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z",
    "boundBrandIds": [],
    "boundCategoryIds": [],
    "groups": [
      {
        "id": "group_details",
        "name": "Details",
        "isDefault": true,
        "sortOrder": 0,
        "fields": [
          {
            "id": "field_name",
            "key": "name",
            "name": "商品名称",
            "type": "text",
            "required": true,
            "placeholder": null,
            "sortOrder": 0,
            "isSystemField": true,
            "systemKey": "name",
            "config": {}
          },
          {
            "id": "field_sku",
            "key": "sku",
            "name": "SKU",
            "type": "text",
            "required": true,
            "placeholder": null,
            "sortOrder": 1,
            "isSystemField": true,
            "systemKey": "sku",
            "config": {}
          },
          {
            "id": "field_main_image",
            "key": "mainImage",
            "name": "商品主图",
            "type": "image",
            "required": true,
            "placeholder": null,
            "sortOrder": 2,
            "isSystemField": true,
            "systemKey": "mainImage",
            "config": {}
          },
          {
            "id": "field_color",
            "key": "color",
            "name": "Color",
            "type": "text",
            "required": false,
            "placeholder": null,
            "sortOrder": 3,
            "isSystemField": false,
            "systemKey": null,
            "config": {}
          }
        ]
      }
    ]
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

更新模板

接口路徑：/product-info-templates/{id}

請求方式：PATCH

接口描述：使用與瀏覽器端共享的批量操作。省略 groups 欄位時保留原定義；提供 groups 時完整替換分組和欄位。會校驗穩定 ID 以及受保護的系統/默認字段。創建新的不可變版本，但不會遷移現有商品的固定版本或字段值；綁定/默認設置的變更會影響後續的模板解析。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
id	String	是	路徑參數。不透明的模板 ID；請勿假定其為 UUID 格式。最短 1 個字符；最長 128 個字符
If-Match	String	否	選填請求標頭；使用讀取時的 ETag，詳見並行更新。
-	TemplatePatch	是	JSON 請求體：application/json

TemplatePatch參數說明：

省略 groups 欄位時保留原定義；提供 groups 時完整替換，陣列中省略的舊分組和欄位會被刪除，但受預設/系統欄位保護規則約束。請保留需要繼續使用的分組和欄位 ID。每次成功寫入都會創建新的不可變版本，包括僅更新元數據的情況。

不接受未定義字段；至少提供字段數：1。

字段名	類型	必填	描述
name	String	否	最短 1 個字符；最長 30 個字符
description	String	否	最長 50 個字符；可為 null
enabled	Boolean	否	—
groups	List<TemplateGroupInput>	否	最少 1 項；最多 200 項。嵌套字段：範本分組欄位
boundBrandIds	List<Integer>	否	每個元素：正整數 ID，最大 2147483647。；最多 10,000 項
boundCategoryIds	List<Integer>	否	每個元素：正整數 ID，最大 2147483647。；最多 10,000 項
isLibraryDefault	Boolean	否	—
syncStrategy	String	否	允許值：newOnly；默認值："newOnly"

響應參數： 200，data：Template。欄位說明

響應頭：ETag

請求示例：

bash

curl --request PATCH \
  'https://open.musedam.cc/api/product/product-info-templates/template_example' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "description": "Updated by API"
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": "template_example",
    "name": "Example template",
    "description": "Updated by API",
    "enabled": true,
    "isSystemDefault": false,
    "isLibraryDefault": false,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:05:00.000Z",
    "boundBrandIds": [],
    "boundCategoryIds": [],
    "groups": [
      {
        "id": "group_details",
        "name": "Details",
        "isDefault": true,
        "sortOrder": 0,
        "fields": [
          {
            "id": "field_name",
            "key": "name",
            "name": "商品名称",
            "type": "text",
            "required": true,
            "placeholder": null,
            "sortOrder": 0,
            "isSystemField": true,
            "systemKey": "name",
            "config": {}
          },
          {
            "id": "field_sku",
            "key": "sku",
            "name": "SKU",
            "type": "text",
            "required": true,
            "placeholder": null,
            "sortOrder": 1,
            "isSystemField": true,
            "systemKey": "sku",
            "config": {}
          },
          {
            "id": "field_main_image",
            "key": "mainImage",
            "name": "商品主图",
            "type": "image",
            "required": true,
            "placeholder": null,
            "sortOrder": 2,
            "isSystemField": true,
            "systemKey": "mainImage",
            "config": {}
          },
          {
            "id": "field_color",
            "key": "color",
            "name": "Color",
            "type": "text",
            "required": false,
            "placeholder": null,
            "sortOrder": 3,
            "isSystemField": false,
            "systemKey": null,
            "config": {}
          }
        ]
      }
    ]
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

刪除模板

接口路徑：/product-info-templates/{id}

請求方式：DELETE

接口描述：軟刪除有效模板，同時保留現有商品所使用的不可變版本。刪除當前商品庫默認模板時，必須顯式指定替代模板或 null；默認/系統保護規則仍然適用。會移除綁定，但不會改寫現有商品的固定版本。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
id	String	是	路徑參數。不透明的模板 ID；請勿假定其為 UUID 格式。最短 1 個字符；最長 128 個字符
If-Match	String	否	選填請求標頭；使用讀取時的 ETag，詳見並行更新。
-	TemplateDelete	否	JSON 請求體：application/json

TemplateDelete參數說明：

可選請求體。若刪除的是當前商品庫默認模板，則此屬性必填：取值為同一商品庫中另一個有效模板的 ID，或顯式 null 以清除默認模板。歷史版本對固定了該版本的商品仍然可用。

不接受未定義字段。

字段名	類型	必填	描述
replacementForLibraryDefault	String	否	最短 1 個字符；最長 128 個字符；可為 null

響應參數： 200，data：DeletedTemplateId。回傳 data.id，即已刪除的資源 ID。

響應頭：ETag

請求示例：

bash

curl --request DELETE \
  'https://open.musedam.cc/api/product/product-info-templates/template_example' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "replacementForLibraryDefault": null
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": "template_example"
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

商品

模板版本與自訂欄位

商品建立時儲存模板版本。讀取 templateDefinition 解釋 templateFields；後續模板變更或刪除不影響這個版本，一般 PATCH 不能更換模板。templateFields 以固定版本中的欄位 ID 為鍵，更新時淺合併；null 清空單個欄位。

明確提供的 templateId 優先；否則，有 categoryId 時依次查找分類、祖先分類、品牌和商品庫預設模板。沒有分類時只考慮商品庫預設模板，即使傳入了品牌。

字段類型	輸入格式
`number`、`currency`	JSON 數字
`dateRange`	起止日期字符串組成的有序數組
`checkbox`	選項值數組
`image`、`file`	FilePath ID 數組，或 null
`richtext`	HTML 模式為字符串；delta 模式為 `{ "ops": [...] }`

草稿可缺少必填值，但提交和合併後的欄位仍須滿足類型／選項規則；發布或編輯已發布商品會驗證完整商品。一次寫入的全部媒體引用合計最多 100 個，只接受本商品庫既有的 FilePath ID。媒體列表省略時保留，[] 清空；未傳 coverAssetId 時，首張 imageAssetIds 圖片成為封面。

同步與檢查點

首次使用 sync=true，省略 updatedAfter；增量週期傳入上次完成的 syncedUntil。
按商品 id 和 updatedAt 合併，保留較新版本。
使用 sync=true&cursor=... 跟隨 nextCursor 直到 null；即使 data 為空，也要繼續。
完成後原樣儲存 syncedUntil，不要改用最後一筆商品的時間。

游標綁定密鑰、角色、商品庫、篩選條件和頁面大小；續頁時不要變更它們。更換授權或篩選條件要開始新週期；範圍擴大時重新完整同步。檢查點和同步 updatedAt 保留完整六位小數，不要用 JavaScript Date 截斷精度。每週期讀取目前狀態的 [updatedAfter, syncedUntil)，上界為首次請求時伺服器時間減 30 秒；長交易仍可能影響完整性，不提供每次變更的事件串流。

清理已刪除或不可見的商品

同步不會回傳刪除事件。定期將本機商品 ID 交給可見性介面，not_visible 時移除本機副本。該介面不檢查品牌、分類或搜尋等業務篩選；若只維護篩選後的副本，須定期完整核對篩選結果，或同步全部可見商品後在本機篩選。

預覽與下載鏈接

展示商品媒體時使用 previewUrl。需要原文件時，檢查 downloadUrl，或使用下一節的下載接口；能預覽不等於有下載權限。

鏈接	返回條件	服務簽發鏈接的有效期上限
派生預覽	具備相應查看權限	3600 秒
圖片原圖預覽回退	僅適用於圖片，`view_only` 也可能返回	300 秒
`downloadUrl`	關聯可解析且可見，`usable` 或更高角色，同時具備 `products:read` 和 `products:download`	300 秒

所有服務簽發鏈接還受 API key 的到期時間限制。鏈接過期後重新獲取商品數據，不要將簽名 URL 當作素材 ID 保存。

封面、圖片和關聯素材返回哪些字段？

cover 是一個媒體對象，無封面時為 null；images、relatedAssets 為媒體對象數組。自定義圖片/文件值可為數組或 null，未填寫的字段可能省略。

字段	類型	說明
`id`	整數或 null	素材查詢返回的 ID（FilePath ID），不是 AssetObject ID 或商品素材關聯 ID
`name`、`mimeType`	字符串或 null	文件名、MIME 類型
`size`	字符串或 null	十進制字節數，如 `"2048"`，不是 JSON 數字
`width`、`height`、`duration`	數字或 null	媒體尺寸和時長
`previewUrl`	URL 或 null	用於展示的預覽地址；不可用時為 null
`downloadUrl`	URL 或 null，可省略	原文件地址；返回條件見上表
`downloadUrlExpiresAt`	時間字符串或 null，可省略	下載地址的到期時間，RFC 3339 格式

鏈接缺失、舊版媒體和外部預覽如何處理？

非圖片素材只返回派生預覽，原始 PDF、壓縮包和文檔不會作為預覽回退。素材庫素材查詢和模板配置只包含預覽。
缺少下載權限或關聯無法解析時，會省略 downloadUrl 和 downloadUrlExpiresAt；已授權但原文件不可用時，這些值可能為 null。
已存儲的外部 DAM 縮略圖或預覽，只對未設置過期時間的 API key 返回，並先排除已知原文件 URL。它們的有效期由第三方控制，不保證短有效期，也不保證校驗提供方簽名。
API key 設置了 expiresAt 時，過期時間無法驗證的外部預覽返回 null。查詢參數中形似簽名的值不能作為可信的過期依據。
服務簽發的鏈接仍遵守上表限制；簽名失敗時不會返回原始存儲 URL。

ProductSummary 回傳欄位

字段名	類型	描述
id	Integer	資源 ID。正整數 ID，最大 2147483647。
name	String	名稱。
spu	String	商品 SKU。可為 null
description	String	說明。可為 null
status	String	當前狀態。允許值：draft、published
brandId	Integer	品牌 ID。正整數 ID，最大 2147483647。；可為 null
categoryId	Integer	分類 ID。正整數 ID，最大 2147483647。；可為 null
ownerUserId	Integer	所有者用戶 ID。正整數 ID，最大 2147483647。；可為 null
publishedAt	String	RFC 3339 時間字串；保留完整精度。草稿時為 `null`。
createdAt	String	RFC 3339 時間字串；保留完整精度。
updatedAt	String	RFC 3339 時間字串；保留完整精度。
draftReason	String	商品處於草稿狀態的原因。可為 null
templateId	String	模板 ID。最短 1 個字符；最長 128 個字符；可為 null
templateVersionId	String	固定的模板版本 ID。最短 1 個字符；最長 128 個字符；可為 null
templateFields	Object	以穩定模板字段 ID 為鍵的字段值。
cover	Object	商品封面。不接受未定義字段；可為 null。嵌套字段：封面媒體欄位
images	List<PublicAsset>	商品圖片。嵌套字段：媒體欄位
relatedAssets	List<PublicAsset>	相關素材。嵌套字段：媒體欄位

ProductDetail 回傳欄位

其他欄位與商品列表回傳欄位相同。

字段名	類型	描述
templateDefinition	NullableTemplateDefinition	固定版本的模板定義。嵌套字段：商品範本定義

獲取或同步商品列表

接口路徑：/products

請求方式：GET

接口描述：普通分頁按 updatedAt/id 降序排序。sync=true 時按 (updatedAt,id) 升序排序，使用包含的下界和不包含的固定上界（PostgreSQL 時鐘減 30 秒）。全量掃描時省略 updatedAfter；請持續跟隨每個 nextCursor，即使 data 頁為空。游標綁定 key/角色/商品庫/篩選條件/pageSize/邊界。僅在遍歷完畢後原樣保存 syncedUntil；按 id 和 updatedAt 進行重放/去重。持續時間超過 30 秒安全窗口的事務屬於 v1 已接受的限制。見同步說明。view_only/usable 僅可見已發佈商品。

所需角色：所有協作者角色。

請求參數：

參數名	類型	必填	描述
page	Integer	否	頁碼，正整數，預設 1；sync=true 時不可用。
pageSize	Integer	否	每頁筆數，正整數，預設 20，上限 100。
search	String	否	查詢參數。去除首尾空白、不區分大小寫的子串匹配：商品名稱/spu，或素材庫素材名稱。
brandId	Integer	否	查詢參數。按本商品庫內的品牌 ID 篩選。正整數 ID，最大 2147483647。
categoryId	Integer	否	查詢參數。按精確的分類 ID 篩選，不包含其後代分類。正整數 ID，最大 2147483647。
status	String	否	查詢參數。請求的商品狀態；不會擴大角色可見範圍。允許值：draft、published
sync	String	否	查詢參數。true 表示使用有界的鍵集同步；false 表示普通分頁。見同步說明。允許值：true、false；默認值："false"
updatedAfter	String	否	查詢參數。僅在 sync=true 時使用。包含的下界；RFC3339 格式，使用 Z 或時區偏移，0..6 位小數，日曆日期/偏移須有效。請將 syncedUntil 作為字符串保存並復用。全量掃描時省略。格式：date-time
cursor	String	否	查詢參數。不透明的續頁令牌，僅在 sync=true 時使用。綁定 key、角色、商品庫、邊界、篩選條件和每頁條數。續頁時省略其他參數，或重復傳入等價的值。重復的同步參數會被拒絕。最短 1 個字符；最長 8,192 個字符

響應參數： 200，data：List<ProductSummary>。欄位說明分頁欄位見請求與回應。

SyncPage

字段名	類型	描述
pageSize	Integer	每頁數量。最小值：1；最大值：100
syncedUntil	String	PostgreSQL 時鐘減 30 秒，在整個週期內固定。僅在 nextCursor 為 null 後原樣保存此字符串。格式：date-time；須匹配 `^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{6}Z$`
nextCursor	String	下一頁游標，掃描結束後為 null。最長 8,192 個字符；可為 null
hasMore	Boolean	是否還有下一頁同步數據。

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/products?page=1&pageSize=20' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": [
    {
      "id": 40,
      "name": "Example product",
      "spu": "EXAMPLE-001",
      "description": null,
      "status": "draft",
      "brandId": 10,
      "categoryId": 20,
      "ownerUserId": null,
      "publishedAt": null,
      "createdAt": "2026-10-08T10:00:00.000Z",
      "updatedAt": "2026-10-08T10:00:00.000Z",
      "draftReason": null,
      "templateId": "template_example",
      "templateVersionId": "version_one",
      "templateFields": {
        "field_color": "Blue"
      },
      "cover": {
        "id": 30,
        "name": "cover.jpg",
        "mimeType": "image/jpeg",
        "size": "9007199254740993",
        "width": 1200,
        "height": 900,
        "duration": null,
        "previewUrl": "https://media.example.test/preview?signature=example"
      },
      "images": [
        {
          "id": 30,
          "name": "cover.jpg",
          "mimeType": "image/jpeg",
          "size": "9007199254740993",
          "width": 1200,
          "height": 900,
          "duration": null,
          "previewUrl": "https://media.example.test/preview?signature=example"
        }
      ],
      "relatedAssets": []
    }
  ],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111",
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1,
    "totalPages": 1
  }
}

響應示例（同步）：

json

{
  "success": true,
  "data": [
    {
      "id": 40,
      "name": "Example product",
      "spu": "EXAMPLE-001",
      "description": null,
      "status": "draft",
      "brandId": 10,
      "categoryId": 20,
      "ownerUserId": null,
      "publishedAt": null,
      "createdAt": "2026-10-08T10:00:00.000Z",
      "updatedAt": "2026-10-08T10:00:00.123456Z",
      "draftReason": null,
      "templateId": "template_example",
      "templateVersionId": "version_one",
      "templateFields": {
        "field_color": "Blue"
      },
      "cover": {
        "id": 30,
        "name": "cover.jpg",
        "mimeType": "image/jpeg",
        "size": "9007199254740993",
        "width": 1200,
        "height": 900,
        "duration": null,
        "previewUrl": "https://media.example.test/preview?signature=example"
      },
      "images": [
        {
          "id": 30,
          "name": "cover.jpg",
          "mimeType": "image/jpeg",
          "size": "9007199254740993",
          "width": 1200,
          "height": 900,
          "duration": null,
          "previewUrl": "https://media.example.test/preview?signature=example"
        }
      ],
      "relatedAssets": []
    }
  ],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111",
  "pagination": {
    "pageSize": 20,
    "syncedUntil": "2026-10-08T10:01:00.123456Z",
    "nextCursor": null,
    "hasMore": false
  }
}

響應示例（空頁續傳）：

json

{
  "success": true,
  "data": [],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111",
  "pagination": {
    "pageSize": 20,
    "syncedUntil": "2026-10-08T10:01:00.123456Z",
    "nextCursor": "opaque-continuation-token",
    "hasMore": true
  }
}

創建草稿商品

接口路徑：/products

請求方式：POST

接口描述：僅創建草稿。創建時解析並固定一個模板版本；模板字段依據該不可變定義進行校驗。可關聯同一商品庫中現有的 FilePath ID；不支持上傳、遠程導入或回寫到提供方。冪等重放會保留原始標量結果/ETag，並且僅對在當前同一槽位中仍然有效的原始媒體按當前權限重新投影。

所需角色：editable 或 manage。

請求參數：

參數名	類型	必填	描述
Idempotency-Key	String	否	選填請求標頭；同一鍵和輸入在 24 小時內重試，詳見冪等重試。
-	ProductCreate	是	JSON 請求體：application/json

ProductCreate參數說明：

始終創建草稿。顯式指定的 templateId 必須是同一商品庫中的有效模板，且優先使用。當 templateId 省略/為 null 且提供了非 null 的 categoryId 時，解析順序為：分類或其祖先分類的綁定，然後是該分類所屬品牌的綁定，最後是商品庫默認模板。當 categoryId 省略或為 null 時，即使提供了 brandId，也僅考慮商品庫默認模板。若未解析出任何模板，則商品沒有模板。分類必須與最終品牌匹配；owner 必須是同一團隊成員，默認為 null，而非 key 創建者。cover/images/related/自定義媒體合計最多 100 個引用。圖片槽位要求使用圖片；自定義媒體必須滿足固定版本的數量/大小/類型限制。

不接受未定義字段。

字段名	類型	必填	描述
name	String	否	會去除首尾空白；草稿可省略或為空。最長 255 個字符
spu	String	否	會去除首尾空白；null/空白表示清除。在商品庫有效商品中唯一。最長 64 個字符；可為 null
description	String	否	可為 null
brandId	Integer	否	正整數 ID，最大 2147483647。；可為 null
categoryId	Integer	否	正整數 ID，最大 2147483647。；可為 null
ownerUserId	Integer	否	正整數 ID，最大 2147483647。；可為 null
templateId	String	否	最短 1 個字符；最長 128 個字符；可為 null
templateFields	Object	否	按穩定的自定義字段 ID 淺合併；null 清除單個字段。未知/系統 ID 會被拒絕。即使是草稿也會校驗類型/選項。image/file 的值為 FilePath ID 數組或 null，而非 URL/對象快照。PATCH 依據固定版本進行校驗，即使其有效模板已被刪除。
coverAssetId	Integer	否	正整數 ID，最大 2147483647。；可為 null
imageAssetIds	List<Integer>	否	每個元素：正整數 ID，最大 2147483647。；最多 100 項
relatedAssetIds	List<Integer>	否	每個元素：正整數 ID，最大 2147483647。；最多 100 項

響應參數： 201，data：ProductDetail。欄位說明

響應頭：ETag

請求示例：

bash

curl --request POST \
  'https://open.musedam.cc/api/product/products' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Example product",
  "spu": "EXAMPLE-001",
  "brandId": 10,
  "categoryId": 20,
  "coverAssetId": 30,
  "imageAssetIds": [
    30
  ]
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": 40,
    "name": "Example product",
    "spu": "EXAMPLE-001",
    "description": null,
    "status": "draft",
    "brandId": 10,
    "categoryId": 20,
    "ownerUserId": null,
    "publishedAt": null,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z",
    "draftReason": null,
    "templateId": "template_example",
    "templateVersionId": "version_one",
    "templateFields": {
      "field_color": "Blue"
    },
    "cover": {
      "id": 30,
      "name": "cover.jpg",
      "mimeType": "image/jpeg",
      "size": "9007199254740993",
      "width": 1200,
      "height": 900,
      "duration": null,
      "previewUrl": "https://media.example.test/preview?signature=example"
    },
    "images": [
      {
        "id": 30,
        "name": "cover.jpg",
        "mimeType": "image/jpeg",
        "size": "9007199254740993",
        "width": 1200,
        "height": 900,
        "duration": null,
        "previewUrl": "https://media.example.test/preview?signature=example"
      }
    ],
    "relatedAssets": [],
    "templateDefinition": {
      "groups": [
        {
          "id": "group_details",
          "name": "Details",
          "isDefault": true,
          "sortOrder": 0,
          "fields": [
            {
              "id": "field_color",
              "key": "color",
              "name": "Color",
              "type": "text",
              "required": false,
              "placeholder": null,
              "sortOrder": 0,
              "isSystemField": false,
              "systemKey": null,
              "config": {}
            }
          ]
        }
      ]
    }
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

獲取商品及其固定版本定義

接口路徑：/products/{id}

請求方式：GET

接口描述：返回可訪問的有效商品及其固定的不可變模板定義，即使有效模板已變更或被刪除。不需要 templates:read。每次響應都會對媒體預覽/下載進行授權；下載需要 products:read 加 products:download，且角色為 usable 或更高。草稿對 view_only/usable 不可見。

所需角色：所有協作者角色。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。

響應參數： 200，data：ProductDetail。欄位說明

響應頭：ETag

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/products/40' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": {
    "id": 40,
    "name": "Example product",
    "spu": "EXAMPLE-001",
    "description": null,
    "status": "draft",
    "brandId": 10,
    "categoryId": 20,
    "ownerUserId": null,
    "publishedAt": null,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z",
    "draftReason": null,
    "templateId": "template_example",
    "templateVersionId": "version_one",
    "templateFields": {
      "field_color": "Blue"
    },
    "cover": {
      "id": 30,
      "name": "cover.jpg",
      "mimeType": "image/jpeg",
      "size": "9007199254740993",
      "width": 1200,
      "height": 900,
      "duration": null,
      "previewUrl": "https://media.example.test/preview?signature=example"
    },
    "images": [
      {
        "id": 30,
        "name": "cover.jpg",
        "mimeType": "image/jpeg",
        "size": "9007199254740993",
        "width": 1200,
        "height": 900,
        "duration": null,
        "previewUrl": "https://media.example.test/preview?signature=example"
      }
    ],
    "relatedAssets": [],
    "templateDefinition": {
      "groups": [
        {
          "id": "group_details",
          "name": "Details",
          "isDefault": true,
          "sortOrder": 0,
          "fields": [
            {
              "id": "field_color",
              "key": "color",
              "name": "Color",
              "type": "text",
              "required": false,
              "placeholder": null,
              "sortOrder": 0,
              "isSystemField": false,
              "systemKey": null,
              "config": {}
            }
          ]
        }
      ]
    }
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

響應示例（無模板或媒體）：

json

{
  "success": true,
  "data": {
    "id": 40,
    "name": "Example product",
    "spu": "EXAMPLE-001",
    "description": null,
    "status": "draft",
    "brandId": 10,
    "categoryId": 20,
    "ownerUserId": null,
    "publishedAt": null,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z",
    "draftReason": null,
    "templateId": null,
    "templateVersionId": null,
    "templateFields": {},
    "cover": null,
    "images": [],
    "relatedAssets": [],
    "templateDefinition": null
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

響應示例（含授權下載）：

json

{
  "success": true,
  "data": {
    "id": 40,
    "name": "Example product",
    "spu": "EXAMPLE-001",
    "description": null,
    "status": "draft",
    "brandId": 10,
    "categoryId": 20,
    "ownerUserId": null,
    "publishedAt": null,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z",
    "draftReason": null,
    "templateId": "template_example",
    "templateVersionId": "version_one",
    "templateFields": {
      "field_color": "Blue"
    },
    "cover": {
      "id": 30,
      "name": "cover.jpg",
      "mimeType": "image/jpeg",
      "size": "9007199254740993",
      "width": 1200,
      "height": 900,
      "duration": null,
      "previewUrl": "https://media.example.test/preview?signature=example",
      "downloadUrl": "https://media.example.test/original?signature=example",
      "downloadUrlExpiresAt": "2026-10-08T10:05:00.000Z"
    },
    "images": [
      {
        "id": 30,
        "name": "cover.jpg",
        "mimeType": "image/jpeg",
        "size": "9007199254740993",
        "width": 1200,
        "height": 900,
        "duration": null,
        "previewUrl": "https://media.example.test/preview?signature=example"
      }
    ],
    "relatedAssets": [],
    "templateDefinition": {
      "groups": [
        {
          "id": "group_details",
          "name": "Details",
          "isDefault": true,
          "sortOrder": 0,
          "fields": [
            {
              "id": "field_color",
              "key": "color",
              "name": "Color",
              "type": "text",
              "required": false,
              "placeholder": null,
              "sortOrder": 0,
              "isSystemField": false,
              "systemKey": null,
              "config": {}
            }
          ]
        }
      ]
    }
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

部分更新商品

接口路徑：/products/{id}

請求方式：PATCH

接口描述：合併標量/自定義字段，並替換所提交的媒體列表。使用不可變的固定版本定義，包括有效模板已被刪除的情況。已發佈商品還需要 products:publish 權限，並保持已發佈狀態；必須以原子方式通過對最終狀態的完整校驗。此處不接受切換狀態/模板。

所需角色：editable 或 manage。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。
If-Match	String	否	選填請求標頭；使用讀取時的 ETag，詳見並行更新。
-	ProductPatch	是	JSON 請求體：application/json

ProductPatch參數說明：

省略的字段保持不變；顯式 null 清除可為 null 的字段，[] 清除列表。templateFields 採用合併；媒體數組替換其所在槽位。若提供 imageAssetIds 但未提供 coverAssetId，則第一張圖片成為封面。已發佈商品需要 products:publish 權限並保持已發佈狀態，且須通過對最終狀態的完整校驗。templateId、templateVersionId 和 status 會被拒絕。

不接受未定義字段。

字段名	類型	必填	描述
name	String	否	會去除首尾空白；草稿可省略或為空。最長 255 個字符
spu	String	否	會去除首尾空白；null/空白表示清除。在商品庫有效商品中唯一。最長 64 個字符；可為 null
description	String	否	可為 null
brandId	Integer	否	正整數 ID，最大 2147483647。；可為 null
categoryId	Integer	否	正整數 ID，最大 2147483647。；可為 null
ownerUserId	Integer	否	正整數 ID，最大 2147483647。；可為 null
templateFields	Object	否	按穩定的自定義字段 ID 淺合併；null 清除單個字段。未知/系統 ID 會被拒絕。即使是草稿也會校驗類型/選項。image/file 的值為 FilePath ID 數組或 null，而非 URL/對象快照。PATCH 依據固定版本進行校驗，即使其有效模板已被刪除。
coverAssetId	Integer	否	正整數 ID，最大 2147483647。；可為 null
imageAssetIds	List<Integer>	否	每個元素：正整數 ID，最大 2147483647。；最多 100 項
relatedAssetIds	List<Integer>	否	每個元素：正整數 ID，最大 2147483647。；最多 100 項

響應參數： 200，data：ProductDetail。欄位說明

響應頭：ETag

請求示例：

bash

curl --request PATCH \
  'https://open.musedam.cc/api/product/products/40' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "description": null,
  "templateFields": {
    "field_color": "Blue"
  }
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": 40,
    "name": "Example product",
    "spu": "EXAMPLE-001",
    "description": null,
    "status": "draft",
    "brandId": 10,
    "categoryId": 20,
    "ownerUserId": null,
    "publishedAt": null,
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z",
    "draftReason": null,
    "templateId": "template_example",
    "templateVersionId": "version_one",
    "templateFields": {
      "field_color": "Blue"
    },
    "cover": {
      "id": 30,
      "name": "cover.jpg",
      "mimeType": "image/jpeg",
      "size": "9007199254740993",
      "width": 1200,
      "height": 900,
      "duration": null,
      "previewUrl": "https://media.example.test/preview?signature=example"
    },
    "images": [
      {
        "id": 30,
        "name": "cover.jpg",
        "mimeType": "image/jpeg",
        "size": "9007199254740993",
        "width": 1200,
        "height": 900,
        "duration": null,
        "previewUrl": "https://media.example.test/preview?signature=example"
      }
    ],
    "relatedAssets": [],
    "templateDefinition": {
      "groups": [
        {
          "id": "group_details",
          "name": "Details",
          "isDefault": true,
          "sortOrder": 0,
          "fields": [
            {
              "id": "field_color",
              "key": "color",
              "name": "Color",
              "type": "text",
              "required": false,
              "placeholder": null,
              "sortOrder": 0,
              "isSystemField": false,
              "systemKey": null,
              "config": {}
            }
          ]
        }
      ]
    }
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

軟刪除商品

接口路徑：/products/{id}

請求方式：DELETE

接口描述：軟刪除一個可見的有效商品。草稿需要 delete 權限；已發佈商品需要 delete 和 publish 權限。歷史模板版本保持不變。不與提供方同步。重復刪除返回 404。

所需角色：editable 或 manage。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。
If-Match	String	否	選填請求標頭；使用讀取時的 ETag，詳見並行更新。

響應參數： 200，data：DeletedId。回傳 data.id，即已刪除的資源 ID。

響應頭：ETag

請求示例：

bash

curl --request DELETE \
  'https://open.musedam.cc/api/product/products/40' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": {
    "id": 40
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

發佈商品或將商品退回草稿

接口路徑：/products/{id}/status

請求方式：PATCH

接口描述：始終同時需要 update 和 publish 權限。發佈時會校驗固定版本的所有必填/類型/選項/媒體規則；狀態無效時返回 422 及字段詳情，且不做任何更改。重復發佈會保留 publishedAt，退回草稿會清除該值。不會啓動審批流程。

所需角色：editable 或 manage。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。
If-Match	String	否	選填請求標頭；使用讀取時的 ETag，詳見並行更新。
-	ProductStatus	是	JSON 請求體：application/json

ProductStatus參數說明：

任一狀態轉換（包括狀態相同的請求）都同時需要 products:update 和 products:publish。發佈會校驗固定版本的所有必填字段以及當前媒體；失敗時為原子操作。publishedAt 在首次發佈時設置，重復發佈時保留，退回草稿時清除。

不接受未定義字段。

字段名	類型	必填	描述
status	String	是	允許值：draft、published

響應參數： 200，data：ProductDetail。欄位說明

響應頭：ETag

請求示例：

bash

curl --request PATCH \
  'https://open.musedam.cc/api/product/products/40/status' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "status": "published"
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": 40,
    "name": "Example product",
    "spu": "EXAMPLE-001",
    "description": null,
    "status": "published",
    "brandId": 10,
    "categoryId": 20,
    "ownerUserId": null,
    "publishedAt": "2026-10-08T10:00:00.000Z",
    "createdAt": "2026-10-08T10:00:00.000Z",
    "updatedAt": "2026-10-08T10:00:00.000Z",
    "draftReason": null,
    "templateId": "template_example",
    "templateVersionId": "version_one",
    "templateFields": {
      "field_color": "Blue"
    },
    "cover": {
      "id": 30,
      "name": "cover.jpg",
      "mimeType": "image/jpeg",
      "size": "9007199254740993",
      "width": 1200,
      "height": 900,
      "duration": null,
      "previewUrl": "https://media.example.test/preview?signature=example"
    },
    "images": [
      {
        "id": 30,
        "name": "cover.jpg",
        "mimeType": "image/jpeg",
        "size": "9007199254740993",
        "width": 1200,
        "height": 900,
        "duration": null,
        "previewUrl": "https://media.example.test/preview?signature=example"
      }
    ],
    "relatedAssets": [],
    "templateDefinition": {
      "groups": [
        {
          "id": "group_details",
          "name": "Details",
          "isDefault": true,
          "sortOrder": 0,
          "fields": [
            {
              "id": "field_color",
              "key": "color",
              "name": "Color",
              "type": "text",
              "required": false,
              "placeholder": null,
              "sortOrder": 0,
              "isSystemField": false,
              "systemKey": null,
              "config": {}
            }
          ]
        }
      ]
    }
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

核對已知商品 ID

接口路徑：/products/visibility

請求方式：POST

接口描述：在當前 key 的可見性下檢查最多 100 個已知 ID。保留順序和重復項，接受空數組。not_visible 不區分已刪除、不存在、屬於其他商品庫以及因角色而隱藏的條目。由於同步不提供刪除墓碑記錄，請定期調用以清理本地的過期條目。此讀操作不支持 Idempotency-Key 或 ETag。

所需角色：所有協作者角色。

請求參數：

參數名	類型	必填	描述
-	VisibilityInput	是	JSON 請求體：application/json

VisibilityInput參數說明：

0..100 個 ID。輸出保留輸入順序和重復項；[] 返回 []。

不接受未定義字段。

字段名	類型	必填	描述
ids	List<Integer>	是	每個元素：正整數 ID，最大 2147483647。；最多 100 項

響應參數： 200，data：List<Visibility>。

Visibility

字段名	類型	描述
id	Integer	資源 ID。正整數 ID，最大 2147483647。
visibility	String	所提交商品 ID 的可見性。允許值：visible、not_visible

請求示例：

bash

curl --request POST \
  'https://open.musedam.cc/api/product/products/visibility' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "ids": [
    40,
    41
  ]
}'

回應範例

json

{
  "success": true,
  "data": [
    {
      "id": 40,
      "visibility": "visible"
    },
    {
      "id": 41,
      "visibility": "not_visible"
    }
  ],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

素材

LibraryAsset 回傳欄位

字段名	類型	描述
id	Integer	資源 ID。正整數 ID，最大 2147483647。
name	String	名稱。可為 null
mimeType	String	MIME 類型。可為 null
size	String	十進制字節數字符串；絕不是 JSON 數字。須匹配 `^\d+$`；可為 null
width	Number	寬度。可為 null
height	Number	高度。可為 null
duration	Number	時長。可為 null
previewUrl	String	預覽地址。格式：uri；可為 null

查找現有素材庫素材

接口路徑：/assets

請求方式：GET

接口描述：列出 key 所屬商品庫中有效的非目錄 FilePath 素材，按 id 排序。需要在 editable/manage 角色下具有 products:create 或 products:update 權限，而非 products:read。僅返回預覽，絕不返回原始文件下載字段。在商品寫入中使用 FilePath id；上傳不在 v1 範圍內。

所需角色：editable 或 manage。

請求參數：

參數名	類型	必填	描述
page	Integer	否	頁碼，正整數，預設 1
pageSize	Integer	否	每頁筆數，正整數，預設 20，上限 100。
search	String	否	查詢參數。去除首尾空白、不區分大小寫的子串匹配：商品名稱/spu，或素材庫素材名稱。
mimeType	String	否	查詢參數。去除首尾空白、不區分大小寫的 MIME 前綴，例如 image/ 或 application/pdf。

響應參數： 200，data：List<LibraryAsset>。欄位說明分頁欄位見請求與回應。

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/assets?page=1&pageSize=20' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": [
    {
      "id": 30,
      "name": "cover.jpg",
      "mimeType": "image/jpeg",
      "size": "9007199254740993",
      "width": 1200,
      "height": 900,
      "duration": null,
      "previewUrl": "https://media.example.test/preview?signature=example"
    }
  ],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111",
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1,
    "totalPages": 1
  }
}

獲取現有素材庫素材詳情

接口路徑：/assets/{id}

請求方式：GET

接口描述：返回同一商品庫中有效的 FilePath 及僅預覽的媒體元數據。與列表接口使用相同的 create 或 update 權限門檻。返回不透明的強 ETag，該 ETag 基於 FilePath 和關聯 AssetObject 的標識以及所維護的更新時間戳；臨時簽名的變化不會改變此標籤。

所需角色：editable 或 manage。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。

響應參數： 200，data：LibraryAsset。欄位說明

響應頭：ETag

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/assets/30' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": {
    "id": 30,
    "name": "cover.jpg",
    "mimeType": "image/jpeg",
    "size": "9007199254740993",
    "width": 1200,
    "height": 900,
    "duration": null,
    "previewUrl": "https://media.example.test/preview?signature=example"
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

記錄中的商品快照有哪些字段？

分享和下載記錄的 products 數組保留操作發生時的商品信息，不隨商品後續修改更新。

字段	類型	說明
`id`	正整數	商品 ID
`name`	字符串	當時的商品名稱
`spu`	字符串或 null	當時的 SKU

ProductShare 回傳欄位

字段名	類型	描述
id	String	資源 ID。
url	String	分享地址。格式：uri
products	List<ProductLabelSnapshot>	商品快照。嵌套字段：商品快照欄位
createdById	Integer	創建者用戶 ID。可為 null
createdByApiKeyId	String	創建者 API key ID。可為 null
createdByName	String	創建者名稱。
createdAt	String	創建時間。格式：date-time
expiresAt	String	過期時間。可為 null；格式：date-time
revokedAt	String	撤銷時間。可為 null；格式：date-time
allowDownload	Boolean	是否允許下載。
hasAccessCode	Boolean	分享是否設置訪問碼。
status	String	當前狀態。允許值：active、expired、revoked
canRevoke	Boolean	當前調用方是否可撤銷此分享。

查詢團隊分享記錄

接口路徑：/product-shares

請求方式：GET

接口描述：按 createdAt 和 id 倒序列出當前團隊所有瀏覽器操作者及 API key 的記錄。可選 productId 返回完整的匹配操作；省略則查詢全團隊。僅接受 productId、page 和 pageSize，未知或重復參數返回 422。不會隱式限制為當前 API key 或創建者的記錄。需要 manage 和 products:history，無需 products:read。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
productId	Integer	否	查詢參數。按一個商品 ID 篩選記錄，仍返回包含其他商品和文件的完整操作。省略時查詢當前團隊全部記錄。正整數 ID，最大 2147483647。
page	Integer	否	頁碼，正整數，預設 1
pageSize	Integer	否	每頁筆數，正整數，預設 20，上限 100。

響應參數： 200，data：List<ProductShare>。欄位說明分頁欄位見請求與回應。

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/product-shares?page=1&pageSize=20' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": [
    {
      "id": "share-example",
      "url": "https://your-deployment.example/share/products/example-recipient-token",
      "products": [
        {
          "id": 40,
          "name": "Example product",
          "spu": "SKU-40"
        }
      ],
      "createdById": null,
      "createdByApiKeyId": "integration-key-id",
      "createdByName": "Catalog integration",
      "createdAt": "2026-10-09T10:00:00.000Z",
      "expiresAt": "2026-10-16T10:00:00.000Z",
      "revokedAt": null,
      "allowDownload": false,
      "hasAccessCode": false,
      "status": "active",
      "canRevoke": true
    }
  ],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111",
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1,
    "totalPages": 1
  }
}

創建商品分享

接口路徑：/product-shares

請求方式：POST

接口描述：為固定的已發佈商品集合創建有效期為 7/30/90 天或永久的分享。accessCode 可選且必須為四位數字。allowDownload 另需 products:download。訪問者無需登錄或 API key；未發佈/已刪除商品會從實時分享中隱藏。創建 key 的變化不會撤銷獨立的團隊分享。可選的 24 小時冪等機制復用同一分享。

所需角色：usable、editable 或 manage。

請求參數：

參數名	類型	必填	描述
Idempotency-Key	String	否	選填請求標頭；同一鍵和輸入在 24 小時內重試，詳見冪等重試。
-	ProductShareCreate	是	JSON 請求體：application/json

ProductShareCreate參數說明：

不接受未定義字段。

字段名	類型	必填	描述
productIds	List<Integer>	是	最少 1 項；最多 100 項；每個 ID 為正整數，最大 2147483647。
expiresInDays	Integer	是	可為 null；允許值：7、30、90、null
accessCode	String	否	須匹配 `^[0-9]{4}$`
allowDownload	Boolean	是	—

響應參數： 201，data：ProductShare。欄位說明

請求示例：

bash

curl --request POST \
  'https://open.musedam.cc/api/product/product-shares' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "productIds": [
    40
  ],
  "expiresInDays": 7,
  "allowDownload": false
}'

回應範例

json

{
  "success": true,
  "data": {
    "id": "share-example",
    "url": "https://your-deployment.example/share/products/example-recipient-token",
    "products": [
      {
        "id": 40,
        "name": "Example product",
        "spu": "SKU-40"
      }
    ],
    "createdById": null,
    "createdByApiKeyId": "integration-key-id",
    "createdByName": "Catalog integration",
    "createdAt": "2026-10-09T10:00:00.000Z",
    "expiresAt": "2026-10-16T10:00:00.000Z",
    "revokedAt": null,
    "allowDownload": false,
    "hasAccessCode": false,
    "status": "active",
    "canRevoke": false
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

撤銷商品分享

接口路徑：/product-shares/{id}

請求方式：DELETE

接口描述：撤銷當前團隊任意分享。需要 manage 和 products:share，無需 products:read。重復撤銷返回原 revokedAt。未知或其他團隊的 ID 返回 404。不使用 ETag 或 If-Match。

所需角色：manage。

請求參數：

參數名	類型	必填	描述
id	String	是	路徑參數。不透明的分享標識符。最短 1 個字符；最長 128 個字符

響應參數： 200，data：RevokedProductShare。

RevokedProductShare

字段名	類型	描述
id	String	資源 ID。
revokedAt	String	撤銷時間。格式：date-time

請求示例：

bash

curl --request DELETE \
  'https://open.musedam.cc/api/product/product-shares/share-example' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": {
    "id": "share-example",
    "revokedAt": "2026-10-09T11:00:00.000Z"
  },
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

下載

選擇檔案、匯出與記錄

先查詢商品下載候選，將回傳的 key 放入 assetKeys，或 URL 編碼後用作單檔路徑參數 assetKey；它不是 FilePath ID。原始檔案下載只有一個檔案時回傳該檔案，多個檔案時回傳 ZIP。每次選擇 1–100 個商品、最多 200 個檔案、合計不超過 500 MiB。

匯出使用 kind: "export"，格式為 xlsx（預設）、csv 或 json，不能傳 assetKeys。includeAssetUrls 預設 true，匯出的連結仍需要 Bearer 請求標頭；給免登入訪客使用時應建立分享。locale 只影響系統標籤和狀態。

附件回應標頭 X-Download-Record-Id 是業務記錄 ID。requested 僅表示請求已接受，不表示傳輸或本機儲存完成。歷史包含團隊瀏覽器操作及其他 API Key 的操作；一般讀取、預覽和直接存取儲存下載 URL 不計入歷史。

下載記錄中的文件快照有哪些字段？

下載記錄的 files 數組保留首次接受操作時的文件信息。

字段	類型	說明
`id`	字符串	文件快照標識
`productId`	正整數	所屬商品 ID
`name`	字符串	當時的文件名

ProductDownloadRecord 回傳欄位

字段名	類型	描述
id	String	資源 ID。
kind	String	操作類型。允許值：product_export、asset_download
status	String	當前狀態。允許值：requested、failed
actorType	String	操作者類型。允許值：member、external、api_key
actorId	Integer	操作者 ID。可為 null
apiKeyId	String	API key ID。可為 null
actorName	String	操作者名稱。
shareId	String	分享 ID。可為 null
products	List<ProductLabelSnapshot>	商品快照。嵌套字段：商品快照欄位
files	List<FileLabelSnapshot>	文件快照。嵌套字段：檔案快照欄位
createdAt	String	創建時間。格式：date-time

ProductDownloadCandidate 回傳欄位

字段名	類型	描述
key	String	下載選擇標識。
name	String	名稱。
productId	Integer	商品 ID。正整數 ID，最大 2147483647。
productName	String	商品名稱。
category	String	媒體類別。允許值：main、related、field
mimeType	String	MIME 類型。可為 null
size	String	文件字節數，以十進制字符串表示。可為 null；須匹配 `^[0-9]+$`
downloadable	Boolean	當前是否可下載此文件。

查詢團隊下載記錄

接口路徑：/product-downloads

請求方式：GET

所需角色：manage。

請求參數：

參數名	類型	必填	描述
productId	Integer	否	查詢參數。按一個商品 ID 篩選記錄，仍返回包含其他商品和文件的完整操作。省略時查詢當前團隊全部記錄。正整數 ID，最大 2147483647。
page	Integer	否	頁碼，正整數，預設 1
pageSize	Integer	否	每頁筆數，正整數，預設 20，上限 100。

響應參數： 200，data：List<ProductDownloadRecord>。欄位說明分頁欄位見請求與回應。

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/product-downloads?page=1&pageSize=20' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": [
    {
      "id": "download-example",
      "kind": "product_export",
      "status": "requested",
      "actorType": "api_key",
      "actorId": null,
      "apiKeyId": "integration-key-id",
      "actorName": "Catalog integration",
      "shareId": null,
      "products": [
        {
          "id": 40,
          "name": "Example product",
          "spu": "SKU-40"
        }
      ],
      "files": [
        {
          "id": "export:xlsx",
          "productId": 40,
          "name": "products.xlsx"
        }
      ],
      "createdAt": "2026-10-09T10:00:00.000Z"
    }
  ],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111",
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1,
    "totalPages": 1
  }
}

下載原文件或導出商品

接口路徑：/product-downloads

請求方式：POST

接口描述：返回一個原文件、所選原文件的 ZIP，或 XLSX/CSV/JSON 業務表格導出。需要 usable 及以上角色的當前讀取和下載權限；usable 只能訪問已發佈商品。已接受的操作在交付前記入記錄。導出鏈接默認指向需認證的單文件 GET URL；每次接受的提取有自己的業務記錄。可選 Idempotency-Key 在 24 小時內保留一條記錄，每次重試仍重新鑒權並傳輸當前內容。商品讀取、預覽和舊存儲 downloadUrl 的訪問不會由此操作記入記錄。

所需角色：usable、editable 或 manage。

請求參數：

參數名	類型	必填	描述
Idempotency-Key	String	否	選填請求標頭；同一鍵和輸入在 24 小時內重試，詳見冪等重試。
-	ProductDownloadCreate	是	JSON 請求體：application/json

ProductDownloadCreate參數說明：

assets 省略 assetKeys 時選擇全部原文件，否則僅選擇提供的當前 key。export 不接受 assetKeys，並生成本地化業務表格。format、includeAssetUrls 和 locale 僅影響導出；素材下載接受這些選項但不據此改變交付內容。導出默認包含需要 Bearer 認證的鏈接，絕不包含 API key 密鑰。locale 影響系統標籤和狀態，不改變用戶自定義標籤或內容。

不接受未定義字段。

字段名	類型	必填	描述
kind	String	是	允許值：assets、export
productIds	List<Integer>	是	最少 1 項；最多 100 項；每個 ID 為正整數，最大 2147483647。
assetKeys	List<String>	否	每個元素：最短 1 個字符；最長 256 個字符；最少 1 項；最多 200 項
format	String	否	允許值：xlsx、csv、json；默認值："xlsx"
includeAssetUrls	Boolean	否	默認值：true
locale	String	否	允許值：zh-CN、en-US、zh-TW、ja-JP、ko-KR、pt-BR、ru-RU、id-ID、fr-FR、it-IT、pl-PL、vi-VN、tr-TR、th-TH、de-DE、es-ES、hi-IN；默認值："zh-CN"

響應參數： 200。成功時回傳附件，回應本文為檔案位元組；JSON 僅用於交付前的錯誤。

響應頭：Content-Disposition、X-Download-Record-Id、X-Idempotency-Replayed

請求示例：

bash

curl --request POST \
  'https://open.musedam.cc/api/product/product-downloads' \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "kind": "export",
  "productIds": [
    40
  ],
  "format": "xlsx",
  "includeAssetUrls": true,
  "locale": "zh-CN"
}' \
  --output products.xlsx

回應範例

http

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment
X-Download-Record-Id: <record-id>

響應體為文件字節。

查詢商品下載候選素材

接口路徑：/products/{id}/download-assets

請求方式：GET

接口描述：在讀取和下載授權下返回當前候選素材的選擇 key 和 downloadable 可用性。不產生業務下載記錄，也不返回原文件或預覽 URL。使用單文件路由或 POST product-downloads 獲取文件字節。

所需角色：usable、editable 或 manage。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。

響應參數： 200，data：List<ProductDownloadCandidate>。欄位說明

請求示例：

bash

curl --request GET \
  'https://open.musedam.cc/api/product/products/40/download-assets' \
  --header 'Authorization: Bearer your_api_key'

回應範例

json

{
  "success": true,
  "data": [
    {
      "key": "p40:a2",
      "name": "example.png",
      "productId": 40,
      "productName": "Example product",
      "category": "main",
      "mimeType": "image/png",
      "size": "1024",
      "downloadable": true
    }
  ],
  "code": null,
  "message": null,
  "requestId": "11111111-1111-4111-8111-111111111111"
}

下載一個商品原文件

接口路徑：/products/{id}/download-assets/{assetKey}

請求方式：GET

接口描述：通過編碼後的候選 key 獲取當前商品的一個原文件。需要 Bearer 請求頭以及當前讀取/下載授權；URL 不含 API key 密鑰。交付前創建業務記錄。可選的 24 小時冪等機制與 POST 下載使用不同作用域，復用記錄時仍重新鑒權並傳輸當前字節。

所需角色：usable、editable 或 manage。

請求參數：

參數名	類型	必填	描述
id	Integer	是	路徑參數。正的有符號 32 位資源 ID。正整數 ID，最大 2147483647。
assetKey	String	是	路徑參數。對商品下載候選列表返回的選擇 key 進行 URL 編碼；它不是 FilePath 或 AssetObject ID。最短 1 個字符；最長 256 個字符
Idempotency-Key	String	否	選填請求標頭；同一鍵和輸入在 24 小時內重試，詳見冪等重試。

響應參數： 200。成功時回傳附件，回應本文為檔案位元組；JSON 僅用於交付前的錯誤。

響應頭：Content-Disposition、X-Download-Record-Id、X-Idempotency-Replayed

請求示例：

示例使用下載候選 key p40:a2，URL 編碼後為 p40%3Aa2。請使用您的下載候選列表返回的 key，它不是 FilePath 或 AssetObject ID。

bash

curl --request GET \
  'https://open.musedam.cc/api/product/products/40/download-assets/p40%3Aa2' \
  --header 'Authorization: Bearer your_api_key' \
  --output product-asset.bin

回應範例

http

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment
X-Download-Record-Id: <record-id>

響應體為文件字節。