信封签署 (eSign)接口列表快速发起信封

快速发起信封

POST/openapi/v1/envelopes/quick-create

一次调用完成信封创建与发送，信封立即进入签署流程。默认通过邮件向接收人发送签署邀请。

关联关系

Tabs[].DocumentId 对应 Documents[].DocumentId，Tabs[].RecipientId 对应 Signers[].RecipientId，三者通过 ID 平铺关联。Tabs 只能引用 Signers 中的 RecipientId，不允许引用 CarbonCopies。

顺序签署

设置 BasicInfo.SigningOrderType=sequential 并为每位签署人指定不同的 SigningOrder（从 1 开始连续），系统将按顺序依次发送签署请求。

校验规则

  1. 每个签署文件至少需要有一个签署人（Signers）的签署控件
  2. 每个签署人至少需要在一个文件中存在签署控件

请求参数

Header 参数
Authorization必填string
Bearer <access_token>
X-Operator-User-Id必填string
操作用户 ID（必填，该用户将作为信封发件人）
Body 请求体
application/json
BasicInfo必填object
信封基本信息（必填）
⌃子属性
EnvelopeTitle必填string
信封标题，最长 100 字符（必填）
SigningOrderType必填string
签署顺序类型（必填）。parallel=并行签署（所有签署人同时收到邀请）；sequential=顺序签署（按 Signers[].SigningOrder 依次发送）
parallelsequential
EnvelopeDescription选填string
信封描述/备注（可选）
Expiration必填object
过期设置（必填）
⌃子属性
ExpiresAt必填string(date-time)
签署截止时间，RFC3339 格式，示例：2024-02-15T23:59:59Z。超过截止时间后信封自动作废
EmailNotification选填object
邮件通知设置（可选）
⌃子属性
EmailSubject选填string
签署邀请邮件的主题（可选，默认同 EnvelopeTitle）
EmailMessage选填string
发送给接收人的邮件正文提示语（可选）
Documents必填array<object>
文档列表，至少 1 个，最多 10 个（必填）
⌃子属性
DocumentId必填string
客户端生成的临时 ID，同一请求内唯一，供 Tab.DocumentId 引用。仅允许字母、数字、连字符(-)、下划线(_)，最长 64 字符
FileId必填string
文件资源 ID，由 UploadFile 接口返回（必填）
Name选填string
文档显示名称（可选，默认使用上传时的文件名）
Order必填integer
文档显示顺序，从 1 开始连续编号，不可重复（必填）
Signers必填array<object>
签署人列表，至少 1 个（必填）
⌃子属性
RecipientId必填string
客户端生成的临时 ID，同一请求内唯一，供 Tab.RecipientId 引用。仅允许字母、数字、连字符(-)、下划线(_)，最长 64 字符
Name必填string
姓名（必填）
Email必填string(email)
邮箱（必填）
SigningOrder选填integer
签署顺序，从 1 开始连续编号。SigningOrderType=sequential 时必填且不可重复；parallel 时忽略（可选）
CarbonCopies选填array<object>
抄送人列表（可选）
⌃子属性
RecipientId必填string
客户端生成的临时 ID，同一请求内唯一，供 Tab.RecipientId 引用。仅允许字母、数字、连字符(-)、下划线(_)，最长 64 字符
Name必填string
姓名（必填）
Email必填string(email)
邮箱（必填）
Tabs选填array<object>
签署控件列表，至少 1 个（必填），通过 Tab.RecipientId 与签署人关联
⌃子属性
TabId选填string
客户端生成的临时 ID（可选），同一请求内唯一
TabType必填string
控件类型。signHere=手写签名；stamp=印章；initialHere=首字母签名；dateSigned=签署日期（系统自动填写）；text=文本框；checkbox=复选框；date=日期（签署人手动填写）
signHerestampinitialHeredateSignedtextcheckboxdate
RecipientId必填string
所属签署人 ID，必须对应 Signers[].RecipientId，不允许引用 CarbonCopies
DocumentId必填string
所属文档 ID，对应 Documents[].DocumentId
Position必填object
控件位置（必填）
⌃子属性
PositionType必填string
定位方式（必填）。`absolute`=绝对坐标定位；`anchor`=关键字定位。
absoluteanchor
PageNumber选填integer
页码（从 1 开始）。`absolute` 模式必填；`anchor` 模式可选，省略或填 0 表示在全文档中搜索关键字。
XPosition选填number(double)
X 坐标，单位 pt。`absolute` 模式必填；`anchor` 模式不应传入。
YPosition选填number(double)
Y 坐标，单位 pt。`absolute` 模式必填；`anchor` 模式不应传入。
Width选填number(double)
宽度，单位 pt（可选，0 表示自动）
Height选填number(double)
高度，单位 pt（可选，0 表示自动）
AnchorString选填string
关键字文本。`anchor` 模式必填，`absolute` 模式不应传入。
AnchorXOffset选填number(double)
关键字定位 X 偏移量，单位 pt（可选，默认 0）。仅 `anchor` 模式有效。
AnchorYOffset选填number(double)
关键字定位 Y 偏移量，单位 pt（可选，默认 0）。仅 `anchor` 模式有效。
MatchWholeWord选填boolean
是否整词匹配，默认 false。仅 `anchor` 模式有效。 - `false`（模糊匹配）：PDF 中每一处出现该关键字的位置（前后允许有其他字符）都会放置控件。 - `true`（整词匹配）：仅匹配前后无其他字符的关键字位置。
RelativeLocation选填string
关键字定位区域对齐方式 (可选) - anchor模式使用，不传默认居中对齐。可选值: Middle(居中), Below(正下方), Right(正右方), LowerRight(右下角), UpperRight(右上角)
MiddleBelowRightLowerRightUpperRight
KeywordIndexes选填array<integer>
关键字索引 (可选) - anchor模式使用，当PDF中存在多个相同关键字时，通过索引指定使用哪些关键字。索引从0开始计数，例如 [0,2] 表示使用第1个和第3个关键字位置
TabLabel选填string
控件标签/说明文字（可选）
Value选填string
预设值（可选，text / date 类型有效）
Required选填boolean
是否必填，默认 true（可选）
ReadOnly选填boolean
是否只读，默认 false（可选）
Tooltip选填string
提示文本（可选）
Style选填object
字体样式（可选，text/date 类型有效）
⌃子属性
FontFamily选填string
字体族，默认 Arial。可选值：Arial / SimSun / SimHei / Microsoft YaHei / Times New Roman / Courier New
FontSize选填integer
字体大小，默认 12，单位 pt
FontColor选填string
字体颜色，十六进制，默认 #000000
Bold选填boolean
是否粗体，默认 false
Italic选填boolean
是否斜体，默认 false
TextAlign选填string
文本对齐方式，默认 left
leftcenterright
OutEnvelopeId选填string
外部业务 ID，用于幂等性控制（可选）。若已存在相同 OutEnvelopeId 的信封，返回原信封 ID
Watermark选填object
水印配置（可选）。不传则信封无水印
⌃子属性
SubType必填string
水印类型：CUSTOM_WATERMARK=自定义文本 / PERSON_INFO_WATERMARK=访问者信息（仅查看/签署阶段，不支持下载阶段）
CUSTOM_WATERMARKPERSON_INFO_WATERMARK
Text选填string
自定义文本，SubType=CUSTOM_WATERMARK 时必填，长度 1-50
ScopeView选填boolean
是否在查看 / 在线签署阶段叠加水印
ScopeDownload选填boolean
是否在下载 PDF 上叠加水印
Style选填object
渲染参数（可选）
⌃子属性
Font选填string
字体（默认 黑体）
黑体宋体仿宋
FontSize选填integer
字号（pt），取值范围 6-72，默认 20
Opacity选填number(double)
透明度，0=完全透明，1=完全不透明，取值范围 0-1，默认 0.1
Rotate选填integer
旋转角度（度，顺时针），取值范围 0-359，默认 45
Density选填integer
平铺密度（仅 Position=None 平铺模式生效）：1=宽松 / 2=标准（默认）/ 3=密集
Position选填string
水印位置：None=平铺（默认）/ LeftTop / LeftBottom / RightTop / RightBottom / Center
NoneLeftTopLeftBottomRightTopRightBottomCenter

