Qingpu Listing Products API
This module documents the Qingpu listing product-library endpoints used by the workspace picker and product source list.
Source Media Editing
The source product editor updates canonical source facts through the source media endpoints. Images live in canonical.media.images, while videos live in canonical.extra.videos; these remain separate from uploaded workspace materials, generated images, publish ordering, and channel videos.
GET /api/qingpu/listing/products/source-detail?productId=...returnscanonical.media.images,sourceVideos, and each available source SKUimageUrl.POST /api/qingpu/listing/products/source-mediaacceptsproductId,baseRevision,images, andvideos. A product must keep 1–50 images, with the first image treated as the source main image; up to 10 videos are accepted. Revision conflicts return409withcurrentRevision.POST /api/qingpu/listing/products/source-media-uploadaccepts multipartproductIdandfile. Images support JPEG, PNG, and WebP up to 10 MB; videos support MP4, WebM, MOV, and M4V up to 50 MB. Uploading returns a stableassetId,mediaType, and hosted URL; the source media save endpoint must still be called to persist it in canonical facts.
Removing a source image also removes its original references from workspace selection, generation-reference, and publish queues. Removing a source video clears an invalid workspace referenceVideoUrl. The web editor accepts public http(s) video URLs and local video files. Local files use the authenticated Qingpu upload service, are stored in NuxtHub Blob or the deployment's local uploads directory, and are registered immediately in qingpu_assets with media_type=video and meta.source=upload.
Task Controls
- Endpoint:
/api/qingpu/listing/tasks/control - Method:
POST - Authentication: Required (User Session or Bearer tenant key). A user can only control their own tasks.
Request Body
{
"taskId": 123,
"action": "pause"
}
action accepts pause, resume, or delete. A running task settles a pause or delete request at the next safe checkpoint after its current non-cancellable remote call. Pausing preserves progress, remote task IDs, child-task ledgers, and generated assets so resume does not create a new task from scratch. Deleting hides the task record without deleting generated assets.
Success Response
{
"code": 0,
"data": {
"taskId": 123,
"status": "pause_requested"
}
}
The status can also be paused, queued, or an existing terminal status. Resume is accepted only after the task has reached paused. Invalid state transitions return 409; missing tasks and tasks owned by another user return 404.
Listing Workflow Ledger
Listing preparation uses the shared engine workflow registry as its only node and dependency definition. The web app, extension, and desktop app enqueue the same cloud Workflow Run. attributes, translate, copy, and images are independent Task Runs; copy and images require successful fact translation, while translation waits for the attribute attempt to settle.
GET /api/qingpu/listing/tasks/workflow?workflowRunId=...returns the Workflow Run and all its tasks without relying on the recent-task page limit.GET /api/qingpu/listing/tasks/attempts?taskId=...returns every immutable execution Attempt and its per-item results.
Task execution success and business readiness are separate. For example, an attribute task may succeed after filling 0/33; the UI reports that it was executed and remains incomplete instead of showing “never run”. Manual retry creates a new Attempt and preserves the previous result, error, and timestamps.
1. List Products
- Endpoint:
/api/qingpu/listing/products?page=1&limit=50&search= - Method:
GET - Authentication: Required (User Session or Bearer tenant key)
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
page | number | No | 1-based page index. Defaults to 1. |
limit | number | No | Page size. Defaults to 20, max 100. |
search | string | No | Matches product title or source product id. |
workspaceOnly | boolean | No | When true, only returns products that already have workspace rows. |
showDeleted | boolean | No | When true, also returns soft-deleted products. When used with workspaceOnly=true, the response also exposes workspaceSoftDeleted. |
Success Response
{
"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,
"softDeletedCount": 0,
"page": 1,
"limit": 50
}
}
2. Delete Products
- Endpoint:
/api/qingpu/listing/products/delete - Method:
POST - Authentication: Required (User Session or Bearer tenant key)
Request Body
{
"productIds": ["p_123", "p_456"]
}
Success Response
{
"code": 0,
"data": {
"deletedCount": 2
}
}
Notes
- This updates
qingpu_listing_products.deleted_atto the current timestamp. - The soft-delete cascades down to
workspaces,channel_drafts, andimage_assetsso the whole resource tree stays hidden by default.
3. Restore Products
- Endpoint:
/api/qingpu/listing/products/restore - Method:
POST - Authentication: Required (User Session or Bearer tenant key)
Request Body
{
"productIds": ["p_123"]
}
Success Response
{
"code": 0,
"data": {
"restoredCount": 1
}
}
Notes
- This clears
qingpu_listing_products.deleted_atback tonull. - Workspaces, channel drafts, and image assets stay on their own restore flow, so downstream content that the user intentionally removed does not get pulled back automatically.
4. Restore Workspace Row
- Endpoint:
/api/qingpu/listing/workspaces/restore - Method:
POST - Authentication: Required (User Session or Bearer tenant key)
Request Body
{
"productId": "p_123"
}
Success Response
{
"code": 0,
"data": {
"restoredCount": 1
}
}
Notes
- This clears
qingpu_listing_workspaces.deleted_atback tonull. - The workspace picker can call this before navigating into an already soft-deleted workspace.
5. Permanently Delete Products
- Endpoint:
/api/qingpu/listing/products/purge - Method:
POST - Authentication: Required (User Session or Bearer tenant key)
Request Body
{
"productIds": ["p_123"]
}
Success Response
{
"code": 0,
"data": {
"deletedCount": 1
}
}
Notes
- This only works for products that are already soft-deleted.
- The API physically removes the matching rows from
qingpu_listing_products. - It also cascades the permanent deletion to
qingpu_listing_workspaces,qingpu_listing_channel_drafts, andqingpu_listing_image_assetsfor the sameproductId.
6. Permanently Delete Workspace Row
- Endpoint:
/api/qingpu/listing/workspaces/purge - Method:
POST - Authentication: Required (User Session or Bearer tenant key)
Request Body
{
"productId": "p_123"
}
Success Response
{
"code": 0,
"data": {
"deletedCount": 1
}
}
Notes
- This only works when the workspace row is already soft-deleted.
- The API physically removes the row from
qingpu_listing_workspaces. - It does not delete the source product or channel drafts.
7. Read and Mutate Workspace SKUs
- Endpoint:
/api/qingpu/listing/skus - Methods:
GET,POST - Authentication: Required (User Session or Bearer tenant key)
GET Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
productId | string | Yes | Listing product id. |
POST Request Body
Every mutation requires the revision returned by the latest GET or POST response as baseRevision.
{
"productId": "p_123",
"baseRevision": 12,
"op": "update",
"variantId": "sku_1",
"patch": {
"priceRub": 1299,
"stock": 20,
"packageWeightG": 450
}
}
Supported operations are create, update, aspect, translation, fillDown, bulkPackaging, cardField, and remove. Empty numeric values are sent as null to clear the SKU override and use the imported or product-level fallback. Stock must be a non-negative integer; prices and package measurements must be positive numbers.
Use create to add an SKU. When sourceVariantId is present, the source SKU's procurement price, stock, packaging, selling-price overrides, and platform-aspect overrides are copied. Without it, the API creates a blank manual SKU. Neither mode copies an SKU image; the new SKU receives its own independent image slot.
{
"productId": "p_123",
"baseRevision": 12,
"op": "create",
"variantId": "manual-550e8400-e29b-41d4-a716-446655440000",
"sourceVariantId": "sku_1",
"optionValues": {
"Color": "Dark green",
"Size": "L"
},
"patch": {
"priceRub": 1299,
"oldPriceRub": 1599,
"stock": 20,
"packageWeightG": 450
},
"aspects": [
{ "attributeId": 10096, "value": "Зеленый" }
]
}
Success Response
{
"code": 0,
"data": {
"revision": 13,
"rows": [],
"dimensions": [],
"cardFields": [],
"modelNameColumn": null,
"defaultMergeModelName": "p_123",
"packagingFallback": {
"depthCm": 20,
"widthCm": 10,
"heightCm": 5,
"weightG": 450
},
"translation": {
"title": "Storage Box",
"description": "Product description",
"hashtags": "#storage"
}
}
}
Conflict Response
{
"statusCode": 409,
"message": "Product data changed",
"data": {
"currentRevision": 14
}
}
The web client serializes immediate edits and retries one 409 mutation with currentRevision. Manual SKUs are stored in listingWorkspace.manualOverrides.manualVariants, keeping canonical source facts unchanged, and specification combinations must be unique. Removing an SKU only appends its id to excludedSkuIds; canonical and manual variant records remain recoverable.
8. Read Channel Commission Rules
- Endpoint:
/api/qingpu/listing/commissions?channel=ozon - Method:
GET - Authentication: Required (User Session or Bearer tenant key)
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
channel | string | No | Channel matcher key. Currently defaults to and supports ozon. |
Success Response
{
"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"
}
]
}
]
}
]
}
}
Notes
- The channel factory first reads the
ozon-commission-treerule bundle and falls back to the bundled official tree when the remote bundle is unavailable. - The UI uses this endpoint only for manual correction. A saved commission binding keeps the selectors collapsed and does not repeatedly ask the user to choose a subcategory.
- An unsupported
channelreturns400.
9. Update Category and Auto-bind Commission
- Endpoint:
/api/qingpu/listing/products/update - Method:
POST - Authentication: Required (User Session or Bearer tenant key)
Request Body
{
"productId": "p_123",
"baseRevision": 12,
"patch": {
"generationReferenceImageIds": ["image_main", "image_side", "image_detail"],
"category": {
"categoryId": 17028922,
"typeId": 97091543,
"categoryName": "Clothing / Women's clothing / Dresses"
}
}
}
Success Response
{
"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
}
}
}
}
Matching and Persistence
generationReferenceImageIdsstores generation-only source-image slots without changing image retention or publish order. The server forces the current main image to the first position and caps the total at5; the request must include the currentbaseRevision.- When the active rule bundle provides category mappings, matching first checks exact
categoryId:typeId(then type/category id) mappings. It then uses explicit keyword mapping and category-name matching with a minimum confidence of0.8. - The complete binding snapshot is stored in
workspace.pricing.commissionBinding. Re-selecting the same Ozon category preserves either an automatic or manually corrected binding. - Changing the Ozon category clears the old binding and runs the matcher again. When no reliable result exists,
matchedisfalseand the UI exposes manual selectors. - A price-only update reselects the price band inside the saved commission category instead of asking for the category again.
- Manual corrections use the same revision-safe update flow and retry one
409with the server-providedcurrentRevision.
10. Read or Start an Image Blueprint
- Endpoint:
/api/qingpu/listing/blueprint - Methods:
GET,POST - Authentication: Required (User Session or Bearer tenant key)
GET Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
productId | string | No | When provided, the response includes the product's effective SKU image slots. |
SKU slots are derived from variants that are not listed in workspace.manualOverrides.excludedSkuIds. A dimension-value slot remains visible when at least one selected variant still uses that value.
POST Request Body
{
"productId": "p_123",
"workMode": "generate",
"mode": "full"
}
Success Response
{
"code": 0,
"data": {
"chain": ["generate", "attributes", "blueprint"],
"enqueued": true
}
}
The API freezes the database-backed main image plus up to four auxiliary references when the blueprint is enqueued. Execution, transient retries, and the sweep retry reuse that snapshot even if the user changes the workspace selection while the task waits. SKU images still use only their own variant image and ignore the product-level reference snapshot. Product main and gallery tasks are otherwise unchanged, while SKU image tasks are generated only for selected variants; excluded SKU variants never enqueue image generation.
11. Read Ozon Categories and Resources
The complete Ozon category tree is not returned by an API. The browser first reads the small manifest at /themes/qingpu/listing/ozon-categories/manifest.json, then downloads its content-hashed tree.<hash>.json asset. The manifest is revalidated periodically, while the hashed tree is cached as immutable. The compact tuple schema is private to the web client and must not be treated as a public API contract.
Search Categories
- Endpoint:
/api/qingpu/listing/categories - Method:
GET - Authentication: Required
| Name | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Space-separated terms matched against the complete category path. |
limit | number | No | Result count, default 20, hard maximum 50. |
{
"code": 0,
"data": {
"items": [
{
"categoryId": 17028922,
"typeId": 97091543,
"name": "Dresses",
"path": "Clothing > Women's clothing > Dresses"
}
]
}
}
view=tree is rejected with 400; callers must never use the dynamic API to transfer the complete tree.
Read Selected Category Resources
- Endpoint:
/api/qingpu/listing/categories/attributes - Method:
GET - Authentication: Required
| Name | Type | Required | Description |
|---|---|---|---|
categoryId | number | Yes | Ozon description category ID. |
typeId | number | Yes | Ozon leaf type ID. |
The response contains all attribute definitions for the selected category, but preloads dictionary candidates only for required or variant-axis attributes. Large optional dictionaries remain on demand.
Load One Attribute Dictionary
- Endpoint:
/api/qingpu/listing/categories/attribute-values - Method:
POST - Authentication: Required
{
"productId": "p_123",
"attributeId": 85
}
{
"code": 0,
"data": { "count": 128 }
}
The fetched candidates are merged into the workspace category snapshot. This endpoint returns only the count; the client reloads the workspace row instead of receiving a large dictionary payload directly.
12. Read Product Detail by Use Case
The former aggregate detail endpoint has been split into three authenticated GET endpoints. Callers must select the smallest read model for their use case:
| Use case | Endpoint | Response scope |
|---|---|---|
| Source product editor | /api/qingpu/listing/products/source-detail?productId=p_123 | Source title, description preview, pricing, attributes, and SKU facts |
| Workspace restore | /api/qingpu/listing/products/workspace-detail?productId=p_123 | Workspace media selection, pricing settings, generated assets, and source videos |
| Buyer preview | /api/qingpu/listing/products/channel-preview?productId=p_123&channel=ozon | A server-normalized ChannelPreviewModel ready for rendering |
The endpoints project only required JSONB paths. Raw crawl payloads, complete workspace objects, unrelated channel/store drafts, and Base64 image fields are never returned.
workspace-detail excludes the Ozon categoryAttributes / attributeDictionaryValues. The client loads attribute definitions from /api/qingpu/listing/products/workspace-category-resources?productId=p_123 only when the category parameters are opened; large dictionary candidates remain lazy per-attribute searches and are never returned with either detail endpoint.
Generated images in workspace-detail also contain only the assetId / url / slotKey / softDeleted / reuseMode / current list summary and exclude the potentially large editorScene. Assets with the same slotKey are versions of one generated slot. POST /api/qingpu/listing/images/select-version accepts { productId, slotKey, assetId } and atomically selects one active version. Regeneration always creates a new plan/asset version and selects it only after successful generation; older versions remain available. When the user opens the editor for one image, the client loads that asset's scene on demand from /api/qingpu/listing/images/editor-scene?productId=p_123&assetId=asset_123.
Image generation requests are semantic and channel-aware. POST /api/qingpu/listing/images/generate accepts { productId, slotKey?, slotGoal?, assignTo?, referenceImageId? }; referenceImageId must identify a canonical source image owned by the product. The server rebuilds the aggregate and uses the shared engine's channel task factory to freeze an immutable v1 task spec. Normal generation and regeneration reference canonical source images only, SKU generation references its own source variant image, and only refinement may place the current generated image first. Unsupported channels fail explicitly instead of inheriting Ozon rules. Blueprint submission freezes one task spec per main/gallery/SKU slot; execution, immediate retry, process recovery, and sweep retry all reuse those stored specs without rebuilding from the current workspace.
Image workers accept v1 task specs only. Before deploying this version, remove or migrate any queued/running image_generate or blueprint rows created with legacy payloads; runtime fallback is intentionally not retained before launch. Authenticated GET /api/qingpu/listing/engine-version returns the loaded vendor package name, version, source repository commit, and build timestamp so operations can verify the running process after restart.
The channel preview selects the Ozon template draft first and falls back to another Ozon store draft when necessary. It resolves original:<imageId>, workspace asset, and generated asset references into browser URLs. When no submitted draft exists, title, description, gallery, attributes, and variants fall back through workspace and canonical data on the server; clients must not interpret private asset references themselves.
13. Save Channel Draft vs. Publish
POST /api/qingpu/listing/drafts only reads the current canonical/workspace aggregate, builds the channel snapshot, performs local completeness and merge-card conflict validation, and writes qingpu_listing_channel_drafts. It must not refresh platform categories, download platform dictionaries, rewrite the workspace, or advance the product revision.
Platform interaction occurs only through POST /api/qingpu/listing/publish; the channel driver is called only when mode=live. Draft saving locks the current product version in publishSnapshot.workspaceRevision and rejects a stale snapshot if the product changes concurrently.
Conversational intake and workspace consistency
For collected products, POST /api/qingpu/launch/intake, /api/qingpu/launch/copilot, and /api/qingpu/launch/save reload source facts, selected SKUs and pricing settings from the authenticated user's workspace. Preview prices use the same pricing engine as the workspace, including each SKU's cost, weight, logistics rules and explicit price overrides. A margin-only change does not rewrite packaging or freeze derived prices as manual overrides.
Missing package dimensions remain missing. Only explicitly changed packaging values are persisted; saving or repricing must not supply sample dimensions, weights or inventory. Copy that introduces unsupported warranty promises, technical claims or excluded-SKU claims is rejected with 422 before persistence. Concurrent workspace changes return 409; generation failures and persistence failures are not reported as successful previews.