dingtalk-approval

name	dingtalk-approval
description	当用户要求'发起审批'、'查看审批'、'催办审批'、'请假'、'报销'、'采购申请'，或提到钉钉OA审批相关操作时使用此技能。管理钉钉审批流程：发起审批实例、查询审批状态、获取审批列表、催办超时审批。
version	0.1.0
metadata	{"openclaw":{"emoji":"📋","requires":{"env":["DINGTALK_APP_KEY","DINGTALK_APP_SECRET"],"bins":["curl","jq"]},"primaryEnv":"DINGTALK_APP_KEY"}}

钉钉审批流操作技能

通过钉钉开放平台 OA 审批 API，实现审批实例的发起、查询、催办等操作。

前置条件

1. 需要在钉钉开放平台创建企业内部应用
2. 应用需申请以下权限：审批实例读写权限（全部 5 个审批相关权限）
3. 环境变量 DINGTALK_APP_KEY 和 DINGTALK_APP_SECRET 已配置

获取 Access Token

所有 API 调用前，先获取 access_token（有效期 7200 秒，可缓存）：

ACCESS_TOKEN=$(curl -s "https://oapi.dingtalk.com/gettoken?appkey=${DINGTALK_APP_KEY}&appsecret=${DINGTALK_APP_SECRET}" | jq -r '.access_token')

核心操作

1. 获取审批模板列表

查询企业已有的审批模板，获取 process_code（发起审批必需）：

curl -s -X POST "https://oapi.dingtalk.com/topapi/process/listbyuserid?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "userid": "<发起人的userId>",
    "offset": 0,
    "size": 100
  }' | jq '.result.process_list'

2. 发起审批实例

用 process_code 和表单数据发起一个审批：

curl -s -X POST "https://oapi.dingtalk.com/topapi/processinstance/create?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "process_code": "<模板的process_code>",
    "originator_user_id": "<发起人userId>",
    "dept_id": <发起人部门ID>,
    "form_component_values": [
      {
        "name": "请假类型",
        "value": "事假"
      },
      {
        "name": "开始时间",
        "value": "2026-03-04"
      },
      {
        "name": "结束时间",
        "value": "2026-03-05"
      },
      {
        "name": "请假事由",
        "value": "家中有事需处理"
      }
    ]
  }'

返回值包含 process_instance_id，需保存用于后续查询。

表单字段类型说明：

• 单行输入框 / 多行输入框："value": "文本内容"
• 数字："value": "12000"
• 日期："value": "2026-03-04"
• 日期区间："value": "[\"2026-03-04\", \"2026-03-05\"]"
• 单选框："value": "选项A"
• 多选框："value": "[\"选项A\", \"选项B\"]"
• 明细（子表）："value": "[{\"name\":\"品名\",\"value\":\"电焊条\"},{\"name\":\"数量\",\"value\":\"500\"}]"

3. 查询单个审批实例详情

curl -s -X POST "https://oapi.dingtalk.com/topapi/processinstance/get?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "process_instance_id": "<审批实例ID>"
  }' | jq '.process_instance'

返回值关键字段：

• status: NEW(新创建) / RUNNING(审批中) / TERMINATED(被撤销) / COMPLETED(完成)
• result: agree(同意) / refuse(拒绝)
• operation_records: 操作记录数组
• tasks: 审批任务数组（当前待审批人）

4. 批量获取审批实例 ID 列表

curl -s -X POST "https://oapi.dingtalk.com/topapi/processinstance/listids?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "process_code": "<模板process_code>",
    "start_time": 1709510400000,
    "end_time": 1709596800000,
    "size": 20,
    "cursor": 0
  }' | jq '.result.list'

时间戳为毫秒级 Unix 时间。可按 userid_list 过滤特定发起人。

5. 获取用户待审批数量

curl -s -X POST "https://oapi.dingtalk.com/topapi/process/gettodonum?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "userid": "<用户userId>"
  }' | jq '.result.count'

6. 发送工作通知（催办）

向指定用户推送一条工作通知消息（出现在钉钉"工作通知"里）：

curl -s -X POST "https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": <应用agentId>,
    "userid_list": "<userId1>,<userId2>",
    "msg": {
      "msgtype": "text",
      "text": {
        "content": "您有一条审批单已超过24小时未处理，请尽快审批。审批单号：XXX"
      }
    }
  }'

典型工作流

查询超时未处理审批并催办：

1. 用 listids 获取近 N 天的审批实例 ID
2. 逐个用 get 查询详情，筛选 status=RUNNING 且创建时间超过阈值的
3. 从 tasks 中提取当前待审批人 userId
4. 用工作通知 API 向待审批人发送催办消息
5. 汇总结果生成报告

自然语言发起审批：

1. 用户说"帮我发起请假，3月10日到3月12日，事假，家中有事"
2. 解析意图，识别模板类型（请假）
3. 用 listbyuserid 获取请假模板的 process_code
4. 构造 form_component_values
5. 调用 create 发起审批
6. 返回审批实例 ID 给用户

注意事项

• access_token 有效期 7200 秒，不要每次调用都重新获取，应缓存复用
• 钉钉 API 有调用频率限制，触发限流会返回错误码，需实现退避重试
• process_code 在钉钉管理后台创建审批模板时，可从浏览器 URL 中的 process_code 参数获取
• 发起审批需要知道发起人的 userId 和 dept_id，可通过通讯录 API 获取
• 审批状态变更可通过 Stream 事件订阅实时获取（事件类型：bpms_instance_change）

Additional Resources

• scripts/dingtalk-auth.sh — Access Token 获取脚本
• 钉钉审批 API 文档：https://open.dingtalk.com/document/orgapp/initiate-approval