Qingpu 商品库与工作区 API
本文档说明 Qingpu 铺货工作台中商品库与工作区选择器使用的接口。
货源媒体编辑
货源商品编辑抽屉通过来源媒体接口修改 canonical 事实层中的图片与视频。图片保存在 canonical.media.images,视频保存在 canonical.extra.videos;它们与工作区上传素材、生成图、发布排序和渠道视频保持分层。
GET /api/qingpu/listing/products/source-detail?productId=...返回canonical.media.images、sourceVideos,并在来源 SKU 中返回可用的imageUrl。POST /api/qingpu/listing/products/source-media接收productId、baseRevision、images和videos。图片必须保留至少 1 张、最多 50 张,数组首项作为来源主图;视频最多 10 条。请求使用 revision 乐观锁,冲突返回409与currentRevision。POST /api/qingpu/listing/products/source-media-upload使用 multipart 的productId与file上传来源媒体。图片支持 JPEG、PNG、WebP,单文件不超过 10MB;视频支持 MP4、WebM、MOV、M4V,单文件不超过 50MB。上传成功返回稳定assetId、mediaType和托管 URL,最终仍需调用来源媒体保存接口写入 canonical。
删除来源图片时,服务端同步移除工作区 selectedImageAssetIds / generationReferenceImageIds / publishedImageAssetIds 中对应的原图引用;删除来源视频时会清理失效的 referenceVideoUrl。网页端既支持公网 http(s) 视频 URL,也支持本地视频文件。本地文件通过已鉴权的 Qingpu 统一上传服务写入 NuxtHub Blob 或部署环境的本地 uploads 目录,并立即以 media_type=video、meta.source=upload 登记到 qingpu_assets。
任务控制
- 请求地址:
/api/qingpu/listing/tasks/control - 请求方法:
POST - 权限要求: 已登录用户或 Bearer 租户 Key;只能操作当前用户自己的任务。
请求体
{
"taskId": 123,
"action": "pause"
}
action 支持 pause、resume、delete。运行中任务收到暂停或删除请求后,会在当前不可取消的远程调用完成后的安全检查点停止;暂停保留原任务进度、远程任务 ID、子任务账本和已生成资产,继续时不会从头创建新任务。删除只隐藏任务记录,不删除已经生成的资产。
成功响应
{
"code": 0,
"data": {
"taskId": 123,
"status": "pause_requested"
}
}
状态还可能是 paused、queued 或原终态。只有真正进入 paused 后才能继续;重复操作或对终态任务执行暂停会返回 409,不存在或不属于当前用户的任务返回 404。
Listing 工作流账本
Listing 内容准备只以共享引擎 Workflow Registry 作为节点和依赖事实源。网页、扩展与桌面端统一提交云端 Workflow Run;attributes、translate、copy、images 是可单独执行和重试的 Task Run。上架文案与生图只依赖事实翻译成功,事实翻译只等待补参执行结束。
GET /api/qingpu/listing/tasks/workflow?workflowRunId=...:直接返回 Workflow Run 及其全部 Task,不受最近任务分页上限影响。GET /api/qingpu/listing/tasks/attempts?taskId=...:返回该 Task 每一次不可覆盖的执行 Attempt 和逐项结果。
任务执行成功与业务就绪度分离。例如补参执行成功但补充 0/33 时,页面显示“已执行但仍不完整”,不会重新显示为“从未执行”。人工重试会新增 Attempt,旧结果、错误和起止时间均保留。
1. 获取商品列表
- 请求地址:
/api/qingpu/listing/products?page=1&limit=50&search= - 请求方法:
GET - 权限要求: 已登录用户或 Bearer 租户 Key
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page | number | 否 | 页码,从 1 开始,默认 1。 |
limit | number | 否 | 每页条数,默认 20,最大 100。 |
search | string | 否 | 按商品标题或来源商品 ID 搜索。 |
workspaceOnly | boolean | 否 | 传 true 时,只返回已经存在工作区行的商品。 |
showDeleted | boolean | 否 | 传 true 时,会把已软删商品一并返回;若同时传 workspaceOnly=true,还会带出 workspaceSoftDeleted。 |
成功响应
{
"code": 0,
"data": {
"items": [
{
"productId": "p_123",
"sourcePlatform": "1688",
"sourceUrl": "https://detail.1688.com/offer/123.html",
"sourceProductId": "123",
"title": "Storage Box",
"mainImageUrl": "https://example.com/image.png",
"skuCount": 3,
"categoryId": 1001,
"categoryTypeId": 2001,
"categoryName": "Home / Storage",
"preprocessStatus": "generated",
"revision": 12,
"updatedAt": "2026-07-20T12:00:00.000Z",
"softDeleted": false,
"workspaceSoftDeleted": false
}
],
"total": 1,
"page": 1,
"limit": 50
}
}
2. 删除商品
- 请求地址:
/api/qingpu/listing/products/delete - 请求方法:
POST - 权限要求: 已登录用户或 Bearer 租户 Key
请求体
{
"productIds": ["p_123", "p_456"]
}
成功响应
{
"code": 0,
"data": {
"deletedCount": 2
}
}
说明
- 该接口会把
qingpu_listing_products.deleted_at更新为当前时间。 - 同时会向下传播到
workspaces / channel_drafts / image_assets,统一进入软删态。
3. 恢复商品
- 请求地址:
/api/qingpu/listing/products/restore - 请求方法:
POST - 权限要求: 已登录用户或 Bearer 租户 Key
请求体
{
"productIds": ["p_123"]
}
成功响应
{
"code": 0,
"data": {
"restoredCount": 1
}
}
说明
- 该接口会把
qingpu_listing_products.deleted_at清回null。 - 工作区、渠道草稿和图片资产仍按各自层级单独恢复,避免误把用户已经删除的下游内容全部自动拉回。
4. 恢复工作区行
- 请求地址:
/api/qingpu/listing/workspaces/restore - 请求方法:
POST - 权限要求: 已登录用户或 Bearer 租户 Key
请求体
{
"productId": "p_123"
}
成功响应
{
"code": 0,
"data": {
"restoredCount": 1
}
}
说明
- 该接口会把
qingpu_listing_workspaces.deleted_at清回null。 - 工作区选择器在进入一个已软删的工作区商品前,可以先调用该接口完成恢复。
5. 永久删除商品
- 请求地址:
/api/qingpu/listing/products/purge - 请求方法:
POST - 权限要求: 已登录用户或 Bearer 租户 Key
请求体
{
"productIds": ["p_123"]
}
成功响应
{
"code": 0,
"data": {
"deletedCount": 1
}
}
说明
- 该接口只对已经处于软删态的商品生效。
- 服务端会物理删除
qingpu_listing_products中对应的商品行。 - 同时会级联永久删除同一
productId下的qingpu_listing_workspaces / qingpu_listing_channel_drafts / qingpu_listing_image_assets。
6. 永久删除工作区行
- 请求地址:
/api/qingpu/listing/workspaces/purge - 请求方法:
POST - 权限要求: 已登录用户或 Bearer 租户 Key
请求体
{
"productId": "p_123"
}
成功响应
{
"code": 0,
"data": {
"deletedCount": 1
}
}
说明
- 该接口只对已经处于软删态的工作区行生效。
- 服务端会物理删除
qingpu_listing_workspaces中对应的工作区行。 - 不会连带删除货源商品和渠道草稿。
7. 读取与修改工作区 SKU
- 请求地址:
/api/qingpu/listing/skus - 请求方法:
GET、POST - 权限要求: 已登录用户或 Bearer 租户 Key
GET 查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
productId | string | 是 | 铺货商品 ID。 |
POST 请求体
每次修改都必须把最近一次 GET 或 POST 响应中的 revision 作为 baseRevision 提交。
{
"productId": "p_123",
"baseRevision": 12,
"op": "update",
"variantId": "sku_1",
"patch": {
"priceRub": 1299,
"stock": 20,
"packageWeightG": 450
}
}
支持 create、update、aspect、translation、fillDown、bulkPackaging、cardField、remove。数值字段传 null 表示清除 SKU 覆盖,回落到采集值或商品级兜底值。库存必须是大于等于 0 的整数;价格和包装尺寸重量必须是正数。
新增 SKU 使用 create。传入 sourceVariantId 时复制来源 SKU 的采购价、库存、包装、售价覆盖和平台规格覆盖;不传时创建空白手工 SKU。两种模式都不会复制 SKU 图片,图片使用新 SKU 自己的独立槽位。
{
"productId": "p_123",
"baseRevision": 12,
"op": "create",
"variantId": "manual-550e8400-e29b-41d4-a716-446655440000",
"sourceVariantId": "sku_1",
"optionValues": {
"颜色": "墨绿色",
"尺码": "L"
},
"patch": {
"priceRub": 1299,
"oldPriceRub": 1599,
"stock": 20,
"packageWeightG": 450
},
"aspects": [
{ "attributeId": 10096, "value": "Зеленый" }
]
}
成功响应
{
"code": 0,
"data": {
"revision": 13,
"rows": [],
"dimensions": [],
"cardFields": [],
"modelNameColumn": null,
"defaultMergeModelName": "p_123",
"packagingFallback": {
"depthCm": 20,
"widthCm": 10,
"heightCm": 5,
"weightG": 450
},
"translation": {
"title": "收纳盒",
"description": "商品简介",
"hashtags": "#收纳"
}
}
}
Revision 冲突响应
{
"statusCode": 409,
"message": "商品数据已更新",
"data": {
"currentRevision": 14
}
}
网页端对即时编辑串行保存,遇到一次 409 时使用 currentRevision 重放当前操作。手工新增 SKU 保存在 listingWorkspace.manualOverrides.manualVariants,不会污染 canonical 来源事实;规格组合必须唯一。删除 SKU 只把 ID 追加到 excludedSkuIds,不会删除 canonical 货源变体或手工 SKU 记录,因此仍可恢复。
8. 获取渠道佣金规则
- 请求地址:
/api/qingpu/listing/commissions?channel=ozon - 请求方法:
GET - 权限要求: 已登录用户或 Bearer 租户 Key
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
channel | string | 否 | 渠道匹配器 Key,当前默认且支持 ozon。 |
成功响应
{
"code": 0,
"data": {
"version": "Tarifs_CN_01_12_2025_1761720496",
"source": "Tarifs_CN_01_12_2025_1761720496.xlsx / MP Tree Tarifs CN / RFBS",
"tree": [
{
"value": "block-03-beauty",
"label": "美容 / Beauty",
"children": [
{
"value": "cat-029-clothing-and-accessories",
"label": "服装和配饰 / Clothing & Accessories",
"children": [
{
"value": "cat-029-clothing-and-accessories-rfbs-0-1500",
"label": "RFBS 0 - 1500 RUB (12%)",
"rate": 12,
"mode": "RFBS",
"band": "0 - 1500 RUB"
}
]
}
]
}
]
}
}
说明
- 渠道工厂优先读取
ozon-commission-tree远程规则包;远程不可用时回退到代码内置的官方佣金树。 - 该接口主要供自动匹配失败后的手动纠正使用。已经保存佣金绑定时,页面默认收起选择器,不会反复要求用户选择子类。
- 不支持的
channel返回400。
9. 更新类目并自动绑定佣金
- 请求地址:
/api/qingpu/listing/products/update - 请求方法:
POST - 权限要求: 已登录用户或 Bearer 租户 Key
请求体
{
"productId": "p_123",
"baseRevision": 12,
"patch": {
"generationReferenceImageIds": ["image_main", "image_side", "image_detail"],
"category": {
"categoryId": 17028922,
"typeId": 97091543,
"categoryName": "服装 / 女装 / 连衣裙"
}
}
}
成功响应
{
"code": 0,
"data": {
"revision": 13,
"commission": {
"matched": true,
"preserved": false,
"source": "explicit-mapping",
"binding": {
"categoryPath": ["block-03-beauty", "cat-029-clothing-and-accessories"],
"categoryLabels": ["美容 / Beauty", "服装和配饰 / Clothing & Accessories"],
"tierLabel": "RFBS 0 - 1500 RUB (12%)",
"rate": 0.12
}
}
}
}
匹配与持久化语义
generationReferenceImageIds独立保存生图参考原图槽位,不改变图片保留集合和发布排序。服务端强制当前主图置首并把总数限制为5;提交时必须携带当前baseRevision。- 当前规则包提供类目映射时,优先检查精确
categoryId:typeId(再回退 type/category id)映射;随后使用显式关键词映射和置信度不低于0.8的类目名称匹配。 - 完整绑定快照保存在
workspace.pricing.commissionBinding。再次选择相同 Ozon 类目时,自动绑定和用户手工纠正过的绑定都会直接复用。 - 切换 Ozon 类目时会清除旧绑定并重新匹配;无法可靠匹配时返回
matched: false,页面才展开手动选择器。 - 只修改售价时,仅在已绑定佣金子类中重新选择价格档位,不会再次要求用户选类目。
- 手工纠正同样采用 revision-safe 串行保存,遇到
409时只使用服务端currentRevision自动重试一次。
10. 获取或启动图集蓝图
- 请求地址:
/api/qingpu/listing/blueprint - 请求方法:
GET、POST - 权限要求: 已登录用户或 Bearer 租户 Key
GET 查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
productId | string | 否 | 传入后,响应会附带该商品当前有效的 SKU 图片槽位。 |
SKU 槽位只根据未出现在 workspace.manualOverrides.excludedSkuIds 中的变体生成。同一个规格值只要仍被至少一个已选 SKU 使用,对应规格值图片槽位就会保留。
POST 请求体
{
"productId": "p_123",
"workMode": "generate",
"mode": "full"
}
成功响应
{
"code": 0,
"data": {
"chain": ["generate", "attributes", "blueprint"],
"enqueued": true
}
}
蓝图入队时从数据库工作区冻结当前主图和最多四张辅助参考图。任务开始、瞬时重试与批后补漏都使用同一快照,不会因排队期间用户改选参考图而漂移。SKU 图片仍只使用该 SKU 自身的规格图,不消费商品级参考图快照。商品主图和场景轮播任务保持不变;SKU 图片任务只为当前已选变体生成,被排除的 SKU 不会再进入生图队列。
11. 获取 Ozon 类目与类目资源
Ozon 完整类目树不再通过 API 返回。浏览器先读取小型 manifest /themes/qingpu/listing/ozon-categories/manifest.json,再下载其中带内容哈希的 tree.<hash>.json 静态资产。manifest 定期重新校验,哈希树文件按 immutable 永久缓存。紧凑元组结构只供网页客户端内部使用,不作为公开 API 协议。
搜索类目
- 请求地址:
/api/qingpu/listing/categories - 请求方法:
GET - 权限要求: 已登录用户
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
q | string | 是 | 按空格拆词,在完整类目路径中进行 AND 匹配。 |
limit | number | 否 | 默认返回 20 条,硬上限 50 条。 |
{
"code": 0,
"data": {
"items": [
{
"categoryId": 17028922,
"typeId": 97091543,
"name": "连衣裙",
"path": "服装 > 女装 > 连衣裙"
}
]
}
}
传入 view=tree 会返回 400;任何调用方都不得再通过动态 API 传输完整类目树。
获取已选类目的属性资源
- 请求地址:
/api/qingpu/listing/categories/attributes - 请求方法:
GET - 权限要求: 已登录用户
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
categoryId | number | 是 | Ozon description category ID。 |
typeId | number | 是 | Ozon 叶子 type ID。 |
响应返回已选类目的完整属性定义,但只预取必填属性和规格轴属性的字典候选。体积较大的选填字典继续按需获取。
补拉单个属性字典
- 请求地址:
/api/qingpu/listing/categories/attribute-values - 请求方法:
POST - 权限要求: 已登录用户
{
"productId": "p_123",
"attributeId": 85
}
{
"code": 0,
"data": { "count": 128 }
}
候选值会合并写入工作区类目快照。该接口只返回数量,前端重新读取工作区行,不直接接收大字典响应。
12. 按使用场景读取商品详情
原聚合详情接口拆为三个需要鉴权的 GET 接口。调用方必须按场景选择最小读模型:
| 使用场景 | 接口 | 返回范围 |
|---|---|---|
| 货源商品编辑 | /api/qingpu/listing/products/source-detail?productId=p_123 | 货源标题、描述预览、价格、属性与 SKU 事实 |
| 工作台恢复 | /api/qingpu/listing/products/workspace-detail?productId=p_123 | 素材选择、定价设置、生成资产与货源视频 |
| 买家侧预览 | /api/qingpu/listing/products/channel-preview?productId=p_123&channel=ozon | 可直接渲染的服务端归一化 ChannelPreviewModel |
三个接口都只投影必要的 JSONB 路径,不返回原始抓取协议、完整 workspace、无关渠道/店铺草稿或 Base64 图片字段。
workspace-detail 不携带 Ozon categoryAttributes / attributeDictionaryValues。用户打开类目参数时,前端才通过 /api/qingpu/listing/products/workspace-category-resources?productId=p_123 读取属性定义;大字典候选继续通过单属性接口按需搜索,不随详情或类目资源接口全量返回。
其中的生成图片也只返回 assetId / url / slotKey / softDeleted / reuseMode / current 列表摘要,不携带可能很大的 editorScene。相同 slotKey 的资产属于同一卡位的历史版本;POST /api/qingpu/listing/images/select-version 接收 { productId, slotKey, assetId },原子切换一个未删除版本为当前图。重新生成每次创建新计划和新资产,只有成功后才自动选中新版,旧版继续保留。用户打开单张图片编辑器时,再通过 /api/qingpu/listing/images/editor-scene?productId=p_123&assetId=asset_123 按需读取该资产的编辑场景。
图片生成请求只表达渠道无关语义。POST /api/qingpu/listing/images/generate 接收 { productId, slotKey?, slotGoal?, assignTo?, referenceImageId? };referenceImageId 必须是当前商品自有的 canonical 来源图。服务端重建商品聚合后,统一调用共享引擎的渠道图片任务工厂,冻结不可变 v1 任务规格。普通生成与重新生成只引用 canonical 原图,SKU 生图只引用该规格自己的来源图,只有精修允许把当前生成图置于参考图首位。未注册渠道会明确失败,不会偷偷套用 Ozon 规则。一键蓝图提交时会为主图、每个轮播槽和每个 SKU 槽分别冻结 taskSpec;执行、即时重试、进程恢复与批后补漏都复用落库规格,不按当前 workspace 重新构造。
图片 worker 只接受 v1 taskSpec。该版本上线前必须清理或迁移旧 payload 创建且仍处于 queued/running 的 image_generate、blueprint 任务;由于尚未上线,运行时明确不保留旧结构兼容。登录后访问 GET /api/qingpu/listing/engine-version 可读取运行实例实际加载的 vendor 包名、版本、源码提交和构建时间,重启后可据此核验实例版本。
渠道预览优先读取 Ozon 模板草稿,必要时回退其他 Ozon 店铺草稿,并在服务端把 original:<imageId>、workspace 资产和生成资产引用解析为浏览器 URL。没有已提交草稿时,标题、描述、图集、属性与 SKU 统一在服务端按 workspace/canonical 回退;客户端不得自行猜测私有资产引用。
13. 保存渠道草稿与正式发布
POST /api/qingpu/listing/drafts 只读取当前 canonical/workspace 聚合,生成渠道快照、执行本地完整性与合卡冲突校验,并写入 qingpu_listing_channel_drafts。该接口不得刷新平台类目、下载平台字典、回写 workspace 或推进商品 revision。
真正的平台交互只发生在 POST /api/qingpu/listing/publish;只有 mode=live 才调用渠道发布驱动。草稿保存通过 publishSnapshot.workspaceRevision 锁定当前商品版本,若保存期间商品被并发修改则立即拒绝旧快照。
对话式上品与工作区一致性
对已采集商品,POST /api/qingpu/launch/intake、/api/qingpu/launch/copilot 与 /api/qingpu/launch/save 从当前登录用户的工作区重新读取来源事实、在售 SKU 和核价设置。预览与加工箱复用同一定价引擎,逐 SKU 采用采购价、重量、物流规则和显式售价覆盖;只改毛利率不回写包装,也不把派生建议价冻结成手工售价。
缺失的包装尺寸保持缺失,仅持久化本轮明确改变的包装值;保存和核价不得补入示例尺寸、重量或库存。新增无依据保修、技术参数或已排除 SKU 的文案声明,在写入前返回 422;工作区并发修改返回 409,生成或保存失败不得伪报预览成功。