飞书如何生成二维码？常见方法有哪些？

Question

如何在飞书中生成二维码？常见方法包括通过飞书文档、群聊分享、日程邀请等场景自动生成二维码。但开发者常遇到的问题是：使用飞书开放平台API生成二维码时，获取ticket后无法正确拼接二维码图片链接，导致二维码无法扫描或过期失效。主要原因是未按官方格式拼接URL（如https://open.feishu.cn/open-apis/qrconnect/v1/qrconnect?ticket=xxx），或忽略了ticket的时效性（通常为300秒）。此外，部分企业自建应用因权限配置不当，调用接口返回“invalid app ticket”错误。该如何正确调用飞书二维码接口并保障二维码可用性？

Answer 1

一、飞书二维码生成的常见方式与使用场景

在日常办公和系统集成中，飞书提供了多种便捷的二维码生成方式，适用于不同的协作需求。以下是几种常见的非开发型二维码生成方法：

• 飞书文档分享：打开任意文档，点击右上角“分享”按钮，选择“生成二维码”，即可获得访问该文档的专属二维码。
• 群聊邀请码：在群设置中启用“群二维码”，成员可通过扫描加入，支持设置有效期或人数限制。
• 日程邀请：创建会议日程时，添加参会人并生成共享链接后，系统自动提供二维码形式，便于外部人员快速加入。
• 个人名片：用户可在个人主页生成包含联系方式、职位信息的二维码，用于商务交流。

这些功能均基于飞书客户端内置逻辑实现，无需调用API，适合普通用户或轻量级集成场景。

二、开发者视角：通过飞书开放平台API生成二维码

对于企业级应用集成，需使用飞书开放平台提供的 qrconnect/v1/qrconnect 接口动态生成登录或授权二维码。其核心流程如下：

1. 应用向飞书服务请求获取临时 ticket；
2. 将 ticket 拼接为标准格式 URL；
3. 将 URL 转换为二维码图像供客户端扫描；
4. 监听扫码状态回调，完成后续认证流程。

关键接口地址为：
POST https://open.feishu.cn/open-apis/qrconnect/v1/ticket/get

三、典型问题分析：为何二维码无法扫描或失效？

问题现象	可能原因	技术影响
二维码图片无法显示	URL拼接错误，缺少协议头或参数编码不当	HTTP 400 错误，资源未找到
扫码后提示“无效ticket”	Ticket已过期（默认300秒）或重复使用	认证失败，需重新获取
返回“invalid app ticket”	应用权限未开启SSO或App Ticket配置错误	接口拒绝响应
扫码无反应	未正确订阅扫码事件回调	状态无法同步

四、正确调用步骤详解

以下为调用飞书二维码接口的标准流程：

POST /open-apis/qrconnect/v1/ticket/get HTTP/1.1
Host: open.feishu.cn
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "app_id": "cli_abc123xxxx",
  "redirect_uri": "https://yourdomain.com/callback",
  "state": "xyz789"
}

成功响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "ticket": "tkt-gH6sK2lVnXQYz...",
    "expire_in": 300
  }
}

随后构造二维码链接：

https://open.feishu.cn/open-apis/qrconnect/v1/qrconnect?ticket=tkt-gH6sK2lVnXQYz...

五、保障二维码可用性的关键技术实践

为确保生成的二维码稳定可用，建议遵循以下最佳实践：

• 使用 HTTPS 协议确保传输安全；
• 对 ticket 进行 URL 编码处理，防止特殊字符解析异常；
• 在前端页面设置倒计时机制，在 ticket 过期前刷新二维码；
• 缓存 access_token 并监控其有效期（通常为2小时），避免频繁申请；
• 在飞书开发者后台启用“扫码登录”权限，并确认应用类型支持 Web 应用；
• 部署消息订阅服务以接收 scan_event 回调事件；
• 记录 ticket 生成时间戳，用于追踪调试；
• 采用 CDN 加速二维码图片渲染，提升用户体验；
• 实施熔断机制，当接口调用失败时自动重试或降级；
• 定期审计应用权限配置，防止因策略变更导致中断。

六、完整流程图：从请求到扫码认证的全链路

graph TD
    A[前端触发生成二维码] --> B{检查缓存中的有效ticket}
    B -- 存在且未过期 --> C[直接返回二维码URL]
    B -- 不存在或已过期 --> D[调用API获取新ticket]
    D --> E[拼接标准二维码链接]
    E --> F[生成Base64图片或PNG下载地址]
    F --> G[前端展示二维码]
    G --> H[用户扫码]
    H --> I[飞书服务器验证ticket]
    I --> J{是否首次扫描?}
    J -- 是 --> K[推送scan_event事件至回调地址]
    J -- 否 --> L[等待用户确认授权]
    L --> M[跳转redirect_uri并携带code]
    M --> N[后端换取user_access_token]