身份证/银行卡/社保卡/其他卡正反面合成一页PDF

概述

身份证/银行卡/社保卡正反面合成 PDF（付费服务）

v3.0.0 重大改造：从"算法+协议混写"重构为纯商户接口描述，与 mch-demo 后端服务配套使用。

v3.1.0：算法升级——新增横躺卡片方向自动修正、残余倾角精调平（收敛至 0.1° 内）、成品方正度自检、满幅卡片照不切边；修复接口 URL 的 scheme 重复 bug。

服务模式

本技能为纯付费服务：所有调用一律走商户接口（x402 / AgentPay 协议，¥0.10/次），不存在免费或本地离线执行路径。算法运行在商户后端，源文件不随技能分发。

功能描述

本服务接收用户上传的身份证、银行卡、社保卡、工作证等 ISO/IEC 7810 ID-1 标准卡片（85.6×54mm）的正反面照片或扫描件，自动完成：

1. 四边形轮廓检测（Canny / Otsu / 形态学多策略融合）
2. 透视变换矫正（消除倾斜、梯形变形）
3. 方向归一化（强制转为横版）
4. 边缘修整 + 300DPI 缩放
5. A4 单页排版（正面上、反面下、水平居中）

输出标准单页 A4 PDF，物理尺寸精确、可直接提交政务/银行系统。

计费：每次调用 ¥0.10 元（10 分），通过微信支付 AgentPay 协议结算。适用：政务服务、银行开户、证件电子化备份、移民材料整理等合规场景。不支持：名片（90×54mm）、180° 自动倒置纠正、单页超过 50MB 的超清扫描件。

付费前置检查

调用本服务之前，必须先确认当前 Agent 已安装 weixinpay 插件（extension）：

• 已安装 → 可继续提供付费服务
• 未安装 → 提示用户"当前 Agent 暂不支持微信支付付费能力，请联系 Agent 管理员安装 weixinpay 插件"，终止流程，不要进入支付环节

提示：本地 weixinpay_pay 工具调用时传入的 paymentCode = 402 响应中 WeixinPay-Required Header 的值。

工作流程（4 步）

第一步：请求资源

向商户服务发起 POST 请求（JSON body 描述用户要做什么）：

curl -X POST https://canreach.cloud/api/resource 
  -H "Content-Type: application/json" 
  -d '{
    "query": "将这两张身份证照片合成为 PDF：front.jpg back.jpg",
    "front_url": "用户上传的正面文件 URL",
    "back_url": "用户上传的反面文件 URL",
    "card_type": "id"
  }'

card_type 可选值：id（身份证，默认）/ bank（银行卡）/ work（工作证）/ card（其他 ID-1 卡片）

第二步：处理 402 响应（支付由插件完成）

如果收到 HTTP 402 响应，weixinpay 插件会自动拦截并完成支付流程，你无需手动调用任何支付接口。响应中会包含：

Header：

• WeixinPay-Required：支付凭证码（payment_code，给插件用）
• X-Out-Trade-No：商户订单号

Body：

{
  "code": "PAYMENT_REQUIRED",
  "message": "需要支付后才能获取内容",
  "out_trade_no": "WX402_xxxxxxxx",
  "amount": "0.10",
  "currency": "CNY",
  "description": "证件合成服务 1 次",
  "WeixinPay": {
    "WeixinPay-Required": "<payment_code>",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  }
}

支付过程由 weixinpay 插件处理，Skill 无需关心支付细节。

第三步：支付成功后获取资源（⚠️ 必须执行）

支付成功后，必须重新发起请求获取付费内容。重试规则：

• JSON body 不变：与第一步完全一致（一个字符都不能改）
• 通过 Header 携带支付信息：将 402 响应中的 WeixinPay-Required 和 X-Out-Trade-No Header 原样带上

curl -X POST https://canreach.cloud/api/resource 
  -H "Content-Type: application/json" 
  -H "WeixinPay-Required: <从第二步获取的支付凭证码>" 
  -H "X-Out-Trade-No: <从第二步获取的订单号>" 
  -d '{
    "query": "将这两张身份证照片合成为 PDF：front.jpg back.jpg",
    "front_url": "用户上传的正面文件 URL",
    "back_url": "用户上传的反面文件 URL",
    "card_type": "id"
  }'

成功响应（HTTP 200）：

{
  "code": "SUCCESS",
  "out_trade_no": "WX402_xxxxxxxx",
  "amount": "0.10",
  "currency": "CNY",
  "content_type": "application/pdf",
  "content": "BASE64编码的PDF文件内容",
  "filename": "id_card_20260806.pdf",
  "size_bytes": 239335
}

