创建并发起签署文档

POST /open/documents/create 强制幂等保护

基于目标企业预设模板在云端快速创建一份签署文档、自动绑定签署人与填充表单控件值，并在同一流程中直接发起签署流程。如果企业或模板配置了审批规则，流程将自动流转至待审批节点并通过响应中的 next_action 返回后续动作标识。

可见范围与权限隔离

接口仅允许调用当前目标企业内、且当前 Access Key 归属成员有权访问的模板。成功创建出的文档数据域归属于该凭证成员，保障多租户与成员级权限隔离。

幂等性要求 (Idempotency-Key)

本接口属于强状态写入操作，必须在请求头中携带 Idempotency-Key（16–100 个 ASCII 字符）。网络超时等未知异常时，必须使用完全相同的 Key 和相同的 Body 重试。若使用相同 Key 发送了不同 Body，接口将返回 40902 (IDEMPOTENCY_KEY_REUSED)。

请求头 (Request Headers)

本接口直接继承开放平台的全部基础通信标头。公共请求头（含 Access Key、时间戳、Nonce、签名与企业标识）规范请参阅：公共请求头与验签规范文档。

Header 名称	类型	是否必填	说明
Idempotency-Key	string	必填	本接口专用强幂等键：16–100 个 ASCII 字符，用于防止网络超时等重试场景下重复创建多份文档造成扣费或资源冲突。
公共请求头组	headers	必填	包含 `X-Api-Access-Key`、`X-Api-Timestamp`、`X-Api-Nonce`、`X-Api-Signature` 以及条件必选的 `X-Api-Enterprise-Id`。详见公共请求头说明。

请求体参数 (Request Body)

参数名	类型	必填	详细描述
source	object	必填	模板数据源定位对象。
└─ source.type	string	必填	数据源类型。当前固定为 `template_id`。
└─ source.template_id	string	必填	模板唯一 UUID（可在管理后台模版列表获取）。
└─ source.version_no	integer	可选	指定模板特定发布版本号。默认使用模板最新发布版本。
title	string	可选	新生成文档的标题。如不传则默认沿用模板配置的名称。
recipients	array<object>	必填	非空的签署人/角色映射数组。每个模板角色只能出现一次，必须精确匹配模板中的配置。
└─ recipients[].recipient_role	string	必填	模板中定义的角色标识键（如 `signer_1`, `employee` 等）。
└─ recipients[].name	string	可选	签署人在界面展示的真实姓名/称谓。默认为角色名。
└─ recipients[].contact	string	条件必填	`sms` 模式下必填的预指定手机号或邮箱； `self_mobile_otp`/`self_email_otp` 模式下请留空。
└─ recipients[].contact_type	string	可选	联系方式类型：`mobile` (手机号)、`email` (电子邮箱) 或 `none`。默认值：`none`
└─ recipients[].auth_mode	string	可选	签署人访问验证策略：`none` (无额外验证)、`sms` (验证预先指定的手机号/邮箱)、`self_mobile_otp` (签署人填写手机号)、 `self_email_otp` (签署人填写邮箱) 或 `password`。默认值：`none`
└─ recipients[].password	string	条件必填	认证方式为 `password` 时必须提供。服务端加密存储，不在任何接口明文回显。
└─ recipients[].sign_order	integer	可选	签署顺序。在按序签署模式下从 1 开始依次轮转。
signing_mode	string	可选	签署流程模式：`parallel` (并行无序签署)、`sequential` (严格顺序签署)。默认值：`parallel`
expires_days	integer	可选	文档有效期（天数）。如果同时传入了 `expires_at`，以 `expires_at` 为准。默认值：`30`
expires_at	integer	可选	签署截止时间的 10 位 Unix 秒级时间戳。
page_fields	object	可选	快捷字段键值映射对象（Key-Value Map）。必须为以字段 Key 为键的 Object，不可传 Array。 • 快捷文本 / 快捷日期：直接传入字符串值。 • 快捷图片：传入包含 base64 数据的对象 `{"base64": "data:image/png;base64,..."}`，支持 PNG/JPEG，解码后限制 5 MiB。
watermark_config_id	string	可选	企业预设的水印策略配置 ID。
approval	object	可选	签署审批策略配置覆盖项。
initiator_delivery_responsibility_acknowledged	boolean	可选	当开启严格送达责任风控时，发起人需显式传入 `true` 确认承担通知与送达责任。
l0_link_risk_acknowledged	boolean	可选	当生成公开直连无鉴权链接时，需确认 L0 等级链接安全风险时传 `true`。

请求示例 (Request Example)

支持使用原生 cURL、官方 PHP SDK 或 Python/Node.js 进行调用：

