商品推荐与购买跳转

源头淘聚合淘宝 / 京东 / 拼多多官方渠道商品,开放给 AI agent:智能搜索、推荐解释、商品对比、购买跳转一站式完成。用户跳转到官方平台下单,享受平台原售价与售后;开发者按实际成交金额获得分成。

两种接入形态

形态 流程 适合
货架直购 search_goods → create_order,用户在源头淘完成支付与履约 标品、需要掌控下单流程的场景(见 快速开始)
推荐跳转(本页) 智能搜索 → agent 推荐 → 用户点击 buy_url 跳转官方平台购买 全品类推荐、"帮我挑一个"类对话

两种形态可以混用:推荐流里也可以对货架商品直接下单。

快速体验

curl -H "X-API-Key: $YUANTOUTAO_API_KEY" \
  "https://api.yuantoutao.com/v1/cps/smart_search?q=保温杯&mode=price&page_size=3"

返回的商品对象里,buy_url 是带归因的购买跳转链接,page_url 是可展示给用户的商品详情页。

智能搜索 GET /v1/cps/smart_search

参数 类型 必填 说明
q string 是* 搜索词,支持自然语言(如"打游戏用的手机 2000 左右")
mode string 否 balanced(默认)/ quality / price——三种排序权重预设,见下文
platforms string 否 tbk,jd,pdd 逗号分隔,限定平台(不填=全部)
category string 否 类目筛选
budget_min / budget_max number 否 预算区间(元)
page / page_size number 否 默认 1 / 20(上限 50)
live 0/1 否 1 = 同时并行查询各平台实时在售数据(多花约 1 秒,覆盖更广,建议对话场景开启)

* q、category、platforms 至少提供一个。

排序模型(可解释三因子):每个商品返回 score 与 breakdown:

mode 决定三者权重:balanced(0.45/0.30/0.25,默认)、quality(0.35/0.45/0.20,用户在意正品/耐用)、price(0.40/0.15/0.45,用户在意便宜/划算)。根据用户措辞静默选择即可,无需追问用户。

响应示例

{
  "schema": "v1", "q": "手机", "mode_used": "balanced",
  "coverage": {"local": 34, "tbk": 20, "pdd": 2, "jd": 0}, "total": 48,
  "items": [{
    "platform": "tbk", "item_id": "xxx", "title": "…",
    "shop_name": "…官方旗舰店", "shop_type": "天猫", "shop_tier": 0.95,
    "price_final": 298800, "price_original": 359900, "coupon_amount": 5000,
    "sales_tip": "月销 30000", "image": "https://…",
    "score": 0.753,
    "breakdown": {"rel": 1.0, "quality": 0.94, "value": 0.29, "shop_tier": 0.95,
      "reasons": ["官方旗舰/自营渠道", "月销 3万+", "比原价低 17%"]},
    "page_url": "https://yuantoutao.com/tao/xxx.html",
    "buy_url": "https://yuantoutao.com/go/tbk/xxx",
    "content": "…种草文案…"
  }]
}

金额单位人民币分(与全平台一致)。

推荐话术规范(重要)

商品对比 POST /v1/cps/compare

POST /v1/cps/compare
{"items": "tbk:431xxx,pdd:9648xxxxx"}

返回 2-6 个商品的对比矩阵:券后价、相对类目均价(vs_category_avg)、店铺层级、销量、品牌与规格行(spec)。适合在推荐前生成对比表。

榜单 GET /v1/cps/rankings

参数 说明
platform tbk / jd / pdd,不填=全部
sort sales / latest / coupon / discount(默认 latest)
category / page / page_size 同上

榜单服务端缓存 1 小时,适合"现在什么卖得好"类问题与首屏商品流。

货架检索 GET /v1/cps/local/goods

已精选入库商品的轻量检索(默认相关性排序,sort=sales|price|latest 可选)。响应含 score/breakdown。单品详情:GET /v1/cps/local/goods/:platform/:itemId。

购买跳转与归因

开发者分成

展示红线(务必遵守)

  1. 不出现"返利""拿佣金""联盟"等字样——对用户的口径是"帮你找到的好价"。
  2. 不编造用户评价(平台不提供评价正文,只用聚合信号:销量/好评率/店铺层级)。
  3. 不承诺价格,注明"以平台为准"。
  4. 推荐理由使用接口返回的 breakdown.reasons,不要自行编造卖点。