请求示例

{
  "BasicInfo": {
    "SigningOrderType": "sequential",
    "Expiration": {
      "ExpiresAt": "2024-02-15T23:59:59Z"
    },
    "EnvelopeTitle": "Procurement Contract 2024-Q1"
  },
  "EmailNotification": {
    "EmailSubject": "Please sign the procurement contract",
    "EmailMessage": "Please review and sign this contract. Thank you."
  },
  "Documents": [
    {
      "DocumentId": "doc1",
      "FileId": "SGf1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
      "Name": "procurement-contract.pdf",
      "Order": 1
    }
  ],
  "Signers": [
    {
      "RecipientId": "r1",
      "Name": "张三",
      "Email": "alice@example.com",
      "SigningOrder": 1
    },
    {
      "RecipientId": "r2",
      "Name": "李四",
      "Email": "bob@example.com",
      "SigningOrder": 2
    }
  ],
  "CarbonCopies": [
    {
      "RecipientId": "cc1",
      "Name": "王五",
      "Email": "carol@example.com"
    }
  ],
  "Tabs": [
    {
      "TabType": "signHere",
      "RecipientId": "r1",
      "DocumentId": "doc1",
      "Position": {
        "PositionType": "absolute",
        "PageNumber": 3,
        "XPosition": 100,
        "YPosition": 200,
        "Width": 120,
        "Height": 40
      }
    },
    {
      "TabType": "signHere",
      "RecipientId": "r2",
      "DocumentId": "doc1",
      "Position": {
        "PositionType": "anchor",
        "AnchorString": "甲方签署",
        "AnchorXOffset": 80,
        "AnchorYOffset": -10,
        "MatchWholeWord": true,
        "RelativeLocation": "Right",
        "KeywordIndexes": [
          0
        ],
        "Width": 120,
        "Height": 40
      }
    }
  ]
}

