資料架構: 庫存

location_code字串必填

倉庫庫位代碼。

示例: "example"

location_id字串必填

倉庫庫位識別碼。

示例: "example"

location_name字串必填

倉庫庫位名稱。

示例: "example"

on_hand整數必填

實物庫存數量。

示例: 10

附加欄位: 否

dataCodeContentData 必填

成功回應的資料。

示例: {"code":"DEMO-ONE","delivery_id":null,"kind":"code","payload_id":"00000000-0000-4000-8000-000000000004","unit_id":"00000000-0000-4000-8000-000000000003"}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta 必填

回應元資料。

示例: {"request_id":"example-request"}

附加欄位: 否

dataDigitalUploadData 必填

成功回應的資料。

示例: {"consumer_id":"00000000-0000-4000-8000-000000000001","consumer_kind":"digital_import","expires_at":"2026-11-03T13:00:00Z","filename":"codes.txt","id":"00000000-0000-4000-8000-000000000002","product_id":"example","purpose":"digital_import","received_bytes":18,"sha256":"636e307039d9ca307836e9a93ea492425545bcccb6cb4ef935ab635560db828a","size_bytes":18,"status":"ready"}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta 必填

回應元資料。

示例: {"request_id":"example-request"}

附加欄位: 否

dataImportData 必填

成功回應的資料。

