verify-et-api

Verify.et API

这项可移植技能适用于 Node.js、Python、PHP、Go、Java、Ruby、.NET、Rust 后端集成，以及通过可信后端代理请求的移动应用。

核心工作流

1. 确定集成方式：后端 REST 适配器、结账／付款验证、Webhook 接收器、轮询／SSE 状态界面、仪表板／报告用法，或特定框架的封装。
2. 仅加载所需参考资料：
   • references/api-endpoints.md：用于了解身份验证、端点、载荷、响应、权限和状态流转。
   • references/bank-specs.md：用于了解明确的银行载荷和通用路由器消歧规则。
   • references/error-codes.md：用于了解 HTTP 故障、验证错误代码、重试决策、额度、配额和幂等性冲突。
   • patterns/integration-methods.md：用于选择同步、排队、Webhook、轮询或 SSE 工作流。
   • patterns/webhooks.md：用于了解账户 Webhook 设置（通过仪表板或 API）、签名密钥、测试投递、签名和重试。
   • patterns/image-processing.md：用于了解可选的收据照片、先识别二维码再进行 OCR、图像额度和多部分上传。
   • debugging/common-mistakes.md：用于了解生产环境中的反模式。
   • debugging/production-checklist.md：用于上线前验证。
3. 修改代码前先检查用户的代码。确认 API 密钥和 VERIFY_ET_WEBHOOK_SECRET 的存储位置、POST /api/verify 的调用位置、账户 Webhook 是否已启用、收据照片是否以多部分形式发送、如何处理 202、是否可能重复提交，以及 Verify.et 调用是否在服务端运行。
4. 将 Verify.et API 密钥保存在服务端。浏览器和移动客户端应调用用户的后端，而不是直接调用 Verify.et。
5. 优先使用一个小型服务端 Verify.et 客户端／适配器，而非在各处散布原始 fetch 调用。
6. 为付款和结账尝试发送 Idempotency-Key，并保存返回的 Verify.et requestId。
7. 将 200 视为内联终态响应，将 202 视为已排队的工作。注册一个账户 Webhook，保存其 whsec_ 密钥，并在依赖它之前确认端点状态为 active。对于 202，保存 requestId。仅在界面需要显示进度时使用轮询或 SSE。该端点激活后，不要设置 webhookUrl。详情请参阅 patterns/webhooks.md。
8. 将 confirmationHistory.confirmedBefore === true 视为重复确认信号。应用产品的重复付款策略之前，不要直接履行订单。
9. 在用户的集成边界添加有针对性的测试：请求构建器测试、Webhook 签名测试、图像上传测试、轮询测试、幂等性冲突测试和错误映射测试。

集成决策

• 仅将 POST /api/verify?waitMs=... 作为尽力而为的便利功能。生产工作流在 Verify.et 返回 202 时仍必须正常运行。
• 如果后端必须在浏览器或移动应用关闭后仍能获知结果，请注册一个账户 Webhook。用户可以在 API Keys → Webhooks 下添加，也可以使用其 API 密钥调用 POST /api/webhook-endpoints。保存密钥，验证端点处于活动状态，然后不要在验证请求中设置 webhookUrl。
• 如果客户端需要简单的待处理状态页面，请使用轮询。
• 如果经过身份验证的 Web UI 需要更低延迟的更新且不想频繁轮询，请使用 SSE。
• 为了获得稳健的结账体验，请同时使用 Webhook 和轮询／SSE：Webhook 更新服务端状态；轮询／SSE 更新用户可见的流程。
• 如果产品已知服务提供商，请发送显式的 bank 载荷。如果 UI 接受不同类型的收据或链接，请使用通用的 reference 载荷。可选的 settlementAccount 用于检查收据是否支付给预期收款方；详情见 references/api-endpoints.md。
• 仅在启用 Image Processing 后，才将收据照片作为可选的 multipart image 发送。QR 和 OCR 由 Verify.et 选择。请参阅 patterns/image-processing.md。
• 对于不可逆的履约操作，必须先检查终态、重复确认策略，以及在产品使用收款方匹配时检查 settlementAccountMatch。

调试基准

诊断前，请记录：

• 请求方法、URL、请求体结构、使用的请求头，以及 API 密钥是否在服务端使用。
• HTTP 状态码、响应体、x-request-id、Retry-After 和 X-Verify-Cache。
• Verify.et 的 requestId、processingStatus、status、error.code 和 error.retryable。
• 银行／服务提供商、原始收据／引用、后缀／电话／settlementAccount 消歧信息、账户 Webhook 状态、Image Processing 的启用状态和余额，以及任何旧版的单次请求 Webhook URL。
• 同一结账尝试是否重复使用了相同的 Idempotency-Key。

安全规则

• 不要将 x-api-key 或 whsec_ 值放在前端代码、移动应用、日志、截图或已提交的文件中。
• 在端点密钥验证原始请求体之前，不要信任 Webhook 载荷。规则见 patterns/webhooks.md。
• 将 VERIFY_ET_WEBHOOK_SECRET 存储在用于提供接收器服务的服务端环境中。API 只会返回一次该密钥。
• 使用 X-Webhook-Event-Id 实现 Webhook 处理的幂等性。
• 遇到速率限制和暂时不可用时，请遵循 Retry-After。
• 日志应实用但需脱敏：包含 requestId、银行、状态和错误代码；省略 API 密钥、Cookie、收据图像字节数据和完整授权请求头。

控制面板设置

可以使用 API 密钥注册 Webhook，但无法启用 Image Processing 或充值图像额度。其他账户设置也可能只能在控制面板中进行。

如果缺少其中某项设置：

1. 说明缺少什么、在哪个页面修改，以及需要将什么复制回项目。
2. 请用户选择。他们可以自行操作，也可以明确允许浏览器或电脑操作工具在其登录后代为操作。
3. 在用户选择让你协助该任务之前，不要打开浏览器、登录、浏览 verify.et 或启用插件。笼统的集成 Verify.et 请求不构成此项授权。
4. 如果没有可用的浏览器工具，请先征求同意，再安装或启用工具。
5. 不要询问、存储或输入用户密码。由用户自行登录。
6. 除非用户明确要求完成付款并提供套餐和付款参考信息，否则不要提交付款或图像额度充值。
7. 无论采用哪种方式，操作后都要通过 API 验证设置。Webhook 验证方法见 patterns/webhooks.md。Image Processing 的验证结果应为 data.enabled: true，且 GET /api/image-processing 返回的 data.balance 为正数。

来源

如果可以访问互联网，请使用当前公开文档：

• https://verify.et/docs/get-started
• https://verify.et/docs/api
• https://verify.et/docs/sdk

如果在 Verify.et 仓库中工作，请优先参考实现源代码，而非过时文档。相关源代码路径列于 references/api-endpoints.md。