API Docs · 只读查询

五分钟开始调用

镜像每10分钟检查源快照更新；Mac或采集进程离线时继续提供最近成功镜像。以 captured_at 和 source_window 判断新鲜度，不能把镜像上传时间当成采集时间。查询 Token 每分钟60次；入口另有每IP和全局并发限制。

ID 保持字符串；金额 gmv.amount 是精确十进制字符串，币种独立，不能转浮点或跨币种相加。null 是未知，0 才是明确零值。

视频与图文通过 type 区分。发布时间筛选只选帖子，不重算筛选期间发生的成交。当前指标累计/区间口径仍未确认。

榜单为每国 SPU 销量 TOP10，非全店；国家 PID 只是已确认关联。上架为近两周已观察到的国家商品上架，不是全量商品库或全球首次上新。

查看 meta.source_window / countries / coverage；200 或空数组不代表覆盖完整。媒体签名地址可能过期，本接口不续签或代理下载。

固定快照分页与轮换 Token

默认50条，上限100条。下一页原样保留筛选及 limit，带上 meta.pagination.next_cursor；游标固定来源快照，不切换到新版本。

相同授权范围的新 Token 可继续旧游标；每一页都重新校验权限。被撤销或过期的 Token 不能继续。更改筛选从第一页开始；快照不存在返回404。

快照历史用 dataset、limit、before=next_before。

错误码与重试

400 参数错误；401 凭证无效、过期或撤销；403 数据集未授权；404 店铺未授权或资源不存在；405 禁止业务写入；414 URI过长；422 超出观察窗口或不支持重算；429 达到请求或并发上限；503 来源暂不可用。

修正400/401/403/422后再试；429按 Retry-After 退避；503可退避重试，其他来源仍独立查询。错误为 {"error":{"code":"…","message":"…"}}，响应头带 X-Request-ID。

Token 管理与部署边界

/admin/api-tokens支持创建、列表，/{id}查询元数据，/{id}/revoke撤销。仅本机独立管理员密钥可操作，只写凭证SQLite；普通查询Token无管理权限。

名称、负责人、店铺、数据集和过期时间必填。完整Token仅创建时返回一次，服务端保存摘要。撤销不可恢复，不会取消已经开始执行的请求。

公网仅提供查询和脱敏Docs；云端读取只读快照镜像，采集事实源保留在本机。入口限流并限制并发，管理通过私有运维通道进行，不公开工作台JSON兼容入口或/admin。

数据可用性与条件查询

/merchants/{merchant_id}/availability仅返回授权数据集的快照时间、窗口与国家覆盖元数据，无参数。有快照不代表完整或最新；无快照为 available=false，未知字段保留 null。不会返回商品或媒体明细。

业务查询响应带 ETag；勾选条件查询后，同 URL 再次发送 If-None-Match。304 无响应体，页面保留上次 JSON。换操作、店铺、参数或重新验证后清除缓存。错误时不继续显示旧结果。

条件查询减少响应体传输；每次仍鉴权并查询保存的数据，不承诺减少快照查询次数或采集耗时。

轻量调用统计口径

/usage只返回当前 Token 统计。管理页可看所有 Token，按启用统计以来累计，不回填历史。请求数包含已鉴权的业务、可用性及店铺目录查询（含 HEAD、304 与授权后的错误）；不计无效 Token、文档文件、管理、/me、/usage。Docs 中发送的业务查询照常计数。

错误数为 HTTP≥400，304 单独累计；平均处理耗时从服务端开始鉴权至响应准备，不是网络时延。无记录时平均值与时间为 null。统计自身查询不计数；统计写入异常时业务仍可查询，响应头 X-Usage-Recorded=false 表示该次未计入。

当前操作全部参数与返回 Schema

正在读取 OpenAPI…

使用你自己的查询 Token；只在页面内存保存，不写入 URL 或浏览器存储。刷新、离开或清除后失效于本页面。

操作

已授权店铺

验证 Token 后显示。

验证查询 Token 后生成示例（不包含真实密钥）。

尚未发送请求。