示例: {"delivery_id":null,"delivery_status":null,"delivery_version":null,"expected_count":2,"expires_at":"2026-11-03T13:00:00Z","id":"00000000-0000-4000-8000-000000000001","kind":"code","product_id":"example","status":"validated","validated_count":2,"validation_digest":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","version":2}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta 必填

回應元資料。

示例: {"request_id":"example-request"}

附加欄位: 否

data陣列 <StockData > 必填

回應示例 · ApiResponse_list_StockData__.

示例: [{"active":true,"available":5,"id":"stock_v1_WyJleGFtcGxlIiwicHJvZHVjdCIsImV4YW1wbGUiXQ","manual_reserved":2,"on_hand":10,"reserved":3,"sellable_limit":10,"target_id":"example","target_type":"product","total_reserved":5,"updated_at":"2026-01-01T12:00:00Z","version":1,"warehouse_id":"example"}]

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta 必填

回應元資料。

示例: {"pagination":{"has_more":false,"limit":20,"next_cursor":null},"request_id":"example"}

附加欄位: 否

dataPoolData 必填

成功回應的資料。

示例: {"configured":true,"counts":{"available":1,"held":0,"issued":1,"planned":0,"retired":0,"staged":0},"email_mode":"order_link","enabled":true,"order_version":2,"product_id":"example","retention_days":null,"version":1}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta 必填

回應元資料。

示例: {"request_id":"example-request"}

附加欄位: 否

dataStockDetailData 必填

回應示例 · StockDetailData.

示例: {"active":true,"allocations":[{"location_code":"example","location_id":"example","location_name":"example","on_hand":10}],"available":5,"id":"stock_v1_WyJleGFtcGxlIiwicHJvZHVjdCIsImV4YW1wbGUiXQ","manual_reserved":2,"on_hand":10,"reserved":3,"sellable_limit":10,"target_id":"example","target_type":"product","total_reserved":5,"updated_at":"2026-01-01T12:00:00Z","version":1,"warehouse_id":"example"}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta 必填

回應元資料。

示例: {"request_id":"example"}

附加欄位: 否

dataUnitsData 必填

成功回應的資料。

示例: {"order_version":2,"total":1,"units":[{"content_state":"present","delivery_id":"delivery-example","filename":null,"id":"00000000-0000-4000-8000-000000000003","issued_at":null,"kind":"code","location_id":"location-digital","mime_type":null,"payload_id":"00000000-0000-4000-8000-000000000004","product_id":"example","size_bytes":null,"sort_order":1,"state":"available","version":1,"warehouse_id":"warehouse-main"}]}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta 必填

回應元資料。

示例: {"pagination":{"has_more":false,"limit":50,"next_cursor":null},"request_id":"example-request"}

附加欄位: 否

code字串必填

數位代碼的完整內容。保留大小寫及內部空格。

minLength: 1maxLength: 512

示例: "DEMO-ONE"

delivery_id字串 | null選填

入庫或訂單分配的ID。

字串:format: "uuid"

示例: null

kind字串選填

由允許值說明的資料結構變體。

const: "code"

預設值: "code"示例: "code"

payload_id字串必填

內容ID，不是公開下載URL。

format: "uuid"

示例: "00000000-0000-4000-8000-000000000004"

unit_id字串必填

單個兌換碼或檔案的ID。

format: "uuid"

示例: "00000000-0000-4000-8000-000000000003"

附加欄位: 否

consumer_id字串必填

關聯匯入或庫存單位的ID。

format: "uuid"

示例: "00000000-0000-4000-8000-000000000001"

consumer_kind字串必填

上傳關聯類型：digital_import / digital_unit。

約束

enum

["digital_import", "digital_unit"]

示例: "digital_import"

filename字串必填

檔案

minLength: 1maxLength: 255

示例: "codes.txt"

purpose字串必填

digital_import：TXT/CSV；digital_unit：獨立出售的檔案。

約束

enum

["digital_unit", "digital_import"]

示例: "digital_import"

sha256字串必填

SHA-256 (hex, 64)

約束

pattern

"^[0-9a-f]{64}$"

示例: "636e307039d9ca307836e9a93ea492425545bcccb6cb4ef935ab635560db828a"

size_bytes整數必填

大小（位元組）

minimum: 1maximum: 262144000

示例: 18

附加欄位: 否

consumer_id字串必填

關聯匯入或庫存單位的ID。

format: "uuid"

示例: "00000000-0000-4000-8000-000000000001"

consumer_kind字串必填

上傳關聯類型：digital_import / digital_unit。

約束

enum

["digital_import", "digital_unit"]

示例: "digital_import"

expires_at字串必填

此上傳或匯入的到期時間。

format: "date-time"

示例: "2026-11-03T13:00:00Z"

filename字串必填

檔案

示例: "codes.txt"

id字串必填

資源識別碼；請保留回傳的原值。

format: "uuid"

示例: "00000000-0000-4000-8000-000000000002"

product_id字串必填

產品識別碼。

示例: "example"

purpose字串必填

digital_import：TXT/CSV；digital_unit：獨立出售的檔案。

約束

enum

["digital_unit", "digital_import"]

示例: "digital_import"

received_bytes整數必填

正在上傳… · 大小（位元組）

示例: 18

sha256字串必填

SHA-256 (hex, 64)

示例: "636e307039d9ca307836e9a93ea492425545bcccb6cb4ef935ab635560db828a"

size_bytes整數必填

大小（位元組）

示例: 18

status字串必填

此操作接受的狀態。

示例: "ready"

附加欄位: 否

delivered_at字串必填

交付日期和時間。

format: "date-time"

示例: "2026-11-03T12:00:00Z"

expected_delivery_version整數必填

入庫版本，新入庫使用0。

minimum: 0maximum: 0

示例: 0

expected_sales_limit_version整數 | null選填

銷售上限版本，publish_for_sale=true時必填。

整數:minimum: 0maximum: 9223372036854775807

示例: 0

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 1maximum: 9223372036854775807

示例: 2

location_id字串必填

倉庫庫位識別碼。

約束

pattern

"^[a-z0-9][a-z0-9_-]{0,62}$"

示例: "location-digital"

publish_for_sale布林值選填

true也會增加有限銷售上限，false維持不變。

預設值: false示例: true

status字串必填

此操作接受的狀態。

約束

enum

["planned", "received"]

示例: "received"

validation_digest字串必填

驗證檢查碼，確認時原樣提交。

約束

pattern

"^[0-9a-f]{64}$"

示例: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"

warehouse_id字串必填

倉庫識別碼。

約束

pattern

"^[a-z0-9][a-z0-9_-]{0,62}$"

示例: "warehouse-main"

附加欄位: 否

count整數必填

此批次的確切單位數量。

minimum: 1maximum: 1000

示例: 2

kind字串必填

由允許值說明的資料結構變體。

約束

enum

["code", "file"]

示例: "code"

附加欄位: 否

delivery_id字串 | null必填

入庫或訂單分配的ID。

示例: null

delivery_status字串 | null必填

入庫狀態：planned / received；確認前為null。

示例: null

delivery_version整數 | null必填

倉庫入庫記錄的目前版本。

示例: null

expected_count整數必填

預期數量，必須整批通過驗證。

示例: 2

expires_at字串必填

此上傳或匯入的到期時間。

format: "date-time"

示例: "2026-11-03T13:00:00Z"

id字串必填

資源識別碼；請保留回傳的原值。

format: "uuid"

示例: "00000000-0000-4000-8000-000000000001"

kind字串必填

由允許值說明的資料結構變體。

約束

enum

["code", "file"]

示例: "code"

product_id字串必填

產品識別碼。

示例: "example"

status字串必填

此操作接受的狀態。

示例: "validated"

validated_count整數必填

最近一次成功驗證所接受的單位數量。

示例: 2

validation_digest字串 | null必填

驗證檢查碼，確認時原樣提交。

示例: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"

version整數必填

用於並行控制的資源版本。

示例: 2

附加欄位: 否

expected_delivery_version整數必填

入庫版本，新入庫使用0。

minimum: 1maximum: 9223372036854775807

示例: 1

expected_sales_limit_version整數 | null選填

銷售上限版本，publish_for_sale=true時必填。

整數:minimum: 0maximum: 9223372036854775807

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 1maximum: 9223372036854775807

示例: 3

publish_for_sale布林值選填

true也會增加有限銷售上限，false維持不變。

預設值: false

附加欄位: 否

code_column字串 | null選填

兌換碼所在CSV欄位，使用code。

字串:const: "code"

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 1maximum: 9223372036854775807

示例: 1

format字串 | null選填

兌換碼清單格式：txt / csv；檔案使用upload_ids。

約束 · 字串 1

enum

["txt", "csv"]

示例: "txt"

source_upload_id字串 | null選填

此匯入所屬的已就緒私人TXT/CSV上傳。

字串:format: "uuid"

示例: "00000000-0000-4000-8000-000000000002"

upload_ids陣列 <字串> | null選填

此匯入所屬的1–100個已就緒私人檔案上傳。

陣列:minItems: 1maxItems: 100

陣列 / 陣列:format: "uuid"

附加欄位: 否

expected_delivery_version整數必填

入庫版本，新入庫使用0。

minimum: 1maximum: 9223372036854775807

示例: 1

expected_order_version整數必填

分配順序的版本，不是客戶訂單的版本。

minimum: 0maximum: 9223372036854775807

示例: 1

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 1maximum: 9223372036854775807

示例: 3

reason字串必填

記錄的變更原因。

minLength: 1maxLength: 500

示例: "Withdraw a revoked license"

附加欄位: 否

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 1maximum: 9223372036854775807

示例: 1

manual_reserved整數必填

手動預留數量。

minimum: 0maximum: 2147483647

示例: 1

reason字串選填

記錄的變更原因。

maxLength: 500

預設值: ""

附加欄位: 否

email_mode字串選填

disabled：不寄郵件；order_link：訂單連結；code_text：也可包含兌換碼。

約束

enum

["disabled", "order_link", "code_text"]

預設值: "disabled"示例: "order_link"

enabled布林值必填

此設定是否啓用。

示例: true

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 0maximum: 9223372036854775807

示例: 0

retention_days整數 | null選填

null為無期限；1–3650為首次存取後的天數。兌換碼不會自動刪除。

整數:minimum: 1maximum: 3650

示例: null

附加欄位: 否

available整數必填

尚未預留或交付的可用單位數量。

示例: 1

held整數必填

已為訂單預留但尚未交付的單位。

示例: 0

issued整數必填

已交付給付款購買的單位。

示例: 1

planned整數必填

已確認但尚未接收的入庫單位。

示例: 0

retired整數必填

撤回後仍保留在歷程記錄中的單位。

示例: 0

staged整數必填

未完成匯入中的單位，尚非可售庫存。

示例: 0

附加欄位: 否

configured布林值必填

是否已儲存數位庫存設定。

示例: true

countsPoolCounts 必填

按庫存狀態統計的單位數量。

示例: {"available":1,"held":0,"issued":1,"planned":0,"retired":0,"staged":0}

email_mode字串必填

disabled：不寄郵件；order_link：訂單連結；code_text：也可包含兌換碼。

約束

enum

["disabled", "order_link", "code_text"]

示例: "order_link"

enabled布林值必填

此設定是否啓用。

示例: true

order_version整數必填

庫存分配順序的版本。

示例: 2

product_id字串必填

產品識別碼。

示例: "example"

retention_days整數 | null必填

null為無期限；1–3650為首次存取後的天數。兌換碼不會自動刪除。

示例: null

version整數必填

用於並行控制的資源版本。

示例: 1

附加欄位: 否

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 1maximum: 9223372036854775807

示例: 1

reason字串選填

記錄的變更原因。

maxLength: 500

預設值: ""

sellable_limit整數必填

銷售上限：-1 表示不限，0 表示不可銷售。

minimum: -1maximum: 2147483647

示例: 1

附加欄位: 否

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 0maximum: 9223372036854775807

示例: 0

locations陣列 <LocationQuantity > 必填

倉庫庫位。

minItems: 1maxItems: 100

示例: [{"location_id":"example","on_hand":1}]

reason字串必填

記錄的變更原因。

minLength: 1maxLength: 500

示例: "Example"

target_id字串必填

操作影響的產品或變體識別碼。

約束

pattern

"^[a-z0-9][a-z0-9_-]{0,62}$"

示例: "example"

target_type字串必填

操作針對產品還是變體。

約束

enum

["product", "variant"]

示例: "product"

warehouse_id字串必填

倉庫識別碼。

約束

pattern

"^[a-z0-9][a-z0-9_-]{0,62}$"

示例: "example"

附加欄位: 否

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 1maximum: 9223372036854775807

示例: 1

locations陣列 <LocationQuantity > 必填

倉庫庫位。

minItems: 1maxItems: 100

示例: [{"location_id":"example","on_hand":1}]

reason字串必填

記錄的變更原因。

minLength: 1maxLength: 500

示例: "Example"

附加欄位: 否

active布林值必填

資源是否處於活動狀態。

示例: true

available整數 | null必填

可售數量；null 表示數量不限。

示例: 5

id字串必填

資源識別碼；請保留回傳的原值。 (StockData).

示例: "stock_v1_WyJleGFtcGxlIiwicHJvZHVjdCIsImV4YW1wbGUiXQ"

manual_reserved整數必填

手動預留數量。

示例: 2

on_hand整數必填

實物庫存數量。

示例: 10

reserved整數必填

訂單預留數量。

示例: 3

sellable_limit整數必填

銷售上限：-1 表示不限，0 表示不可銷售。

示例: 10

target_id字串必填

操作影響的產品或變體識別碼。

示例: "example"

target_type字串必填

操作針對產品還是變體。

約束

enum

["product", "variant"]

示例: "product"

total_reserved整數必填

總預留數量。

示例: 5

updated_at字串必填

最近更新時間。

format: "date-time"

示例: "2026-01-01T12:00:00Z"

version整數必填

用於並行控制的資源版本。

示例: 1

warehouse_id字串必填

倉庫識別碼。

示例: "example"

附加欄位: 否

active布林值必填

資源是否處於活動狀態。

示例: true

allocations陣列 <AllocationData > 必填

分配給倉庫庫位的數量。

示例: [{"location_code":"example","location_id":"example","location_name":"example","on_hand":10}]

available整數 | null必填

可售數量；null 表示數量不限。

示例: 5

id字串必填

資源識別碼；請保留回傳的原值。 (StockDetailData).

示例: "stock_v1_WyJleGFtcGxlIiwicHJvZHVjdCIsImV4YW1wbGUiXQ"

manual_reserved整數必填

手動預留數量。

示例: 2

on_hand整數必填

實物庫存數量。

示例: 10

reserved整數必填

訂單預留數量。

示例: 3

sellable_limit整數必填

銷售上限：-1 表示不限，0 表示不可銷售。

示例: 10

target_id字串必填

操作影響的產品或變體識別碼。

示例: "example"

target_type字串必填

操作針對產品還是變體。

約束

enum

["product", "variant"]

示例: "product"

total_reserved整數必填

總預留數量。

示例: 5

updated_at字串必填

最近更新時間。

format: "date-time"

示例: "2026-01-01T12:00:00Z"

version整數必填

用於並行控制的資源版本。

示例: 1

warehouse_id字串必填

倉庫識別碼。

示例: "example"

附加欄位: 否

content_state字串必填

內容狀態：present / deleting / deleted。

示例: "present"

delivery_id字串 | null必填

入庫或訂單分配的ID。

示例: "delivery-example"

filename字串 | null必填

檔案

示例: null

id字串必填

資源識別碼；請保留回傳的原值。

format: "uuid"

示例: "00000000-0000-4000-8000-000000000003"

issued_at字串 | null必填

首次交付時間，此前為null。

字串:format: "date-time"

示例: null

kind字串必填

由允許值說明的資料結構變體。

約束

enum

["file", "code"]

示例: "code"

location_id字串 | null必填

倉庫庫位識別碼。

示例: "location-digital"

mime_type字串 | null必填

媒體內容類型。

示例: null

payload_id字串必填

內容ID，不是公開下載URL。

format: "uuid"

示例: "00000000-0000-4000-8000-000000000004"

product_id字串必填

產品識別碼。

示例: "example"

size_bytes整數 | null必填

大小（位元組）

示例: null

sort_order整數必填

在有序集合中的位置。

示例: 1

state字串必填

狀態

示例: "available"

version整數必填

用於並行控制的資源版本。

示例: 1

warehouse_id字串 | null必填

倉庫識別碼。

示例: "warehouse-main"

附加欄位: 否

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 1

示例: 1

reason字串必填

記錄的變更原因。

minLength: 1maxLength: 500

示例: "Withdraw a revoked license"

附加欄位: 否

expected_order_version整數必填

分配順序的版本，不是客戶訂單的版本。

minimum: 1

示例: 1

unit_ids陣列 <字串> 必填

未篩選頁面上的全部單位，依所需順序排列。

minItems: 2maxItems: 100

陣列:format: "uuid"

示例: ["00000000-0000-4000-8000-000000000008","00000000-0000-4000-8000-000000000003"]

window_cursor字串 | null選填

未篩選頁面的游標，首頁為null。

字串:maxLength: 1024

附加欄位: 否

code字串 | null選填

數位代碼的完整內容。保留大小寫及內部空格。

字串:minLength: 1maxLength: 512

示例: "SYNTHETIC-REPLACEMENT"

expected_version整數必填

寫入前讀取的版本；不匹配時拒絕更新。

minimum: 1

示例: 1

reason字串必填

記錄的變更原因。

minLength: 1maxLength: 500

示例: "Replace an invalid activation code"

upload_id字串 | null選填

資源識別碼；請保留回傳的原值。 · upload_id

字串:format: "uuid"

附加欄位: 否

order_version整數必填

庫存分配順序的版本。

示例: 2

total整數必填

總金額。

示例: 1

units陣列 <UnitData > 必填

單位中繼資料；讀取內容需另行傳送授權請求。

示例: [{"content_state":"present","delivery_id":"delivery-example","filename":null,"id":"00000000-0000-4000-8000-000000000003","issued_at":null,"kind":"code","location_id":"location-digital","mime_type":null,"payload_id":"00000000-0000-4000-8000-000000000004","product_id":"example","size_bytes":null,"sort_order":1,"state":"available","version":1,"warehouse_id":"warehouse-main"}]

附加欄位: 是