REST API

ShopFaaS 提供 REST API 供第三方系统集成店铺数据，如 ERP 同步订单、CRM 同步客户、营销工具同步商品等。

认证

所有 REST API 请求需携带认证信息：

API Key 认证（推荐）

X-ShopFaaS-API-Key: <app-api-key>

API Key 由店长在「设置 → 应用 → API 密钥」创建，适用于服务器端集成。

JWT Bearer Token 认证

Authorization: Bearer <jwt-token>

JWT Token 通过登录接口获取，适用于需要模拟用户身份的场景。

商品 API

获取商品列表

GET /api/products?page=1&pageSize=20&status=ACTIVE

响应：

{
  "code": "ok",
  "msg": "成功",
  "data": {
    "items": [
      {
        "id": "uuid-1",
        "title": "商品 A",
        "handle": "product-a",
        "status": "ACTIVE",
        "price": 99.5,
        "currency": "CNY",
        "inventory": 100,
        "createdAt": "2026-07-14T10:00:00Z"
      }
    ],
    "total": 50,
    "page": 1,
    "pageSize": 20
  }
}

获取单个商品

GET /api/products/{id}

创建商品

POST /api/products
Content-Type: application/json

{
  "title": "新商品",
  "price": 99.5,
  "currency": "CNY",
  "inventory": 100,
  "description": "商品描述"
}

更新商品

PUT /api/products/{id}
Content-Type: application/json

{
  "title": "更新后的标题",
  "price": 89.5
}

删除商品

DELETE /api/products/{id}

调整库存

POST /api/products/{id}/inventory
Content-Type: application/json

{
  "quantity": 100,
  "reason": "补货"
}

订单 API

获取订单列表

GET /api/orders?page=1&pageSize=20&status=PAID

支持的 status 值：PENDING / PAID / FULFILLED / CANCELLED / REFUNDED

获取单个订单

GET /api/orders/{id}

响应包含订单明细、收货地址、支付信息、履约信息。

订单履约

POST /api/orders/{id}/fulfill
Content-Type: application/json

{
  "trackingNumber": "SF1234567890",
  "carrier": "顺丰速运"
}

订单退款

POST /api/orders/{id}/refund
Content-Type: application/json

{
  "amount": 99.5,
  "reason": "商品损坏"
}

取消订单

POST /api/orders/{id}/cancel
Content-Type: application/json

{
  "reason": "客户取消"
}

客户 API

获取客户列表

GET /api/customers?page=1&pageSize=20

获取单个客户

GET /api/customers/{id}

创建客户

POST /api/customers
Content-Type: application/json

{
  "email": "customer@example.com",
  "name": "张三",
  "phone": "13800138000"
}

集合（分类）API

获取集合列表

GET /api/collections

获取集合下的商品

GET /api/collections/{id}/products

文件上传

文件上传（如商品图片、主题包）使用 multipart/form-data：

POST /api/uploads
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="file"; filename="image.jpg"
Content-Type: image/jpeg

<binary data>
------FormBoundary--

响应：

{
  "code": "ok",
  "msg": "上传成功",
  "data": {
    "url": "https://cdn.example.com/uploads/uuid-1.jpg",
    "filename": "image.jpg",
    "size": 102400
  }
}

限制：

• 单文件最大 50MB
• 支持格式：图片（jpg/png/gif/webp）、文档（pdf/doc/xls）、压缩包（zip）

分页约定

所有列表 API 支持分页：

响应包含分页信息：

{
  "data": {
    "items": [...],
    "total": 50,
    "page": 1,
    "pageSize": 20
  }
}

限流

为保护店铺稳定性，REST API 有限流保护：

• 默认限制：每分钟 600 次请求（按 API Key 计算）
• 超限响应：HTTP 429 + RATE_LIMITED 错误码
• 响应头包含剩余配额信息：

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1627000000

健康检查

公开端点，无需认证：

SDK 示例

const response = await fetch("https://your-store.com/api/products", {
  headers: {
    "X-ShopFaaS-API-Key": "your-api-key",
  },
});
const result = await response.json();
console.log(result.data.items);

import requests

response = requests.get(
    "https://your-store.com/api/products",
    headers={"X-ShopFaaS-API-Key": "your-api-key"}
)
data = response.json()
print(data["data"]["items"])

<?php
$ch = curl_init("https://your-store.com/api/products");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-ShopFaaS-API-Key: your-api-key",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data["data"]["items"]);

curl -X GET https://your-store.com/api/products \
  -H "X-ShopFaaS-API-Key: your-api-key"

req, _ := http.NewRequest("GET", "https://your-store.com/api/products", nil)
req.Header.Set("X-ShopFaaS-API-Key", "your-api-key")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

相关文档

• Webhook 事件
• 应用扩展开发
• 角色权限码