ABSign REST API 参考：v2 端点、身份验证和集成指南

ABSign API v2 简介

ABSign REST API v2 是官方编程接口，用于将企业级电子签名功能集成到您的业务系统、交易平台和文档管理工作流程中。该 API 基于带有 JSON 请求和响应负载的 REST 原则构建，可与任何能够进行 HTTPS 调用的技术堆栈无缝连接 – 从 Python 和 Node.js 应用程序到 Java Spring Boot 服务、PHP Laravel 系统和 .NET Core 应用程序。所有 v2 API 调用的基本端点是 https://www.abroadsign.com/api/v2/，它取代了旧版 v1 端点，并引入了增强的安全性、扩展的 Webhook 事件覆盖范围以及改进的大容量企业集成的速率限制。

180 多个国家/地区的组织依靠 ABSign API 来自动化文档签署工作流程，涵盖货运代理合同、贸易融资信用证、报关单、多方供应链协议和企业采购文件。 v2 版本引入了对批量文档操作、高级模板合并、区块链时间戳锚定和实时协作功能的本机支持，这些功能允许从任何浏览器或移动设备同时进行多签名者仪式，而无需参与者安装专门的软件或创建 ABSign 帐户。无论您是构建第一个客户加入流程的初创公司，还是替换整个纸质合同基础设施的企业，ABSign API 都可以为全球范围内的全自动、合法合规的数字签名提供构建块。

身份验证和安全配置

在处理具有法律约束力的数字签名时，确保 API 访问的安全至关重要。 ABSign API v2 采用基于 API 密钥的身份验证与 TLS 1.3 传输加密相结合，确保每个请求和响应在传输过程中都经过加密，并且不会受到拦截或中间人攻击。所有 API 密钥均从 ABSign 仪表板的“设置”下生成，具有遵循最小权限原则的精细权限范围 – 每个集成都准确接收其所需的权限，仅此而已。密钥永远不会在 URL 中传输，仅在 HTTP 标头中传输，您的系统应将它们存储在环境变量或专用机密管理平台（例如 AWS Secrets Manager、HashiCorp Vault 或 Azure Key Vault）中，而不是将它们嵌入源代码存储库或提交给版本控制系统的配置文件中。

• 不记名令牌标头： 每个 API 请求都必须包含 Authorization: Bearer YOUR_API_KEY 标头。切勿在应用程序源代码中硬编码 API 密钥；使用环境变量或秘密管理系统在运行时注入凭据。
• TLS 1.3 执行： 所有 API 连接必须使用 TLS 1.3。尝试使用较旧 TLS 版本的连接将被拒绝，并显示 400 错误请求响应。这可确保文档内容和签名数据永远不会通过未加密的通道暴露。
• 权限范围： API 密钥的范围仅限于特定操作 — Documents.read、documents.write、templates.read、templates.write、signers.manage、webhooks.admin 和organization.read。仅分配每个集成用例所需的范围，以在密钥泄露时限制影响范围。
• 密钥轮换政策： 按 90 天的计划实施自动密钥轮换。 ABSign 仪表板通过主密钥和辅助密钥的概念支持零停机密钥轮换，使您可以在不中断正在进行的签名工作流程的情况下滚动凭证。
• IP 许可名单： 企业帐户可以将 API 访问限制为特定 IP 地址或 CIDR 范围。从“安全设置”页面启用 IP 白名单，以实现调用 IP 已知且稳定的服务器到服务器集成。

“实施 TLS 1.3 和 API 密钥范围将我们的安全审计结果减少到零。ABSign API 的设计考虑到了企业安全要求 – 它体现在集成过程的每个细节中。”

— 全球商品贸易公司信息安全主管

核心 API 端点参考

v2 API 围绕面向资源的端点组织功能，这些端点自然映射到数字签名工作流程中的实体：文档、模板、签名者、签名、Webhooks 和组织。每个资源都支持标准 CRUD 操作以及特定于资源的操作，例如发送文档进行签名、提醒待签名者或下载带有嵌入式签名和加密完整性证书的完整文档包。下表提供了快速集成开发的完整端点组参考。

端点组	基本路径	关键操作	常见用例
文件	/documents	创建、读取、列出、更新、下载、存档、删除	启动签名，检索已完成的文件
合同模板	/templates	创建、读取、更新、删除、克隆、列表	标准化文档工作流程
签名者	/signers	邀请、重新发送邀请、取消、验证身份	管理签约方
签名	/signatures	申请、验证、状态检查、检索审核跟踪	完成并验证签名
网络钩子	/webhooks	创建、列出、删除、测试、启用/禁用	实时事件通知
组织机构	/organizations	阅读、更新、设置、团队成员	管理和合规性配置
审核日志	/audit-logs	列表、过滤、导出、下载 PDF	合规报告和取证
批量操作	/bulk	创建批次、状态、取消批次	大批量文档处理

文档生命周期集成模式

