{"openapi":"3.1.0","info":{"title":"TikTok Selling Read API","version":"1.2.0","description":"查询已保存的观测；业务数据只读。每个查询Token仅访问其明确授权的商家和数据集。管理接口仅本机管理员使用，只修改独立凭证记录。"},"servers":[{"url":"/api/v1"}],"security":[{"readToken":[]}],"paths":{"/merchants":{"get":{"summary":"查询本实例商家","description":"列出此查询Token明确授权、且已保存目录的店铺；不会返回其他店铺。不支持分页参数。","responses":{"200":{"description":"已保存观测的只读查询；不触发采集。","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Merchant"}},"meta":{"type":"object","properties":{"scope":{"const":"authorized_merchants"}}}}},"examples":{"shape":{"summary":"脱敏形状示例，具体字段以schema为准","value":{"data":[],"meta":{"scope":"authorized_merchants"}}}}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"Vary":{"$ref":"#/components/headers/Vary"},"X-Usage-Recorded":{"$ref":"#/components/headers/X-Usage-Recorded"}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"get_merchants"},"head":{"summary":"查询本实例商家（仅响应头）","responses":{"200":{"$ref":"#/components/responses/ConditionalHeadOK"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"head_merchants"},"parameters":[{"$ref":"#/components/parameters/IfNoneMatch"}]},"/merchants/{merchant_id}/countries":{"get":{"summary":"查询国家店铺","description":"","responses":{"200":{"description":"已保存观测的只读查询；不触发采集。","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"Vary":{"$ref":"#/components/headers/Vary"},"X-Usage-Recorded":{"$ref":"#/components/headers/X-Usage-Recorded"}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"get_merchants_merchant_id_countries"},"head":{"summary":"查询国家店铺（仅响应头）","responses":{"200":{"$ref":"#/components/responses/ConditionalHeadOK"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"head_merchants_merchant_id_countries"},"parameters":[{"$ref":"#/components/parameters/merchant_id"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/snapshot_id"},{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/seller_id"},{"$ref":"#/components/parameters/IfNoneMatch"}]},"/merchants/{merchant_id}/accounts":{"get":{"summary":"查询账号绑定","description":"","responses":{"200":{"description":"已保存观测的只读查询；不触发采集。","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Account"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"Vary":{"$ref":"#/components/headers/Vary"},"X-Usage-Recorded":{"$ref":"#/components/headers/X-Usage-Recorded"}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"get_merchants_merchant_id_accounts"},"head":{"summary":"查询账号绑定（仅响应头）","responses":{"200":{"$ref":"#/components/responses/ConditionalHeadOK"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"head_merchants_merchant_id_accounts"},"parameters":[{"$ref":"#/components/parameters/merchant_id"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/snapshot_id"},{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/seller_id"},{"$ref":"#/components/parameters/creator_id"},{"$ref":"#/components/parameters/IfNoneMatch"}]},"/merchants/{merchant_id}/contents":{"get":{"summary":"查询短视频或图文","description":"默认按发布时间倒序；相同时间以国家、店铺、账号、帖子ID稳定排序。指标不是按该发布时间范围重新计算的成交区间指标。","responses":{"200":{"description":"已保存观测的只读查询；不触发采集。","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Content"}},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"video":{"summary":"脱敏短视频示例，非真实经营记录","value":{"data":[{"merchant_id":"7000000000000000001","country":"US","seller_id":"7000000000000000002","creator_id":"7000000000000000003","content_id":"7000000000000000004","title":"Synthetic example","published_at":"2026-10-20T00:00:00Z","metrics":{"views":null,"sku_orders":0,"gmv":{"amount":"20.610000000000000001","currency":"USD"}},"type":"video","preview":{"type":"video","playback_url":"https://example.com/video.mp4","images":[]}}],"meta":{"merchant_id":"7000000000000000001","dataset":"video","scope":"observed_records","coverage":null,"source_window":{"start":"2026-10-17","end":"2026-10-24","timezone":"UTC","end_exclusive":true},"pagination":{"limit":50,"total_observed":1,"next_cursor":null}}}},"photo":{"summary":"脱敏图文示例，非真实经营记录","value":{"data":[{"merchant_id":"7000000000000000001","country":"US","seller_id":"7000000000000000002","creator_id":"7000000000000000003","content_id":"7000000000000000004","title":"Synthetic example","published_at":"2026-10-20T00:00:00Z","metrics":{"views":null,"sku_orders":0,"gmv":{"amount":"20.610000000000000001","currency":"USD"}},"type":"photo","preview":{"type":"gallery","playback_url":null,"images":["https://example.com/photo.jpg"]}}],"meta":{"merchant_id":"7000000000000000001","dataset":"photo","scope":"observed_records","coverage":null,"source_window":{"start":"2026-10-17","end":"2026-10-24","timezone":"UTC","end_exclusive":true},"pagination":{"limit":50,"total_observed":1,"next_cursor":null}}}}}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"Vary":{"$ref":"#/components/headers/Vary"},"X-Usage-Recorded":{"$ref":"#/components/headers/X-Usage-Recorded"}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"get_merchants_merchant_id_contents"},"head":{"summary":"查询短视频或图文（仅响应头）","responses":{"200":{"$ref":"#/components/responses/ConditionalHeadOK"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"head_merchants_merchant_id_contents"},"parameters":[{"$ref":"#/components/parameters/merchant_id"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/snapshot_id"},{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/seller_id"},{"$ref":"#/components/parameters/type"},{"$ref":"#/components/parameters/contents_creator_id"},{"$ref":"#/components/parameters/content_id"},{"$ref":"#/components/parameters/product_id"},{"$ref":"#/components/parameters/published_from"},{"$ref":"#/components/parameters/published_before"},{"$ref":"#/components/parameters/IfNoneMatch"}]},"/merchants/{merchant_id}/product-rankings":{"get":{"summary":"查询各国销量TOP10观测","description":"按国家代码、平台名次排序；销量指标粒度为SPU，不能归因为某个PID的独立销量。","responses":{"200":{"description":"已保存观测的只读查询；不触发采集。","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Ranking"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"Vary":{"$ref":"#/components/headers/Vary"},"X-Usage-Recorded":{"$ref":"#/components/headers/X-Usage-Recorded"}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"get_merchants_merchant_id_product_rankings"},"head":{"summary":"查询各国销量TOP10观测（仅响应头）","responses":{"200":{"$ref":"#/components/responses/ConditionalHeadOK"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"head_merchants_merchant_id_product_rankings"},"parameters":[{"$ref":"#/components/parameters/merchant_id"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/snapshot_id"},{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/seller_id"},{"$ref":"#/components/parameters/product_rankings_product_id"},{"$ref":"#/components/parameters/spu_code"},{"$ref":"#/components/parameters/stats_from"},{"$ref":"#/components/parameters/stats_before"},{"$ref":"#/components/parameters/IfNoneMatch"}]},"/merchants/{merchant_id}/listings":{"get":{"summary":"查询各国近期上架商品","description":"按该国商品上架时间倒序；不将新增颜色算作上架，不推断为全球新款。","responses":{"200":{"description":"已保存观测的只读查询；不触发采集。","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"Vary":{"$ref":"#/components/headers/Vary"},"X-Usage-Recorded":{"$ref":"#/components/headers/X-Usage-Recorded"}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"get_merchants_merchant_id_listings"},"head":{"summary":"查询各国近期上架商品（仅响应头）","responses":{"200":{"$ref":"#/components/responses/ConditionalHeadOK"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"head_merchants_merchant_id_listings"},"parameters":[{"$ref":"#/components/parameters/merchant_id"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/snapshot_id"},{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/seller_id"},{"$ref":"#/components/parameters/listings_product_id"},{"$ref":"#/components/parameters/listings_spu_code"},{"$ref":"#/components/parameters/listed_from"},{"$ref":"#/components/parameters/listed_before"},{"$ref":"#/components/parameters/IfNoneMatch"}]},"/merchants/{merchant_id}/snapshots":{"get":{"summary":"查询有效历史快照元数据","description":"仅返回快照身份、采集和入库时间，排除无效快照及原始采集页。此索引为动态历史列表；业务数据分页使用cursor固定快照。","responses":{"200":{"description":"已保存观测的只读查询；不触发采集。","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Snapshot"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"Vary":{"$ref":"#/components/headers/Vary"},"X-Usage-Recorded":{"$ref":"#/components/headers/X-Usage-Recorded"}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"get_merchants_merchant_id_snapshots"},"head":{"summary":"查询有效历史快照元数据（仅响应头）","responses":{"200":{"$ref":"#/components/responses/ConditionalHeadOK"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"head_merchants_merchant_id_snapshots"},"parameters":[{"$ref":"#/components/parameters/merchant_id"},{"$ref":"#/components/parameters/dataset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/before"},{"$ref":"#/components/parameters/IfNoneMatch"}]},"/openapi.json":{"get":{"summary":"读取本接口说明","responses":{"200":{"description":"OpenAPI 3.1文档。"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"422":{"$ref":"#/components/responses/Error422"},"503":{"$ref":"#/components/responses/Error503"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"get_openapi_json","security":[]},"head":{"summary":"读取接口说明（仅响应头）","responses":{"200":{"$ref":"#/components/responses/HeadOK"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"}},"operationId":"head_openapi_json","security":[]}},"/me":{"get":{"operationId":"get_current_grant","summary":"查看当前查询Token授权范围","responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Grant"}}}}}},"401":{"$ref":"#/components/responses/Error401"},"429":{"$ref":"#/components/responses/Error429"}}},"head":{"operationId":"head_current_grant","summary":"查看授权响应头","responses":{"200":{"$ref":"#/components/responses/HeadOK"},"401":{"$ref":"#/components/responses/Error401"},"429":{"$ref":"#/components/responses/Error429"}}}},"/usage":{"get":{"operationId":"get_own_usage","summary":"查看当前Token累计调用统计","responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Usage"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"503":{"$ref":"#/components/responses/Error503"},"429":{"$ref":"#/components/responses/Error429"}}},"head":{"operationId":"head_own_usage","summary":"查看当前Token累计调用统计（仅响应头）","responses":{"200":{"$ref":"#/components/responses/HeadOK"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"503":{"$ref":"#/components/responses/Error503"},"429":{"$ref":"#/components/responses/Error429"}}}},"/merchants/{merchant_id}/availability":{"get":{"operationId":"get_availability","summary":"查询授权数据集的快照与覆盖元数据","responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Availability"}},"meta":{"type":"object","required":["merchant_id","scope"],"properties":{"merchant_id":{"type":"string"},"scope":{"const":"authorized_datasets"}}}}}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"Vary":{"$ref":"#/components/headers/Vary"},"X-Usage-Recorded":{"$ref":"#/components/headers/X-Usage-Recorded"}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"503":{"$ref":"#/components/responses/Error503"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}}},"head":{"operationId":"head_availability","summary":"查询授权数据集的快照与覆盖元数据（仅响应头）","responses":{"200":{"$ref":"#/components/responses/ConditionalHeadOK"},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"414":{"$ref":"#/components/responses/Error414"},"503":{"$ref":"#/components/responses/Error503"},"304":{"$ref":"#/components/responses/NotModified"},"429":{"$ref":"#/components/responses/Error429"}}},"parameters":[{"$ref":"#/components/parameters/merchant_id"},{"$ref":"#/components/parameters/IfNoneMatch"}]}},"components":{"securitySchemes":{"readToken":{"type":"http","scheme":"bearer","description":"当前商家只读访问Token，不支持URL参数传递。"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Meta":{"type":"object","description":"包含dataset、snapshot_id、captured_at、stored_at、source_window、comparison_window、scope、coverage、countries和pagination。total_observed仅为当前筛选匹配的已观察记录数；不是平台全部数据数量。所有未知元数据保留null。","properties":{"merchant_id":{"type":"string"},"dataset":{"type":"string"},"snapshot_id":{"type":"string"},"captured_at":{"type":"string"},"stored_at":{"type":"string"},"source_window":{"type":["object","null"]},"comparison_window":{"type":["object","null"]},"scope":{"type":"string"},"coverage":{"type":["object","null"]},"countries":{"type":"array","items":{"type":"object"}},"pagination":{"type":"object"}}},"Merchant":{"type":"object","properties":{"merchant_id":{"type":"string"},"name":{"type":"string"}}},"Country":{"type":"object","properties":{"merchant_id":{"type":"string"},"country":{"type":"string"},"seller_id":{"type":"string"},"returned":{"type":["boolean","null"]}}},"Account":{"type":"object","properties":{"merchant_id":{"type":"string"},"country":{"type":"string"},"seller_id":{"type":"string"},"creator_id":{"type":"string"},"display_name":{"type":["string","null"]},"fans_count":{"type":["integer","null"]},"role_code":{"type":["integer","null"]},"status_code":{"type":["integer","null"]},"profile_error":{"type":["string","null"]}}},"Content":{"type":"object","properties":{"merchant_id":{"type":"string"},"country":{"type":"string"},"seller_id":{"type":"string"},"creator_id":{"type":"string"},"content_id":{"type":"string"},"type":{"type":"string","enum":["video","photo"]},"handle":{"type":["string","null"]},"title":{"type":["string","null"]},"published_at":{"type":["string","null"]},"commerce_captured_at":{"type":["string","null"]},"media_captured_at":{"type":["string","null"]},"shoppable":{"type":["string","null"]},"product_evidence_count":{"type":["integer","null"]},"products":{"type":["array","null"],"items":{"type":"object"}},"metrics":{"type":"object","properties":{"views":{"type":["integer","null"]},"likes":{"type":["integer","null"]},"comments":{"type":["integer","null"]},"shares":{"type":["integer","null"]},"sku_orders":{"type":["integer","null"]},"items_sold":{"type":["integer","null"]},"product_impressions":{"type":["integer","null"]},"product_clicks":{"type":["integer","null"]},"ctr_raw":{"type":["string","null"]},"ctor_raw":{"type":["string","null"]},"gmv":{"type":["object","null"],"description":"amount为精确十进制字符串；currency独立保存，不跨币种相加。","properties":{"amount":{"type":["string","null"]},"currency":{"type":["string","null"]},"formatted":{"type":["string","null"]}}}}},"preview":{"type":"object","properties":{"type":{"type":"string","enum":["video","gallery"]},"cover_url":{"type":["string","null"]},"post_url":{"type":["string","null"]},"playback_url":{"type":["string","null"]},"images":{"type":"array","items":{"type":"string"}}}}},"required":["merchant_id","country","seller_id","creator_id","content_id","type","metrics","preview"]},"Ranking":{"type":"object","properties":{"merchant_id":{"type":"string"},"country":{"type":"string"},"seller_id":{"type":"string"},"spu_id":{"type":"string"},"spu_code":{"type":["string","null"]},"product_id":{"type":["string","null"]},"rank":{"type":"integer"},"title":{"type":["string","null"]},"image_url":{"type":["string","null"]},"image_detail_url":{"type":["string","null"]},"trend_captured_at":{"type":["string","null"]},"metrics":{"type":"object","description":"保留源指标value、formatted、change_direction、change_formatted、latest_ready_date、raw。比率value为原比例字符串；品质指标为近30日口径。"},"sales_trend":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"value":{"type":"integer"}}},"description":"仅返回平台已有日期，不补零。"}}},"Listing":{"type":"object","properties":{"merchant_id":{"type":"string"},"country":{"type":"string"},"seller_id":{"type":"string"},"product_id":{"type":"string"},"spu_code":{"type":"string"},"title":{"type":["string","null"]},"image_url":{"type":["string","null"]},"listed_at":{"type":"string"},"classification":{"type":"string","enum":["existing_style_new_country","style_age_unknown"]},"style_evidence_at":{"type":["string","null"]},"skc_count":{"type":["integer","null"]}}},"Snapshot":{"type":"object","properties":{"snapshot_id":{"type":"string"},"captured_at":{"type":"string"},"stored_at":{"type":"string"}}},"Token":{"type":"object","required":["id","name","owner","prefix","merchant_ids","datasets","created_at","expires_at","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"owner":{"type":"string"},"prefix":{"type":"string"},"merchant_ids":{"type":"array","items":{"type":"string"}},"datasets":{"type":"array","items":{"enum":["accounts","video","photo","rankings","listings"]}},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"status":{"enum":["active","expired","revoked"]}}},"TokenCreate":{"type":"object","additionalProperties":false,"required":["name","owner","expires_at","merchant_ids","datasets"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"owner":{"type":"string","minLength":1,"maxLength":100},"expires_at":{"type":"string","format":"date-time"},"merchant_ids":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"datasets":{"type":"array","minItems":1,"uniqueItems":true,"items":{"enum":["accounts","video","photo","rankings","listings"]}}}},"Grant":{"type":"object","required":["id","name","merchant_ids","datasets","expires_at"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"merchant_ids":{"type":"array","items":{"type":"string"}},"datasets":{"type":"array","items":{"enum":["accounts","video","photo","rankings","listings"]}},"expires_at":{"type":"string","format":"date-time"}}},"Usage":{"type":"object","additionalProperties":false,"required":["requests","errors","not_modified","first_request_at","last_request_at","token_id","total_duration_ms","average_duration_ms"],"properties":{"requests":{"type":"integer","minimum":0},"errors":{"type":"integer","minimum":0},"not_modified":{"type":"integer","minimum":0},"first_request_at":{"type":["string","null"],"format":"date-time"},"last_request_at":{"type":["string","null"],"format":"date-time"},"token_id":{"type":"string"},"total_duration_ms":{"type":"number","minimum":0},"average_duration_ms":{"type":["number","null"],"minimum":0}},"description":"统计启用以来每Token累计一行，不回填历史。仅已鉴权业务/店铺目录/可用性GET或HEAD（含授权后错误和304）；不计/me、/usage、管理、文档文件、无效Token。Docs中的业务试调照常计数。错误>=400。耗时为鉴权开始至响应准备，非网络时延；无记录平均为null。统计写入失败不影响业务响应，X-Usage-Recorded=false。"},"Availability":{"type":"object","additionalProperties":false,"required":["dataset","available","snapshot_id","captured_at","stored_at","source_window","comparison_window","coverage","countries"],"properties":{"dataset":{"type":"string","enum":["accounts","video","photo","rankings","listings"]},"available":{"type":"boolean"},"snapshot_id":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$"},"captured_at":{"type":["string","null"],"format":"date-time"},"stored_at":{"type":["string","null"],"format":"date-time"},"source_window":{"type":["object","null"]},"comparison_window":{"type":["object","null"]},"coverage":{"type":["object","null"]},"countries":{"type":"array","items":{"type":"object","description":"仅国家身份及覆盖元数据，沿用来源状态/null/error；无明细或签名媒体。"}}},"description":"仅授权数据集的最新有效快照元数据。available只表示快照存在，不代表覆盖完整、最新或国家可用。无快照时元数据null、countries为空；窗口原样保留，不回算。"}},"responses":{"Error400":{"description":"非法参数或游标","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error401":{"description":"缺失或无效Bearer Token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error404":{"description":"资源、国家店铺或快照不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error405":{"description":"只允许GET、HEAD","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error414":{"description":"URI超过8192字符","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error422":{"description":"请求超出已观察日期范围，或试图重算榜单区间","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error503":{"description":"PG或来源数据不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"HeadOK":{"description":"与GET一致的状态和Content-Length，无响应体。"},"Error403":{"description":"数据集未授权，或管理请求不是可信本机来源","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotModified":{"description":"仍有授权且结果未改变，无响应体；复用上次结果。","headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"Vary":{"$ref":"#/components/headers/Vary"}}},"ConditionalHeadOK":{"description":"响应头与GET一致，无响应体；支持If-None-Match。","headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"Vary":{"$ref":"#/components/headers/Vary"},"X-Usage-Recorded":{"$ref":"#/components/headers/X-Usage-Recorded"}}},"Error429":{"description":"公网Token或网关请求/并发上限，稍后重试；Retry-After单位秒。","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"limit":{"name":"limit","in":"query","required":false,"description":"每页1–100条，默认50。分页期间保持参数不变。","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"cursor":{"name":"cursor","in":"query","required":false,"description":"上一页next_cursor；签名绑定快照、路径及全部筛选。","schema":{"type":"string"}},"snapshot_id":{"name":"snapshot_id","in":"query","required":false,"description":"指定该来源的有效历史快照SHA256。","schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"merchant_id":{"name":"merchant_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,39}$"},"description":"当前Token明确获授权的商家ID；未授权与不存在均返回404。"},"country":{"name":"country","in":"query","required":false,"description":"国家代码；英国使用GB。","schema":{"type":"string","pattern":"^[A-Z]{2}$"}},"seller_id":{"name":"seller_id","in":"query","required":false,"description":"国家店铺ID，十进制字符串。","schema":{"type":"string"}},"creator_id":{"name":"creator_id","in":"query","required":false,"description":"创作者ID字符串。","schema":{"type":"string"}},"type":{"name":"type","in":"query","required":true,"description":"必须明确内容类型。","schema":{"type":"string","enum":["video","photo"]}},"contents_creator_id":{"name":"creator_id","in":"query","required":false,"description":"创作者ID。","schema":{"type":"string"}},"content_id":{"name":"content_id","in":"query","required":false,"description":"视频/图文帖子ID字符串。","schema":{"type":"string"}},"product_id":{"name":"product_id","in":"query","required":false,"description":"精确筛选带货商品国家PID。","schema":{"type":"string"}},"published_from":{"name":"published_from","in":"query","required":false,"description":"发布时间下界，含；YYYY-MM-DD或带时区ISO时间，默认快照窗口开始。","schema":{"type":"string"}},"published_before":{"name":"published_before","in":"query","required":false,"description":"发布时间上界，不含；默认快照窗口结束。","schema":{"type":"string"}},"product_rankings_product_id":{"name":"product_id","in":"query","required":false,"description":"唯一已确认的国家PID；未绑定PID不推断。","schema":{"type":"string"}},"spu_code":{"name":"spu_code","in":"query","required":false,"description":"业务SPU代码，精确匹配。","schema":{"type":"string"}},"stats_from":{"name":"stats_from","in":"query","required":false,"description":"平台统计日期开始，须与stats_before一起给出并精确匹配所选快照。","schema":{"type":"string"}},"stats_before":{"name":"stats_before","in":"query","required":false,"description":"平台统计日期结束，不含。","schema":{"type":"string"}},"listings_product_id":{"name":"product_id","in":"query","required":false,"description":"国家PID。","schema":{"type":"string"}},"listings_spu_code":{"name":"spu_code","in":"query","required":false,"description":"业务SPU代码。","schema":{"type":"string"}},"listed_from":{"name":"listed_from","in":"query","required":false,"description":"该国商品上架时间下界，含；默认快照窗口开始。","schema":{"type":"string"}},"listed_before":{"name":"listed_before","in":"query","required":false,"description":"该国商品上架时间上界，不含；默认快照窗口结束。","schema":{"type":"string"}},"dataset":{"name":"dataset","in":"query","required":true,"description":"查询来源。","schema":{"type":"string","enum":["accounts","video","photo","rankings","listings"]}},"before":{"name":"before","in":"query","required":false,"description":"上一页next_before快照ID；继续查询更早版本。","schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"IfNoneMatch":{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"上次同URL响应的ETag，可为弱标签或逗号分隔列表。每次先校验当前Token及数据权限。匹配时304无body；不省略PG查询。"}},"headers":{"ETag":{"description":"绑定当前Token身份、授权范围、路径/参数及完整响应。","schema":{"type":"string"}},"Cache-Control":{"schema":{"const":"private, no-cache"}},"Vary":{"schema":{"const":"Authorization"}},"X-Usage-Recorded":{"description":"该次调用是否计入轻量统计；false时业务查询仍可成功。","schema":{"type":"string","enum":["true","false"]}}}}}