API 文档

使用我们的API查询玩家数据和游戏统计信息

开发者API接口

CNTIER提供开放API，允许开发者访问我们的玩家数据、服务器信息和排行榜。以下是可用的API端点和使用示例。

API密钥认证

所有API请求都需要提供有效的API密钥进行认证。您需要联系管理员获取API密钥，或在管理后台创建密钥。您可以通过以下两种方式之一提供API密钥：

1. 请求头方式（推荐）

X-API-Key: your_api_key_here

在HTTP请求头中添加X-API-Key字段

2. URL参数方式

/api/v1/players?api_key=your_api_key_here

在请求URL中添加api_key参数

API密钥管理

API密钥由管理员在后台系统中创建和管理。每个API密钥有以下特性：

可设置访问权限（允许访问的资源和操作）
可设置请求频率限制和配额管理
可设置过期时间
可随时启用、禁用或吊销
自动记录使用情况和详细访问日志
提供实时统计和监控仪表板
支持每日和每月配额限制
完整的审计日志和安全追踪

高级功能

📊 使用统计

实时请求计数
响应时间监控
错误率统计
热门端点分析

🔒 安全控制

IP地址追踪
访问日志记录
密钥吊销机制
权限细粒度控制

示例代码（JavaScript）


// 方法1: 使用请求头
fetch('https://cntier.com/api/v1/players', {
  headers: {
    'X-API-Key': 'your_api_key_here'
  }
})
.then(response => response.json())
.then(data => console.log(data));

// 方法2: 使用URL参数
fetch('https://cntier.com/api/v1/players?api_key=your_api_key_here')
.then(response => response.json())
.then(data => console.log(data));

API错误响应

API可能返回以下错误响应码：

状态码	错误类型	描述
401	缺少API密钥	API请求未提供有效的API密钥
401	API密钥无效	提供的API密钥无效、已过期或已停用
403	权限不足	API密钥没有访问请求资源的权限
429	请求频率过高	请求超过了API密钥的频率限制
500	服务器错误	服务器内部错误

GET

获取所有玩家

获取所有玩家的列表，包括他们的基本信息、段位和分数，支持分页、筛选和排序。可以按地区、游戏模式筛选，并可以按名称、分数或创建时间排序。

GET/api/v1/players

参数

名称	类型	必需	描述
X-API-Key	string	是	API密钥，可以在请求头传递或通过api_key查询参数传递
limit	number	否	每页返回的最大结果数（默认20）
page	number	否	页码（默认1）
region	string	否	按地区筛选
mode	string	否	按游戏模式筛选 (SWORD, CRYSTAL, BUHC, POTION, NPOT, SMP, AXE)
sort	string	否	排序字段 (name, score, createdAt)，默认name
order	string	否	排序方向 (asc, desc)，默认asc
includeBlacklisted	boolean	否	是否包含黑名单玩家（默认false）

响应示例

{
  "players": [
    {
      "id": "1",
    "name": "玩家名称",
    "avatar": "/default-avatar.jpg",
    "region": "地区名称",
      "region_id": "region1",
      "region_color": "#FF5733",
      "is_blacklisted": false,
      "score": 145,
      "match_score": 35,
      "tier_score": 110,
      "level_name": "Combat Ace",
      "created_at": "2025-03-15T12:00:00.000Z",
      "tiers": {
        "sword": {
          "value": 4,
          "name": "LT2"
        },
        "crystal": {
          "value": 3,
          "name": "HT2"
        },
        "buhc": {
          "value": 2,
          "name": "LT1"
        },
        "potion": {
          "value": 1,
          "name": "HT1"
        },
        "npot": {
          "value": 5,
          "name": "HT3"
        },
        "smp": {
          "value": 3,
          "name": "HT2"
        },
        "axe": {
          "value": null,
          "name": "无等级"
        }
      }
  },
  ...
  ],
  "meta": {
    "total": 120,
    "pages": 6,
    "current": 1
  }
}

使用示例

fetch('/api/v1/players?limit=10&page=1&mode=SWORD&sort=score&order=desc').then(res => res.json())

GET

