REST API 文档

基础 URL: http://www.oplin.top

版本: 1.0.0 · 计费模式: off

认证

支持两种方式：

• Session Cookie — 浏览器登录后自动携带（Web 控制台）
• API Key — Header: X-API-Key: ksp_xxx... 或 Authorization: Bearer ksp_xxx...

在个人中心创建 API Key（需登录）。密钥仅创建时显示一次，请妥善保存。

搜索

GET /api/search

参数	说明
q	关键词（俄/中）
category	一级类目
sort	relevance | price_asc | price_desc | reviews_desc | rating_desc
page	页码，默认 1
price_min / price_max	价格区间（KZT）
aggs=1	返回聚合（类目、价格分布）

curl -H "X-API-Key: ksp_YOUR_KEY" \
  "http://www.oplin.top/api/search?q=iphone&sort=reviews_desc&page=1"

商品详情

GET /api/products/{id}

id 为数据库内部 ID（非 Kaspi SKU）。

统计数据

GET /api/stats — 平台概览

GET /api/categories — 类目列表

价格历史

GET /api/products/{id}/price-history

SaaS 管理（需 Session 登录）

方法	路径	说明
GET	/api/saas/plans	套餐列表
GET	/api/saas/subscription	当前订阅
POST	/api/saas/subscribe	订阅套餐 {"plan":"pro"}
GET	/api/saas/usage	今日用量
GET	/api/saas/api-keys	API Key 列表
POST	/api/saas/api-keys	创建 Key {"name":"My App"}
DELETE	/api/saas/api-keys/{id}	吊销 Key

配额与错误码

HTTP	说明
401	未认证
403	无访问权限（CDK/订阅未满足）
429	超出每日配额

响应中可能包含 usage 字段：{"used": 10, "limit": 100, "remaining": 90, "plan": "free"}

健康检查

GET /health — 无需认证