YOUYOUMI 开放数据 API 接入说明

快速开始

1. 准备 API Key

   向管理员索取以 ydk_ 开头的密钥。完整密钥只在创建时显示一次。

2. 验证连通性

   curl -sS \
     -H "Authorization: Bearer ydk_你的密钥" \
     "https://youyoumi.asia/api/open/v1/"

   成功时返回 ok: true 与当前 Key 标签。

3. 拉取 catalog，再读快照

   curl -sS \
     -H "Authorization: Bearer ydk_你的密钥" \
     "https://youyoumi.asia/api/open/v1/catalog"

   从返回的 datasets[].fetchUrl 或下方「数据集速查」选择目标，再请求对应快照 URL。

基础信息

鉴权

除本说明页外，所有 /api/open/v1/* 读取接口都需要 HTTP Header：

Authorization: Bearer ydk_你的密钥

• Key 前缀固定为 ydk_
• 请勿把 Key 写进 URL 查询参数或前端公开代码
• Key 泄露时请立即联系管理员 revoke 并重新发放

推荐流程

快照是完整 JSON 文件，不是分页列表 API。大文件请本地缓存，并用 ETag / generatedAt 判断是否需要重新拉取。

端点

广告分点 API

首页广告数据由服务器持有的 TikTok Marketing API Token 定时同步到 R2。开发者调用下面的接口时只需要ydk_... API Key；Marketing Token 不会返回到浏览器、响应体或日志。

筛选与分页

• “账户”筛选：profile、storeId、advertiserId，适用于所有数据端点
• campaignId 只适用于 Campaign、Ad Group、Ad、商品和商品日趋势
• productId（GMV Max item_group_id）只适用于商品、商品日趋势和视频
• startDate、endDate 只适用于日趋势和商品日趋势，格式为 YYYY-MM-DD
• 分页：page 默认 1；pageSize 默认 200，最大 1000
• 端点不支持的筛选会返回 400，不会被静默忽略

curl -sS \
  -H "Authorization: Bearer ydk_你的密钥" \
  "https://youyoumi.asia/api/open/v1/ads/campaigns?storeId=7494242775829480988&pageSize=100"

curl -sS \
  -H "Authorization: Bearer ydk_你的密钥" \
  "https://youyoumi.asia/api/open/v1/ads/daily?profile=shop1-gmv-max&startDate=2026-08-01&endDate=2026-08-25"

这些端点读取最近一次成功同步的快照，不会因为每次请求而消耗 TikTok 上游配额。响应的updatedAt、dataSource 和各行状态用于判断新鲜度；缺失字段保持 null 或空数组，不伪造数据。 鉴权响应使用 private, no-store，如需缓存请在调用端按 updatedAt 管理私有副本。

数据集速查

共 28 个内置 datasetId。完整可用性与字节数以 catalog 实时返回为准。

常用 Upseller datasetId

• upsellerSampleProfit — 摘要与 dataViews 索引
• upsellerSampleProfitGlobalSkus — 全量 SKU 明细
• upsellerSampleProfitStockIndex — 库存索引
• upsellerSampleProfitShopSkus?shopId=... — 单店 SKU
• upsellerSampleProfitSource — 完整源 JSON（体积较大）

错误码

错误响应体统一为 JSON：{ "ok": false, "message": "..." }

代码示例

将 ydk_你的密钥 替换为管理员提供的 Key。

cURL

# 1) 验证 Key
curl -sS -H "Authorization: Bearer ydk_你的密钥" \
  "https://youyoumi.asia/api/open/v1/"

# 2) 获取 catalog
curl -sS -H "Authorization: Bearer ydk_你的密钥" \
  "https://youyoumi.asia/api/open/v1/catalog"

# 3) 读取多店摘要
curl -sS -H "Authorization: Bearer ydk_你的密钥" \
  "https://youyoumi.asia/api/open/v1/snapshots/tiktokShopsSummary"

# 4) 读取 Upseller 全量 SKU
curl -sS -H "Authorization: Bearer ydk_你的密钥" \
  "https://youyoumi.asia/api/open/v1/snapshots/upsellerSampleProfitGlobalSkus"

Python

import requests

BASE = "https://youyoumi.asia"
API_KEY = "ydk_你的密钥"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Accept": "application/json"}

# catalog
catalog = requests.get(f"{BASE}/api/open/v1/catalog", headers=HEADERS, timeout=60)
catalog.raise_for_status()
print(len(catalog.json()["datasets"]), "datasets")

# snapshot
resp = requests.get(
    f"{BASE}/api/open/v1/snapshots/tiktokShopsSummary",
    headers=HEADERS,
    timeout=120,
)
resp.raise_for_status()
data = resp.json()
print(data.get("updated_at") or data.get("generatedAt"))

JavaScript (fetch)

const BASE = "https://youyoumi.asia";
const API_KEY = "ydk_你的密钥";
const headers = { Authorization: `Bearer ${API_KEY}`, Accept: "application/json" };

const catalog = await fetch(`${BASE}/api/open/v1/catalog`, { headers });
if (!catalog.ok) throw new Error(await catalog.text());
const { datasets } = await catalog.json();
console.log(datasets.length, "datasets");

const snapshot = await fetch(
  `${BASE}/api/open/v1/snapshots/profitDashboard`,
  { headers },
);
if (!snapshot.ok) throw new Error(await snapshot.text());
const profit = await snapshot.json();
console.log(profit.updatedAt || profit.meta?.generated_at);

调用建议

• 频率：建议每 dataset 至少间隔 1–5 分钟；catalog 可 1 分钟拉一次。
• 超时：小快照 30–60s；Upseller 全量 SKU / source 建议 120–300s。
• 缓存：响应带 ETag；可发 If-None-Match，命中时返回 304。
• 重试：仅对 503 / 网络错误做有限次指数退避（如 3 次：2s、4s、8s）。401/403/404 不要重试。
• 增量：比较 JSON 内 generatedAt / updated_at / updatedAt，未变化则跳过下载。
• 大文件：upsellerSampleProfitSource 体积大，优先用 summary / global-skus / shop 分片。

数据更新

重新 deploy 网站不会使 API Key 失效；Key 存在 D1，快照存在 R2。

在线探测

输入 API Key 后加载 catalog（只读，密钥不会保存到服务器）。

管理员 · 发放 API Key

仅管理员可见。为每位外部使用者创建一个 Key。