查询文档列表

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

在当前凭证归属企业及成员的数据可见范围内，分页查询其发起的签署文档列表。支持按文档生命周期状态进行过滤筛选。

数据可见范围与敏感信息保护

本接口严格限制仅返回“当前目标企业内、当前 Access Key 归属成员创建”的未删除文档。为保护隐私合规，列表响应中不返回签署人联系方式、签署链接与内部文件主键。

请求头 (Request Headers)

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

请求体参数 (Request Body)

参数名	类型	必填	详细描述
page	integer	可选	分页页码，从 1 开始计数。默认值：`1`
page_size	integer	可选	每页返回记录数，取值范围为 `1` 至 `100`。默认值：`20`
status	string	可选	按文档生命周期状态筛选： • `in_progress`：签署中 • `completed`：全部完成 • `ready`：就绪草稿 • `declined`：已拒签 • `voided`：已作废/已撤销 • `expired`：已逾期过期

请求示例 (Request Example)

curl -X POST "https://api.example.com/open/documents/list" \
  -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 '{
    "page": 1,
    "page_size": 20,
    "status": "in_progress"
  }'

<?php
use DsignSdk\DsignClient;

$client = new DsignClient([
    'base_url'      => 'https://api.example.com',
    'access_key'    => 'ak_live_d83e201048b94103',
    'secret_key'    => 'sk_live_948f2038102941029',
    'enterprise_id' => '1002',
]);

$response = $client->documents->list([
    'page'      => 1,
    'page_size' => 20,
    'status'    => 'in_progress',
]);

echo "查询到总记录数: " . $response['total'];
foreach ($response['items'] as $doc) {
    echo "文档: " . $doc['title'] . " (" . $doc['status'] . ")\n";
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.UUID;

public class ListDocumentsDemo {
    public static void main(String[] args) throws Exception {
        String accessKey = "ak_live_d83e201048b94103";
        String secretKey = "sk_live_948f2038102941029";
        String enterpriseId = "1002";
        long timestampMs = System.currentTimeMillis();
        String nonce = UUID.randomUUID().toString().replace("-", "");

        String jsonBody = "{\n" +
            "  \"page\": 1,\n" +
            "  \"page_size\": 20,\n" +
            "  \"status\": \"in_progress\"\n" +
            "}";

        String signature = DsignSigner.buildSignature(
            secretKey, "POST", "/open/documents/list", "", jsonBody,
            timestampMs, nonce, enterpriseId, ""
        );

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.example.com/open/documents/list"))
            .header("Content-Type", "application/json; charset=utf-8")
            .header("X-Api-Access-Key", accessKey)
            .header("X-Api-Timestamp", String.valueOf(timestampMs))
            .header("X-Api-Nonce", nonce)
            .header("X-Api-Signature", signature)
            .header("X-Api-Enterprise-Id", enterpriseId)
            .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("HTTP 状态码: " + response.statusCode());
        System.out.println("响应列表: " + response.body());
    }
}

import requests, json
# 使用通用签名算法组装请求头
resp = requests.post("https://api.example.com/open/documents/list",
    headers=headers,
    data=json.dumps({"page": 1, "page_size": 20, "status": "in_progress"})
)
print(resp.json())

const axios = require('axios');

axios.post('https://api.example.com/open/documents/list', {
  page: 1,
  page_size: 20,
  status: 'in_progress'
}, { headers }).then(res => console.log(res.data));

响应数据结构 (Response Body)

字段名	类型	详细说明
code	integer	`0` 表示成功。
data.page	integer	当前页码。
data.page_size	integer	当前每页容量条数。
data.total	integer	满足筛选条件的文档总记录数。
data.total_pages	integer	总页数。
data.items	array<object>	文档记录列表。
└─document_id	string	文档唯一 UUID。
└─title	string	文档名称/标题。
└─status	string	生命周期状态：`in_progress`、`completed`、`voided` 等。
└─signing_mode	string	签署流程模式：`parallel` 或 `sequential`。
└─recipient_count	integer	需签署的有效签署人数量。
└─signed_count	integer	当前已完成签署的人数。
└─expires_at	integer	签署截止 Unix 时间戳（秒级）。
└─created_at	string	创建时间（`YYYY-MM-DD HH:mm:ss`）。

响应示例 (Response Example)

200 OK (查询成功)

{
  "code": 0,
  "message": "success",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "items": [
      {
        "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,
        "created_at": "2026-09-16 10:00:00",
        "updated_at": "2026-09-16 10:30:00"
      }
    ]
  },
  "request_id": "req_68dfb7829a10ef4"
}

HTTP 状态	错误码 (code)	错误标识 (Constant)	产生原因与排查指引
400	40001	BAD_REQUEST	页码小于 1，或 page_size 超出 1–100 允许范围。
401	40101	AUTH_FAILED	凭证失效或请求签名不匹配。