create_order — 创建订单

替用户创建订单。金额服务端计算，必须携带 Idempotency-Key。返回支付链接与呈现方式。

何时用

用户明确确认商品、价格、收货信息之后。未经用户确认不要下单。

硬规则

Idempotency-Key 头必填（UUID）；网络超时用同一个 key 重试，不会重复扣单
禁止传价格——金额由服务端按货架价计算
receiver 六字段缺一不可（name/phone/province/city/district/address，手机号 1 开头 11 位）

参数

参数	类型	必填	说明
merchant_id / product_id	number	是	来自 search_goods 结果
qty	number	是	1-99（新品限购期更小）
receiver	object	是	收货人信息（用于发货，加密存储）
user_ref	string	否	你的用户匿名标识（见身份页）

响应

order_no（订单号）/amount（分）/pay_url/render_hint（qrcode=桌面渲染二维码，redirect=跳转收银台）/expire_in_minutes: 30。

示例

curl

curl -X POST "https://api.yuantoutao.com/v1/orders" \
  -H "Authorization: Bearer ak_你的key" \
  -H "Idempotency-Key: 9f8b7c6d-1a2b-3c4d-5e6f-7a8b9c0d1e2f" \
  -H "Content-Type: application/json" \
  -d '{"merchant_id":2,"product_id":13,"qty":1,"receiver":{...},"user_ref":"u-123"}'

node

const o = await (await fetch('https://api.yuantoutao.com/v1/orders', {
  method: 'POST',
  headers: { Authorization: `Bearer ${KEY}`, 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' },
  body: JSON.stringify(body)
})).json();

python

o = requests.post('https://api.yuantoutao.com/v1/orders',
    headers={'Authorization': f'Bearer {KEY}', 'Idempotency-Key': str(uuid.uuid4())},
    json=body).json()

常见错误

OUT_OF_STOCK（换推荐）/ RECEIVER_INVALID（补全信息）/ PAY_EXPIRED（重新下单）/ INVALID_PARAM（qty 超限购）。