接口名称：用户登录

请求URL：/api/v1/auth/login

请求方法：POST

内容类型：application/json

请求参数（JSON Body）

• username: string   必填   用户名（手机号或邮箱）
• password: string   必填   密码（SHA256加密后）
• captcha_token: string   选填   验证码token（触发风控时必填）
• device_info: object   选填   设备信息
      • device_id: string   必填   设备唯一标识
      • os: string   必填   操作系统
      • app_version: string   必填   APP版本

成功响应（HTTP 200）

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user_id": "u_10086",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx",
    "expires_in": 7200,
    "refresh_token": "rt_xxxxx",
    "user_info": {
      "nickname": "张三",
      "avatar": "https://cdn.example.com/avatar/u10086.png",
      "phone": "138****8000"
    }
  },
  "timestamp": 1711456789012
}

错误响应（HTTP 400）

{
  "code": 400102,
  "message": "密码错误，剩余尝试次数：2",
  "data": null,
  "timestamp": 1711456789012
}

错误码说明

• 400101   用户名不存在
• 400102   密码错误
• 400103   验证码失效
• 403001   账号已被冻结
• 429001   请求过于频繁
• 500000   服务端内部错误

调用示例（cURL）

curl -X POST https://api.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d "{ \"username\": \"13800138000\", \"password\": \"5f4dcc3b5aa765d61d8327deb882cf99\", \"device_info\": { \"device_id\": \"d_7a3b9c\", \"os\": \"Android 13\", \"app_version\": \"3.2.1\" } }"

注意事项

• 密码需客户端SHA256加密，禁止明文传输
• Token使用：Header携带 Authorization: Bearer <token>
• Token有效期2小时，过期调用 /auth/refresh 续期
• 连续失败3次触发滑块验证码
• 时间戳为毫秒级Unix时间戳（UTC+8）
• 文档版本：v1.2.0   更新日期：2026-03-27