服务器 API
通过你自己的工具读取服务器的工单、销售、评价和抽奖统计数据。
API 提供的内容
该 API 为只读，且仅限于一台服务器。它适用于状态页面、电子表格和内部工具，让它们无需登录即可获取仪表盘显示的数据。它无法更改设置、关闭工单或创建发票。
所有端点均位于 https://noxyrbot.com/api/v1 之下，并返回 JSON。密钥本身已标识服务器，因此任何端点都不需要传入服务器 ID。
- GET /api/v1/
- 此密钥启用了哪些权限范围，以及它可以访问哪些端点。
- GET /api/v1/server
- 名称、图标、成员数、在线人数、服务器助力数和创建日期。
- GET /api/v1/tickets
- 总数、未关闭和已关闭数量、过去 7 天和 30 天的工单量，以及平均评分。
- GET /api/v1/activity?days=30
- 每日消息数、加入和离开人数，最多可查询 90 天。
- GET /api/v1/invoices
- 发票数量、按货币统计的收入以及付款状态。启用发票链接权限范围后，?limit= 会附加最近的发票及其可下载的图片链接。
- GET /api/v1/reviews
- 平均评分、星级分布，以及最新的五条公开评价。
- GET /api/v1/giveaways
- 进行中和已结束的抽奖数量、参与总数以及当前的抽奖。
创建密钥
每台服务器只有一个密钥。它在服务器的 API 页面中生成，并且只显示一次，因为系统只保存其哈希值。因此，丢失的密钥只能重新生成，而这会使旧密钥失效。
- 在仪表盘中打开服务器，然后进入“API”。
- 点击“生成”，并复制以 nxr_ 开头的密钥。该密钥不会再次显示。
- 关闭你不需要的任何权限范围。发票链接默认关闭，因为它会暴露客户的发票图片。
- 可选：点击“设置频道”，让机器人在服务器中创建一个 API 分类和频道，并附带端点列表。
该页面还会显示密钥最后一次使用的时间以及它已发出的请求数，这是发现密钥泄露最快的方式。可以使用开关将其停用，或将其撤销以彻底删除。
权限范围
权限范围控制的是端点，而非字段。请求某个权限范围已关闭的端点时，会返回 403，并附带说明该权限范围的消息。
- overview
- /server
- tickets
- /tickets
- activity
- /activity
- invoices
- /invoices
- invoiceLinks
- 添加带有图片链接的最近发票列表。默认关闭。
- reviews
- /reviews
- giveaways
- /giveaways
身份验证与示例请求
将密钥作为 Bearer 令牌放在 Authorization 请求头中发送。允许从浏览器调用（CORS 已开放），但前端代码中的密钥属于公开密钥，因此请从你自己控制的服务器调用 API。
- curl -H "Authorization: Bearer nxr_your_key" https://noxyrbot.com/api/v1/tickets
- 响应：{"total":128,"open":4,"closed":124,"opened7d":9,"opened30d":41,"closed7d":8,"averageRating":4.6,"ratingsCount":37}
速率限制
每个密钥每分钟最多可发出 60 个请求。限制信息会通过标准的 RateLimit 响应头返回在每个响应中；超出限制时返回 HTTP 429，错误为“rate_limited”。轮询频率不要超过数据的更新频率，每分钟读取一次工单和销售总数即可。
错误
每个错误都以 JSON 形式返回，包含机器可读的错误代码和人类可读的消息。
- 401 未授权
- 缺少 Authorization 请求头、不是 Bearer 令牌，或者密钥不存在。
- 403 key_disabled
- 该密钥已在仪表盘中被关闭。
- 403 scope_disabled
- 该密钥已关闭此权限范围。
- 404 not_found
- 端点不存在。消息中会列出有效的端点。
- 404 guild_unavailable
- 机器人已不在该服务器中。
- 429 rate_limited
- 一分钟内超过 60 个请求。
- 500 internal_error
- Noxyr 一侧出现故障，请稍后重试。