Qingpu Listing Channels API

This module documents the Qingpu listing workbench channel-draft library endpoints. The library reads from qingpu_listing_channel_drafts and only returns active rows where deleted_at is null.

Setup

  1. Configure QINGPU_DATABASE_URL or reuse DATABASE_URL.
  2. Execute the SQL file at app/themes/qingpu/database/listing.sql.
  3. Call the listing endpoints under /api/qingpu/listing/channels*.

Storage Rules

  • Channel draft rows live in qingpu_listing_channel_drafts.
  • deleted_at is the authoritative soft-delete flag for draft rows.
  • Rebuilding or resubmitting a draft clears deleted_at back to null.
  • The channels page only shows the default Ozon template row: channel='ozon' and store_key=''.

1. List Channel Drafts

  • Endpoint: /api/qingpu/listing/channels?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 50, max 100.
searchstringNoMatches product title or source product id.
showDeletedbooleanNoWhen true, include soft-deleted drafts in the list.

Success Response

{
  "code": 0,
  "data": {
    "items": [
      {
        "productId": "p_123",
        "title": "Storage Box",
        "mainImageUrl": "https://example.com/image.png",
        "skuCount": 3,
        "categoryName": "Home Storage",
        "preprocessStatus": "generated",
        "updatedAt": "2026-07-20T12:00:00.000Z",
        "draft": {
          "channel": "ozon",
          "ready": true,
          "errors": [],
          "steps": [
            { "key": "translate", "done": true },
            { "key": "copy", "done": true },
            { "key": "images", "done": true },
            { "key": "category", "done": true }
          ],
          "checkedAt": "2026-07-20T11:58:00.000Z"
        }
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}

2. Soft Delete Channel Draft

  • Endpoint: /api/qingpu/listing/channels/delete
  • Method: POST
  • Authentication: Required (User Session or Bearer tenant key)

Request Body

{
  "productId": "p_123",
  "channel": "ozon"
}

Success Response

{
  "code": 0,
  "data": {
    "deletedCount": 1
  }
}

Notes

  • This operation does not physically delete the row.
  • The API sets qingpu_listing_channel_drafts.deleted_at = now().
  • Re-running the draft submission flow can recreate or reactivate the row later.

3. Restore Channel Draft

  • Endpoint: /api/qingpu/listing/channels/restore
  • Method: POST
  • Authentication: Required (User Session or Bearer tenant key)

Request Body

{
  "productId": "p_123",
  "channel": "ozon"
}

Success Response

{
  "code": 0,
  "data": {
    "restoredCount": 1
  }
}

Notes

  • This operation clears qingpu_listing_channel_drafts.deleted_at back to null.
  • The channels page can optionally display deleted drafts through showDeleted=true.

4. Permanently Delete Channel Draft

  • Endpoint: /api/qingpu/listing/channels/purge
  • Method: POST
  • Authentication: Required (User Session or Bearer tenant key)

Request Body

{
  "productId": "p_123",
  "channel": "ozon"
}

Success Response

{
  "code": 0,
  "data": {
    "deletedCount": 1
  }
}

Notes

  • This only works for channel drafts that are already soft-deleted.
  • The API physically deletes the matching row from qingpu_listing_channel_drafts.
  • It does not affect the source product or workspace row.