智排文档｜扫描件转可编辑 Word

概述

通用扫描件转可编辑 Word

通过 https://www.conmes.cn/api/skillpay/general-document 提供微信 SkillPay 付费转换服务。每个文件收费人民币 1 元，最多 10 页、64 MB。转换失败时，服务端自动发起全额退款。

调用前准备

开始前告知用户：源文件将上传至 www.conmes.cn；单次价格为 1 元；限制为 10 页、64 MB。每次订单只接受一个 .pdf、.png、.jpg、.jpeg、.webp、.bmp、.tif 或 .tiff 文件。

不得在首次请求前因缺少 weixinpay 或 weixinpay_pay 而终止。必须先执行第一步，请求商户服务并取得真实的 HTTP 402 支付响应；只有收到完整支付信息后才判断当前 Agent 能否调用支付插件。

SkillPay 工作流程

必须依次完成首次请求、处理 HTTP 402、微信支付、携带支付 Header 重试、等待履约和下载结果。不得绕过支付直接请求结果。

第一步：首次请求资源

运行：

python scripts/scan_to_word.py start --file "/absolute/path/source.pdf"

脚本向以下商户服务发起 multipart POST 请求：

POST https://www.conmes.cn/api/skillpay/general-document
Content-Type: multipart/form-data

file=<源 PDF 或扫描图片>

首次请求不携带订单 Header。正常结果必须是 HTTP 402 Payment Required，并同时包含：

• Header WeixinPay-Required：微信支付凭证码。
• Header X-Out-Trade-No：商户订单号。
• Body code: PAYMENT_REQUIRED。
• Body WeixinPay.WeixinPay-Required：与 Header 中相同的支付凭证码。
• Body amount: "1.00"、currency: "CNY"。

保存 WeixinPay-Required 和 X-Out-Trade-No，两者在支付后重试时都必须使用。若没有收到完整的 402 支付响应，不得发起支付。

第二步：处理 402 并完成支付

将第一步的 WeixinPay-Required 值作为 paymentCode 交给微信支付插件：

weixinpay_pay(paymentCode=<WeixinPay-Required>)

支付授权和扣款由 weixinpay 插件完成，不要直接调用微信支付商户接口。只有插件明确返回支付成功后才能继续。用户取消或支付失败时立即终止，不得声称转换已经开始。

如果收到完整 402 后确认当前 Agent 不提供 weixinpay_pay，此时再告知用户“当前 Agent 暂不支持微信支付付费能力”，同时保留 WeixinPay-Required 和 X-Out-Trade-No，不得创建新订单、重复请求或声称已经支付。

第三步：支付成功后必须重新请求

支付成功后，必须使用原始文件重新请求：

python scripts/scan_to_word.py resume 
  --file "/absolute/path/source.pdf" 
  --out-trade-no "<X-Out-Trade-No>" 
  --payment-code "<WeixinPay-Required>"

该命令向同一商户接口重新发送文件，并原样携带：

WeixinPay-Required: <第一步保存的支付凭证码>
X-Out-Trade-No: <第一步保存的商户订单号>

必须使用与首次请求完全相同、字节未改变的源文件。不得重命名后重新生成内容，不得创建新订单代替重试。服务端会校验文件 SHA-256、查询微信支付订单，并只对同一订单履约一次。

正常响应为 PROCESSING 或 SUCCESS，并返回 status_url 和 download_url。NOT_PAID 表示支付状态尚未确认，短暂等待后使用同一订单再次执行 resume。

第四步：等待履约

python scripts/scan_to_word.py wait 
  --status-url "<status_url>" 
  --out-trade-no "<X-Out-Trade-No>" 
  --timeout 3600 
  --interval 5

仅按服务端返回值判断最终状态：

• SUCCESS：继续下载 Word。
• REFUNDED：转换失败，服务端已发起全额退款；告知用户并终止。
• FULFILL_AND_REFUND_FAILED：转换失败且自动退款失败；告知用户联系服务方，并提供订单号。
• 超时或网络错误：只说明结果尚未确认，不得声称成功、失败或已经退款。

第五步：下载 Word

python scripts/scan_to_word.py download 
  --download-url "<download_url>" 
  --out-trade-no "<X-Out-Trade-No>" 
  --output "/absolute/path/result.docx"

只有命令返回 DOWNLOADED，且本地 .docx 文件存在、大小大于 0 时，才向用户交付结果。说明服务会尽量保留文字、表格、图片和页面结构，复杂扫描件仍可能需要人工校对。

错误处理

• PAGE_LIMIT_EXCEEDED：服务端会返回实际页数、10 页上限、charged: false 和登录链接。明确告诉用户本次未创建支付订单、不会扣费，并提供两种选择：拆分为每份不超过 10 页后分别支付，或打开 login_url 登录因智排版，按 1 积分/页处理完整文件。
• INVALID_FILE：改用受支持、非空且不超过 64 MB 的文件。
• FILE_MISMATCH：使用原订单和首次请求时完全相同的源文件重试。
• INVALID_PAYMENT_CODE：使用第一步返回的原始 WeixinPay-Required。
• RESULT_NOT_READY：继续查询状态，不要重复支付。
• REFUNDED：告知用户已自动退款，不得再次请求或重新支付。
• 不得将 WeixinPay-Required、X-Out-Trade-No 或源文件发送到 www.conmes.cn 之外的主机。