接口文档 - 竹鞦

📖 概述

v2.1 重要变更： 所有接口请求方式已升级为 POST，服务端兼容 GET（参数从 $_REQUEST 取，向下兼容旧客户端）。强烈推荐新客户端统一使用 POST。

📐 通用约定

传输方式：HTTP（生产环境强烈建议 HTTPS）
请求方式：POST（推荐）/ GET（兼容）
请求编码：application/x-www-form-urlencoded
返回格式：JSON（默认）/ XML（format=xml）
签名算法：MD5
加密算法：RSA 2048 公钥加密 / RC4 + Base64Url（可选）
所有接口必带：app_key、timestamp、nonce、sign

公共参数

参数	必填	说明
app_key	是	应用唯一标识（管理后台 → 应用管理获取）
timestamp	是	当前 Unix 时间戳（秒），与服务器时间相差 ≤ 60s
nonce	是	6~32 位随机字符串，每次请求必须不同（防重放）
sign	是	MD5 签名（见下文规则）
format	否	`json`（默认）/ `xml`
enc	否	`1`=加密返回 data（RC4）
payload	否	RC4 加密的 JSON（base64url），可代替明文参数
payload_rsa	否	RSA 公钥加密的 JSON（base64），最安全

🔏 签名算法

服务端 PHP 实现：includes/Crypto.php :: makeSign()，客户端可对照实现。

收集所有非空业务参数（剔除 sign、signature、null、空字符串）
按 key 字典序排序
数组类型 value 用 JSON.stringify() 转为字符串
拼接成 k1=v1&k2=v2&...
末尾追加 &key={app_secret}&salt={SIGN_SALT}
对整体 MD5 小写

JavaScript 示例

function buildSign(params, secret, salt) {
  var keys = Object.keys(params)
    .filter(k => k !== 'sign' && params[k] !== null && params[k] !== '')
    .sort();
  var parts = keys.map(k => {
    var v = params[k];
    if (typeof v === 'object') v = JSON.stringify(v);
    return k + '=' + v;
  });
  return md5(parts.join('&') + '&key=' + secret + '&salt=' + salt);
}

Python 示例

import hashlib, json

def build_sign(params: dict, secret: str, salt: str) -> str:
    items = sorted(
        (k, v) for k, v in params.items()
        if k != 'sign' and v not in (None, '')
    )
    parts = []
    for k, v in items:
        if isinstance(v, (dict, list)):
            v = json.dumps(v, separators=(',', ':'))
        parts.append(f'{k}={v}')
    raw = '&'.join(parts) + f'&key={secret}&salt={salt}'
    return hashlib.md5(raw.encode()).hexdigest()

📥 统一返回

所有接口（无论成功失败）均返回如下结构：

{
  "code": 200,           // 200=成功，其它=失败（详见错误码表）
  "msg":  "ok",          // 提示信息
  "time": 1700000000,    // 服务器时间戳
  "data": { /* 业务数据，可能为 null */ }
}

加密返回（enc=1）

{
  "code": 200,
  "msg": "ok",
  "time": 1700000000,
  "encrypted": 1,
  "data": "xxxxxbase64url..."
}

解密：RC4(base64UrlDecode(data), app_secret) 后再 JSON.parse()。

⚠️ 错误码速查

范围	含义
200	成功
400 / 401 / 403 / 404 / 405	参数错误 / 未登录 / 权限不足 / 资源不存在 / 请求方式错误
4001~4099	加密 / 签名 / nonce 相关
4101~4108	邮箱验证码相关
4201~4299	注册相关
4301~4399	登录相关
4401~4499	心跳 / 会话相关
4501~4599	充值相关
4601~4699	消费相关
4701~4799	改密相关
4801~4899	重置密码 / 修改昵称
4901~4999	用户信息
5001~5399	用户配置文件相关
5401~5499	聊天 - 发送
5601~5799	用户发布相关
5801~5899	反馈相关
500	服务器内部错误

🔑 公钥获取

POST /api/public_key.php 无需签名

获取服务端 RSA 2048 公钥（PEM 格式），用于 payload_rsa 加密敏感参数。

因为客户端尚未握手，此接口不需要签名也不需要 app_key。

响应示例