最常见的 API 集成模式遵循从创建到签名收集再到归档的文档生命周期。此端到端工作流程演示了您的系统如何在每个阶段与 ABSign API 交互，从而实现完全自动化的签名流程，无需手动干预或管理开销。了解此生命周期对于构建可靠的集成至关重要，这些集成可以优雅地处理故障场景并维护分布式系统之间的数据一致性。

第 1 步：文档创建和模板填充

首先从预配置的模板或直接提交到 API 的原始 HTML 或 PDF 内容创建文档。对于基于模板的创建，在请求正文中传递模板变量值，以自定义每个特定签署场合的文档内容，同时保持品牌一致性和法律条款标准化。 API 会立即响应一个文档 ID，您的系统会存储该 ID 以供对此文档进行所有后续操作。文档创建支持批处理模式，您可以在单个 API 调用中提交最多 500 个文档，用于处理在交易高峰期需要同时启动数十或数百个签名工作流程的队列。

• 使用 POST /documents 与 template_id 和 template_data 从模板创建，或提交 content_html 或 content_pdf_base64 对于原始内容。
• 设置 signing_sequence 到 sequential 对于订购的多方签名或 parallel 当所有各方可以同时签名以最大程度地减少等待时间时。
• 指定 expiry_days 控制在文档自动过期并需要续订之前签名邀请保持有效的时间。
• 使能够 block_download_until_completed 以防止在任何所需的签名尚未完成时过早访问文档。

第2步：签名者配置和工作流程调度

创建文档后，添加所需的签名者，指定他们的电子邮件地址、显示名称及其在签名序列中的位置。对于需要增强身份保证的集成（例如高价值贸易融资交易或受监管的进出口文件），启用 identity_verification_required 在接受签名之前强制要求进行生物识别或政府 ID 验证的标志。只需一次 API 调用即可将文档发送给所有签名者，ABSign 平台会自动生成专业格式的电子邮件邀请，其中包含个性化文档链接、到期通知以及采用收件人首选语言的清晰签名说明。

• 添加签名者通过 POST /documents/{document_id}/signers 包含电子邮件、姓名和角色（signer, witness, 或 抄送 对于抄送）。
• 配置 reminder_schedule 以 24 小时和 72 小时为间隔自动向尚未采取行动的签名者发送提醒电子邮件。
• 放 redirect_url_after_signed 在签名者完成签名后引导他们进入系统中的自定义完成页面。
• 使能够 signer_authentication 需要电子邮件 OTP 或 SMS 验证作为签名者身份确认的附加层。

第 3 步：Webhook 驱动的完成和下游处理

每当签名者采取操作或文档生命周期状态发生变化时，ABSign Webhook 系统都会向您配置的 HTTPS 端点发送实时事件通知。配置 Webhook 来接收自动触发下游进程的推送通知，而不是重复轮询 API 来检查文档状态（这会消耗您的速率限制配额并增加延迟）。收到后 document.completed 事件发生后，您的系统会检索完整的文档包，包括签名的 PDF、加密哈希证书、区块链时间戳锚点和完整的审计跟踪文档，作为法律纠纷或合规审计的主要证据。

---

Webhook 事件和实时通知参考

Webhooks 是自动化集成架构的支柱。 ABSign API v2 支持整个文档生命周期的全面事件覆盖，使您的系统能够在发生状态更改时立即响应，而不是依赖于浪费 API 配额并在工作流程中引入不必要的延迟的轮询间隔。每个 Webhook 交付都包含一个包含特定于事件的数据的 JSON 负载和一个 HMAC-SHA256 签名标头，您的端点在处理通知之前必须验证该标头，以防止欺骗事件在您的系统中触发未经授权的操作。

事件类型	触发条件	关键有效负载字段	整合反应
document.created	新文档已添加到平台	文档 ID、标题、创建时间、创建者	在内部跟踪系统中注册
document.sent	文件发送给签名者	document_id、签名者[]、expires_at、主题	更新工作流程仪表板状态
signer.viewed	签名者打开文档链接	document_id、signer_id、viewed_at、ip_address	记录参与度和触发计时器
signer.completed	签名者提交签名	document_id、signer_id、signed_at、signature_hash	检查完成，通知下游
document.completed	已获得所有必需的签名	document_id、completed_at、download_url、audit_trail_url	触发下一个工作流程步骤
document.expired	超过签约期限	document_id、expired_at、signers_pending[]	启动更新或提醒运营团队
document.declined	签名者明确拒绝签名	document_id、signer_id、拒绝原因、拒绝原因	警报操作并升级
document Voided	文档被创建者取消	document_id、voided_by、voided_at、原因	关闭内部记录并通知

速率限制、配额和性能优化