响应参数

Response.Data
EnvelopeId选填string
信封 ID
OutEnvelopeId选填string
外部业务 ID（创建时传入则返回，否则为空）
Status选填string
本次调用的处理结果。取值： - success：调用成功，信封已发起 - partial：部分签署人处理失败 - failed：全部处理失败 说明：邮件由系统在后台投递，签署人可能会有几秒到几分钟的延迟才收到邮件。如需查询信封的最新状态（如是否已签署），请调用信封详情接口。
CreatedAt选填string(date-time)
创建时间，RFC3339 格式

响应示例

{
  "Response": {
    "RequestId": "req-abc123",
    "Error": null,
    "Data": {
      "EnvelopeId": "SGEVa1b2c3d4e5f6",
      "Status": "success",
      "CreatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

错误码

错误码说明
OPENAPI.OPERATOR_USER_ID_REQUIRED未传入 X-Operator-User-Id
OPENAPI.OPERATOR_USER_NOT_FOUNDX-Operator-User-Id 对应的用户不存在或不在当前空间内
INVALID_REQUEST请求体解析失败
VALIDATION.TITLE_EMPTY信封标题为空
VALIDATION.TITLE_TOO_LONG信封标题超过 100 字符
VALIDATION.SIGNING_ORDER_TYPE_INVALIDSigningOrderType 取值非法
VALIDATION.DOCUMENT_REQUIRED文档列表为空
VALIDATION.DOCUMENT_ID_DUPLICATE文档 ID 重复
VALIDATION.DOCUMENT_FILE_ID_EMPTY文档 FileId 为空
VALIDATION.SIGNER_REQUIRED签署人列表为空
VALIDATION.RECIPIENT_ID_DUPLICATE签署人或抄送人 ID 重复
VALIDATION.RECIPIENT_EMAIL_INVALID邮箱格式错误
VALIDATION.SIGNER_REQUIRES_TAB签署人缺少签署控件
VALIDATION.DOCUMENT_REQUIRES_SIGNER_TAB文档缺少签署人控件
VALIDATION.SIGNING_ORDER_INVALID签署顺序设置错误
VALIDATION.TAB_TYPE_INVALID控件类型不合法
VALIDATION.TAB_DOCUMENT_INVALID控件关联的文档不存在
VALIDATION.TAB_RECIPIENT_NOT_SIGNER控件的 RecipientId 不是 Signers 中的 ID
VALIDATION.EXPIRES_AT_PAST过期时间早于当前时间
ENVELOPE.OUT_ID_DUPLICATEOutEnvelopeId 已存在（返回原信封信息）
INTERNAL_ERROR服务内部错误
上传文件查询信封详情