Telegram 授权登录接口文档

[用户打开 Mini App]
    ↓
[前端调用 /init?source=miniapp&inviteCode=xxx] → [后端返回 botUsername, inviteCode]
    ↓
[前端获取 WebApp.initData]
    ↓
[前端调用 /callback, 传 initData, inviteCode] → [后端验证, 返回 JWT token]
    ↓
[前端保存 token, 显示用户界面]

[用户点击网页登录]
    ↓
[前端调用 /init?source=web&redirectUrl=xxx&inviteCode=xxx] → [后端返回 authUrl]
    ↓
[前端跳转 authUrl, 用户授权]
    ↓
[Telegram 回调 redirectUrl, 附带 telegramData]
    ↓
[前端调用 /callback, 传 telegramData, inviteCode] → [后端验证, 返回 JWT token]
    ↓
[前端保存 token, 显示用户界面]

/auth/telegram/init：作用：初始化认证，获取必要信息。Mini App 模式：返回 botUsername（如 @battletgmini_bot）和 inviteCode，帮助前端确认机器人和保存邀请码。 Web 模式：返回 authUrl，用于跳转到 Telegram 的 OAuth 页面。

必要性：统一入口，验证 source 和 inviteCode，为后续回调准备。

/auth/telegram/callback：作用：处理 Telegram 回调，验证用户数据（initData 或 telegramData），生成 JWT token。 必要性：完成用户认证，创建或更新用户，返回 token 用于后续操作。

两种模式都需要这两个接口，但：Mini App 模式是静默的，前端直接获取 WebApp.initData 并调用 /callback，无需跳转。 Web 模式需要跳转到 Telegram OAuth 页面，回调后处理 telegramData。

说明：Mini App 模式直接使用 WebApp.initData，无需跳转。 Web 模式需解析 Telegram 回调 URL 中的 telegramData。

基地址: https://api.desigee.vip

认证方式: - 以下接口为匿名访问，无需 JWT token。

1. 初始化 Telegram 认证

  • URL: /auth/telegram/init
  • Method: GET
  • 描述: 初始化 Telegram 认证，支持 Mini App（静默登录）和 Web（网页登录）两种模式。
  • 请求参数: | 参数名 | 类型 | 必填 | 描述 | 示例 | |-------------|--------|------|-------------------------------|--------------------------------| | source | String | 是 | 认证来源（miniapp 或 web） | miniapp 或 web | | redirectUrl | String | 否 | Web 模式回调地址 | https://api.desigee.vip/callback | | inviteCode | String | 否 | 邀请码 | abc12345 |
  • 请求示例:
  • Mini App: bash GET https://api.desigee.vip/auth/telegram/init?source=miniapp&inviteCode=abc12345
  • Web: bash GET https://api.desigee.vip/auth/telegram/init?source=web&redirectUrl=https%3A%2F%2Fapi.desigee.vip%2Fcallback&inviteCode=abc12345
  • 响应示例:
  • Mini App: json { "code": 200, "botUsername": "@battletgmini_bot", "inviteCode": "abc12345" }
  • Web: json { "code": 200, "authUrl": "https://oauth.telegram.org/auth?bot_id=@battletgmini_bot&origin=https%3A%2F%2Fapi.desigee.vip&..." }
  • 错误: json { "code": 400, "message": "Invalid source" }
  • 操作步骤:
  • Mini App:
    1. 调用接口，传入 source=miniapp 和可选 inviteCode。
    2. 保存 inviteCode（localStorage）。
    3. 使用 Telegram WebApp SDK 获取 WebApp.initData。
  • Web:
    1. 调用接口，传入 source=web、redirectUrl 和可选 inviteCode。
    2. 保存 inviteCode（localStorage）。
    3. 跳转到 authUrl，用户在 Telegram 授权。

2. Telegram 认证回调

  • URL: /auth/telegram/callback
  • Method: POST
  • 描述: 处理 Telegram 认证回调，验证用户数据，返回 JWT token。
  • 请求头:
  • Content-Type: application/json
  • 请求体:
  • Mini App: json { "initData": "user=%7B%22id%22%3A123456789%2C%22first_name%22%3A%22John%22%2C%22username%22%3A%22john_doe%22%2C%22auth_date%22%3A1697059200%2C%22hash%22%3A%22abc123...%22%7D", "inviteCode": "abc12345" }
  • Web: json { "telegramData": { "id": "123456789", "first_name": "John", "username": "john_doe", "auth_date": "1697059200", "hash": "abc123..." }, "inviteCode": "abc12345" }
  • 请求示例:
  • Mini App: javascript fetch('https://api.desigee.vip/auth/telegram/callback', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ initData: WebApp.initData, inviteCode: 'abc12345' }) })
  • Web: javascript fetch('https://api.desigee.vip/auth/telegram/callback', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ telegramData: { id: '123456789', first_name: 'John', ... }, inviteCode: 'abc12345' }) })
  • 响应示例: ```json { "code": 200, "data": { "token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "user": { "username": "tg_123456789", "nickName": "John", "sparksBalance": 0, "usdtBalance": 0, "inviteCode": "xyz67890" } } }