查询文档详情

POST /open/documents/detail 只读查询接口

根据 document_id 获取单份签署文档的详细信息,包括文档生命周期状态、各签署人节点的签署进度与时间戳。

隐私安全与敏感字段隔离
详情接口严格遵循安全规范,不会直接回显签署人联系电话/邮箱、签署链接与物理存储地址。获取专属签署链接请调用 获取签署链接接口;下载文件请调用 文档下载地址接口

请求头 (Request Headers)

本接口无特殊请求头,仅需携带标准公共请求头(无需 Idempotency-Key)。详细标头定义与 HMAC-SHA256 签名算法请参阅:公共请求头与验签规范

请求体参数 (Request Body)

参数名 类型 必填 详细描述
document_id string 必填 需要查询的目标文档唯一 UUID v4 标识符。

请求示例 (Request Example)

curl -X POST "https://api.example.com/open/documents/detail" \
  -H "Content-Type: application/json" \
  -H "X-Api-Access-Key: ak_live_d83e201048b94103" \
  -H "X-Api-Timestamp: 1789461000000" \
  -H "X-Api-Nonce: 00112233445566778899aabbccddeeff" \
  -H "X-Api-Signature: SIGNATURE_BASE64" \
  -H "X-Api-Enterprise-Id: 1002" \
  -d '{
    "document_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }'

响应数据结构 (Response Body)

字段名 类型 详细说明
document_id string 文档唯一 UUID。
title string 文档标题。
status string 文档状态:in_progress(签署中)、completed(已完成)、voided(已撤销)。
signing_mode string 签署顺序模式:parallel (并行) 或 sequential (顺序)。
page_count integer 文档总页数。
recipient_count integer 有效签署人数量。
signed_count integer 已签署完成的人数。
recipients array<object> 收件人/签署节点列表。
└─recipient_id string 签署节点唯一 UUID。后续调用获取专属签署链接时必须提供该 ID。
└─name string 签署人姓名或角色名。
└─role string 节点角色:signer(签署方)或 cc(抄送方)。
└─sign_order integer 签署顺序编号。
└─status string 该签署人的状态:pending (待签)、signed (已签)、declined (拒签)。
└─signed_at integer 完成签署的时间戳(Unix 秒级);若未签署则为 0

响应示例 (Response Example)

200 OK (成功)
{
  "code": 0,
  "message": "success",
  "data": {
    "document_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "title": "在线教育服务协议",
    "status": "in_progress",
    "signing_mode": "parallel",
    "page_count": 3,
    "recipient_count": 2,
    "signed_count": 1,
    "expires_at": 1790000000,
    "sent_at": 1789900000,
    "completed_at": 0,
    "voided_at": 0,
    "created_at": "2026-09-16 10:00:00",
    "updated_at": "2026-09-16 10:30:00",
    "recipients": [
      {
        "recipient_id": "0a0549da-9e8d-4b6f-b0f6-d422842f0d18",
        "name": "张三",
        "role": "signer",
        "sign_order": 1,
        "status": "signed",
        "signed_at": 1789901000
      }
    ]
  },
  "request_id": "req_68dfb7829a10ef4"
}

相关错误码 (Error Codes)

全部公共状态码与安全拦截说明请参阅:全局错误码字典 (Error Codes)

HTTP 状态 错误码 (code) 错误标识 (Constant) 产生原因与排查指引
400 40001 BAD_REQUEST 缺少 document_id 参数或格式不正确。
404 40401 NOT_FOUND 指定的文档 ID 不存在,或非当前企业/当前凭证归属成员名下的文档。