获取所有玩家Tier等级

获取所有玩家的不同游戏模式Tier等级，包括SWORD、CRYSTAL、BUHC、POTION、NPOT、SMP和AXE模式

GET/api/players/tiers

参数

名称	类型	必需	描述
X-API-Key	string	是	API密钥，可以在请求头传递或通过api_key查询参数传递

响应示例

[
  {
    "id": "1",
    "name": "玩家名称",
    "avatar": "/default-avatar.jpg",
    "region": "地区名称",
    "region_id": "region1",
    "region_color": "#FF5733",
    "is_blacklisted": false,
    "tiers": {
      "SWORD": {
        "value": 4,
        "name": "LT2"
      },
      "CRYSTAL": {
        "value": 3,
        "name": "HT2"
      },
      "BUHC": {
        "value": 2,
        "name": "LT1"
      },
      "POTION": {
        "value": 1,
        "name": "HT1"
      },
      "NPOT": {
        "value": 5,
        "name": "HT3"
      },
      "SMP": {
        "value": 3,
        "name": "HT2"
      },
      "AXE": {
        "value": null,
        "name": "无等级"
      }
    }
  },
  ...
]

使用示例

fetch('/api/players/tiers').then(res => res.json())

GET

获取单个玩家

根据玩家ID获取单个玩家的详细信息

GET/api/v1/players/:id

参数

名称	类型	必需	描述
X-API-Key	string	是	API密钥，可以在请求头传递或通过api_key查询参数传递
id	number	是	玩家的唯一ID

响应示例

{
  "id": 1,
  "name": "玩家名称",
  "avatar": "/default-avatar.jpg",
  "region": "地区名称",
  "swordTier": 4,
  "crystalTier": 3,
  "buhcTier": 2,
  "potionTier": 1,
  "npotTier": 5,
  "smpTier": 3,
  "createdAt": "2025-09-15T12:00:00.000Z",
  "lastLogin": "2025-09-20T15:30:00.000Z"
}

使用示例

fetch('/api/v1/players/1').then(res => res.json())

GET

搜索玩家

按名称或地区搜索玩家，支持多种筛选选项，如游戏模式段位要求、精确匹配和最低段位门槛等。响应包含完整的玩家信息，包括段位和分数。

GET/api/v1/search?query=

参数

名称	类型	必需	描述
X-API-Key	string	是	API密钥，可以在请求头传递或通过api_key查询参数传递
query	string	是	搜索关键词
field	string	否	搜索字段 (name, region, all)，默认为all
tierMode	string	否	按拥有特定模式段位的玩家筛选 (SWORD, CRYSTAL, BUHC, POTION, NPOT, SMP, AXE)
limit	number	否	返回的最大结果数（默认20）
exactMatch	boolean	否	是否执行精确匹配（默认false）
includeBlacklisted	boolean	否	是否包含黑名单玩家（默认false）
minTier	string	否	最低段位要求（如 HT1, LT2）

响应示例

{
  "results": [
    {
      "id": "1",
      "name": "玩家名称",
      "avatar": "/default-avatar.jpg",
      "region": "地区名称",
      "region_id": "region1",
      "region_color": "#FF5733",
      "is_blacklisted": false,
      "score": 145,
      "match_score": 35,
      "tier_score": 110,
      "level_name": "Combat Ace",
      "tiers": {
        "sword": {
          "value": 3,
          "name": "HT2"
        },
        "crystal": {
          "value": 3,
          "name": "HT2"
        },
        "buhc": {
          "value": 2,
          "name": "LT1"
        },
        "potion": {
          "value": 1,
          "name": "HT1"
        },
        "npot": {
          "value": 5,
          "name": "HT3"
        },
        "smp": {
          "value": 3,
          "name": "HT2"
        },
        "axe": {
          "value": null,
          "name": "无等级"
        }
      }
    },
    ...
  ],
  "meta": {
    "query": "搜索关键词",
    "field": "all",
    "total": 5
  }
}

使用示例

fetch('/api/v1/search?query=玩家&field=name&limit=5&tierMode=SWORD&minTier=HT2').then(res => res.json())