跳转到内容

API 概览

rCommerce 提供带版本的 REST API。所有端点收发 JSON。

https://your-domain.com/api/v1

三种认证方式:

Terminal window
curl -H "Authorization: Bearer <token>" https://api.example.com/api/v1/products

通过 /api/v1/auth/login 获取。token 24 小时后过期(可配置)。

Terminal window
curl -H "Authorization: Bearer <api_key>" https://api.example.com/api/v1/products

通过 CLI 创建:rcommerce api-key create --name "My App" --scopes "products:read,orders:write"

部分端点无需认证:

  • GET /api/v1/products —— 商品列表
  • GET /api/v1/products/:id —— 商品详情
  • GET /api/v1/categories —— 分类列表
  • POST /api/v1/auth/register —— 注册账户
  • POST /api/v1/auth/login —— 登录

列表端点返回分页结果:

{
"products": [...],
"meta": {
"page": 1,
"per_page": 20,
"total": 150,
"total_pages": 8
}
}

查询参数:?page=2&per_page=50(列表端点 per_page 上限为 100)

会计导出端点是例外:它使用 cursor / next_cursor 的 keyset 分页而不是页码——见 会计导出。

{
"error": {
"code": "validation_error",
"message": "Field 'title' is required"
}
}

HTTP 状态码:400 参数校验失败,401 未认证,403 禁止访问, 404 不存在,429 触发限流,500 服务器错误。

默认:每 IP 60 请求/分钟。API key 有更高的限额(可配置)。

通过 /api/v1/ws 的 WebSocket 提供实时事件。需要 JWT 认证。

资源端点
ProductsCRUD、变体、图片、分类
OrdersCRUD、状态流转、履约
CustomersCRUD、地址
Cart增删商品、合计
Checkout发起、选择物流、完成
Payments支付、退款
Shipping运费、跟踪
WebhooksCRUD、事件订阅
Accounting Export订单/支付/退款导出、结算同步

每个 API 操作都有对应的 CLI 命令:

Terminal window
rcommerce product list
rcommerce order get <id>
rcommerce api-key create --name "Integration" --scopes "read"

完整命令列表见 CLI 参考。