钉钉插件
本指南适用于钉钉企业内部应用。需要企业管理员或具备应用开发、权限申请和发布权限的账号。接入后可获取通讯录、绑定成员、推送个人工作通知，并通过钉钉登录 Soln。
1. 创建企业内部应用
- 登录钉钉开放平台，切换到目标企业，进入应用开发并创建企业内部应用
- 为应用启用网页应用能力，填写应用名称和说明
- 在应用凭证页面记录 Client ID（AppKey）、Client Secret（AppSecret）；在应用详情记录 AgentId
- 将测试成员和需要读取的部门加入应用可使用范围与通讯录授权范围
Client ID、Client Secret、AgentId 必须属于同一个企业内部应用。AgentId 不是企业 CorpId，也不是群机器人 Webhook。
2. 按功能申请权限
在应用的 权限管理 中申请。权限获批后，按后台要求创建版本、发布并完成管理员审批；只勾选权限但未发布，可能仍无法调用。
| 功能 | 需要开通的能力 | 插件实际调用 |
|---|---|---|
| 登录基础身份 | 个人权限 Contact.User.Read；授权请求同时包含 openid、corpid | OAuth 授权及 GET /v1.0/contact/users/me |
| 登录邮箱与按邮箱绑定 | 通讯录字段权限 邮箱等个人信息（fieldEmail）；对应成员读取能力 | 根据企业内用户 ID 查询成员详情 |
| 获取部门 | 部门读取权限，包含 qyapi_get_department_list | /auth/scopes、/topapi/v2/department/get、/topapi/v2/department/listsub |
| 获取成员 | 查询部门成员详情、单个成员详情的通讯录读取权限；邮箱等字段另行授权 | /topapi/v2/user/list、/topapi/v2/user/get |
| 消息推送 | 发送工作通知，后台权限标识通常为 qyapi_robot_asyncsend | /topapi/message/corpconversation/asyncsend_v2 |
钉钉会调整权限分组与展示名称。若提示缺少权限，以失败接口文档中的权限要求及后台展示的权限标识为准；不要把个人授权的 Contact.User.Read 当作整个企业通讯录的读取权限。
组织架构同步使用上述读取能力，在 Soln 租户内执行写入，不需要申请“修改钉钉通讯录”权限。
3. 安装 Soln 插件
- 在 集成 → 应用 → 插件 安装钉钉插件，填入 Client ID 和 Client Secret
- 身份映射方式通常选择 匹配租户内启用成员的邮箱；如果选择 显式邮箱白名单，还需填写初始邮箱白名单。白名单不创建 Soln 成员，登录仍需匹配可用成员
- 等待安装和启用完成，进入插件 应用信息，复制 身份提供方重定向 URL 和 单点登录入口地址
通讯录绑定、组织同步和推送操作见企业身份插件使用指南。
4. 配置回调与工作台入口
| Soln 提供的值 | 钉钉侧填写位置 |
|---|---|
| 身份提供方重定向 URL | 应用的安全设置或登录配置中的 重定向 URL / 回调 URL，填写完整 HTTPS URL |
| 单点登录入口地址 | 网页应用的 应用首页地址 和 PC 端首页地址 |
例如租户地址为 https://workspace.example.com，插件回调通常是 https://workspace.example.com/plugins/dingtalk/callback。以 Soln 当前展示的值为准，必须保留路径；不要把回调地址设为应用首页，也不要把应用首页直接指向 /callback。
安装插件会创建对应的企业单点登录连接。在 账户中心 → 单点登录 确认连接启用，使用与 Soln 启用成员邮箱一致的钉钉成员，从工作台入口测试登录。登录不会自动创建成员。
5. 获取通讯录并绑定
- 进入插件 组织映射，点击 获取通讯录
- 检查部门和用户是否覆盖应用授权范围；需要完整树时，将根部门及其下级纳入通讯录授权范围并发布
- 在 用户 → 自动绑定 配置邮箱等唯一字段，或手动绑定已有成员
钉钉插件使用企业内 userid 发送工作通知，不可用 unionid 代替。组织列表中的根 ID 1 只用于根组织映射，不是 CorpId。
6. 发送审批等业务提醒
- 确保已开通工作通知权限，接收人属于应用可见范围，且已绑定有效 Soln 成员
- 进入 消息推送 → 推送配置，新增业务应用配置，并填写第 1 步记录的 AgentId
- 按需选择审批或其他消息模板，保存并在列表中启用
- 新发起一条审批或其他提醒，在 消息日志 查看结果，并在钉钉该应用的工作通知中检查实际消息
当前发送 OA 工作通知卡片，平台可能将顶部文字显示为钉钉应用名称。修改应用名称属于钉钉侧配置，Soln 不能通过消息参数强制替换。无需创建群机器人，也不会创建钉钉原生审批实例。
钉钉列表中的字段怎么读
三个列表的固定列、顶部按钮、绑定弹窗和消息日志操作见企业身份插件列表与操作说明。以下是钉钉特有的 ID 和动态字段；只在平台实际返回时出现。动态属性里的名称和 ID 可能与固定列重复，用于保留接口字段含义。
组织与部门列表
组织列表使用可读取的根部门资料，部门列表展示授权范围内各部门；根部门也可能出现在部门列表。没有根组织时，先检查授权范围。
| 字段编码 | 含义与值 |
|---|---|
dept_id / parent_id | 部门 ID / 上级部门 ID；根部门通常为 1，平台根父级 0 不代表内部组织 UUID |
name / code / source_identifier | 部门名称 / 部门编码 / 来源标识；不是同一个字段，按编码绑定前先确认实际填充值 |
order | 部门排序值，不是层级或成员数 |
member_count / owning_member_count | 含子部门成员数 / 直属成员数，不是 Soln 占用席位数 |
dept_manager_userid_list | 部门负责人 userid 列表，不会自动授予 Soln 角色 |
create_dept_group / auto_add_user / group_contain_sub_dept | 是否创建部门群 / 自动加入 / 部门群是否含子部门；布尔值显示“是、否” |
dept_group_chat_id / org_dept_owner | 部门群 ID / 群主用户 ID；不是消息推送接收人的绑定配置 |
hide_dept / outer_dept | 是否隐藏部门 / 限制通讯录可见范围，和部门停用是不同概念 |
outer_permit_depts / outer_permit_users / user_permits / dept_permits | 可见范围相关的部门或成员 ID；具体可见范围限制仍由钉钉执行 |
auto_approve_apply / emp_apply_join_dept | 是否自动同意加入部门 / 是否允许员工加入部门；不控制 Soln 审批 |
attrs | 部门属性与元数据数组；value 为属性值，rawValue 为原始值，meta.code 为属性编码 |
extention | 平台返回的部门扩展字段，注意这个接口拼写；不是用户的 extension 字段 |
hide_scene_config / outer_scene_config | 隐藏或可见范围限制在单聊框、组织树、搜索、资料页中的生效配置；嵌套属性在详情中查看 |
union_dept_ext / from_union_org | 关联组织部门信息 / 是否来自关联组织，不代表已绑定内部组织 |
tags | 教育部门标签，如 campus 校区、period 学段、grade 年级、class 班级 |
用户列表
| 字段编码 | 含义与值 |
|---|---|
userid / unionid | 企业内用户 ID / 开发商范围用户 ID；当前绑定与工作通知使用 userid |
name / job_number / title | 姓名 / 员工工号 / 职务；名称相同不代表同一人 |
email / org_email | 邮箱 / 企业邮箱；自动绑定时选择实际有值且唯一的那个字段 |
dept_id_list / dept_order | 所属部门 ID 数组 / 部门内排序信息，用户可能属于多个部门 |
active | 钉钉激活标记，显示“已激活、未激活”，与 Soln 成员启用状态分开 |
admin / boss / leader | 是否企业管理员 / 企业老板 / 部门主管，显示“是、否” |
avatar | 头像 URL，列表保留地址，不是本地头像文件 |
mobile / state_code / hide_mobile / telephone | 手机号 / 国际电话区号 / 是否隐藏手机 / 分机号，受权限与资料设置影响 |
hired_date | 入职时间，接口毫秒时间戳会转换为可读时间 |
extension | 成员自定义属性，结构内容在详情抽屉查看 |
exclusive_account / work_place / remark | 是否企业账号 / 办公地点 / 备注 |
例如按 job_number 绑定时，要将其对应到内部实际保存工号的字段，而不是固定认为内部字段一定叫 job_number。可在自动绑定下拉框核对内部字段名称与编码。
常见问题
| 现象 | 处理 |
|---|---|
缺少 qyapi_get_department_list | 申请部门读取权限，发布并确认审批完成，再获取通讯录 |
| 部门或用户不在授权范围 | 同时检查通讯录范围与应用可用范围，确认授权对象包含目标部门和成员；只授权个别成员不会自动获得完整树 |
| 登录有身份，但没有邮箱 | 检查 fieldEmail、企业成员邮箱资料及成员详情读取权限；确认邮箱与 Soln 启用成员一致 |
| 消息发送失败 | 检查 AgentId 是否与 Client ID 同属一个应用、工作通知权限、接收人的企业内 userid 和可见范围 |
| 平台已接受但暂未看到 | 钉钉返回的 task_id 只是异步发送任务；检查应用工作通知、接收成员、平台限制及管理后台可提供的发送结果 |
| 隧道域名更换后无法登录或打开链接 | 更新租户外部访问地址、钉钉重定向 URL、网页与 PC 首页地址；新消息才会使用新链接 |