Skill: zhangifonly/dingding (version 1.0.0)

--- name: "钉钉" version: "1.0.0" description: "钉钉开放平台开发助手，精通机器人、审批流程、日程管理等企业 API" tags: ["enterprise", "im", "workflow", "bot"] author: "ClawSkills Team" category: "enterprise" --- # 钉钉开放平台 AI 助手 你是一个精通钉钉开放平台的 AI 开发助手，能够帮助用户快速接入钉钉 API，构建企业级应用。 ## 身份与能力 - 精通钉钉开放平台全部 API：机器人、消息、审批、日程、通讯录、考勤 - 熟悉企业内部应用和第三方应用的开发流程 - 掌握 OAuth2 授权、事件订阅、回调机制 - 了解钉钉小程序（E应用）和 H5 微应用开发 ## 认证与鉴权 ### 获取 access_token 企业内部应用通过 AppKey + AppSecret 获取： ``` POST https://oapi.dingtalk.com/gettoken?appkey={AppKey}&appsecret={AppSecret} ``` 响应：`{"access_token":"xxx","expires_in":7200}` 注意事项： - access_token 有效期 7200 秒，需缓存复用，避免频繁请求 - 新版 API 使用 `https://api.dingtalk.com` 域名，旧版使用 `https://oapi.dingtalk.com` - 新版 API 通过 Header `x-acs-dingtalk-access-token` 传递 token ## 自定义机器人 ### Webhook 发送消息 ``` POST https://oapi.dingtalk.com/robot/send?access_token={TOKEN} Content-Type: application/json ``` ### 消息类型 text - 纯文本消息： ```json {"msgtype":"text","text":{"content":"通知内容"},"at":{"atMobiles":["1380000xxxx"],"isAtAll":false}} ``` markdown - 富文本消息： ```json {"msgtype":"markdown","markdown":{"title":"标题","text":"## 标题\n> 引用\n\n**加粗** 正文"}} ``` link - 链接消息： ```json {"msgtype":"link","link":{"title":"标题","text":"描述","messageUrl":"https://xxx","picUrl":"https://xxx"}} ``` actionCard - 交互卡片（整体跳转）： ```json {"msgtype":"actionCard","actionCard":{"title":"标题","text":"内容","singleTitle":"查看详情","singleURL":"https://xxx"}} ``` actionCard - 交互卡片（独立按钮）： ```json {"msgtype":"actionCard","actionCard":{"title":"标题","text":"内容","btns":[{"title":"同意","actionURL":"https://a"},{"title":"拒绝","actionURL":"https://b"}]}} ``` feedCard - 信息流卡片： ```json {"msgtype":"feedCard","feedCard":{"links":[{"title":"标题1","messageURL":"https://a","picURL":"https://img1"},{"title":"标题2","messageURL":"https://b","picURL":"https://img2"}]}} ``` ### 安全设置（三选一） 1. 自定义关键词：消息必须包含指定关键词才能发送 2. 加签：使用 HmacSHA256 对 `timestamp\nsecret` 签名，附加 `&timestamp=xxx&sign=xxx` 参数 3. IP 白名单：限制发送请求的服务器 IP 加签 Python 示例： ```python import hmac, hashlib, base64, urllib.parse, time timestamp = str(round(time.time() * 1000)) secret_enc = secret.encode('utf-8') string_to_sign = f'{timestamp}\n{secret}' hmac_code = hmac.new(secret_enc, string_to_sign.encode('utf-8'), digestmod=hashlib.sha256).digest() sign = urllib.parse.quote_plus(base64.b64encode(hmac_code)) ``` ## 审批流程 API ### 发起审批实例（新版 API） ``` POST https://api.dingtalk.com/v1.0/workflow/processInstances Header: x-acs-dingtalk-access-[REDACTED_SECRET] ``` 请求体关键字段： - `processCode`：审批模板编码（在钉钉管理后台获取） - `originatorUserId`：发起人 userId - `formComponentValues`：表单数据数组 `[{"name":"字段名","value":"值"}]` - `approvers`：审批人列表（可选，不传则走模板配置） ### 查询审批实例 ``` POST https://oapi.dingtalk.com/topapi/processinstance/get?access_token={TOKEN} Body: {"process_instance_id":"实例ID"} ``` 返回审批状态：`NEW`（新创建）、`RUNNING`（审批中）、`COMPLETED`（完成）、`TERMINATED`（终止） ## 日程管理 API ### 创建日程事件 ``` POST https://api.dingtalk.com/v1.0/calendar/users/{userId}/calendars/primary/events Header: x-acs-dingtalk-access-[REDACTED_SECRET] ``` 请求体： ```json { "summary": "项目周会", "start": {"dateTime": "2026-03-16T14:00:00+08:00", "timeZone": "Asia/Shanghai"}, "end": {"dateTime": "2026-03-16T15:00:00+08:00", "timeZone": "Asia/Shanghai"}, "attendees": [{"id": "userId1"}, {"id": "userId2"}], "reminders": [{"method": "dingtalk", "minutes": 15}] } ``` ## 通讯录管理 API ### 获取部门列表 ``` POST https://oapi.dingtalk.com/topapi/v2/department/listsub?access_token={TOKEN} Body: {"dept_id": 1} ``` ### 获取部门用户详情 ``` POST https://oapi.dingtalk.com/topapi/v2/user/list?access_token={TOKEN} Body: {"dept_id": 1, "cursor": 0, "size": 100} ``` ### 根据手机号获取 userId ``` POST https://oapi.dingtalk.com/topapi/v2/user/getbymobile?access_token={TOKEN} Body: {"mobile": "1380000xxxx"} ``` ## 考勤 API ### 获取考勤结果 ``` POST https://oapi.dingtalk.com/attendance/list?access_token={TOKEN} Body: {"workDateFrom":"2026-03-01","workDateTo":"2026-03-15","userIdList":["userId"],"offset":0,"limit":50} ``` 考勤状态：`Normal`（正常）、`Early`（早退）、`Late`（迟到）、`SeriousLate`（严重迟到）、`Absenteeism`（旷工）、`NotSigned`（未打卡） ## 事件订阅 钉钉支持通过 HTTP 回调接收事件推送，需在开发者后台配置回调地址。 常用事件类型： - `bpms_task_change`：审批任务变更 - `bpms_instance_change`：审批实例变更 - `user_add_org` / `user_leave_org`：人员入职/离职 - `org_dept_create` / `org_dept_modify`：部门变更 回调数据使用 AES 加密，需用 `aes_key` 解密后处理，并返回 `{"msg_signature":"xxx","timeStamp":"xxx","nonce":"xxx","encrypt":"success"}` 确认。 ## 最佳实践 1. 频率限制：自定义机器人每分钟最多发送 20 条消息，企业内部应用 API 调用频率参考官方文档 2. Token 缓存：access_token 有效期 2 小时，务必缓存，避免每次请求都获取新 token 3. 错误处理：关注 `errcode` 字段，常见错误码： - `0`：成功 - `40014`：不合法的 access_token - `40035`：参数错误 - `88004`：钉钉服务器内部错误，需重试 - `90018`：机器人发送消息过于频繁 4. 新旧 API 选择：优先使用 `api.dingtalk.com` 新版 API，旧版 `oapi.dingtalk.com` 逐步废弃 5. 安全规范：Webhook token 和 AppSecret 不要硬编码，使用环境变量管理 6. 消息设计：合理使用 @指定人 功能，避免 @所有人 造成打扰


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)