REST API

ShopsGuard 提供只读 REST API 给 Business 套餐用户。用于把店铺健康分、告警接进自己的数据仓库 / BI / 自动化工作流。

鉴权

所有请求需带 Authorization: Bearer <token>。Token 在 /settings/api-keys 创建，格式 sg_XXXXXXXX...。

curl https://shopsguard.com/api/v1/shops \
  -H "Authorization: Bearer sg_yourtokenhere"

错误响应：

Status	含义
401	token 缺失 / 无效 / 已撤销 / 已过期
403	当前套餐不允许 API 访问（`required_tier` 字段说明需要哪档）
404	资源不存在或不属于你
500	服务端错误（已记 Sentry）

速率限制

每 token 100 req/min（按滑动窗口计）。超出返回 429 Too Many Requests。

Endpoints

`GET /api/v1/shops`

列出你绑定的所有店铺。

响应

{
  "shops": [
    {
      "id": "uuid",
      "tiktok_shop_id": "7XXXXX",
      "shop_name": "My Shop",
      "region": "US",
      "status": "active",
      "last_synced_at": "2026-05-14T08:00:00Z",
      "created_at": "2026-05-01T10:00:00Z"
    }
  ]
}

`GET /api/v1/shops/{id}`

单店详情 + 最新指标。

响应

{
  "shop": { /* 同上 */ },
  "latest_metrics": {
    "captured_at": "2026-05-14T09:00:00Z",
    "ahr": 0.012,
    "otdr": 0.94,
    "vtr": 0.97,
    "ldr": 0.018,
    "health_score": 82.5,
    "deposit_balance_usd": 1500
  }
}

`GET /api/v1/shops/{id}/metrics`

历史快照。降序，最多 1000 条/次。

查询参数

参数	类型	默认	说明
`start`	ISO 8601	—	起始时间
`end`	ISO 8601	—	结束时间
`limit`	int	100	上限 1000

响应

{
  "shop_id": "uuid",
  "count": 24,
  "snapshots": [
    {
      "captured_at": "2026-05-14T09:00:00Z",
      "ahr": 0.012,
      "otdr": 0.94,
      "vtr": 0.97,
      "ldr": 0.018,
      "health_score": 82.5,
      "deposit_balance_usd": 1500,
      "source": "tiktok_api"
    }
  ]
}

`GET /api/v1/alerts`

告警列表。

查询参数

参数	取值	说明
`status`	`open` / `acknowledged` / `resolved`	—
`shop_id`	uuid	过滤单店
`severity`	`info` / `warning` / `critical`	—
`limit`	int	默认 50，上限 500

响应

{
  "count": 3,
  "alerts": [
    {
      "id": "uuid",
      "shop_id": "uuid",
      "severity": "critical",
      "metric": "ahr",
      "threshold": 0.02,
      "actual_value": 0.018,
      "days_until_breach": 1,
      "message_zh": "异常处理率预计 1 天内破线...",
      "message_en": "AHR projected to breach in 1 day...",
      "sop_slug": "fix-abnormal-handling-rate",
      "status": "open",
      "created_at": "2026-05-14T09:01:00Z"
    }
  ]
}

完整示例

# 列店铺
curl https://shopsguard.com/api/v1/shops -H "Authorization: Bearer sg_xxx"

# 拉过去 7 天指标
curl "https://shopsguard.com/api/v1/shops/$SHOP_ID/metrics?start=$(date -u -d '7 days ago' +%FT%TZ)&limit=200" \
  -H "Authorization: Bearer sg_xxx"

# 列未确认 critical 告警
curl "https://shopsguard.com/api/v1/alerts?status=open&severity=critical" \
  -H "Authorization: Bearer sg_xxx"

版本策略

/api/v1 长期保留。Breaking change → 直接出 v2 而非破坏 v1
新字段会向后兼容增加（你必须忽略未知字段）
Deprecation 提前 90 天 sunset header 通知