商店 API 文档 · IDCGo 管理系统

一、基本信息

接口地址

https://api.idcxb.com/api/v1/store

认证方式

无需登录，无需 Token，不读取 Cookie

请求方法

全部为 GET

限流

每个 IP 每分钟 120 次

跨域

允许任意来源读取，不支持携带凭证

编码与时区

UTF-8；时间使用 ISO 8601，例如 2026-10-27T20:18:00+08:00

接口只返回已上架且开发者正常的应用、启用中的分类。草稿、审核中、已下架的内容不会出现。

二、接口一览

接口	方法	用途
/	GET	商店概览：应用总数与推荐应用
/categories	GET	分类清单及各分类应用数量，可附带类型清单
/types	GET	应用类型（插件 / 主题 / 程序补丁）及各类型数量、下属分类
/apps	GET	应用列表，支持分类、类型、搜索、推荐、排序、分页
/apps/{slug}	GET	应用详情，含开发者与同类应用
/apps/{slug}/download	GET	应用下载跳转，302，并累计下载量
/search	GET	按关键词搜索应用

三、统一响应

成功：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

失败：

{
  "code": 42201,
  "message": "每页数量不能超过 50",
  "data": null,
  "errors": {
    "per_page": ["每页数量不能超过 50"]
  }
}

code	HTTP	含义
0	200	成功
40402	404	应用不存在或未上架
40403	404	应用未提供下载地址
42201	422	参数校验失败，`errors` 内含具体字段
42901	429	请求过于频繁，响应头带 `Retry-After`
50001	500	服务器内部错误

四、商店概览

GET https://api.idcxb.com/api/v1/store

一次返回应用总数、最多 3 个推荐应用与服务器时间，适合作为首页首屏数据。

curl "https://api.idcxb.com/api/v1/store"

{
  "code": 0,
  "message": "ok",
  "data": {
    "apps_total": 12,
    "featured_apps": [
      {
        "id": 12,
        "name": "示例应用",
        "slug": "demo-app",
        "icon": "示",
        "icon_text": "示",
        "summary": "一句话简介",
        "category": { "id": null, "name": "登录方式", "slug": "login", "full_name": "登录方式", "type": "plugin", "type_name": "插件" },
        "type": "plugin",
        "type_text": "插件",
        "version": "1.0.0",
        "downloads": 128,
        "featured": true,
        "developer": { "id": 5, "display_name": "admin", "developer_since": "2026-10-01" },
        "web_url": "https://api.idcxb.com/uc/store/12",
        "download_endpoint": "https://api.idcxb.com/api/v1/store/apps/demo-app/download",
        "updated_at": "2026-10-27T20:18:00+08:00"
      }
    ],
    "server_time": "2026-10-27T23:00:00+08:00"
  }
}

五、类型与分类

GET https://api.idcxb.com/api/v1/store/categories

参数	必填	默认	说明
type	否	—	`plugin` / `theme` / `patch`，只返回该类型下的分类
include_empty	否	1	`0` 只返回有应用分类

curl "https://api.idcxb.com/api/v1/store/categories?type=plugin&include_empty=0"

{
  "code": 0,
  "message": "ok",
  "data": {
    "tab": "apps",
    "type": "plugin",
    "categories": [
      {
        "id": null,
        "parent_id": null,
        "name": "登录方式",
        "slug": "login",
        "full_name": "登录方式",
        "description": null,
        "type": "plugin",
        "type_name": "插件",
        "icon": "key",
        "color": 1,
        "sort": 0,
        "count": 3,
        "total_count": 3,
        "children": []
      }
    ],
    "types": [],
    "uncategorized_count": 0
  }
}

GET https://api.idcxb.com/api/v1/store/types 只返回类型维度：

{
  "code": 0,
  "message": "ok",
  "data": {
    "tab": "apps",
    "types": [
      { "slug": "plugin", "name": "插件", "icon": "package", "color": 1, "count": 8, "categories": [ { "slug": "login", "name": "登录方式", "count": 3 } ] },
      { "slug": "theme", "name": "主题", "icon": "grid", "color": 2, "count": 3, "categories": [] },
      { "slug": "patch", "name": "程序补丁", "icon": "code", "color": 3, "count": 1, "categories": [] }
    ],
    "total": 12
  }
}

六、应用列表

GET https://api.idcxb.com/api/v1/store/apps

参数	必填	默认	说明
category	否	—	分类 slug，`__none` 表示未分类
type	否	—	`plugin` / `theme` / `patch`
q	否	—	关键词，匹配名称、简介与描述
featured	否	0	`1` 只返回推荐应用
sort	否	featured	`featured` / `newest` / `downloads`
page	否	1	页码
per_page	否	12	每页数量，最大 50

curl "https://api.idcxb.com/api/v1/store/apps?type=plugin&sort=downloads&per_page=10"

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": 12,
        "name": "示例应用",
        "slug": "demo-app",
        "icon": "示",
        "icon_text": "示",
        "summary": "一句话简介",
        "category": { "id": null, "name": "登录方式", "slug": "login", "full_name": "登录方式", "type": "plugin", "type_name": "插件" },
        "type": "plugin",
        "type_text": "插件",
        "version": "1.0.0",
        "downloads": 128,
        "featured": true,
        "developer": { "id": 5, "display_name": "admin", "developer_since": "2026-10-01" },
        "web_url": "https://api.idcxb.com/uc/store/12",
        "download_endpoint": "https://api.idcxb.com/api/v1/store/apps/demo-app/download",
        "updated_at": "2026-10-27T20:18:00+08:00"
      }
    ],
    "pagination": { "page": 1, "per_page": 10, "total": 8, "last_page": 1, "has_more": false },
    "filters": { "type": "plugin", "type_name": "插件", "category": null, "category_name": null, "q": null }
  }
}

七、应用详情

GET https://api.idcxb.com/api/v1/store/apps/{slug}

在列表字段基础上追加完整描述、文档地址、下载能力与最多 3 个同类应用。

curl "https://api.idcxb.com/api/v1/store/apps/demo-app"

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": 12,
    "name": "示例应用",
    "slug": "demo-app",
    "version": "1.0.0",
    "downloads": 128,
    "description": "完整应用介绍",
    "docs_url": "https://example.com/docs",
    "download": { "available": true, "endpoint": "https://api.idcxb.com/api/v1/store/apps/demo-app/download" },
    "related_apps": [],
    "created_at": "2026-10-01T10:00:00+08:00"
  }
}

八、应用下载

GET https://api.idcxb.com/api/v1/store/apps/{slug}/download

成功返回 302 跳转到下载地址，并累计下载量；未配置下载地址返回 40403。

curl -I "https://api.idcxb.com/api/v1/store/apps/demo-app/download"

九、聚合搜索

GET https://api.idcxb.com/api/v1/store/search?q=关键词

参数	必填	默认	说明
q	是	—	关键词，1–80 字符
limit	否	6	返回条数，1–20

curl "https://api.idcxb.com/api/v1/store/search?q=登录&limit=6"

{
  "code": 0,
  "message": "ok",
  "data": {
    "q": "登录",
    "total": 3,
    "app_total": 3,
    "apps": []
  }
}

十、分页与限制

分页参数

page 从 1 开始，per_page 默认 12、最大 50

缓存

响应带 Cache-Control: public, max-age=30，分类与类型为 60 秒

限流

按 IP 每分钟 120 次，超限返回 42901

写入

接口只读，不会创建授权或修改数据；下载会累计下载量

应用商店 API