源头淘 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→ 6 工具定义（inputSchema 完整）tools/call{name, arguments}→structuredContent= 对应 REST 的 data
平台当前状态
系统与协议层已上线；商品供给与真实履约在商家接入后开放，届时工具签名不变。沙箱阶段支付为模拟串。