API 参考

Base URL: https://api.yuantoutao.com/v1 · MCP: https://mcp.yuantoutao.com/mcp(同源同语义) 鉴权:Authorization: Bearer ak_xxx 或 X-API-Key: ak_xxx 金额:人民币分(int) · 时间:ISO 8601(UTC) · 信封:{schema:"v1", code, msg, data, agent_ref}

GET /goods

搜索货架(只读)。

参数 位置 类型 必填 说明
q query string 否 关键词(标题+描述模糊匹配)
category_id query int 否 类目
price_min / price_max query int 否 价格区间(分)
page / page_size query int 否 默认 1 / 20(上限 50)

响应 items[]:sku_id, product_id, title, retail_price(分), available_qty, inventory_snapshot_at, ship_within_hours, free_ship_threshold, merchant_id, images[], qty_cap

GET /goods/:skuId

单品详情。追加:agent_desc(AI 可读规格)、aftersale_rules、完整 images。

POST /orders

Headers:Idempotency-Key: <uuid>(必填)

字段 类型 必填 说明
merchant_id int 是 商家 id(来自 goods 响应)
product_id int 是 商品 id
qty int 是 1-99(新品限购期有更小上限)
receiver object 是 {name, phone, province, city, district, address}
user_ref string 否 你的用户匿名标识(见身份页)

响应:order_no, status, amount(分), pay_url, render_hint(qrcode|redirect), expire_in_minutes;重放同 key 返回 200 + duplicate:true。

GET /orders/:orderNo

订单详情:status, items[](含 unit_price 成交快照), grand_total, receiver_masked, events[]。只能查你自己 key 创建的订单。

GET /orders/:orderNo/logistics

waybill_no, express_co, traces[{time, context}]。未发货返回 400。

POST /orders/:orderNo/aftersales

字段 类型 必填 说明
type string 是 refund_only / return_refund
reason string 否 用户描述
reason_class string 否 quality / not_as_described / no_reason / shipping_issue
pickup bool 否 默认 true(预约上门取件)
user_ref string 否 配额按自然人(human_key)共享

响应:aftersale_id, status, pickup_waybill_no, return_freight_payer(us|user)。

GET /orders/:orderNo/aftersales

该单全部售后记录。

MCP 端点

JSON-RPC 2.0,POST https://mcp.yuantoutao.com/mcp:

商品智能搜索(推荐流)

详见 商品推荐与购买跳转指南。信封同上;金额人民币分。

GET /cps/smart_search

参数:q(推荐必填), mode(balanced|quality|price), platforms(tbk,jd,pdd), category, budget_min, budget_max(元), page, page_size(≤50), live(0/1)。

响应 items[]:platform, item_id, slug, title, subtitle, content(种草文案), category, shop_name, shop_type, shop_tier(0.6-1.0 店铺层级), price_original/price_final(分), coupon_amount(分), sales_tip, review_count/good_rate/dsr_score(可得时), image, score, breakdown{rel,quality,value,shop_tier,reasons[]}, page_url, buy_url。

coverage 返回各供给源命中数;live=1 时合并各平台实时在售数据(约 +1s,对话推荐场景建议开启)。

POST /cps/compare

body:{"items": "tbk:ID,pdd:ID"} 或 {"items": [{"platform","item_id"}]}(2-6 个)。 响应:category_avg_price(分) + items[](含 vs_category_avg 百分比与 spec[] 规格行)。

GET /cps/rankings

参数:platform, category, sort(sales|latest|coupon|discount), page, page_size。服务端缓存 1 小时;响应 items[] 与智能搜索同构(无 score)。

GET /cps/local/goods

参数:q, platform, price_min, price_max(分), sort(relevance|sales|price|latest), page, page_size。默认相关性排序,响应 items[] 含 score/breakdown。

GET /cps/local/goods/:platform/:itemId

单品全量:含 attrs(规格)、content(种草文案)、page_url、buy_url。

平台实时接口

直接查询对应平台官方在售数据(实时、独立于本地货架;各平台有独立的调用频次限制,请勿轮询):

GET /cps/pdd/goods

参数:q(必填), page, page_size。响应 items[]:goods_id, goods_sign, title, pict_url, price/normal_price(元), coupon_amount(元), sales_tip, category_name, shop_name。

POST /cps/pdd/convert

body:{"goods_id": "...", "goodsSign": "..."} → click_url(购买链接)。goodsSign 来自商品查询结果,必传。

GET /cps/jd/goods

参数:q(必填), page, page_size, sort(price|commitRatio|commentCount|saleCount)。响应 items[] 含 sku_id, title, jd_price/price(元), comment_count, good_comments_rate(%), shop_name, commission_rate。仅返回带推广链接的商品,转链用 POST /cps/jd/convert {material_url}。

GET /cps/jd/orders

参数:start_time, end_time, page, page_size。转化订单查询。

GET /dataoke/goods / GET /dataoke/line-report / GET /dataoke/convert

淘宝渠道选品/实时好价线报/购买链接(goods 支持 keyword/cids/月销下限等筛选)。

本地生活(美团外卖 / 到店 / 酒店)

详见 本地生活优惠指南。

GET /meituan/nearby

参数:longitude, latitude(×1e6 整数,必填), searchText, listTopiId(榜单), platform, bizLine, cityId, sortField, ascDescOrder, categoryId, pageSize, pageNo。响应:hasNext, searchId, data(优惠信息:名称/价格/销量/可用门店)。

GET /meituan/convert

参数:act_id | product_view_sign | text(三选一),link_type(1/2/3/4/5/6),sid。响应:click_url 等。

GET /meituan/orders

参数:start_time, end_time, page, page_size, type。转化订单查询。

POST /meituan/call

美团侧订单事件回推(平台间对接,agent 无需调用)。

其他

GET /cps/shops

淘宝店铺搜索(q 必填)。返回店铺与推广链接。

GET /cps/items

淘宝商品批量详情(num_iids 逗号分隔,≤40)。

POST /cps/tpwd

淘宝口令生成(text, url)。仅用于微信等屏蔽外链场景。

GET /cps/eleme/convert

饿了么官方活动跳转链接(activity_id 可选,默认服务端配置)。外卖红包场景。

平台当前状态

货架商品为真实商家供给(首批生鲜冻品商家已接入,持续扩充);推荐跳转覆盖淘宝/京东/拼多多官方渠道。美团本地生活接口灰度联调中。各平台接口可用性变化见 更新日志。