Agent 收到后应将 content 解码为 PDF 文件，保存到用户指定路径或直接呈现。

⚠️ 第三步最容易被遗漏：不携带 X-Out-Trade-No Header 重试，就永远拿不到付费内容（返回 NOT_PAID）。Body 与首次请求保持一致，仅通过 Header 传递订单号。

第四步：处理异常响应

输入文件要求

⚠️ 输入校验在支付之前完成：文件不存在、格式不对、过大等问题会直接返回错误提示，不会触发 402，也不会产生任何费用。

注意事项

1. 必须先通过"付费前置检查"确认 weixinpay 插件已安装，否则不要进入支付流程
2. 收到 402 响应时，支付由 weixinpay 插件完成，Skill 无需关心支付细节
3. 支付成功后必须主动发起重试请求，body 保持不变，通过 Header X-Out-Trade-No 传递订单号
4. 如果返回 NOT_PAID，说明支付尚未完成，请等待 3-5 秒后重试（最多 3 次）
5. 如果返回 REFUNDED，说明服务异常已退款，告知用户并终止流程
6. 如果返回 FULFILL_AND_REFUND_FAILED，建议用户联系客服（提供 out_trade_no）
7. 同一 out_trade_no 只会履约一次，重复请求会返回首次结果

商户信息

• 运营方：加康达国际咨询（北京）有限公司
• 微信支付商户号：1748560465
• 接口地址：https://canreach.cloud/api/resource（部署到公网后替换）
• 支付回调：https://canreach.cloud/api/pay/notify（可选，主流程靠主动查单）
• 退款回调：https://canreach.cloud/api/refund/notify
• 客服联系：通过 SkillHub 站内信或商户平台

版本历史

v3.1.2（2026-10-14）

• 商业化封装：发布包移除本地算法脚本与免费执行路径，纯付费接口模式（源文件不随技能分发，防抄袭复用）
• 满幅照自动纠偏（本次核心升级）：新增「满幅照边界恢复」——整图宽高比接近 ID-1（±8%）时，改用亮度分割把浅色卡片从深色背景中分离，取其外轮廓四边形做透视拉正，同时去掉四周黑边；轮廓退化为不规则形状时回退外接矩形（仅纠旋转）
• 修复满幅卡片照误检：原先满幅照直接跑四边形检测，极易误抓卡面纹理（如背面天安门图案、文字块）导致只截取局部，现已由上述边界恢复方案替代
• 边界恢复后轻微内收 0.6% 去除残余暗边
• 算法能力基于 v3.1.0，运行于商户后端

v3.1.0（2026-09-30）

• 算法升级（服务端），继承 v2.7.0 全部算法并新增：
  • 横躺/倒放卡片方向自动修正：检测前预旋转摆正，角点几何排序唯一，方向零歧义
  • 迭代精调平：按内容直线（文字行/MRZ/条形码）加权平均角，把残余 1~2° 倾角收敛到 0.1° 内
  • 成品残角自检：合成前回测两面残角，方正与否客观判定
  • 留白边策略：检测框外扩 4.5% + 上移 3%，宁留白边不切卡片内容
  • 满幅卡片照支持：卡片铺满画面（无背景）时整图采用，不再中心裁剪切边
  • 精调平在标准尺寸下执行：固定分辨率测角参数稳定，残余倾角可靠收敛
• 修复 URL bug：v3.0.0 全部接口地址写成 https://https://canreach.cloud/...（scheme 重复），已统一为 https://canreach.cloud/...
• 明确付费接口模式依赖 mch-demo 后端在线

v3.0.0（2026-08-06）— 重大重构

• 架构：从"算法+协议混写"改为纯商户接口描述，算法实现移至 mch-demo 后端
• 必做：部署 mch-demo 商户后端服务（Go 或 Java）到公网 HTTPS 地址
• 删除：算法实现细节（多策略检测、裁剪补偿、CLAHE 等内部逻辑）
• 强化：付费前置检查、4 步工作流程、异常处理（REFUNDED/NOT_PAID/FULFILL_AND_REFUND_FAILED）
• 修复：解决 v2.5.0 审核被拒问题"缺少必要的支付服务"

v2.5.0 及之前（已弃用）

• 算法在客户端 Python 脚本中，无后端服务
• 不符合 SkillHub Pay Skill 规范，审核未通过