{
  "code": 200,
  "data": {
    "public_key": "-----BEGIN PUBLIC KEY-----\nMII...IDAQAB\n-----END PUBLIC KEY-----"
  }
}

🚀 应用初始化

POST /api/app_init.php

客户端首次启动调用，获取应用版本/公告/强制更新等信息。

响应字段

字段	类型	说明
name	string	应用名称
version	string	当前版本号
latest_version	string	最新版本号
force_update	int	0=可选更新，1=强制更新
download_url	string	新版下载链接
notice	string	系统公告
server_time	int	服务器时间戳

📦 应用列表

POST /api/app_list.php

获取所有启用的应用列表，便于客户端"切换应用"。

响应示例

{
  "data": {
    "apps": [
      { "id": 1, "name": "示例应用", "app_key": "abc123", "version": "1.0", "notice": "公告" }
    ]
  }
}

🏠 主页内容

POST /api/home.php

动态拉取主页文案、特性列表、自定义 HTML、客服购卡链接等运营内容。

字段	说明
site_name	站点名
title	主标题
subtitle	副标题
features	特性卡片数组（icon/title/desc）
home_html	自定义 HTML 区块
buy_card_url	购卡跳转链接

📧 发送邮箱验证码

POST /api/send_email_code.php

参数	必填	说明
email	是	QQ 邮箱（默认仅允许 @qq.com）
purpose	是	`register` 或 `reset`

成功返回 { ttl: 300, cooldown: 60 }。

⚠️ 后台需先配置 SMTP（系统设置 → 邮件 SMTP），否则会返回发送失败。

👤 用户注册

POST /api/register.php

参数	必填	说明
username	是	账号（4-32 位字母/数字/下划线）
password	是	密码（≥6 位）
email	是	QQ 邮箱
code	是	邮箱验证码（6 位）

成功返回 { user_id, username }。

🔐 用户登录

POST /api/login.php

参数	必填	说明
username	是	账号
password	是	密码
device	否	设备名称（如 "PC1"）
bind_code	否	机器码（首次登录会绑定，再次登录必须一致）

响应示例

{
  "data": {
    "token": "xxxxx...",
    "token_expire": 1701000000,
    "user": {
      "username": "demo",
      "email": "12345@qq.com",
      "points": 0,
      "expire_at": "2024-12-31 23:59:59",
      "expire_left": 86400,
      "remain_count": 5,
      "is_expired": false
    }
  }
}

🚪 退出登录

POST /api/logout.php

使当前 token 立即失效。

参数	必填	说明
token	是	登录态 token

💓 心跳保活

POST /api/heartbeat.php 建议 60s 一次

客户端定时调用，用于保活 + 刷新最新积分/到期时间/剩余次数。

参数	必填	说明
token	是	登录态 token

如果返回 4401/4402，表示 token 失效，应跳转到登录页。

👤 用户信息

POST /api/user_info.php

获取当前登录用户的完整资料（含昵称、QQ、注册时间、绑定设备等）。

参数	必填	说明
token	是	登录态 token

✏️ 修改昵称

POST /api/update_nickname.php

参数	必填	说明
token	是	登录态 token
nickname	是	新昵称（2-20 字符）

🔒 修改密码

POST /api/change_password.php

参数	必填	说明
token	是	登录态 token
old_password	是	旧密码
new_password	是	新密码（≥6 位）

🔓 找回密码

POST /api/reset_password.php

调用前请先调用 send_email_code.php?purpose=reset 发送验证码。

参数	必填	说明
email	是	注册邮箱
code	是	验证码
new_password	是	新密码

💳 卡密充值

POST /api/recharge.php

参数	必填	说明
token	是	登录态 token
card_no	是	卡号（含前缀）

响应示例

{
  "data": {
    "detail": "时效充值 +60 分钟",
    "expire_at": "2024-01-01 12:30:00",
    "expire_left": 3600,
    "remain_count": 10,
    "points": 100
  }
}

💰 业务消费

POST /api/consume.php

参数	必填	说明
token	是	登录态 token
mode	是	`time`=检查时效 / `count`=扣次数 / `points`=扣积分
amount	否	扣减数量（默认 1）

📁 配置列表

