1. 接入三方 Token

• token 格式要求及对接配置位置

# 头部/Header

{
  "typ": "JWT",
  "alg": "HS256"
}

# 载荷/Payload

{
  "username": "test1008",
  "nickname": "张三", // 可选，昵称
  "id": 1008,
  "iss": "localhost:2999", // 发放方
  "aud": "localhost:2999", // 接收方
  "iat": 1763223109,  // 签发时间
  "nbf": 1763223109, // 生效时间
  "exp": 1794759109, // 过期时间
  "jti": "1008_user" // 格式要求：{id}_user
}

# 对接生成/配置位置 后端项目/.env 文件 。更改后 后端需要重启项目

# JWT 密钥 32位
JWT_SECRET = <配置你自己的密钥，不要提交到文档>
# JWT 对称加密算法（HS256, HS384, HS512）
JWT_ALGO = HS256

2. 创建用户

接口地址：POST /home/base/parseUserToken

认证：无

请求参数：

参数名	类型	必填	说明
token	String	是	用户 Token（JWT 格式）

响应示例：

{
  "code": 1,
  "msg": "登录成功"
}

说明：

• 此接口用于通过 JWT Token 创建用户信息
• 如果用户不存在，会自动创建用户（类型为普通用户，user_type=2）
• JWT payload 可选传 nickname，不传时后端按 username 生成默认昵称

3. MiniApp 用户登录

接口地址：POST /home/base/miniAppUserLogin

认证：无

请求参数：

参数名	类型	必填	说明
initData	String	是	MiniApp window.Telegram.WebApp.initData
user_spread_id	Integer	否	用户邀请人 ID；仅首次注册登录用户端时生效

响应示例：

{
  "code": 1,
  "msg": "登录成功",
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  }
}

说明：

• 此接口用于用户端 MiniApp 授权登录
• 后端会校验 initData，校验通过后创建或获取用户
• 用户类型为普通用户，user_type=2
• 如果 用户没有 username，系统会使用 tg_用户ID 作为用户名
• Telegram first_name、last_name 会在首次创建用户或用户昵称为空时写入 nickname
• 登录成功后前端将 access_token 按用户端登录态保存，后续用户端接口使用 Authorization: Bearer {access_token}
• 旧接口 POST /home/base/generateAppToken 已兼容调用此登录逻辑
• 前端从 user_spread_{邀请人ID} 启动参数解析 user_spread_id；已有用户再次打开邀请链接不会改绑

4. 用户注销条件

接口地址：/home/cancellation/check

认证：需要登录

响应示例：

{
  "code": 1,
  "msg": "满足注销条件"
}

错误响应示例：

{
  "code": 0,
  "msg": "用户不存在" // 其余状态公示：存在商铺无法注销，请先注销商户、账户余额不为0，无法注销
}

说明：

• 检查用户是否满足注销条件
• 不满足条件会返回具体原因

5. 用户注销确认

接口地址：/home/cancellation/cancel

认证：需要登录

请求参数：

参数名	类型	必填	说明
reason	String	否	注销原因

响应示例：

{
  "code": 1,
  "msg": "注销成功"
}

说明：

• 注销前会再次检查注销条件
• 注销后会立即返回 注销成功提示，并后台队列清理用户相关数据
• 注销操作不可逆

V3 开发测试账号

新增 POST /home/base/debugAccounts 和 POST /home/base/debugLogin，仅 DEVELOPMENT=1 开放，账号范围 1000–1050。详见 V3账户与访问设置。