查询信封详情

POST/openapi/v1/envelopes/detail

查询信封的当前状态及签署人签署进度。

请求参数

Header 参数

Authorization必填string

Bearer <access_token>

X-Operator-User-Id选填string

操作用户 ID。授权码模式下无需传（自动使用授权用户）；客户端凭据模式下可选，不填时使用系统用户 ID。

Body 请求体

application/json

EnvelopeId必填string

信封 ID（必填）

请求示例

{
  "EnvelopeId": "SGEV1234567890"
}

响应参数

Response.Data

EnvelopeId选填string

信封 ID

OutEnvelopeId选填string

外部业务 ID（创建时传入则返回，否则为空）

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 默认使用信封标题，EmailMessage 为空

⌃子属性

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` 同时传。本设置仅影响邮件，不影响短信与邮箱验证码。

StatusDetail选填object

信封状态详情

⌃子属性

Status选填string

信封当前状态。draft=草稿；sending=发送中（大文档异步关键字解析中）；sent=签署中（含已发送/已投递/已查看/部分签署）；sent_failed=发送失败（大文档异步关键字解析失败或超时）；completed=已完成；voided=已作废；declined=已拒签

draftsendingsentsent_failedcompletedvoideddeclined

CreatedAt选填string(date-time)

创建时间，RFC3339 格式

SentAt选填string(date-time)

发送时间，RFC3339 格式（草稿状态为空）

CompletedAt选填string(date-time)

完成时间，RFC3339 格式（仅 completed 状态有值）

VoidedAt选填string(date-time)

作废时间，RFC3339 格式（仅 voided 状态有值）

VoidReason选填string

作废原因（仅 voided 状态有值）

FailureReason选填string

发送失败原因（仅当 Status = sent_failed 时返回）。

Documents选填array<object>

文档列表

⌃子属性

DocumentId选填string

系统分配的文档 ID

Name选填string

文档名称

Order选填integer

文档显示顺序

PageCount选填integer

文档页数

DocPages选填array<object>

文档页面列表

⌃子属性

PageNumber选填integer

页码（从 1 开始）

Width选填number(double)

页面宽度（PDF 原生单位）

Height选填number(double)

页面高度（PDF 原生单位）

Signers选填array<object>

签署人列表，含签署状态

⌃子属性

RecipientId选填string

系统分配的接收人 ID

Name选填string

姓名（必填）

Email选填string

邮箱（脱敏展示，如 z***@example.com）

SigningOrder选填integer

签署顺序（SigningOrderType=parallel 时统一为 0）

Status选填string

签署人状态。created=已创建；sent=已发送；delivered=已投递；viewed=已查看；signed=已签署；declined=已拒签；voided=已作废

createdsentdeliveredviewedsigneddeclinedvoided

SignedAt选填string(date-time)

签署完成时间，RFC3339 格式（仅 signed 状态有值）

StatusUpdatedAt选填string(date-time)

状态最后更新时间，RFC3339 格式

DeclineReason选填string

拒签原因（仅 declined 状态有值）

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

Name选填string

姓名（必填）

Email选填string

邮箱（脱敏展示，如 z***@example.com）

Status选填string

抄送人状态。created=已创建；sent=已发送；delivered=已投递；viewed=已查看

createdsentdeliveredviewed

StatusUpdatedAt选填string(date-time)

状态最后更新时间，RFC3339 格式

Tabs选填array<object>

信封内所有签署控件列表

⌃子属性

TabId选填string

系统分配的控件 ID

TabType选填string

控件类型

signHerestampinitialHeredateSignedtextcheckboxdate

RecipientId选填string

所属签署人 ID

DocumentId选填string

所属文档 ID

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

控件标签，在签署页作为该控件的占位提示文字显示

Value选填string

预设值

Required选填boolean

是否必填

ReadOnly选填boolean

是否只读

Tooltip选填string

提示文本

Style选填object

字体样式

⌃子属性

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

CurrentValue选填string

签署人实际填写/选择的值（text/checkbox/date 类型有值）

FilledAt选填string(date-time)

控件填写时间，RFC3339 格式

Properties选填string

类型特定扩展属性（JSON 字符串），与创建时传入的 Tab.Properties 一致

Name选填string

控件名称，与该控件创建时传入的 Name 一致；创建时未传 Name 时为其 TabLabel 值

CreatedBy选填object

创建人信息

⌃子属性

UserId选填string

用户 ID

Name选填string

用户名称

Email选填string

用户邮箱

Watermark选填object

水印配置 - 信封无水印配置时该字段为 null

⌃子属性

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 项

错误码

错误码	说明
`INVALID_REQUEST`	请求体解析失败或 EnvelopeId 为空
`NOT_FOUND`	信封不存在
`INTERNAL_ERROR`	服务内部错误

快速发起信封获取签署链接