名称: zinc-订单管理描述: 通过Zinc API (zinc.com) 下单、查询订单状态和管理订单。当用户想要从在线零售商购买产品、检查订单状态、列出近期订单或任何涉及Zinc电子商务订购API的操作时使用。需要设置ZINC_API_KEY环境变量。

Zinc 订单管理

通过Zinc API (https://api.zinc.com) 在在线零售商处下单和管理订单。

前提条件

必须设置 ZINC_API_KEY 环境变量。从 https://app.zinc.com 获取。

认证

所有请求使用Bearer令牌认证：

Authorization: Bearer $ZINC_API_KEY

接口端点

创建订单 — `POST /orders`

提交新订单。订单异步处理。

必填字段：

products — { url, quantity?, variant? } 对象数组
- url: 支持零售商的产品页面直接URL
- quantity: 整数（默认1）
- variant: { label, value } 数组，用于尺寸/颜色等选项
shipping_address — 包含 first_name、last_name、address_line1、address_line2、city、state（2字母）、postal_code、phone_number、country（ISO alpha-2，如"US"）的对象
max_price — 整数，最高价格以美分为单位

可选字段：

idempotency_key — 字符串（最多36字符），防止重复提交
retailer_credentials_id — 短ID，如 zn_acct_XXXXXXXX
metadata — 任意键值对象
po_number — 采购订单号字符串

响应： 包含 id（UUID）、status、items、shipping_address、created_at、tracking_numbers 等的订单对象。

订单状态： pending → in_progress → order_placed | order_failed | cancelled

列出订单 — `GET /orders`

返回 { orders: [...] } 订单对象数组。

获取订单 — `GET /orders/{id}`

通过UUID检索单个订单。

示例：下单

curl -X POST https://api.zinc.com/orders \
  -H "Authorization: Bearer $ZINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{ "url": "https://example.com/product", "quantity": 1 }],
    "max_price": 5000,
    "shipping_address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "phone_number": "5551234567",
      "country": "US"
    }
  }'

错误处理

完整错误代码参考见 references/errors.md。

要点：

HTTP错误返回 { code, message, details }
订单处理失败会出现在webhook/订单响应中的 error_type
常见问题：max_price_exceeded、product_out_of_stock、invalid_shipping_address

订单状态跟踪

订单异步处理，通常需要5–10分钟。下单后：

安排一个cron任务在创建后约7分钟检查订单状态。
使用 GET /orders/{id} 轮询。
在同一渠道向用户报告结果。
如果仍为pending/in_progress，5分钟后安排另一次检查。

终止状态： order_placed、order_failed、cancelled — 停止轮询。 非终止状态： pending、in_progress — 3–5分钟后安排另一次检查。

示例cron任务（独立，向渠道公告）：

{
  "name": "zinc-order-check-<short_id>",
  "schedule": { "kind": "at", "at": "<ISO-8601 ~7min from now>" },
  "payload": {
    "kind": "agentTurn",
    "message": "Check Zinc order <order_id> via GET https://api.zinc.com/orders/<order_id>"
  },
  "sessionTarget": "isolated",
  "delivery": {
    "mode": "announce",
    "channel": "<channel>",
    "to": "<channel_id>"
  }
}

安全

下单前（POST /orders）务必与用户确认。这会花费真实资金。
读取订单（GET）始终安全。
提交前验证 max_price 是否合理。

名称: zinc-订单管理 描述: 通过Zinc API (zinc.com) 下单、查询订单状态和管理订单。当用户想要从在线零售商购买产品、检查订单状态、列出近期订单或任何涉及Zinc电子商务订购API的操作时使用。需要设置ZINC_API_KEY环境变量。