数据架构: 库存

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"}]

附加字段: 是