信封签署 (eSign)接口列表查询信封详情

查询信封详情

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
发送给接收人的邮件正文提示语（可选）
StatusDetail选填object
信封状态详情
⌃子属性
Status选填string
信封当前状态。draft=草稿；sent=签署中（含已发送/已投递/已查看/部分签署）；completed=已完成；voided=已作废；declined=已拒签
draftsentcompletedvoideddeclined
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 状态有值）
Documents选填array<object>
文档列表
⌃子属性
DocumentId选填string
系统分配的文档 ID
Name选填string
文档名称
Order选填integer
文档显示顺序
PageCount选填integer
文档页数
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 状态有值）
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（可选，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
预设值
Required选填boolean
是否必填
ReadOnly选填boolean
是否只读
Tooltip选填string
提示文本
Style选填object
字体样式
⌃子属性
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
CurrentValue选填string
签署人实际填写/选择的值（text/checkbox/date 类型有值）
FilledAt选填string(date-time)
控件填写时间，RFC3339 格式
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
字体（默认 黑体）
黑体宋体仿宋
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

错误码

错误码说明
INVALID_REQUEST请求体解析失败或 EnvelopeId 为空
NOT_FOUND信封不存在
INTERNAL_ERROR服务内部错误
快速发起信封获取签署链接