先说清楚：需要公网 HTTPS 域名
企业微信的消息与事件只能回调公网 HTTPS 地址。没有域名，扫码登录、打印通知、卡片按钮的回调都收不到，云打印也收不到文件。可以用反向代理、frp 或 Tailscale funnel 把内网服务暴露成一个 HTTPS 地址，但那个域名必须有。
入口在企微，打印在别处
员工每天开着企业微信，打印动作却要跳出去做。
多一套账号要记
复合机要输工号或刷工卡，企微里的身份用不上。
打完了靠人喊
提交之后没人知道，文件堆在机器上，行政要挨个问。
文件传来传去
手机里的 PDF、Office 要先转到电脑，再找共享盘提交。
四项功能
扫码、通知、云打印、通讯录，四件事共用一套服务。
企微扫码登录
复合机面板显示二维码，员工用企业微信扫码确认；state 一次性、5 分钟内有效，设备轮询取登录结果。
- state 一次性
- 5 分钟有效
- 设备轮询取结果
打印通知 + 卡片释放
作业提交后推企业微信消息，卡片上释放或取消；回调 5 秒内 ack，重复推送只执行一次。释放范围是该用户在该队列的待释放任务，不是按单份任务精确释放——这是 PaperCut API 的限制。
- 5 秒内 ack
- 幂等
- 按队列释放
企微云打印
把 PDF、图片或 Office 发给应用，Office 由 LibreOffice 转成 PDF 后进队列，到机刷卡再出纸。
- PDF / 图片 / Office
- LibreOffice 转换
- 到机刷卡出纸
通讯录同步
同步部门与人员；通讯录接口要单独申请通讯录同步 Secret；默认不删除本地账号。
- 单独申请 Secret
- 默认不删除
- 保留本地账号
和飞书版、钉钉版的区别
功能目标差不多，收事件的方式和前置条件差很多。选型时先看这一栏。
| 通道 | 收事件方式 | 前置条件 |
|---|---|---|
| 飞书版 | 长连接（出站 443 到 open.feishu.cn） | 服务器能出网即可 |
| 钉钉版 | 钉钉 Stream 长连接（出站 443） | 扫码登录需手机可达的 redirect_uri |
| 企业微信版 | 公网 HTTPS 回调 | 需要公网 HTTPS 域名，并报备可信域名 |
三套服务各自独立授权；同一台 PaperCut 可以只接其中一条，也可以并存。
前提
使用前提
企业微信版的前置条件比另外两条通道硬，先核对再谈工期。
必须项
- 一个公网 HTTPS 域名，用于企微事件回调。没有域名，扫码登录和按钮回调都收不到。
- 在企微后台把该域名报备为可信域名。
- PaperCut MF/NG 启用 Web Services API（9191）。
释放范围的限制
- 卡片释放的范围是该用户在该队列的待释放任务，不是按单份任务精确释放。
- 这是 PaperCut API 的限制，不是配置项，也不能靠改代码绕过。
网络与部署
- 事件回调要在 5 秒内 ack，否则企微会重试；服务对重复事件做了幂等。
- 可与 PaperCut 同机或分开部署，单进程运行，需要可写的 data/ 目录。
规格
部署与技术规格
参数表按企微自建应用的配置项列，实施时逐项核对。
| 项目 | 要求 | 说明 |
|---|---|---|
| PaperCut 侧 | 启用 Web Services API（9191） | 适配区间 22.0–27.x，以联调为准 |
| 企微应用 | 自建应用：CorpID / AgentId / Secret | 在企微管理后台创建 |
| 回调安全 | Token / EncodingAESKey | 与企微后台填写一致 |
| 可信域名 | 公网 HTTPS 域名 | 需在企微后台报备 |
| 可见范围 | 按部门或人员设置 | 决定谁能收到通知 |
| 服务器 | Windows Server 2019+ / Linux | 按现有运维习惯选 |
| 运行时 | Python 3.10+ | 单进程部署，可写 data/ |
| 通讯录 | 通讯录同步 Secret | 需单独申请 |
FAQ
常见问题
没有公网域名能用吗？
用不了。企业微信的消息与事件只能回调公网 HTTPS 地址，扫码登录、通知、卡片释放、云打印收文件都依赖这条回调。
为什么释放不能精确到某一份任务？
PaperCut 的接口按「用户 + 队列」给出待释放任务集合，没有按单份任务释放的接口。所以卡片释放会释放该用户在该队列的待释放任务。
支持哪些 MFD 和品牌？
只要是 PaperCut MF/NG 已支持并接入的设备即可，我们不单独维护一份设备名单；具体型号以 PaperCut 官方列表为准。
离职员工会自动删账号吗？
不会。通讯录同步默认不删除本地账号，避免历史用量丢失；停用请按你们自己的流程处理。
适配哪些 PaperCut 版本？
适配区间 22.0–27.x，以现场联调为准；版本差异主要体现在 Web Services API 的字段上。
事件一直重试怎么办？
回调要在 5 秒内返回 ack；服务对重复事件做了幂等，重复推送不会重复执行。超时通常是域名、证书或网络策略问题。
先确认有没有可用的公网域名
这是企业微信版能不能上的第一道门。把域名、PaperCut 版本和企微应用情况发给我们，我们先判断。