SDK 下载 进入管理台
开放平台 / 开发者指南 / 快速上手指南

API 快速上手指南 (Quickstart Guide)

5 MINS 端到端电子签署完整闭环集成路径 快速开通 沙箱与生产同构

欢迎接入 Dsign Link 开放平台！本文档将引导您在 5 分钟内 走通「获取凭据 → 选用模板 → 发起签署 → 获取签署链接 → 监听事件回调 → 归档下载」完整的电子签署业务链路。

端到端标准业务流转闭环
① 开通凭证（获取 AccessKey / SecretKey） ➔ ② 模板准备（云端配置或选择模板控件） ➔ ③ 发起签署（调用 Create 接口创建流程） ➔ ④ 交付签署（调用 SignUrl 接口引导用户签署） ➔ ⑤ 事件回调（Webhook 接收签署完成通知） ➔ ⑥ 归档下载（调用 Download 接口获取已完成平台签署流程的归档文件）。

核心集成步骤 (Step-by-Step)

1
开通开发者凭证与企业绑定

登录 Dsign Link 企业管理控制台，在【开发者中心 / API 密钥管理】中生成当前企业的专属 API 密钥：

  • Access Key：开放平台的身份唯一标识（例如 ak_live_d83e201048b94103）。
  • Secret Key：用于 HMAC-SHA256 签名加密的私密密钥，仅生成时展示一次，请妥善保存在服务器端。
  • Enterprise ID：当前登录企业的数字标识（例如 1002），请求时需携带在 X-Api-Enterprise-Id 标头中。
前往控制台开通凭证
2
下载官方 SDK 或配置签名工具

平台为开放接口统一采用 POST 请求与 HMAC-SHA256 数字签名通信。推荐直接使用官方开箱即用的开发包：

  • 推荐方式：前往 官方 SDK 下载中心 获取纯原生独立封装的 PHP SDK（自包含零第三方包依赖）。
  • 自行封装：若使用 Java、Python、Node.js 等其它语言，请参阅 公共请求头与验签规范 复制对应的通用签名函数并使用官方测试用例自检。
3
在控制台配置或选取签署模板

在发起签署之前，企业管理员需在控制台【模板管理】中准备合同样本：

  • 上传 PDF 底稿合同；
  • 设置签署参与方角色标识（例如 signer_a）；
  • 拖拽配置需要业务系统动态替换填充的文本或日期表单域（例如 quick-text-contract-no、quick-date-signing）；
  • 保存后记录该模板的 template_id（如 7c9e6679-7425-40de-944b-e07fc1f90ae7）。
4
调用接口创建并发起签署流程

通过后端向接口 POST /open/documents/create 发送 JSON 报文，传入模板 ID、参与人手机号及待填充表单值：

cURL 创建文档请求示例 
curl -X POST "https://api.example.com/open/documents/create" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9a5b3e1c-7b24-4fc6-b258-1f6920ad518e" \
  -H "X-Api-Access-Key: ak_live_d83e201048b94103" \
  -H "X-Api-Timestamp: 1789461000000" \
  -H "X-Api-Nonce: 00112233445566778899aabbccddeeff" \
  -H "X-Api-Signature: SIGNATURE_BASE64" \
  -H "X-Api-Enterprise-Id: 1002" \
  -d '{
    "source": {
      "type": "template_id",
      "template_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    },
    "title": "2026年度业务合作协议",
    "recipients": [
      {
        "recipient_role": "signer_a",
        "name": "李经理",
        "contact": "13800138000",
        "contact_type": "mobile",
        "auth_mode": "sms"
      }
    ],
    "expires_days": 30,
    "page_fields": {
      "quick-text-contract-no": "PACT-2026-0916",
      "quick-date-signing": "2026-09-16"
    }
  }'

请求成功将返回 HTTP 200，并获得合同主键 document_id 与签署人 signer_id。详见：创建文档接口文档。

5
获取签署链接并引导用户签署

如需将签署流程嵌入企业自有 App、小程序 Webview 或以短信触达签署人，调用 POST /open/documents/signUrl 获取免密安全专属签署链接：

获取签署链接 (SignUrl) 
curl -X POST "https://api.example.com/open/documents/signUrl" \
  -H "Content-Type: application/json" \
  -H "X-Api-Access-Key: ak_live_d83e201048b94103" \
  -H "X-Api-Timestamp: 1789461000000" \
  -H "X-Api-Nonce: 00112233445566778899aabbccddeeff" \
  -H "X-Api-Signature: SIGNATURE_BASE64" \
  -H "X-Api-Enterprise-Id: 1002" \
  -d '{
    "document_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "signer_id": "0a0549da-9e8d-4b6f-b0f6-d422842f0d18"
  }'

返回中将包含 sign_url。签署人打开后可按页面设置完成联系方式验证和签署同意确认，并提交签名或印章图片。详见：获取签署链接接口文档。

6
配置 Webhook 实时接收签署完成事件

在控制台配置您的回调接收 URL（必须为公网可达的 HTTPS 服务）。在合同流转过程中，系统将自动发起实时推送：

  • signer.completed：当某一签署方完成手写签名或加盖印章时触发。
  • document.completed：当所有方均完成签署、最终受控归档完成时触发。

接收服务请严格参考 Webhook 事件通知与验签规范 使用原始 Body 进行校验并返回 HTTP 200。

7
调用下载接口获取已完成平台签署流程的归档文件

收到 document.completed 事件后，调用 POST /open/documents/download（参数 type=signed），获取最终 PDF 归档文件及完整性校验记录：

接口将返回具有时效性的安全直链 download_url（有效期通常为 600 秒）。详见：文档下载接口文档。

下一步进阶阅读 (Next Steps)

公共请求头与验签规范
了解 8 组通信标头、RFC 3986 待签串构造算法与多语言代码。
全局错误码字典
查阅 400xx、401xx、409xx 业务错误码释义与处理建议。
官方 SDK 下载中心
下载纯原生独立 PHP SDK 压缩包，极速跑通示例代码。
Webhook 事件通知
了解回调报文结构、5次重试退避机制与 Raw Body 验签。