飞书插件
本指南适用于飞书企业自建应用。需要能管理应用、申请权限、设置通讯录范围并发布应用的账号。当前插件连接 open.feishu.cn，不要混用 Lark 国际版凭据与域名。
1. 创建应用并记录凭据
- 登录飞书开放平台，创建企业自建应用
- 在凭证与基础信息中记录 App ID 和 App Secret
- 添加 网页应用 能力；需要消息推送时，再添加 机器人 能力
- 在权限管理设置通讯录数据权限范围，并在应用发布配置中设置可用范围，包含测试成员与目标部门
2. 申请接口与字段权限
| 功能 | 需要的权限或设置 | 实际接口 |
|---|---|---|
| 通讯录 | 申请应用身份的通讯录读取权限，例如 以应用身份读取通讯录（contact:contact:readonly_as_app）；若控制台要求细分权限，按右侧各接口的权限要求申请 | GET /contact/v3/scopes、/contact/v3/departments/{id}、/contact/v3/departments/{id}/children、/contact/v3/users/find_by_department、/contact/v3/users/{id} |
| 用户组授权 | 使用用户组作为通讯录范围时，额外申请 contact:group:readonly | 用户组成员查询 |
| 登录邮箱 | contact:user.email:readonly | 授权请求与 /authen/v1/user_info 的邮箱字段 |
| 登录企业成员资料 | contact:user.employee:readonly | 授权请求与登录用户信息 |
| 通讯录邮箱、手机号等 | 按需开通对应字段权限，并确认企业已填写资料；应用身份读取与用户授权登录的权限分别检查 | 通讯录用户详情 |
| 个人消息 | 添加机器人能力，并申请 以应用的身份发消息（im:message:send_as_bot） | POST /im/v1/messages?receive_id_type=open_id |
上表接口路径相对于 https://open.feishu.cn/open-apis。需要用户登录授权的权限与以 tenant_access_token 读取通讯录的应用权限不同，不能相互替代。
申请完权限和数据范围后，创建并发布应用版本，完成企业管理员审批。后续修改权限、机器人能力或可用范围，也要按飞书后台流程发布生效。
组织架构同步修改的是 Soln 内部数据，无需申请修改飞书通讯录的权限。
3. 安装 Soln 插件
- 在 集成 → 应用 → 插件 安装飞书插件，填写 App ID 和 App Secret
- 选择用于登录的 邮箱字段：默认是
enterprise_email（企业邮箱）；如果企业实际使用普通邮箱，选择email。插件按选中的字段识别成员，不会自动切换 - 身份映射方式通常选择 匹配租户内启用成员的邮箱。使用 显式邮箱白名单 时还需填写白名单；白名单不创建成员
- 安装启用后，在 应用信息 复制 身份提供方重定向 URL 和 单点登录入口地址
4. 配置重定向与工作台入口
| Soln 提供的值 | 飞书侧填写位置 |
|---|---|
| 身份提供方重定向 URL | 安全设置 → 重定向 URL，填写完整 URL |
| 单点登录入口地址 | 网页应用的工作台主页或应用主页，分别设置后台要求的桌面端、移动端入口 |
例如租户地址是 https://workspace.example.com，插件回调通常为 https://workspace.example.com/plugins/feishu/callback。以 Soln 展示的值为准，不要漏掉路径，也不要将回调 URL 当作工作台主页。
安装会创建企业单点登录连接，在 账户中心 → 单点登录 检查其启用状态。使用可用范围内的飞书成员，从工作台入口登录；选定邮箱字段必须能匹配 Soln 中启用成员的邮箱。登录不会创建新成员。
5. 获取通讯录和推送消息
- 在插件 组织映射 点击 获取通讯录，检查组织、部门、用户列表
- 使用邮箱等唯一字段自动绑定，或手动绑定；如果只授权了个别用户，可能只有用户列表有数据，不能据此判断部门读取正常
- 进入 消息推送 → 推送配置，为业务应用新增配置，选择允许的消息模板并启用
- 产生一条新的审批或普通提醒，在 消息日志 与飞书应用机器人单聊中核对结果
飞书通知使用当前应用范围内的 open_id，不能拿另一个应用的 open_id、user_id 或 union_id 替换。无需填写钉钉 AgentId，也无需群机器人 Webhook。
当前发送机器人卡片和 Soln 详情链接，不创建飞书三方审批或任务。消息与组织同步的完整说明见企业身份插件使用指南。
飞书列表中的字段怎么读
固定列、搜索、分页、下载、绑定和消息日志的详细用法见企业身份插件列表与操作说明。飞书字段受应用数据范围与字段权限限制，并非每家企业都会返回下列所有字段。
组织与部门列表
组织列表使用可读取的根部门信息，根 ID 为 0；授权部分成员或部门时根组织可能不可见，不能把“暂无组织”直接理解为企业没有组织。
| 字段编码 | 含义与值 |
|---|---|
open_department_id / department_id | 飞书系统部门 ID / 自定义部门 ID；当前插件按 open_department_id 遍历，不能把两种 ID 混用 |
name / i18n_name | 部门名称 / 国际化名称，如 zh_cn、en_us、ja_jp；不是三个不同部门 |
parent_department_id | 上级部门 ID，按本次查询的部门 ID 类型返回 |
leader_user_id / leaders | 部门主管 / 负责人数组；leaderType 为 1 主负责人、2 副负责人，leaderID 为负责人 ID |
order / chat_id | 部门排序 / 部门群 ID，不是个人消息接收 ID |
member_count / primary_member_count | 含子部门成员数 / 主属成员数，不是 Soln 已激活席位 |
status.is_deleted | 部门删除标记，布尔值显示“是、否”；不等于可以跳过内部依赖直接删除 |
unit_ids / department_hrbps | 所属单位 ID / 部门 HRBP 用户 ID 列表 |
group_chat_employee_types | 部门群允许的人员类型；人员类型编码见用户表 |
用户列表
| 字段编码 | 含义与值 |
|---|---|
open_id / user_id / union_id | 应用范围用户 ID / 用户 ID / 开发商范围 ID；当前插件绑定和个人卡片接收使用本应用的 open_id |
name / en_name / nickname | 姓名 / 英文名 / 别名；重名不应直接绑定 |
email / enterprise_email | 邮箱 / 企业邮箱；列表自动绑定规则与插件登录邮箱字段是分别配置的 |
employee_no / job_title | 员工工号 / 职务 |
department_ids / orders | 所属部门 ID / 各部门排序信息；orders[].is_primary_dept 表示是否主部门 |
status.is_activated | 是否激活，显示“已激活、未激活”；不代表 Soln 已启用 |
status.is_frozen / is_frozen | 是否暂停使用，布尔值显示“是、否” |
status.is_resigned / status.is_exited / status.is_unjoin | 是否离职 / 主动退出 / 尚未加入，不要将多个标记合并当作一个状态数字 |
is_tenant_manager | 是否飞书租户超级管理员，不授予 Soln 管理权限 |
gender | 0 保密、1 男、2 女、3 其他 |
employee_type | 1 正式员工、2 实习生、3 外包、4 劳务、5 顾问 |
join_time | 入职时间，秒时间戳会格式化为时间 |
avatar / avatar_key | 头像地址对象 / 文件 Key；avatar_72、avatar_240、avatar_640、avatar_origin 是不同尺寸地址 |
mobile / mobile_visible | 手机号 / 是否可见；不可见或未授权时可能缺失 |
leader_user_id / dotted_line_leader_user_ids | 直属上级 / 虚线上级用户 ID |
custom_attrs | 自定义字段数组；包括 id、type、value，不是可以直接复制成内部成员 ID 的对象 |
custom_attrs[].type | TEXT 文本、HREF 网页、ENUMERATION 枚举、PICTURE_ENUM 图片、GENERIC_USER 引用人员；详情中展开相应值 |
assign_info | 飞书产品席位信息，如许可标识、产品名、起止时间，不是 Soln 订阅席位 |
department_path | 部门路径与国际化名称等嵌套信息，可在详情抽屉阅读 |
city / country / work_station / geo | 工作城市 / 国家地区 / 工位 / 数据驻留地 |
例如列表出现 status.is_frozen 为“是”，先核对外部成员状态及内部成员启用状态，不要把绑定状态“已绑定”误认为可以正常接收消息。
常见问题
| 现象 | 处理 |
|---|---|
| 只有 1 位用户，没有组织和部门 | 查看通讯录授权范围是否只包含该用户；需要部门树时授权对应部门，需要完整树时授权全员或根范围 |
| 能读取根部门，但同步不执行删除 | 根部门可读不代表全企业授权；检查通讯录授权范围，只有插件确认完整范围时才处理外部缺失部门 |
| 开通了通讯录权限仍提示无权限 | 检查应用身份权限、通讯录数据范围、版本是否发布和管理员是否批准；再看失败接口要求 |
| 邮箱字段为空或登录不匹配 | 检查字段权限、企业邮箱资料，以及插件选择的 enterprise_email 或 email 是否正确 |
| 消息失败或接收人不可用 | 检查机器人能力、im:message:send_as_bot、发布状态、接收人可见范围及当前应用的 open_id |
| 点消息链接后要求登录 | 详情页仍需 Soln 登录；从单点登录入口完成登录，并确认成员拥有业务权限 |
| 域名更换后登录失败 | 更新租户公开地址、飞书重定向 URL 和工作台主页，使用新入口重新测试 |