信封签署 (eSign)接口列表获取签署链接

获取签署链接

POST/openapi/v1/envelopes/signing-view

为信封的签署人生成一次性签署链接。

  • 链接有效期以响应 ExpiresAt 为准，默认 1 小时（Trusted 与普通模式一致）。过期须重新调用本接口获取
  • 同一签署人多次调用会使旧链接失效，请勿缓存链接
  • 抄送人（CarbonCopies）不返回签署链接

筛选规则

  • 同时传 RecipientId 与 RecipientEmail 时，以 RecipientId 为准，RecipientEmail 被忽略
  • 只传其中一项，按该字段筛选返回单个签署人的链接
  • 两者都不传，返回该信封下所有签署人的链接列表

Embedded（内嵌）签署

将 SigningUrl 内嵌到自有系统（iframe / 新窗口）即构成内嵌签署页。可通过请求体扩展字段定制：

  • TrustedMode=true：跳过平台登录认证（客户已完成自有认证），要求 App 已开通 Trusted Signing 且本签署人已提供 ClientUserId（本接口仅单签署人）
  • ReturnUrl：签署人完成或结束签署后浏览器自动回跳到该地址，并附带 event（如 signing_complete）、envelopeId、recipientId 参数，客户系统可据此处理后续流程，无需轮询信封状态
  • ClientUserId：本签署人对应的客户侧用户标识（单值写法，无需数组），供客户系统识别签署人身份；与该签署人已绑定的值不一致时报错（防错绑），未绑定时首次写入

请求参数

Header 参数
Authorization必填string
Bearer <access_token>
X-Operator-User-Id选填string
操作用户 ID。授权码模式下无需传（自动使用授权用户）；客户端凭据模式下可选，不填时使用系统用户 ID。
Body 请求体
application/json
EnvelopeId必填string
信封 ID（必填）
RecipientId选填string
签署人 ID（可选，用于筛选单个签署人）
RecipientEmail选填string(email)
签署人邮箱（可选，用于筛选单个签署人）。若同时传 RecipientId 与 RecipientEmail，以 RecipientId 为准，Email 被忽略
ClientUserId选填string
单个签署人的客户侧用户标识（可选；本接口仅支持单签署人）。作用于 RecipientId / RecipientEmail 选定的那一个签署人：与该签署人已绑定的 ClientUserId 不一致时报错（防错绑）、未绑定时首次写入。TrustedMode=true 时必须提供。
ReturnUrl选填string
签署完成回跳地址（可选，仅 Embedded 场景）。须经该 App 的 signing_return 集成 allowlist 校验通过后才会随签署链接生效；仅允许 HTTPS 地址。
TrustedMode选填boolean
Trusted Embedded Signing 模式（可选，默认 false）。true 表示客户已完成自有登录认证，其用户可跳过我方认证直接进入签署；须 App 已开通 Trusted Signing 能力，且每个目标签署人已绑定 ClientUserId，否则报错。

请求示例

{
  "EnvelopeId": "SGEV1234567890",
  "RecipientId": "r1",
  "ClientUserId": "my-client-user-001"
}

响应参数

Response.Data
EnvelopeId选填string
信封 ID
EnvelopeStatus选填string
信封当前状态。draft=草稿；sending=发送中（大文档异步关键字解析中）；sent=签署中；sent_failed=发送失败（异步解析失败或超时）；completed=已完成；voided=已作废；declined=已拒签
draftsendingsentsent_failedcompletedvoideddeclined
SignerInfos选填array<object>
签署人签署链接列表
RecipientId选填string
系统分配的接收人 ID
Name选填string
姓名（必填）
Email选填string
邮箱（脱敏展示，如 z***@example.com）
SigningOrder选填integer
签署顺序（SigningOrderType=parallel 时统一为 0）
SigningUrl选填string
签署链接
ExpiresAt选填string(date-time)
链接过期时间，RFC3339 格式，示例：2024-01-15T11:00:00Z

响应示例

{
  "Response": {
    "RequestId": "req-abc123",
    "Error": null,
    "Data": {
      "EnvelopeId": "SGEV1234567890",
      "EnvelopeStatus": "sent",
      "SignerInfos": [
        {
          "RecipientId": "r1",
          "Name": "Alice",
          "Email": "a***@example.com",
          "SigningOrder": 1,
          "SigningUrl": "https://sign.example.com/signing/eyJhbGciOi...",
          "ExpiresAt": "2024-01-15T11:00:00Z"
        }
      ]
    }
  }
}

错误码

错误码说明
INVALID_REQUEST请求参数错误（EnvelopeId 为空等）
NOT_FOUND信封不存在
RECIPIENT.NOT_RECIPIENT指定的 RecipientId / Email 不是该信封的签署人
ENVELOPE.INVALID_STATUS信封状态不允许签署（已完成、已作废、草稿等）
SIGNING.RECIPIENT_ALREADY_SIGNED该签署人已完成签署
SIGNING.RECIPIENT_DECLINED该签署人已拒签
INTERNAL_ERROR服务内部错误
API_SIGNING.TRUSTED_SIGNING_NOT_ENABLEDTrusted 模式未开通（该 App 未启用 Trusted Signing 能力）
API_SIGNING.TRUSTED_SIGNING_CLIENT_USER_ID_REQUIREDTrusted 模式下目标签署人缺少 ClientUserId 绑定
API_SIGNING.RETURN_URL_NOT_ALLOWEDReturnUrl 不在该 App 的 signing_return allowlist 中
查询信封详情撤销信封