n8n-nodes-wecom-approval

一个 N8N 1.x 社区节点插件，用于批量导出企业微信「审批」应用的审批流数据。

基于企业微信官方 OA 审批接口实现，核心链路为：

1. GET /cgi-bin/gettoken — 获取 access_token（进程级缓存）
2. POST /cgi-bin/oa/getapprovalinfo — 按日期范围批量获取审批单号（自动分页）
3. POST /cgi-bin/oa/getapprovaldetail — 按审批单号获取审批详情

功能特性

• ✅ 完成日期 + 通过状态过滤：按审批「通过时间」范围（完成日期）过滤已通过单据；因企业微信仅支持按提交时间拉取，插件采用「回溯拉取 + 客户端按通过时间精确过滤」
• ✅ 多条件过滤：审批状态（默认「已通过」）、审批模板、申请人、部门、审批类型
• ✅ 直接查单：支持按审批单号（可多个，逗号分隔）跳过批量查询直接取详情
• ✅ 自动分页：基于 new_cursor / new_next_cursor 游标分页，pageSize 上限 100
• ✅ 容错与限流：access_token 缓存与过期自动刷新、接口限流（45009/45033）指数退避重试、网络错误重试、业务错误码解析
• ✅ 结构化输出：字段命名清晰、层级合理，并额外附加 _text 可读时间与扁平化内容明细，兼容 N8N 数据流转

目录结构

n8n-nodes-wecom-approval/
├── package.json                        # n8n 注册块（nodes/credentials 入口）
├── tsconfig.json
├── credentials/
│   └── WeComApprovalApi.credentials.ts # 企业微信凭证（corpid / secret / agentid）
├── nodes/
│   └── WeComApproval/
│       ├── WeComApproval.node.ts       # 节点实现
│       ├── WeComApproval.node.json     # codex 元数据
│       └── wecomapproval.svg           # 节点图标
├── scripts/
│   └── copy-assets.js                  # 构建后复制图标等静态资源
└── README.md

安装

1. 开发 / 本地安装

cd n8n-nodes-wecom-approval
npm install
npm run build          # 输出到 dist/

# 将包链接到 n8n 的自定义节点目录（目录不存在则先创建）
mkdir -p ~/.n8n/custom
cd ~/.n8n/custom
npm link n8n-nodes-wecom-approval

然后启动 n8n（n8n start），在节点面板搜索「企业微信审批导出」即可。

2. 通过 n8n 社区节点安装（发布到 npm 后）

在 n8n 的 Settings → Community Nodes 中安装包名 n8n-nodes-wecom-approval。

凭证配置

新建「企业微信审批 API」凭证，填写：

权限前置条件（重要）

调用审批接口前，需要在企业微信管理后台完成以下授权：

1. 管理后台 → 应用管理 → 审批 → API → 可调用应用：将自建应用加入列表
2. 管理后台 → 应用管理 → 审批 → API → 审批数据权限：授权应用允许查询审批单据
3. 自建应用只能获取「应用可见范围内」成员提交的审批单

自 2023-12-01 起，不再支持使用系统应用 secret 调用审批接口，请使用审批应用或已授权的自建应用 secret。

节点参数

输出 JSON 结构

输出模式：每条记录一个 Item（默认）

每条审批记录对应一个 item，json 结构如下：

{
  "sp_no": "202409010001",
  "sp_name": "请假申请",
  "template_id": "ZLqk8pcsAoaXZ1eY56vpAgfX28MPdYU3ayMaSPHaaa",
  "sp_status": 2,
  "sp_status_text": "已通过",
  "record_type": "1",
  "record_type_text": "请假",
  "apply_userid": "zhangsan",
  "apply_partyid": 1,
  "apply_time": 1725156000,
  "apply_time_text": "2024-09-01 10:00:00",
  "approve_time": 1725160000,
  "approve_time_text": "2024-09-01 11:06:40",
  "approver_userids": ["lisi"],
  "content": [
    {
      "control": "Text",
      "id": "Text-15111111111",
      "title": "请假事由",
      "value": { "text": "家中有事" },
      "value_text": "家中有事"
    },
    {
      "control": "DateRange",
      "id": "DateRange-15111111112",
      "title": "请假时间",
      "value": {
        "date_range": {
          "type": "day",
          "new_begin": 1725156000,
          "new_end": 1725242400,
          "new_duration": 86400
        }
      },
      "value_text": "2024-09-01 10:00:00 ~ 2024-09-02 10:00:00"
    }
  ],
  "approval_steps": [
    {
      "sp_status": 2,
      "sp_status_text": "已通过",
      "approverattr": 1,
      "approverattr_text": "或签",
      "details": [
        {
          "userid": "lisi",
          "speech": "同意",
          "sp_status": 2,
          "sp_status_text": "已通过",
          "sptime": 1725160000,
          "sptime_text": "2024-09-01 11:06:40",
          "media_id": []
        }
      ]
    }
  ],
  "notifyer": [],
  "comments": [],
  "apply_data": {
    "contents": [
      {
        "control": "Text",
        "id": "Text-15111111111",
        "value": { "text": "家中有事" }
      }
    ]
  }
}

输出模式：合并为单个 Item

{
  "summary": {
    "total": 128,
    "generated_at": "2024-09-01T12:00:00.000Z"
  },
  "records": [
    { "sp_no": "202409010001", "sp_name": "请假申请", "...": "..." }
  ]
}

字段说明

说明：value_text 对常见控件（文本、数字、金额、单选/多选、成员、日期、时长等）做了可读文本提取，便于下游组件直接引用；复杂控件（明细表、假勤、附件等）会以 JSON 字符串形式返回，原始完整结构见 apply_data。

企业微信 API 说明

约束：

• starttime ~ endtime 时间跨度不能超过 31 天（本插件自动切分）
• 单次拉取审批单号上限 100（本插件自动分页）
• 自建应用只能获取应用可见范围内申请人提交的表单
• getapprovalinfo 的 starttime/endtime 仅支持按「提交时间」过滤，不支持按通过时间过滤；因此本插件的「完成日期」过滤 = 按提交时间回溯拉取（完成日期起点 - 回溯天数 至 完成日期终点）+ 拉取详情后按 approve_time 精确过滤，回溯天数由「拉取回溯天数」参数控制（默认 90 天）

开发

npm install
npm run build    # 编译到 dist/
npm run lint     # 代码检查

常见错误码

License

MIT