curl -X POST "https://api.example.com/open/documents/create" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9a5b3e1c-7b24-4fc6-b258-1f6920ad518e" \
  -H "X-Api-Access-Key: ak_live_d83e201048b94103" \
  -H "X-Api-Timestamp: 1789461000000" \
  -H "X-Api-Nonce: 00112233445566778899aabbccddeeff" \
  -H "X-Api-Signature: iFzS5vOmFdjcL4bj0M34JyhcLZyuFvmTHUGOb+qook0=" \
  -H "X-Api-Enterprise-Id: 1002" \
  -d '{
    "source": {
      "type": "template_id",
      "template_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    },
    "title": "2026年度业务合作协议",
    "recipients": [
      {
        "recipient_role": "signer_a",
        "name": "李经理",
        "contact": "13800138000",
        "contact_type": "mobile",
        "auth_mode": "sms",
        "sign_order": 1
      }
    ],
    "expires_days": 30,
    "page_fields": {
      "quick-text-contract-no": "PACT-2026-0916",
      "quick-date-signing": "2026-09-16"
    },
    "initiator_delivery_responsibility_acknowledged": true
  }'

<?php
use DsignSdk\DsignClient;

// 1. 初始化客户端
$client = new DsignClient([
    'base_url'      => 'https://api.example.com',
    'access_key'    => 'ak_live_d83e201048b94103',
    'secret_key'    => 'sk_live_948f2038102941029',
    'enterprise_id' => '1002',
]);

// 2. 创建并立即发起签署
$result = $client->documents->create([
    'source' => [
        'type'        => 'template_id',
        'template_id' => '7c9e6679-7425-40de-944b-e07fc1f90ae7',
    ],
    'title' => '2026年度业务合作协议',
    'recipients' => [
        [
            'recipient_role' => 'signer_a',
            'name'           => '李经理',
            'contact'        => '13800138000',
            'contact_type'   => 'mobile',
            'auth_mode'      => 'sms',
        ]
    ],
    'expires_days' => 30,
    'page_fields' => [
        'quick-text-contract-no' => 'PACT-2026-0916',
        'quick-date-signing'     => '2026-09-16',
    ],
    'initiator_delivery_responsibility_acknowledged' => true,
]);

echo "文档创建成功，ID: " . $result['document_id'];

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 CreateDocumentDemo {
    public static void main(String[] args) throws Exception {
        String accessKey = "ak_live_d83e201048b94103";
        String secretKey = "sk_live_948f2038102941029";
        String enterpriseId = "1002";
        String idempotencyKey = UUID.randomUUID().toString();
        long timestampMs = System.currentTimeMillis();
        String nonce = UUID.randomUUID().toString().replace("-", "");

        String jsonBody = "{\n" +
            "  \"source\": {\n" +
            "    \"type\": \"template_id\",\n" +
            "    \"template_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n" +
            "  },\n" +
            "  \"title\": \"2026年度业务合作协议\",\n" +
            "  \"recipients\": [\n" +
            "    {\n" +
            "      \"recipient_role\": \"signer_a\",\n" +
            "      \"name\": \"李经理\",\n" +
            "      \"contact\": \"13800138000\",\n" +
            "      \"contact_type\": \"mobile\",\n" +
            "      \"auth_mode\": \"sms\"\n" +
            "    }\n" +
            "  ],\n" +
            "  \"expires_days\": 30,\n" +
            "  \"page_fields\": {\n" +
            "    \"quick-text-contract-no\": \"PACT-2026-0916\"\n" +
            "  }\n" +
            "}";

        // 计算 HMAC-SHA256 签名 (详见公共请求头与验签文档 DsignSigner)
        String signature = DsignSigner.buildSignature(
            secretKey, "POST", "/open/documents/create", "", jsonBody,
            timestampMs, nonce, enterpriseId, idempotencyKey
        );

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.example.com/open/documents/create"))
            .header("Content-Type", "application/json; charset=utf-8")
            .header("Idempotency-Key", idempotencyKey)
            .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 json, time, uuid, hmac, hashlib, base64, requests

access_key = "ak_live_d83e201048b94103"
secret_key = "sk_live_948f2038102941029"
org_id = "1002"
base_url = "https://api.example.com"

body = {
    "source": {
        "type": "template_id",
        "template_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    },
    "title": "2026年度业务合作协议",
    "recipients": [{
        "recipient_role": "signer_a",
        "name": "李经理",
        "contact": "13800138000",
        "contact_type": "mobile",
        "auth_mode": "sms"
    }],
    "page_fields": {
        "quick-text-contract-no": "PACT-2026-0916"
    }
}
raw_body = json.dumps(body, separators=(',', ':'))
timestamp = str(int(time.time() * 1000))
nonce = uuid.uuid4().hex
idem_key = str(uuid.uuid4())

# 计算规范化签名
sign_str = f"POST\n/open/documents/create\n\n{raw_body}\n{timestamp}\n{nonce}\nx-api-enterprise-id:{org_id}\nidempotency-key:{idem_key}"
signature = base64.b64encode(
    hmac.new(secret_key.encode(), sign_str.encode(), hashlib.sha256).digest()
).decode()

resp = requests.post(f"{base_url}/open/documents/create", data=raw_body, headers={
    "Content-Type": "application/json",
    "Idempotency-Key": idem_key,
    "X-Api-Access-Key": access_key,
    "X-Api-Timestamp": timestamp,
    "X-Api-Nonce": nonce,
    "X-Api-Signature": signature,
    "X-Api-Enterprise-Id": org_id
})
print(resp.json())

const crypto = require('crypto');
const axios = require('axios');

const accessKey = 'ak_live_d83e201048b94103';
const secretKey = 'sk_live_948f2038102941029';
const orgId = '1002';
const idemKey = crypto.randomUUID();

const payload = {
  source: {
    type: 'template_id',
    template_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7'
  },
  title: '2026年度业务合作协议',
  recipients: [{
    recipient_role: 'signer_a',
    name: '李经理',
    contact: '13800138000',
    contact_type: 'mobile'
  }]
};

const rawBody = JSON.stringify(payload);
const timestamp = Date.now().toString();
const nonce = crypto.randomBytes(16).toString('hex');

const stringToSign = [
  'POST',
  '/open/documents/create',
  '', // empty query
  rawBody,
  timestamp,
  nonce,
  `x-api-enterprise-id:${orgId}`,
  `idempotency-key:${idemKey}`
].join('\n');

const signature = crypto.createHmac('sha256', secretKey)
  .update(stringToSign, 'utf8')
  .digest('base64');

axios.post('https://api.example.com/open/documents/create', rawBody, {
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': idemKey,
    'X-Api-Access-Key': accessKey,
    'X-Api-Timestamp': timestamp,
    'X-Api-Nonce': nonce,
    'X-Api-Signature': signature,
    'X-Api-Enterprise-Id': orgId
  }
}).then(res => console.log(res.data));

响应数据结构 (Response Body)

字段名	类型	详细说明
code	integer	业务状态码。`0` 表示处理成功，其他值表示异常。
message	string	状态提示文本，成功固定为 `"success"`。
request_id	string	系统全链路唯一请求跟踪 ID，排查问题时请提供此标识。
data	object	创建成功后的文档实体信息。
└─ data.document_id	string	全新创建的签署文档唯一 UUID v4。
└─ data.title	string	实际保存并展示的签署文档标题。
└─ data.status	string	文档当前内部生命周期状态： • `in_progress`：签署中（已有待签方） • `ready`：草稿就绪状态 • `completed`：全部签署已完成
└─ data.created_at	string	文档创建标准时间，格式：`YYYY-MM-DD HH:mm:ss`。
└─ data.next_action	string \| null	发起后的下一步流转动作。例如 `"approval_pending"` 表示已进入企业审批流程、尚未正式流转至签署人。如直接流转签署则为 `null`。

响应示例 (Response Example)

包含正常响应与常见异常状态示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "document_id": "0a0549da-9e8d-4b6f-b0f6-d422842f0d18",
    "title": "2026年度业务合作协议",
    "status": "in_progress",
    "created_at": "2026-09-16 11:20:00",
    "next_action": null
  },
  "request_id": "req_68dfb7829a10ef4"
}

