# 源头淘 Agent 商城（Yuantoutao Agent Mall）

> Commerce plugin for any AI agent. AI agent 的货源与发货后端：商品信息流开放给所有 agent，资金流与物流由平台持有（agent 永不碰钱）。

## MCP

- Endpoint: `https://mcp.yuantoutao.com/mcp`（JSON-RPC, streamable HTTP）
- Auth: `Authorization: Bearer ak_xxx`
- Optional: `Idempotency-Key` header on create_order（必填，防重复扣单）

## Tools

- search_goods: 搜索货架。返回 retail_price（人民币分）、available_qty 与 inventory_snapshot_at（快照时间戳）。
- get_goods_detail: 单品详情，含 agent 可读规格、图片、售后规则。
- create_order: 下单。金额服务端计算，禁止传价。返回 order_no、pay_url、render_hint（qrcode=桌面宿主渲染二维码；手机宿主 redirect 跳微信收银台）。
- get_order_status: 订单状态与事件时间线（已支付/商家接单/已发货/已签收/已退款）。
- get_logistics: 运单轨迹。
- request_aftersale: 仅退款或退货退款；退货含免费上门取件（每用户每月 3 次，跨平台共享配额）。

## Docs（开发者文档站: https://mcp.yuantoutao.com/docs/ ）

- 首次接入: /docs/quickstart.html （你的第一笔订单：MCP 配置/REST 三语言示例）
- 支付与收银台: /docs/payments.html （render_hint 呈现矩阵/桌面二维码/手机跳转）
- 订单与履约: /docs/orders.html （状态机/事件时间线/轨迹/幂等重试）
- 售后与退款: /docs/aftersales.html （两种类型/免费取件月配额/状态机）
- 用户身份: /docs/identity.html
- 教程: /docs/tutorial-shopping-agent.html （50 行做一个购物 agent）
- 接入佣金: 每笔成交订单额的 5% 归接入 agent，按月结算 （user_ref 与跨平台自然人识别 human_key）
- 错误码与限流: /docs/errors.html （错误码总表/退避重试）
- API 参考: /docs/api-reference.html （全接口参数表）
- 更新日志: /docs/changelog.html
- 工具参考（每工具一页）: /docs/tool-search-goods.html · /docs/tool-get-goods-detail.html · /docs/tool-create-order.html · /docs/tool-get-order-status.html · /docs/tool-get-logistics.html · /docs/tool-request-aftersale.html
- 商品目录（人看）: https://yuantoutao.com/catalog.html
- 平台对比: https://yuantoutao.com/learn/agentic-commerce-platforms.html （Rye/ACP/Agora/源头淘 全景）
- 英文介绍: https://yuantoutao.com/en/rye-alternative.html （China supply shelf for AI agents）
- 错误码: INVALID_PARAM / UNAUTHORIZED / RATE_LIMITED / OUT_OF_STOCK / PRICE_CHANGED / RECEIVER_INVALID / ORDER_NOT_FOUND / PAY_EXPIRED / UPSTREAM_JST_ERROR / INTERNAL

## User identity

- `user_ref`：agent 自己的用户匿名标识（作用域=该 agent）
- 跨平台自然人识别：平台按收货手机号加盐哈希得 human_key（不可逆）——同手机号从任何 agent 下单即同一人（配额/风控按人共享）
- 边界：human_key 仅用于履约配额与风控，不做跨平台营销画像串联

## Policies

- 售后：7 天无理由退货；退货上门取件月配额 3 次；商家仓验货后自动原路退款
- 价格：人民币分（int）；价格变动以订单成交快照为准
- 隐私：收货人信息仅用于履约，手机号存储加密，见主站隐私政策

## Changelog

- 0.1.2 (2026-10-03): 接入方佣金政策公布（成交额 5%，月结）；购物 agent 教程上线；工具参考独立成页
- 0.1.1 (2026-10-03): 跨平台自然人识别（human_key）；接入文档三件套上线
- 0.1.0 (2026-10-03): M1 端点上线（货架/交易/售后/轨迹，沙箱模式）