ABSign API v2 强制执行速率限制，以确保平台稳定性和所有 API 使用者之间的公平资源分配。标准层帐户每个 API 密钥每分钟的请求数不得超过 1,000 个，而企业帐户则收到根据记录的集成要求和预期交易量协商的更高限制。速率限制状态通过以下方式在每个 API 响应中传达： X-RateLimit-Remaining 和 X-RateLimit-Reset 响应标头，使您的集成能够实施主动限制，而不是等待 429 响应来触发退避行为。对于处理数千个文档的大批量批量操作，请使用专用的 /bulk 专为批量吞吐量而设计的端点，具有更高的每分钟配额并减少每个文档的开销。

• 监视器 X-RateLimit-Remaining 每个响应上的标头，并在接近零时暂停请求，以避免接收到停止重置窗口处理的 429 Too Many Requests 响应。
• 使用 Retry-After 头值在恢复请求之前等待确切的持续时间，而不是实现可能太短或不必要的长的任意睡眠间隔。
• 对于批量文档处理，首选 POST /bulk 个人的终点 POST /documents 调用 — 批量操作可为大批量工作流程提供高达 10 倍的吞吐量提升。
• 对所有重试逻辑实施带抖动的指数退避，以处理瞬态服务器端错误，而不会在恢复期间压垮平台。
• 使用 Conditional Requests 与 If-Modified-Since 或者 ETag 检索文档状态时的标头，以避免不必要的数据传输并减少状态检查的延迟。

“我们每月通过 ABSign API 处理超过 50,000 个货运文件。批量操作端点与适当的 Webhook 处理相结合意味着我们的整个签名工作流程以亚分钟的延迟运行 – 在初始 API 调用后完全无需干预。”

— 全球货运代理网络首席平台工程师

官方SDK包及快速入门

ABSign 为最广泛采用的编程语言和框架维护官方 SDK 包，每个包都提供本机语言数据结构、针对瞬时故障具有指数退避功能的自动重试逻辑、用于编译时安全的全面类型定义以及符合 API 安全要求的预配置 HTTP 客户端设置。 SDK 包是开源的，可在 GitHub 上获取，欢迎社区对其他语言做出贡献，并由 ABSign 工程团队进行审核。所有官方 SDK 的版本控制均与 API 同步，以确保 SDK 方法签名和行为与底层 REST 端点保持一致。

• Python SDK： 安装通过 pip install abroadsign-api。对现代 Python 应用程序的完全异步/等待支持，并为 Django、FastAPI 和基于 Celery 的后台任务系统提供自动集成帮助程序。包括完整的类型提示和 IDE 自动完成支持。
• Node.js / TypeScript SDK： 安装通过 npm install abroadsign-api。完全类型化的 TypeScript 包，具有​​所有请求和响应对象的完整类型定义。包括对 Express.js、Next.js API 路由以及 AWS Lambda 和 Vercel 上的无服务器函数的本机中间件支持。
• Java/Spring Boot SDK： Maven 坐标可在 Maven Central 上找到。兼容 Spring Boot 2.x 和 3.x，为企业 Java 开发团队提供自动配置支持和全面的 Javadoc 文档。
• PHP SDK： 符合 PSR 的包与 Laravel、Symfony 和独立 PHP 8.1+ 应用程序兼容。包括 Laravel 服务提供程序，用于通过 Laravel 服务容器进行无缝依赖注入配置。
• .NET/C# SDK： .NET Standard 2.0 兼容性，支持 Windows、Linux 和 macOS 上的 .NET Framework、.NET Core 和 .NET 5+。包括 ASP.NET Core 依赖项注入与 HttpClientFactory 模式的集成。

---

入门：您的第一个 API 集成

通过访问 ABSign API 沙箱环境开始集成，该环境提供功能齐全的 API 镜像，其中包含独立的测试数据，不会影响生产文档库或计入生产配额。从仪表板的“设置”下生成沙箱 API 凭据，并立即开始进行 API 调用，以在安全的环境中探索文档创建、签名者配置和 Webhook 交付。沙箱自动模拟签名仪式，因此您可以测试完整的端到端工作流程，而无需等待真正的人类签名者在开发和质量检查周期中采取行动。我们的 交互式 API 文档门户 提供实时 API 浏览器，您可以在其中直接在浏览器中执行请求、检查请求和响应有效负载，并使用任何支持的 SDK 语言为任何端点生成现成的代码片段。

对于高级集成模式，包括大批量批处理、多租户白标实施和自定义 Webhook 可靠性架构，请探索我们的 文档工作流程自动化指南 其中涵盖性能调优、错误处理策略和企业部署最佳实践。我们的集成工程团队还为企业客户提供免费的技术架构审查会议，以便在您投入生产流量之前验证您的集成设计。

准备好构建您的集成了吗？ 访问 API 文档门户 获取完整的端点参考、SDK 下载和工作代码示例。有关企业 API 要求、自定义集成架构或生产扩展的问题， 联系我们的技术集成团队 安排与我们的一位高级 API 工程师进行免费的架构审查会议。