// HTTP 409 Conflict
// Retry-After: 5
{
  "code": 40903,
  "message": "请求正在处理中",
  "request_id": "req_68dfb7834190fa1"
}

// HTTP 400 Bad Request
{
  "code": 40001,
  "message": "recipients 必须是非空数组",
  "request_id": "req_68dfb7842a8b9e1"
}

HTTP 状态	错误码 (code)	错误标识 (Constant)	产生原因与排查指引
400	40001	BAD_REQUEST	请求参数校验失败：缺少 `source.template_id`、`recipients` 为空数组、`page_fields` 不是以字段为键的对象，或者包含了当前不支持的字段（如 `template_vars`）。
404	40401	NOT_FOUND	资源不存在：指定的 `source.template_id` 模板不存在、属于其他企业，或当前凭证归属成员无权使用该模板。
409	40901	RESOURCE_CONFLICT	资源状态冲突：目标模板处于草稿或停用状态，无法以此模板发起正式签署。
409	40902	IDEMPOTENCY_KEY_REUSED	幂等键冲突：相同的 `Idempotency-Key` 被重复使用，但携带了不同的请求参数 Body。幂等重试必须保证请求体完全一致。
409	40903	PROCESSING	幂等任务处理中：相同的 `Idempotency-Key` 正在服务端异步处理中。请按响应头 `Retry-After`（通常为 5 秒）等待后再次发起重试。
413	41301	QUOTA_EXHAUSTED	签署额度耗尽：当前企业账号下的电子签署合同配额已用尽，请在企业管理后台充值配额后重试。
429	42901	RATE_LIMITED	超出频控限制：当前凭证或企业调用频率触发安全限流规则，请降低请求并发并在调用端加入指数退避重试。
500	50001	INTERNAL_ERROR	服务端处理异常：生成签署文件或底层组件发生非预期错误。可携带返回的 `request_id` 提交技术支持排查。

创建并发起签署文档

请求头 (Request Headers)

请求体参数 (Request Body)

请求示例 (Request Example)

响应数据结构 (Response Body)

响应示例 (Response Example)

相关错误码 (Error Codes)