Revised:
1. 功能简介
WareRushAI REST API 允许其他程序读取单家公司的数据:产品、各库位库存、订单、数据缺失的产品以及电商平台刊登错误。此版本为只读模式,基于与 Web 应用和 MCP 连接器相同的服务与权限校验构建。基础地址为 https://app.warerushai.com/api/v1。该 API 正在逐步开放:在平台正式启用之前,所有调用均返回 404,且无法创建密钥。
2. 创建 API 密钥
所有者或管理员依次打开“设置”、“集成”以及“API 密钥”,为密钥命名,勾选权限(catalog.read、inventory.read、orders.read、account.read)、设置有效期和每分钟请求速率限制,然后点击创建。完整密钥以 wra_live_ 开头且仅显示一次。WareRushAI 仅存储单向哈希和前缀字符,因此丢失的密钥无法找回:请直接创建新密钥。您可以随时撤销密钥或进行密钥轮换:轮换时新密钥仅显示一次,旧密钥将继续有效 24 小时。
3. 身份验证
通过 HTTPS 在 Authorization 请求头中发送密钥:Authorization: Bearer wra_live_...。切勿将密钥放在网址中;凡包含密钥的请求都会被拒绝并返回 key_in_url 错误。示例:curl -H "Authorization: Bearer $WRA_KEY" "https://app.warerushai.com/api/v1/products?limit=20"。系统同样接受 MCP 连接器的 OAuth 2.1 访问令牌,并遵循用户所授权的权限范围。
4. 端点列表
GET /me(密钥信息、限制额度与今日用量)、GET /products(搜索和列表,支持 query、limit、cursor)、GET /products/{id}、GET /locations、GET /inventory(库存明细行,支持分页)、GET /inventory/summary、GET /orders(支持 updated_since、status、source、limit、cursor)、GET /missing-data 以及 GET /marketplace-errors(支持 channel)。每个端点都需要相应的权限:产品、缺失数据和电商平台错误需要 catalog.read,库位与库存需要 inventory.read,订单需要 orders.read。仅支持 GET 请求;其他请求方法均返回 405。
5. 分页与轮询
列表接口返回 data、next_cursor 和 has_more,每页最多返回 50 项(limit 范围为 1 至 50,默认 20)。将 next_cursor 作为 cursor 参数回传即可获取下一页。对于 Zapier、Make 和 n8n 的轮询触发器,调用 GET /orders?updated_since=2026-11-15T08:00:00Z 并记录上次成功轮询的时间:您将获取自那时起新建或变更的订单,按最新优先排序。
6. 限流与错误
每个密钥都有每分钟速率限制(默认 60,上限 600)以及可选的每日限制。每家公司还会根据方案享有每日调用配额:默认 Starter 为 1 000 次,Business 为 10 000 次,Pro 为 100 000 次。达到限制后,API 会返回 429 状态码并附带 Retry-After 响应头。响应头 X-RateLimit-Limit、X-RateLimit-Remaining、X-Daily-Limit 和 X-Daily-Remaining 显示剩余可用额度。错误响应格式固定为 {"error":{"code","message","request_id"}};联系支持团队时请提供 request_id。常见错误码:invalid_api_key (401)、insufficient_scope (403)、not_found (404)、invalid_parameter (400)、rate_limited 和 daily_quota_exceeded (429)。
7. OpenAPI 规范描述
机器可读的 OpenAPI 3.1 规范描述位于 https://app.warerushai.com/api/v1/openapi.json,无需密钥即可访问。将其导入 Postman、Zapier、Make、n8n 或 AI 助手,即可获取所有端点、参数和响应结构。后续更新均保持向后兼容,不破坏现有字段;API 版本为 /api/v1。
8. 安全性
密钥仅归属于单家公司,且每次调用都会进行验证;密钥绝无法读取其他公司的数据,若创建该密钥的管理员离开公司,密钥将立即失效。密钥绝不会出现在日志或错误信息中,调用日志仅显示路径、状态码和时间。采购价等财务数据不会通过此 API 暴露。
