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=... returns canonical.media.images, sourceVideos, and each available source SKU imageUrl.
  • POST /api/qingpu/listing/products/source-media accepts productId, baseRevision, images, and videos. 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 return 409 with currentRevision.
  • POST /api/qingpu/listing/products/source-media-upload accepts multipart productId and file. Images support JPEG, PNG, and WebP up to 10 MB; videos support MP4, WebM, MOV, and M4V up to 50 MB. Uploading returns a stable assetId, 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

NameTypeRequiredDescription
pagenumberNo1-based page index. Defaults to 1.
limitnumberNoPage size. Defaults to 20, max 100.
searchstringNoMatches product title or source product id.
workspaceOnlybooleanNoWhen true, only returns products that already have workspace rows.
showDeletedbooleanNoWhen 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_at to the current timestamp.
  • The soft-delete cascades down to workspaces, channel_drafts, and image_assets so 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_at back to null.
  • 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_at back to null.
  • 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, and qingpu_listing_image_assets for the same productId.

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

NameTypeRequiredDescription
productIdstringYesListing 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

NameTypeRequiredDescription
channelstringNoChannel 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-tree rule 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 channel returns 400.

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

  • generationReferenceImageIds stores 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 at 5; the request must include the current baseRevision.
  • 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 of 0.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, matched is false and 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 409 with the server-provided currentRevision.

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

NameTypeRequiredDescription
productIdstringNoWhen 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
NameTypeRequiredDescription
qstringYesSpace-separated terms matched against the complete category path.
limitnumberNoResult 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
NameTypeRequiredDescription
categoryIdnumberYesOzon description category ID.
typeIdnumberYesOzon 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 caseEndpointResponse scope
Source product editor/api/qingpu/listing/products/source-detail?productId=p_123Source title, description preview, pricing, attributes, and SKU facts
Workspace restore/api/qingpu/listing/products/workspace-detail?productId=p_123Workspace media selection, pricing settings, generated assets, and source videos
Buyer preview/api/qingpu/listing/products/channel-preview?productId=p_123&channel=ozonA 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.