快速发起信封

POST/openapi/v1/envelopes/quick-create

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

关联关系

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

顺序签署

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

校验规则

每个签署文件至少需要有一个签署人（Signers）的签署控件
每个签署人至少需要在一个文件中存在签署控件
当 BasicInfo.SigningOrderType=sequential 时，所有签署人必须填写 SigningOrder，且必须从 1 开始连续（如 1,2,3），不可跳号

所需 Scope：envelope:create（持有 envelope:manage 超集 scope 亦可）

请求参数

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

发送给接收人的邮件正文提示语（可选）

SkippedNotifications选填array<string>

邮件通知跳过项。命中的通知对象在对应阶段不再收到邮件；不传或传空数组 = 不跳过任何通知（默认行为）。可选值（6 个）： - `sender_on_sent`：发起后不通知发起方 - `signer_on_sent`：发起后不通知签署方 - `cc_on_sent`：发起后不通知抄送方 - `sender_on_finished`：完成/结束后不通知发起方 - `signer_on_finished`：完成/结束后不通知签署方 - `cc_on_finished`：完成/结束后不通知抄送方 “完成/结束”涵盖全部终态：全部签署完成、作废、过期、拒签。注意：同一个人可能同时属于多个通知对象（如发起方同时是签署方），此时需把对应的多个取值都传入才能让他完全不收 —— 例如 `sender_on_finished` 与 `signer_on_finished` 同时传。本设置仅影响邮件，不影响短信与邮箱验证码。

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

签署顺序。SigningOrderType=sequential 时必填，从 1 开始连续编号且不可重复；parallel 时须不传或为 0，传非 0 值将返回 VALIDATION.SIGNING_ORDER_CONFLICT

Authentication选填object

签署人身份验证设置（可选，不传时签署人打开链接无需额外验证）

⌃子属性

AuthMethods选填array<string>

验证方式，单选（可组合能力暂未开放）。可选值: "email"(邮箱验证) | "access_code"(线下口令) | "ekyc"(实名核验)。不支持 "none"；不传 Authentication 即为无验证

AccessCode选填string

访问口令 - AuthMethods 含 "access_code" 时必填，签署人须输入口令才能进入签署页

EkycCertType选填string

实名核验证件类型 - AuthMethods 含 "ekyc" 时必填。可选值: "idcard"(身份证) | "passport"(护照) | "hkid"(香港身份证)

CarbonCopies选填array<object>

抄送人列表（可选）

⌃子属性

RecipientId必填string

客户端生成的临时 ID，同一请求内唯一，供 Tab.RecipientId 引用。仅允许字母、数字、连字符(-)、下划线(_)，最长 64 字符

Name必填string

姓名（必填）

Email必填string(email)

邮箱（必填）

Tabs必填array<object>

签署控件列表，至少 1 个（必填），通过 Tab.RecipientId 与签署人关联；SigningSettings.AllowFreePlaceTabs=true 时可为空，由签署人签署时自行添加

⌃子属性

TabId选填string

客户端生成的临时 ID（可选），同一请求内唯一

TabType必填string

控件类型。signHere=手写签名；stamp=印章；initialHere=首字母签名；dateSigned=签署日期（系统自动填写）；text=文本框；checkbox=复选框；date=日期（签署人手动填写）；attachment=附件（签署人上传图片，需配合 Properties 使用）

signHerestampinitialHeredateSignedtextcheckboxdateattachment

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（1 pt = 1/72 英寸）。建议传入具体数值（范围 60~300）。传 0 或不传时，服务端按 TabType 填入默认宽度：signHere / initialHere / stamp / attachment / text 为 120，checkbox 为 16。

Height选填number(double)

控件高度，单位 pt（1 pt = 1/72 英寸）。建议传入具体数值（范围 20~120）。传 0 或不传时，服务端按 TabType 填入默认高度：signHere / initialHere 为 50，stamp 为 120，attachment 为 120，checkbox 为 16，text 为 18。

AnchorString选填string

关键字文本。`anchor` 模式必填，`absolute` 模式不应传入。

AnchorXOffset选填number(double)

关键字定位 X 偏移量，单位 pt（可选，默认 0）。仅 `anchor` 模式有效。表示在 `RelativeLocation` 指定的位置基础上，沿水平方向额外偏移的距离；正值向右，负值向左。

AnchorYOffset选填number(double)

关键字定位 Y 偏移量，单位 pt（可选，默认 0）。仅 `anchor` 模式有效。表示在 `RelativeLocation` 指定的位置基础上，沿垂直方向额外偏移的距离；正值向下，负值向上。

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

