接口说明

本文档为独立登录注册系统提供全维度、可落地的接入指南，覆盖从环境准备、接口调用到异常处理的全流程，适配各类编程语言（Java/Python/Go/Node.js/C#/PHP 等）的开发场景。可用于独立APP/网站/游戏/小程序使用，可自定义登录注册等页面，提供更高的品牌形象。

此接口仅为合作机构、下游、旗下团队平台、定制项目使用。如您有特殊情况或申请使用客户端，请联系邮箱service@rutno.com

接入前准备

1. 必备信息

联系 Rutno 管理员获取以下核心信息（务必妥善保管）：表格

2. 开发环境要求

• 支持 HTTP/HTTPS 请求的编程语言 / 框架
• 支持 JSON 解析（所有接口均使用 JSON 交互）
• 网络环境可访问 API Base URL（生产环境建议配置白名单）

通用说明

1. 请求规范

表格

2. 响应规范

所有接口返回统一 JSON 结构，客户端需先校验 status 字段再处理数据：

成功响应（通用）

json

{
  "status": "success",
  "message": "ok", // 成功描述，固定为 "ok"
  "data": {} // 业务数据，不同接口结构不同
}

失败响应（通用）

json

{
  "status": "error",
  "message": "账号或密码错误", // 可直接展示给用户的错误描述
  "data": [] // 失败时为空数组
}

3. 鉴权机制

表格

⚠️ 重要：appkey 仅允许在服务端调用时使用，禁止在前端（H5/APP/ 小程序）代码中明文暴露。

API 接口详情

1. 登录

接口用途

验证用户账号密码，返回用户基础信息和会话凭证（session_token）。

接口信息

• 地址：{API Base URL}/account-api/login/api_login_v2
• 方法：POST
• Content-Type：application/json

请求参数

表格

响应数据（data 字段）

json

{
  "account_id": "100001", // 用户唯一ID（核心字段，后续接口必传）
  "username": "testuser", // 用户名
  "nickname": "测试用户", // 昵称
  "avatar": "https://avatar.rutno.com/100001.png", // 头像URL（空则返回默认值）
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // 会话Token（有效期2小时）
  "created_at": "2024-01-01 12:00:00" // 注册时间（格式：YYYY-MM-DD HH:MM:SS）
}

错误场景示例

json

{
  "status": "error",
  "message": "账号或密码错误",
  "data": []
}

2. 注册

接口用途

完成用户注册全流程，包含人机验证→短信验证码→提交注册三个核心环节（拆分为 4 个步骤）。

接口信息

• 地址：{API Base URL}/account-api/register/api_register_v2
• 方法：POST
• Content-Type：application/json

2.1 获取验证题（人机验证初始化）

请求参数

表格

响应数据（data 字段）

json

{
  "token": "captcha_123456789", // 验证题Token（有效期5分钟）
  "question": "1 + 2 = ?" // 算术题/滑块验证等（前端展示给用户）
}

2.2 验证题目（校验用户答案）

请求参数

表格

响应结果

• 成功：{"status":"success","message":"ok","data":[]}
• 失败：{"status":"error","message":"答案错误，请重新输入","data":[]}

2.3 发送注册验证码（短信）

请求参数

表格

响应结果

• 成功：{"status":"success","message":"验证码已发送，请注意查收","data":[]}
• 失败：{"status":"error","message":"手机号格式错误/验证码发送过于频繁","data":[]}

2.4 提交注册（最终步骤）

请求参数

表格

响应数据（data 字段）

json

{
  "account_id": "100002", // 新注册用户ID
  "username": "13800138000", // 默认用户名（手机号）
  "nickname": "用户13800138000" // 默认昵称
}

3. 找回密码

接口用途

通过手机号验证码重置用户密码，分 3 个步骤。

接口信息

• 地址：{API Base URL}/account-api/repass/api_repass_v2
• 方法：POST
• Content-Type：application/json

3.1 发送验证码（短信）

请求参数

表格

响应结果

• 成功：{"status":"success","message":"验证码已发送","data":[]}
• 失败：{"status":"error","message":"手机号未注册","data":[]}

3.2 校验验证码

请求参数

表格

响应结果

• 成功：{"status":"success","message":"验证码验证通过","data":[]}
• 失败：{"status":"error","message":"验证码错误或已过期","data":[]}

3.3 重置密码

请求参数

表格

响应结果

• 成功：{"status":"success","message":"密码重置成功","data":[]}
• 失败：{"status":"error","message":"密码格式不符合要求","data":[]}

4. 换绑手机号

接口用途

用户登录状态下更换绑定的手机号，需验证原手机号 + 新手机号双验证码。

接口信息

• 地址：{API Base URL}/account-api/rephone/api_rephone_v2
• 方法：POST
• Content-Type：application/json

4.1 验证原手机号 - 发送验证码

请求参数

表格

响应结果

• 成功：{"status":"success","message":"验证码已发送","data":[]}
• 失败：{"status":"error","message":"会话已过期，请重新登录","data":[]}

4.2 验证原手机号 - 提交验证

请求参数

表格

响应结果

• 成功：{"status":"success","message":"原手机号验证通过","data":[]}
• 失败：{"status":"error","message":"验证码错误","data":[]}

4.3 验证新手机号 - 发送验证码

请求参数

表格

响应结果

• 成功：{"status":"success","message":"验证码已发送","data":[]}
• 失败：{"status":"error","message":"新手机号已被注册","data":[]}

4.4 确认换绑（最终步骤）

请求参数

表格

响应结果

