首次接入：你的第一笔订单

源头淘把一个"能下单、能履约、能售后"的商品货架开放给你的 AI agent。本页带你从零跑通第一笔订单，全程约 5 分钟。

接入参数

agent key 向平台申请（文末联系方式）。key 形如 ak_xxxxxxxxxxxxxxxx，请保存到环境变量：

export YUANTOUTAO_API_KEY="ak_xxxxxxxxxxxxxxxx"

NOTE 所有金额单位为人民币分（int）：1500 = ¥15.00。这是为了杜绝浮点误差，agent 转述给用户时除以 100 即可。

方式一：MCP 接入（推荐）

任何支持 MCP 的宿主（ZCode / Claude / WorkBuddy / Cherry Studio / Dify / Coze / 自研 harness）在配置中加入：

{
  "mcpServers": {
    "yuantoutao-agentmall": {
      "type": "url",
      "url": "https://mcp.yuantoutao.com/mcp",
      "headers": { "Authorization": "Bearer ak_你的key" }
    }
  }
}

挂载后 agent 立即获得 6 个工具：search_goods、get_goods_detail、create_order、get_order_status、get_logistics、request_aftersale。

方式二：REST 接入

1. 搜索货架

curl "https://api.yuantoutao.com/v1/goods?q=宠物&page_size=3" \
  -H "Authorization: Bearer $YUANTOUTAO_API_KEY"

// npm install undici（或 Node 18+ 自带 fetch）
const API = 'https://api.yuantoutao.com/v1';
const KEY = process.env.YUANTOUTAO_API_KEY;

const goods = await (await fetch(`${API}/goods?q=宠物&page_size=3`, {
  headers: { Authorization: `Bearer ${KEY}` }
})).json();
console.log(goods.items.map(g => [g.product_id, g.title, g.retail_price, g.available_qty]));

# pip install requests
import os, requests

API = 'https://api.yuantoutao.com/v1'
KEY = os.environ['YUANTOUTAO_API_KEY']

goods = requests.get(f'{API}/goods', params={'q': '宠物', 'page_size': 3},
                     headers={'Authorization': f'Bearer {KEY}'}).json()
print([(g['product_id'], g['title'], g['retail_price']) for g in goods['items']])

响应中的关键字段：retail_price（分）、available_qty（库存快照）、inventory_snapshot_at（快照时间戳——下单前务必确认快照新鲜）、product_id 与 merchant_id（下单要用的两个 id）。

2. 创建订单

必须携带 Idempotency-Key 头（UUID，同一业务动作复用同一值——网络超时用原 key 重试，不会重复扣单）：

curl -X POST "https://api.yuantoutao.com/v1/orders" \
  -H "Authorization: Bearer $YUANTOUTAO_API_KEY" \
  -H "Idempotency-Key: 9f8b7c6d-1a2b-3c4d-5e6f-7a8b9c0d1e2f" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": 2,
    "product_id": 13,
    "qty": 1,
    "receiver": {
      "name": "张三", "phone": "13800138000",
      "province": "浙江省", "city": "杭州市", "district": "西湖区",
      "address": "文一西路 100 号"
    },
    "user_ref": "your-user-uuid-123"
  }'

const idem = crypto.randomUUID();
const order = await (await fetch(`${API}/orders`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${KEY}`, 'Idempotency-Key': idem, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    merchant_id: 2, product_id: 13, qty: 1,
    receiver: { name: '张三', phone: '13800138000', province: '浙江省', city: '杭州市', district: '西湖区', address: '文一西路 100 号' },
    user_ref: 'your-user-uuid-123'
  })
})).json();
console.log(order.order_no, order.amount, order.pay_url, order.render_hint);

import uuid
order = requests.post(f'{API}/orders',
    headers={'Authorization': f'Bearer {KEY}', 'Idempotency-Key': str(uuid.uuid4())},
    json={
        'merchant_id': 2, 'product_id': 13, 'qty': 1,
        'receiver': {'name': '张三', 'phone': '13800138000', 'province': '浙江省',
                     'city': '杭州市', 'district': '西湖区', 'address': '文一西路 100 号'},
        'user_ref': 'your-user-uuid-123'
    }).json()
print(order['order_no'], order['amount'], order['pay_url'], order['render_hint'])

响应：order_no（订单号）、amount（分，服务端计算——你永远不需要传价格）、pay_url + render_hint（支付呈现，见支付与收银台）、expire_in_minutes（30 分钟支付窗口）。

3. 用户付款后

轮询订单状态（建议 5-10 秒间隔），events 时间线会依次出现 paid → merchant_accepted → shipped（含运单号）→ delivered：

curl "https://api.yuantoutao.com/v1/orders/YM20261003100003" \
  -H "Authorization: Bearer $YUANTOUTAO_API_KEY"

const st = await (await fetch(`${API}/orders/${order.order_no}`, {
  headers: { Authorization: `Bearer ${KEY}` }
})).json();
console.log(st.status, st.events.map(e => e.event));

st = requests.get(f"{API}/orders/{order['order_no']}",
                  headers={'Authorization': f'Bearer {KEY}'}).json()
print(st['status'], [e['event'] for e in st['events']])

agent 的体验三件事（检查清单）

1. 按 render_hint 呈现支付：qrcode=桌面宿主把 pay_url 渲染成二维码；手机宿主跳转。
2. 下单前向用户复述商品、价格、收货信息并确认——确认记录是售后争议时最有力的证据。
3. 状态变化主动告诉用户（商家已发货/已签收/退款到账），不要等用户回来问。

接入佣金

通过你的 agent 成交的每笔订单，成交金额的 5% 归接入方，按月结算。这是"agent 引荐交易"的回报：你带用户，平台供货源、管发货、扛售后——详见用户身份与佣金。

下一步

• 支付与收银台：桌面/移动两种宿主的支付呈现细节
• 订单与履约：状态机与物流轨迹
• 售后与退款：免费上门取件的完整流程
• 用户身份：user_ref 与跨平台自然人识别

申请 agent key

提供 agent 名称、所属平台、预估调用量，联系平台（见 yuantoutao.com 证照页）。默认档位 t1=60 次/分钟，高频可申请 t2。