控件标签（可选）。在签署页作为该控件的占位提示文字显示（如文本框的输入提示）。渲染到最终文档上的标题请用 Name。

Value选填string

预设值（可选，text / date 类型有效）

Required选填boolean

是否必填，默认 true（可选）

ReadOnly选填boolean

是否只读，默认 false（可选）

Tooltip选填string

提示文本（可选）

Style选填object

字体样式（可选，text/date 类型有效）

⌃子属性

FontFamily选填string

字体族（默认 SimHei）。SimHei=黑体（无衬线）；SimSun=宋体（衬线）；FangSong=仿宋（衬线）。可选值：SimHei / SimSun / FangSong

SimHeiSimSunFangSong

FontSize选填integer

字体大小，默认 12，单位 pt

FontColor选填string

字体颜色，十六进制，默认 #000000

Bold选填boolean

是否粗体，默认 false

Italic选填boolean

是否斜体，默认 false

TextAlign选填string

文本对齐方式，默认 left

leftcenterright

Properties选填string

类型特定扩展属性（可选），JSON 字符串。结构随 TabType 不同，如下

⌃子属性

attachment（附件控件）

"{\"AttachmentType\":\"image\",\"MaxCount\":3}"

字段	类型	必填	说明
`AttachmentType`	string	否	附件类型。当前仅支持 `image`（签署人上传图片），不传默认为 `image`
`MaxCount`	integer	否	单个附件控件可上传的图片数量。取值范围 1-6，不传或传 0 时按 1 处理，超过 6 返回参数错误

text（文本框）

"{\"FormatType\":\"email\",\"MaxLength\":100}"

字段	类型	必填	说明
`FormatType`	string	否	填写格式。`text`=单行文本（默认）；`email`=邮箱；`number`=数字
`MaxLength`	integer	否	最大长度，默认 4000

注意：须为合法的 JSON 对象，且只能使用对应 TabType 支持的字段，否则返回参数错误。

Name选填string

控件名称（可选）。作为该控件渲染到最终文档上的标题；attachment 类型下即附件页上的附件名称。未传入时回退使用 TabLabel。

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

字体（默认 SimHei）。SimHei=黑体（无衬线）；SimSun=宋体（衬线）；FangSong=仿宋（衬线）。可选值：SimHei / SimSun / FangSong

SimHeiSimSunFangSong

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

SigningSettings选填object

签署设置（可选）

⌃子属性

AllowFreePlaceTabs选填boolean

是否允许签署人在签署时自行添加签署控件（可选，默认 false）。设为 true 时 Tabs 可为空，签署人于签署页自助添加控件后完成签署；设为 false 时 Tabs 至少须含 1 项

请求示例

{
  "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

信封状态，发送成功后为 sent；大文档异步关键字解析中为 sending

sendingsent

CreatedAt选填string(date-time)

创建时间，RFC3339 格式

响应示例

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

错误码

错误码	说明
`OPENAPI.OPERATOR_USER_ID_REQUIRED`	未传入 X-Operator-User-Id
`OPENAPI.OPERATOR_USER_NOT_FOUND`	X-Operator-User-Id 对应的用户不存在或不在当前空间内
`OPENAPI.OPERATOR_USER_NOT_HUMAN`	操作用户必须是当前空间内的成员
`INVALID_REQUEST`	请求体解析失败
`VALIDATION.TITLE_EMPTY`	信封标题为空
`VALIDATION.TITLE_TOO_LONG`	信封标题超过 100 字符
`VALIDATION.SIGNING_ORDER_TYPE_INVALID`	SigningOrderType 取值非法
`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.SIGNING_ORDER_REQUIRED`	sequential 模式下 SigningOrder 缺失
`VALIDATION.SIGNING_ORDER_NOT_SEQUENTIAL`	签署顺序未从 1 开始连续
`VALIDATION.SIGNING_ORDER_CONFLICT`	parallel 模式下签署人传了非 0 的 SigningOrder
`VALIDATION.TAB_TYPE_INVALID`	控件类型不合法
`VALIDATION.TAB_DOCUMENT_NOT_EXIST`	控件关联的文档不存在
`VALIDATION.TAB_RECIPIENT_NOT_SIGNER`	控件的 RecipientId 不是 Signers 中的 ID
`VALIDATION.EXPIRES_AT_PAST`	过期时间早于当前时间
`ENVELOPE.OUT_ID_DUPLICATE`	OutEnvelopeId 已存在（返回原信封信息）
`EXTENSION.SKIPPED_NOTIFICATION_INVALID`	SkippedNotifications 取值非法（不在 6 个可选值内）
`INTERNAL_ERROR`	服务内部错误

批量查询文件转换任务查询信封详情