POST /api/config_list.php

获取当前用户在当前应用下的所有配置文件（按 ID 倒序，最多 200 条）。

参数	必填	说明
token	是	登录态 token

响应示例

{
  "data": {
    "allow_user_upload": 1,
    "list": [
      { "id": 10, "name": "my-config.json", "size": 1024, "source": 0,
        "created_at": "2024-01-01 12:00:00" }
    ]
  }
}

📄 配置详情

POST /api/config_get.php

参数	必填	说明
token	是	登录态 token
id	是	配置 ID

返回完整 content 字段（仅本人可读）。

📤 上传 / 更新配置

POST /api/config_upload.php

参数	必填	说明
token	是	登录态 token
name	是	配置名称（≤100 字符）
content	是	配置内容（≤1MB）
source	否	0=用户上传（默认）；1=API 上传
id	否	提供则更新已有配置，否则新建

⚠️ source=0（用户手动上传）需要后台开关 allow_user_upload_config=1 允许，否则返回 5104。

🗑️ 删除配置

POST /api/config_delete.php

参数	必填	说明
token	是	登录态 token
id	是	配置 ID（仅能删除自己的）

💬 聊天消息列表

POST /api/chat_list.php 无需登录

拉取当前应用的聊天室消息（最多 100 条），按 ID 升序。建议轮询调用。

参数	必填	说明
since_id	否	只拉取 ID 大于此值的新消息（用于增量轮询）

响应示例

{
  "data": {
    "open": 1,                          // 聊天室是否开放
    "list": [
      { "id": 123, "username": "demo", "nickname": "小明",
        "content": "大家好", "created_at": "2024-01-01 12:00:00" }
    ]
  }
}

📨 发送聊天消息

POST /api/chat_send.php

参数	必填	说明
token	是	登录态 token
content	是	消息内容（≤500 字）

限制

每用户 3 秒最多 1 条；每 60 秒最多 12 条
禁言用户无法发送（错误码 5405）
包含敏感词的消息会被拒绝（错误码 5408）
聊天室关闭时无法发送（错误码 5402）

📋 公开发布列表

POST /api/post_list.php 无需登录

已通过审核的用户发布信息列表（公开），按审核通过时间倒序。

参数	必填	说明
page	否	页码（默认 1）
page_size	否	每页数量（默认 30，最大 100）

响应示例

{
  "data": {
    "page": 1, "page_size": 30, "total": 156,
    "list": [
      { "username": "demo", "title": "标题", "coordinate": "120.5,30.2",
        "content": "详情", "upload_time": "...", "approved_time": "..." }
    ]
  }
}

📝 我的发布

POST /api/post_my.php

当前用户上传的所有发布（含未通过/已驳回），最多 100 条。

参数	必填	说明
token	是	登录态 token

响应字段

字段	说明
id	发布 ID
title / coordinate / content	名称 / 坐标 / 详情
status	0=待审核，1=已通过，2=已驳回
review_at	审核时间
reject_reason	驳回原因（status=2 时有值）

📮 创建发布

POST /api/post_create.php

用户上传新的发布信息（待审核状态）。提交后系统会自动给管理员邮箱发送通知。

参数	必填	说明
token	是	登录态 token
title	是	标题（≤100 字符）
coordinate	是	坐标信息（≤100 字符）
content	否	详情内容（≤2000 字符）

每用户每小时最多 10 条；提交后状态为 "待审核"。

💌 提交反馈

POST /api/feedback.php

用户提交反馈意见（无需登录也可，但登录后会自动关联用户身份）。

参数	必填	说明
content	是	反馈内容（5~2000 字符）
token	否	登录态 token（可选，登录后自动关联）
email	否	联系邮箱（用于回复）

每 IP 每小时最多 5 条反馈。提交后系统会通知管理员邮箱。

💁 客服列表

POST /api/cs_list.php 无需登录

获取所有启用的客服渠道（QQ/微信/在线客服等），按 sort 排序。

响应示例

{
  "data": {
    "buy_card_url": "https://shop.example.com",
    "list": [
      { "id": 1, "name": "QQ客服", "icon": "🐧",
        "value": "12345678", "link": "https://qm.qq.com/..." }
    ]
  }
}