PDF批量处理·全能转换（满血付费版）【煋旺智能·出品】

概述

PDF批处理专业版

付费的 PDF 批处理服务。每次调用走 作者后端支付校验（¥0.99/次）：付费前置检查 → 请求后端接口 → 返回 WeixinPay-Required → 用户通过微信支付 AI 专属卡授权 → 支付成功后由服务端执行处理并返回结果文件。

服务端运行 PyMuPDF 引擎，本机零依赖、零占用。支持批量转换、合并拆分、压缩、水印、密码保护，单次最多 50 个文件，百份级批量不卡不崩。

Step 0：选择支付路径（不阻断服务）

看一眼你的工具列表里有没有 weixinpay_pay（对话内支付授权工具，名称含 weixinpay_ 即可）。这个判断只决定走哪条路，不决定是否提供服务。

禁止因为「没检测到 weixinpay 插件」就终止流程、回复「当前暂不支持」，或让用户空等。

没有 weixinpay_pay 只说明要走扫码路径，不说明不能卖。

两条路都经过同一个服务端支付校验，服务照常提供，不要因为工具缺失而拒单。

Step 1：请求资源（创建付费订单）

首次请求：调用作者后端统一接口（不带 X-Out-Trade-No 请求头）创建订单：

POST https://xinpect.xingwangzhineng.com/pdf-pro/api/pdf/process
Content-Type: application/json

{
  "operation": "to_word",
  "files": ["https://example.com/report.pdf"]
}

files 使用公网 https 直链。operation 取值见文末「支持的操作类型」，附加参数（pages_per_file / dpi / watermark / opacity / password）与 operation 同层传入。

响应：HTTP 402 Payment Required（触发支付）：

{
  "code": "PAYMENT_REQUIRED",
  "message": "本次调用需要付费（0.99 元/次），支付后携 X-Out-Trade-No 重试即可获取结果。",
  "WeixinPay": {
    "WeixinPay-Required": "0e21787f-cf3a-40da-9886-f8da61b6353e",
    "prompt": "本次使用微信支付。若你有 weixinpay_pay 工具，将 WeixinPay-Required 作为 paymentCode 调用它申请支付授权；若没有该工具，把 code_url 转成二维码让用户微信扫码支付。两条路同等有效。"
  },
  "out_trade_no": "WX402_202610121107423736c9bbd348",
  "amount": "0.99",
  "currency": "CNY",
  "code_url": "weixin://wxpay/bizpayurl?pr=AbCdEfG",
  "query_url": "https://xinpect.xingwangzhineng.com/pdf-pro/api/pdf/order?out_trade_no=WX402_202610121107423736c9bbd348"
}

响应头（Header）同时携带三个关键值（必须提取并保存）：

• WeixinPay-Required：支付码（paymentCode，A 路用）
• X-Out-Trade-No：订单号（tradeNo / out_trade_no）——支付成功后重试必须携带
• X-Pay-Code-Url：扫码链接（B 路用，与 body 的 code_url 相同）

重要：X-Out-Trade-No（订单号）不可修改、不可丢失，贯穿 Step 3 履约与订单查询。

Step 2：发起支付（按 Step 0 选的路径走）

路径 A：有 weixinpay_pay

将 402 响应里的 WeixinPay-Required 值作为 paymentCode，调用 weixinpay_pay 向用户申请支付授权（拉起微信支付 AI 专属卡）。

路径 B：没有 weixinpay_pay，或路径 A 拉起失败

不要重试、不要放弃、不要终止流程，直接切到这条路：

1. 取 402 响应体的 code_url（取不到就用响应头 X-Pay-Code-Url）
2. 把它转成二维码展示给用户（任何二维码工具/图片均可）
3. 告诉用户：「用微信扫这个码支付 ¥0.99，付完告诉我，我继续处理」
4. 用户确认付款后走 Step 3；也可每 3 秒 GET 一次 query_url 确认到账，最多 20 次

两条路的订单摘要相同：

重要：无论走哪条路，支付完成后都必须保留 X-Out-Trade-No（订单号），用于 Step 3 履约。

Step 3：支付成功后获取处理结果（⚠️ 必须执行）

携带支付凭证重试原请求（Body 与第一步完全一致，仅增加请求头）：

POST https://xinpect.xingwangzhineng.com/pdf-pro/api/pdf/process
Content-Type: application/json
X-Out-Trade-No: WX402_202610121107423736c9bbd348
WeixinPay-Required: 0e21787f-cf3a-40da-9886-f8da61b6353e

{
  "operation": "to_word",
  "files": ["https://example.com/report.pdf"]
}

服务端查单验证通过后返回 HTTP 200：

{
  "success": true,
  "already_fulfilled": false,
  "elapsed_seconds": 3.2,
  "output_files": ["https://xinpect.xingwangzhineng.com/pay/files/WX402_xxx/report.docx"]
}

⚠️ 关键要求：

• operation 与 files 必须与第一步完全一致（body 不一致会被服务端拒绝履约）
• 必须携带 X-Out-Trade-No（值为第一步保存的订单号）
• 不携带订单号重试，将永远拿不到处理结果；也不要重复下单付款
• 若仍返回 402 / PAYMENT_NOT_CONFIRMED：说明支付尚未确认，等待后携同一订单号重试，不要重新下单

订单查询

支付状态不明或需要核对时，查询原订单（不要重复下单）：

GET https://xinpect.xingwangzhineng.com/pdf-pro/api/pdf/order?out_trade_no=WX402_xxx

{"success": true, "out_trade_no": "WX402_xxx", "status": "CREATED", "amount_fen": 99, "paid_at": null}

status 取值：CREATED（已下单未支付）/ PAID（已支付）/ FULFILLED（已履约）/ EXPIRED（已过期）。

结果处理

• output_files：处理完成的文件下载链接，交付给用户
• success / failed / errors：批量结果总览，按条目向用户汇报
• elapsed_seconds：服务端处理耗时

支持的操作类型

限制

• 单次最多 50 个文件，单文件 ≤ 30MB
• 扫描件OCR识别、PDF转Excel（表格结构化）为规划中能力，当前版本不支持

能力边界

• 免费部分：本 Skill 的说明文档与调用示例可自由查阅，不产生任何费用
• 付费触发点：任何一次实际 PDF 处理调用（Step 1）都会触发 WeixinPay-Required，需支付 ¥0.99 后才能取得结果文件

部署形态

• 形态：server（作者自建 HTTPS 服务端，端点见 Step 1）
• 支付触发：由服务端调用 X402 AI 预下单，返回 WeixinPay-Required + X-Out-Trade-No
• 履约：服务端查单验证通过后返回处理结果（幂等，同一订单不重复扣费）

安全声明

• 服务端 X402 AI 预下单所需签名由作者服务端在运行时从环境变量读取私钥完成，私钥不入 Skill 包、不出服务端。
• 本 Skill 包内不含任何密钥、Token 或用户隐私数据。