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:
initialize→ serverInfoyuantoutao-agentmalltools/list→ 20 个工具定义(履约 6 个 + 商品搜索/推荐/对比/榜单 + 平台实时接口;工具与 REST 同源同语义)tools/call{name, arguments}→structuredContent= 对应 REST 的 data
商品智能搜索(推荐流)
详见 商品推荐与购买跳转指南。信封同上;金额人民币分。
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 可选,默认服务端配置)。外卖红包场景。
平台当前状态
货架商品为真实商家供给(首批生鲜冻品商家已接入,持续扩充);推荐跳转覆盖淘宝/京东/拼多多官方渠道。美团本地生活接口灰度联调中。各平台接口可用性变化见 更新日志。