API 概览
rCommerce 提供带版本的 REST API。所有端点收发 JSON。
Base URL
Section titled “Base URL”https://your-domain.com/api/v1三种认证方式:
JWT Bearer token
Section titled “JWT Bearer token”curl -H "Authorization: Bearer <token>" https://api.example.com/api/v1/products通过 /api/v1/auth/login 获取。token 24 小时后过期(可配置)。
API key
Section titled “API key”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 有更高的限额(可配置)。
WebSocket
Section titled “WebSocket”通过 /api/v1/ws 的 WebSocket 提供实时事件。需要 JWT 认证。
| 资源 | 端点 |
|---|---|
| Products | CRUD、变体、图片、分类 |
| Orders | CRUD、状态流转、履约 |
| Customers | CRUD、地址 |
| Cart | 增删商品、合计 |
| Checkout | 发起、选择物流、完成 |
| Payments | 支付、退款 |
| Shipping | 运费、跟踪 |
| Webhooks | CRUD、事件订阅 |
| Accounting Export | 订单/支付/退款导出、结算同步 |
CLI 参考
Section titled “CLI 参考”每个 API 操作都有对应的 CLI 命令:
rcommerce product listrcommerce order get <id>rcommerce api-key create --name "Integration" --scopes "read"完整命令列表见 CLI 参考。