• 成功：{"status":"success","message":"手机号换绑成功","data":[]}
• 失败：{"status":"error","message":"验证码已过期，请重新获取","data":[]}

5. 获取用户信息

接口用途

根据用户 ID / 用户名查询用户详细信息，支持按需获取扩展信息（等级 / 勋章等）。

接口信息

• 地址：{API Base URL}/account-api/user/api_user_get_v2
• 方法：GET
• Content-Type：application/json

请求参数（URL 参数）

表格

响应数据（data 字段）

json

{
  "user": {
    "id": "100001",
    "account_id": "100001",
    "username": "testuser",
    "nickname": "测试用户",
    "avatar": "https://avatar.rutno.com/100001.png",
    "bio": "这个人很懒，什么都没写", // 个性签名
    "phone": "138****8000", // 手机号（脱敏）
    "email": "test***@rutno.com", // 邮箱（脱敏）
    "created_at": "2024-01-01 12:00:00"
  },
  "location": { // 仅userplace=true时返回
    "latitude": "39.908823", // 纬度
    "longitude": "116.397470" // 经度
  },
  "level": { // 仅lv=true时返回
    "level": 5, // 等级
    "name": "黄金会员", // 等级名称
    "exp": 1500, // 当前经验值
    "next_exp": 2000 // 升级所需经验值
  },
  "medals": [ // 仅medal=true时返回
    {
      "id": "medal_001",
      "name": "新人勋章",
      "icon": "https://medal.rutno.com/001.png",
      "obtained_at": "2024-01-01 12:00:00"
    }
  ],
  "titles": [ // 仅title=true时返回
    {
      "id": "title_001",
      "name": "萌新",
      "color": "#FFFFFF"
    }
  ]
}

错误码规范

接口返回的 message 字段为用户可读的错误描述，以下是常见错误类型及处理建议：表格

安全最佳实践

1. AppKey 保护：仅在服务端存储和使用 AppKey，前端仅传递 AppID，所有接口调用通过服务端中转。
2. 密码处理：客户端密码传输建议做 HTTPS 加密，服务端可对密码做二次哈希后存储（接口接收明文由统一认证系统处理）。
3. Token 管理：session_token 需存储在客户端安全区域（如 APP 的安全存储、Web 的 HttpOnly Cookie），避免 localStorage 明文存储。
4. 请求校验：所有接口请求需校验 status 字段，失败时根据 message 友好提示用户，避免直接暴露接口细节。
5. 频率限制：客户端需对验证码发送、登录失败等操作做频率限制（如 5 分钟内最多 5 次），避免触发系统风控。

完整请求示例（Python）

以下是 Python 调用登录接口的完整示例，其他接口可参考此模板：python运行

import requests
import json

# 配置信息
API_BASE_URL = "https://id.rutno.com"
APPID = "你的AppID"
APPKEY = "你的AppKey"

def user_login(identifier, password, ip_address=None, user_agent=None):
    """
    用户登录接口调用
    :param identifier: 账号（手机号/用户名/邮箱）
    :param password: 密码
    :param ip_address: 客户端IP
    :param user_agent: 客户端UA
    :return: 登录结果（dict）
    """
    # 接口地址
    url = f"{API_BASE_URL}/account-api/login/api_login_v2"
    
    # 请求参数
    params = {
        "appid": APPID,
        "appkey": APPKEY,
        "identifier": identifier,
        "password": password
    }
    # 可选参数
    if ip_address:
        params["ip_address"] = ip_address
    if user_agent:
        params["user_agent"] = user_agent
    
    # 发送请求
    try:
        response = requests.post(
            url=url,
            headers={"Content-Type": "application/json"},
            data=json.dumps(params),
            timeout=10
        )
        # 解析响应
        result = response.json()
        return result
    except Exception as e:
        return {"status": "error", "message": f"请求失败：{str(e)}", "data": []}

# 调用示例
if __name__ == "__main__":
    login_result = user_login(
        identifier="13800138000",
        password="Pass123456",
        ip_address="192.168.1.100",
        user_agent="Python/3.9 requests/2.31.0"
    )
    print(login_result)
    # 处理登录结果
    if login_result["status"] == "success":
        print(f"登录成功！用户ID：{login_result['data']['account_id']}")
        print(f"会话Token：{login_result['data']['session_token']}")
    else:
        print(f"登录失败：{login_result['message']}")

常见问题

Q1：接口返回 "status":"error" 但 message 为空？

A1：通常是请求格式错误（如 Content-Type 不匹配、参数类型错误），建议检查请求头和参数格式，确保为 JSON 字符串。

Q2：验证码发送成功但收不到？

A2：可能是手机号脱敏 / 运营商拦截，可检查手机号是否正确，或联系 Rutno 管理员核查短信通道。

Q3：session_token 有效期是多久？

A3：默认 2 小时，过期后需重新登录。客户端可在接口返回 "会话已过期" 时自动引导用户重新登录。

Q4：获取用户信息接口需要鉴权吗？

A4：基础信息查询无需鉴权，如需获取敏感信息（如完整手机号 / 邮箱），需在请求中携带 session_token 做二次验证（联系管理员开启）。

总结

1. 核心鉴权：所有写入类接口需携带 appid + appkey，用户操作类接口（换绑手机号）需额外验证 account_id + session_token。
2. 流程规范：注册 / 找回密码 / 换绑手机号均为多步骤流程，需严格按步骤传递 token / 验证码，且每步有有效期限制。
3. 安全原则：AppKey 仅服务端使用，敏感信息（session_token）需安全存储，所有请求必须使用 HTTPS 加密传输。