tencentcloud-sdk-python-ess 3.1.164__tar.gz → 3.1.169__tar.gz

{tencentcloud_sdk_python_ess-3.1.164 → tencentcloud_sdk_python_ess-3.1.169}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tencentcloud-sdk-python-ess
-Version: 3.1.164
+Version: 3.1.169
 Summary: Tencent Cloud Ess SDK for Python
 Home-page: https://github.com/TencentCloud/tencentcloud-sdk-python
 Author: Tencent Cloud
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 2.7
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.6
 Classifier: Programming Language :: Python :: 3.7
-Requires-Dist: tencentcloud-sdk-python-common<4.0.0,>=3.1.164
+Requires-Dist: tencentcloud-sdk-python-common<4.0.0,>=3.1.169
 
 ============================
 Tencent Cloud SDK for Python

{tencentcloud_sdk_python_ess-3.1.164 → tencentcloud_sdk_python_ess-3.1.169}/setup.py

@@ -8,7 +8,7 @@ ROOT = os.path.dirname(__file__)
 
 setup(
     name='tencentcloud-sdk-python-ess',
-    install_requires=["tencentcloud-sdk-python-common>=3.1.164,<4.0.0"],
+    install_requires=["tencentcloud-sdk-python-common>=3.1.169,<4.0.0"],
     
     version=tencentcloud.__version__,
     description='Tencent Cloud Ess SDK for Python',

{tencentcloud_sdk_python_ess-3.1.164 → tencentcloud_sdk_python_ess-3.1.169}/tencentcloud/__init__.py

@@ -14,4 +14,4 @@
 # limitations under the License.
 
 
-__version__ = '3.1.164'
+__version__ = '3.1.169'

{tencentcloud_sdk_python_ess-3.1.164 → tencentcloud_sdk_python_ess-3.1.169}/tencentcloud/ess/v20201111/ess_client.py

@@ -755,49 +755,43 @@ class EssClient(AbstractClient):
 
 
     def CreateDocument(self, request):
-        r"""创建签署流程电子文档<br />
+        r"""本接口用于基于**模板**创建合同的电子文档，并填充模板中由发起方补充的信息（归属发起方填写控件）。
 
-        ###  调用流程
-        该接口需要给对应的流程指定一个模板id，并且填充该模板中需要补充的信息。需要配置<a href="https://qian.tencent.com/developers/companyApis/startFlows/CreateFlow" target="_blank">创建签署流程</a>和<a href="https://qian.tencent.com/developers/companyApis/startFlows/StartFlow" target="_blank">发起签署流程</a>接口使用。具体逻辑可以参考下图:
+        ### 1.1 调用流程
 
-        ![image](https://qcloudimg.tencent-cloud.cn/raw/1f38ebd7c5afed8763ad961741d81438.png)
+        本接口需指定一个模板 ID，并填充该模板中需补充的信息。它需要与<a href="https://qian.tencent.com/developers/companyApis/startFlows/CreateFlow" target="_blank">创建签署流程</a>和<a href="https://qian.tencent.com/developers/companyApis/startFlows/StartFlow" target="_blank">发起签署流程</a>接口配合使用，完整调用顺序如下：
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/dbd2eba8200d812d76b7e9e34d739e75.svg)
 
+        ### 1.2 发起方填写控件
 
-        ### 填充模板中定义的填写控件
-        模板中配置的<font color="red">发起人填充控件</font>可以通过本接口的**FormFields数组**字段填充。
-
-        **<font color="red">填充填写控件需要进行Pdf合成工作，文档合成完成后会收到[合同文档合成完成回调](https://qian.tencent.com/developers/company/callback_types_contracts_sign#%E4%B9%9D-%E5%90%88%E5%90%8C%E6%96%87%E6%A1%A3%E5%90%88%E6%88%90%E5%AE%8C%E6%88%90%E5%9B%9E%E8%B0%83),建议在收到此回调后再调用 [StartFlow](https://qian.tencent.com/developers/companyApis/startFlows/StartFlow) 接口。</font>**
+        模板中配置的<font color="red">发起人填充控件</font>，可通过本接口的 **FormFields 数组**字段填充。
 
         ![image](https://qcloudimg.tencent-cloud.cn/raw/37457e0e450fc221effddfcb8b1bad55.png)
 
-        填充的传参示例如下
-
+        填充的传参示例如下（以 ComponentName 匹配模板中的控件名）：
+
+        ```json
+        [
+            { "ComponentName": "项目的名字", "ComponentValue": "休闲山庄" },
+            { "ComponentName": "项目的地址", "ComponentValue": "凤凰山北侧" },
+            { "ComponentName": "范围", "ComponentValue": "凤凰山至107国道" },
+            { "ComponentName": "面积", "ComponentValue": "100亩" },
+            { "ComponentName": "基本情况", "ComponentValue": "完好" },
+            { "ComponentName": "用途", "ComponentValue": "经营农家乐" }
+        ]
         ```
-            request.FormFields = [{
-                    "ComponentName": "项目的名字",
-                    "ComponentValue": "休闲山庄"
-                }, {
-                    "ComponentName": "项目的地址",
-                    "ComponentValue": "凤凰山北侧",
-                }, {
-                    "ComponentName": "范围",
-                    "ComponentValue": "凤凰山至107国道",
-                }, {
-                    "ComponentName": "面积",
-                    "ComponentValue": "100亩",
-                }, {
-                    "ComponentName": "基本情况",
-                    "ComponentValue": "完好",
-                }, , {
-                    "ComponentName": "用途",
-                    "ComponentValue": "经营农家乐",
-                }
-            ]
-        ```
-        合成后合同样子示例
+
+        合成后的合同样例：
 
         ![image](https://qcloudimg.tencent-cloud.cn/raw/140a2fb771ac66a185d0a000d37485f6.png)
 
+        ### 1.3 注意事项
+
+        -  本接口<font color="red">只能填充分配给发起方的填写控件</font>，不能填充分配给签署方的签署控件。
+        - <font color="red">若使用预览方式（`NeedPreview=true`），预览确认无误后，需用同样的参数再次调用本接口</font>（`NeedPreview=false`），并使用新调用返回的 `FlowId` 去调用 <a href="https://qian.tencent.com/developers/companyApis/startFlows/StartFlow" target="_blank">StartFlow</a>发起签署。预览模式返回的 `FlowId` 为临时 ID，不能用于发起。
+        - 只要存在发起方的填写控件，填充时会触发 PDF 合成工作，文档合成完成后会收到[合同文档合成完成回调](https://qian.tencent.com/developers/company/callback_types_contracts_sign#%E4%B9%9D-%E5%90%88%E5%90%8C%E6%96%87%E6%A1%A3%E5%90%88%E6%88%90%E5%AE%8C%E6%88%90%E5%9B%9E%E8%B0%83)。<font color="red">一定要等待该回调（或等待数秒）后再调用 [StartFlow](https://qian.tencent.com/developers/companyApis/startFlows/StartFlow) 接口发起签署</font>，以确保文档已合成完毕。
+        - 调用本接口（CreateDocument）成功后，请**在 5 分钟内调用 [StartFlow](https://qian.tencent.com/developers/companyApis/startFlows/StartFlow) 启动合同**，不要长时间暂存仅调用了 CreateDocument 而未发起的合同；否则会导致该合同长时间后无法再启动，且合同额度不再返还。
+
         :param request: Request instance for CreateDocument.
         :type request: :class:`tencentcloud.ess.v20201111.models.CreateDocumentRequest`
         :rtype: :class:`tencentcloud.ess.v20201111.models.CreateDocumentResponse`
@@ -1060,40 +1054,26 @@ class EssClient(AbstractClient):
 
     def CreateFlow(self, request):
         r"""通过模板创建签署流程<br/>
-        适用场景：在标准制式的合同场景中，可通过提前预制好模板文件，每次调用模板文件的id，补充合同内容信息及签署信息生成电子合同。
-        <table>
-        	<thead>
-        		<tr>
-        			<th>签署人类别</th>
-        			<th>需要提前准备的信息</th>
-        		</tr>
-        	</thead>
-        	<tbody>
-        		<tr>
-        			<td>自己企业的员工签署（未认证加入或已认证加入）</td>
-        			<td>签署企业的名字、员工的真实名字、员工的触达手机号、员工的证件号（证件号非必传）</td>
-        		</tr>
-        		<tr>
-        			<td>自己企业的员工签署（已认证加入）</td>
-        			<td>签署企业的名字、员工在电子签平台的ID（UserId）</td>
-        		</tr>
-        		<tr>
-        			<td>其他企业的员工签署</td>
-        			<td>签署企业的名字、员工的真实名字、员工的触达手机号、员工的证件号（证件号非必传）</td>
-        		</tr>
-        		<tr>
-        			<td>个人（自然人）签署</td>
-        			<td>个人的真实名字、个人的触达手机号、个人的身份证（证件号非必传）</td>
-        		</tr>
-        	</tbody>
-        </table>
-
-
-        注：配合<a href="https://qian.tencent.com/developers/companyApis/startFlows/CreateDocument" target="_blank">创建电子文档</a>和<a href="https://qian.tencent.com/developers/companyApis/startFlows/StartFlow" target="_blank">发起签署流程</a>接口使用。整体的逻辑如下图
-
-        ![image](https://qcloudimg.tencent-cloud.cn/raw/1f38ebd7c5afed8763ad961741d81438.png)
-
-        注：**静默（自动）签署不支持合同签署方存在填写**功能
+        适用场景：在标准制式的合同场景中，可通过提前预制好模板文件，每次使用这个配置好的模板，补充合同内容信息及签署信息生成电子合同。
+        ## 1.1 传参方式指引
+
+        | 签署方类型 | ApproverType | 需要提前准备的信息 | 对应 Approvers 关键字段 |
+        |------|------|------|------|
+        | 本企业员工（未认证加入） | 0 | 签署企业名、员工真实姓名、员工触达手机号、证件号（非必传） | OrganizationName + ApproverName + ApproverMobile |
+        | 本企业员工（已认证加入） | 0 | 签署企业名、员工在电子签平台的 ID（UserId） | OrganizationName + UserId |
+        | 他方企业员工 | 0 | 签署企业名、员工真实姓名、员工触达手机号、证件号（非必传） | OrganizationName + ApproverName + ApproverMobile |
+        | 个人（自然人） | 1 | 个人真实姓名、个人触达手机号、身份证号（非必传） | ApproverName + ApproverMobile |
+
+        ## 1.2 接口调用流程
+        此接口需<font color="red">配合<a href="https://qian.tencent.com/developers/companyApis/startFlows/CreateDocument" target="_blank">创建电子文档</a>和<a href="https://qian.tencent.com/developers/companyApis/startFlows/StartFlow" target="_blank">发起签署流程</a>接口使用</font> 。整体的逻辑如下图
+
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/dbd2eba8200d812d76b7e9e34d739e75.svg)
+
+        ## 1.3 注意事项
+        -  合同<font color="red">发起后就会扣减合同的额度</font> , 只有撤销没有参与方签署过或只有自动签署签署过的合同，且<font color="red">有撤销合同额度</font>的情形下，才会返还合同额度。（**过期，拒签，签署完成，解除完成等状态不会返还额度**）。具体可以参考[合同撤销返还额度说明](https://qian.tencent.com/developers/company/contract_cancel_quota)。
+        - 支持的证件类型可以参考[支持的证件类型](https://qian.tencent.com/developers/company/id_card_support)。
+        - 合同发起方需要【组织管理】->【角色管理】中拥有<font color="red">接口发起合同</font>的权限
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/c8553d1823ca1323e82c11f01c86e8cd.png)
         <br>
 
         <font color="red">相关视频指引</font> <br>
@@ -1224,43 +1204,26 @@ class EssClient(AbstractClient):
         r"""此接口（CreateFlowByFiles）用来通过上传后的pdf资源编号来创建待签署的合同流程。<br/>
         适用场景：适用非制式的合同文件签署。一般开发者自己有完整的签署文件，可以通过该接口传入完整的PDF文件及流程信息生成待签署的合同流程。<br/>
 
-        <table>
-        	<thead>
-        		<tr>
-        			<th>签署人类别</th>
-        			<th>需要提前准备的信息</th>
-        		</tr>
-        	</thead>
-        	<tbody>
-        		<tr>
-        			<td>自己企业的员工签署（未认证加入或已认证加入）</td>
-        			<td>签署企业的名字、员工的真实名字、员工的触达手机号、员工的证件号（证件号非必传）</td>
-        		</tr>
-        		<tr>
-        			<td>自己企业的员工签署（已认证加入）</td>
-        			<td>签署企业的名字、员工在电子签平台的ID（UserId）</td>
-        		</tr>
-        		<tr>
-        			<td>其他企业的员工签署</td>
-        			<td>签署企业的名字、员工的真实名字、员工的触达手机号、员工的证件号（证件号非必传）</td>
-        		</tr>
-        		<tr>
-        			<td>个人（自然人）签署</td>
-        			<td>个人的真实名字、个人的触达手机号、个人的身份证（证件号非必传）</td>
-        		</tr>
-        	</tbody>
-        </table>
+        ## 传参方式指引
 
+        | 签署方类型 | ApproverType | 需要提前准备的信息 | 对应 Approvers 关键字段 |
+        |------|------|------|------|
+        | 本企业员工（未认证加入） | 0 | 签署企业名、员工真实姓名、员工触达手机号、证件号（非必传） | OrganizationName + ApproverName + ApproverMobile |
+        | 本企业员工（已认证加入） | 0 | 签署企业名、员工在电子签平台的 ID（UserId） | OrganizationName + UserId |
+        | 他方企业员工 | 0 | 签署企业名、员工真实姓名、员工触达手机号、证件号（非必传） | OrganizationName + ApproverName + ApproverMobile |
+        | 个人（自然人） | 1 | 个人真实姓名、个人触达手机号、身份证号（非必传） | ApproverName + ApproverMobile |
 
 
-        该接口需要依赖[上传文件](https://qian.tencent.com/developers/companyApis/templatesAndFiles/UploadFiles)接口生成pdf资源编号（FileIds）进行使用。（如果非pdf文件需要调用[创建文件转换任务](https://qian.tencent.com/developers/companyApis/templatesAndFiles/CreateConvertTaskApi)接口转换成pdf资源）<br/>
+        该接口需要依赖[上传文件](https://qian.tencent.com/developers/companyApis/templatesAndFiles/UploadFiles)接口生成pdf资源编号（FileIds）进行使用。（如果非pdf文件需要调用[创建文件转换任务](https://qian.tencent.com/developers/companyApis/templatesAndFiles/DescribeFileConvertTask)接口转换成pdf资源）<br/>
 
-
-        ![image](https://qcloudimg.tencent-cloud.cn/raw/f097a74b289e3e1acd740936bdfe9843.png)
+        ## 整体流程图
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/9bf547fe0bc738f9a97b4b619dea0633.svg)
 
         注：
-        -  合同**发起后就会扣减合同的额度**, 只有撤销没有参与方签署过或只有自动签署签署过的合同，才会返还合同额度。（**过期，拒签，签署完成，解除完成等状态不会返还额度**）
-        - **静默（自动）签署不支持合同签署方存在填写**功能
+        -  合同<font color="red">发起后就会扣减合同的额度</font> , 只有撤销没有参与方签署过或只有自动签署签署过的合同，且<font color="red">有撤销合同额度</font>的情形下，才会返还合同额度。（**过期，拒签，签署完成，解除完成等状态不会返还额度**）。具体可以参考[合同撤销返还额度说明](https://qian.tencent.com/developers/company/contract_cancel_quota)。
+        - 支持的证件类型可以参考[支持的证件类型](https://qian.tencent.com/developers/company/id_card_support)。
+        - 合同发起方需要【组织管理】->【角色管理】中拥有<font color="red">接口发起合同</font>的权限
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/c8553d1823ca1323e82c11f01c86e8cd.png)
 
 
         <font color="red">相关视频指引</font> <br>
@@ -2396,6 +2359,145 @@ class EssClient(AbstractClient):
                 raise TencentCloudSDKException(type(e).__name__, str(e))
 
 
+    def CreateRequestWithEncryption(self, request):
+        r"""该接口支持对请求内容进行加密传输。调用方需使用约定的 AES-CBC 或 SM4-CBC 算法对请求内容进行加密，并使用 HMAC-SHA256 或 HMAC-SM3 算法对 IV 和加密后的数据进行完整性校验，防止请求内容被篡改。
+
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/391df0a37c2b213445c4909ba98824ac.svg)
+
+        **请求端加密流程**
+        1. 每次请求使用密码学安全的随机源生成 16 字节 的 IV。每次请求必须重新生成，严禁复用。
+        2. 使用约定的 AES-CBC 或 SM4-CBC 算法对原始请求体进行加密，使用 PKCS#7 Padding。
+        3. 将加密后的密文原始字节进行标准 Base64 编码，作为 EncryptedData 参数。
+        4. 将 IV 原始字节进行标准 Base64 编码，作为 IV 参数。
+        5. 对 IV 原始字节和密文原始字节直接拼接（不添加分隔符），计算 HMAC-SHA256 或 HMAC-SM4：HMAC(Key, IVBytes || CiphertextBytes)
+        6. 将 HMAC 的结果进行 标准 Base64 编码，作为 EncryptionSignature 参数。
+
+        **响应端解密流程**
+        1. 先判断本接口自身是否返回外层错误，此时错误为明文（标准腾讯云错误体），有则直接失败处理。
+        2. 分别对 IV、EncryptedData、EncryptionSignature 做标准 Base64 解码，得到原始字节。
+        3. 将 IV 与密文原始字节直接拼接（无分隔符），计算 HMAC-SHA256 或 HMAC-SM4：HMAC(Key, IVBytes || CiphertextBytes)。
+        4. 与响应中 EncryptionSignature 解码后的字节做恒定时间比较，不一致立即失败，不得继续解密。
+        5. 使用约定的 AES-CBC 或 SM4-CBC，以 IV 和密钥解密 EncryptedData，去除 PKCS#7 Padding 得到明文。
+        6. 先用腾讯云标准错误体反序列化明文，判断被加密业务接口是否返回 Error。
+        7. 无业务错误时，再用目标业务接口的响应结构体反序列化明文，取出实际业务参数。
+
+        **响应端错误处理**
+        1. 外层错误（本接口本身调用失败）：返回标准腾讯云错误 JSON（含 Error.Code / Error.Message），无 EncryptedData，不需要解密即可处理。
+        2. 内层错误（业务接口执行失败）：外层成功，但解密后的明文里包含 Error.Code / Error.Message，按目标业务接口的错误规范处理。
+
+        **处理过程示例**
+        ```
+        # ========== 前置约定 ==========
+        AESKey  : 加密 密钥（AES 32 字节，SM4 16 字节）
+        HMACKey : HMAC 密钥（与加密密钥需要不同）
+        ALGO    : AES-CBC 或 SM4-CBC，双方约定
+        HMAC    : ALGO == AES-CBC ? HMAC-SHA256 : HMAC-SM3
+
+        # ========== 请求端：加密并调用 ==========
+        function CallWithEncryption(bizAction, bizRequestObj):
+            # 1. 序列化业务请求
+            plaintext = JSON.stringify(bizRequestObj)
+            # 2. 生成 16 字节随机 IV（每次新生成，禁止复用）
+            iv = SecureRandom(16)
+            # 3. 对称加密（PKCS#7 Padding）
+            ciphertext = SymmetricEncrypt(ALGO, AESKey, iv, plaintext)
+            # 4. 计算完整性签名：HMAC(Key, IV || Ciphertext)
+            signature = HMAC(HMACKey, concat(iv, ciphertext))
+            # 5. 组装外层请求参数
+            encReq = {
+                RequestAction:       bizAction,
+                IV:                  Base64(iv),
+                EncryptedData:       Base64(ciphertext),
+                EncryptionSignature: Base64(signature),
+            }
+            # 6. 调用 CreateRequestWithEncryption
+            #    TC3-HMAC-SHA256 鉴权由官方 SDK 自动完成
+            encResp = CloudAPI.CreateRequestWithEncryption(encReq)
+            # 7. 外层错误：明文，直接抛出
+            if encResp.Error != nil:
+                raise OuterError(encResp.Error)
+            # 8. 解密并返回业务响应
+            return DecryptResponse(encResp.Response)
+
+        # ========== 响应端：校验并解密 ==========
+        function DecryptResponse(resp):
+            # 1. Base64 解码
+            ivBytes  = Base64Decode(resp.IV)
+            ctBytes  = Base64Decode(resp.EncryptedData)
+            sigBytes = Base64Decode(resp.EncryptionSignature)
+            # 2. 重新计算 HMAC
+            expected = HMAC(HMACKey, concat(ivBytes, ctBytes))
+            # 3. 恒定时间比较，失败立即终止（不得继续解密）
+            if not ConstantTimeEqual(expected, sigBytes):
+                raise SignatureMismatch
+            # 4. 对称解密，去除 PKCS#7 Padding
+            plaintext = SymmetricDecrypt(ALGO, AESKey, ivBytes, ctBytes)
+            # 5. 先按腾讯云错误体解析，判断业务是否失败
+            bizErr = TryParseTencentCloudError(plaintext)
+            if bizErr != nil:
+                raise BusinessError(bizErr)
+            # 6. 按目标业务接口的响应结构反序列化
+            return JSON.parse(plaintext, BizResponseSchema)
+        ```
+
+        **AES-CBC 示例**
+
+        以下示例参数及结果可用于验证 AES-CBC 加密和 HMAC-SHA256 签名算法的实现是否正确。
+
+        加密密钥：AES-CBC-Key-1234
+        签名密钥：AES-HMAC-Key-123
+        IV：1234567890abcdef
+        请求内容：{"Request": "This is a test."}
+
+        最终请求参数：
+        ```
+        {
+          "RequestAction": "DescribeFlowComponents",
+          "IV": "MTIzNDU2Nzg5MGFiY2RlZg==",
+          "EncryptedData": "Iqp2W1jislwMNmE7bH9dKZZiMQsfkAPyvAAqDFRnWLw=",
+          "EncryptionSignature": "4TT3PUCZgZT7YmEPtXDm5PDcM6xT7FoYHfMW8xunB5I="
+        }
+        ```
+
+        **SM4-CBC 示例**
+
+        以下示例参数及结果可用于验证 SM4-CBC 加密和 HMAC-SM4 签名算法的实现是否正确。
+
+        加密密钥：SM4-CBC-Key-1234
+        签名密钥：SM4-HMAC-Key-123
+        IV：fedcba0987654321
+        请求内容：{"Request": "This is a test."}
+
+        最终请求参数：
+        ```
+        {
+          "RequestAction": "DescribeFlowComponents",
+          "IV": "ZmVkY2JhMDk4NzY1NDMyMQ==",
+          "EncryptedData": "GwUovQhNUPaUnVM/UDXMtPOYTpTSi2B1oyZDFbyyvns=",
+          "EncryptionSignature": "nHB/v/AvOaDCQ66esFNnp12lHKcGkwaLGid0Warl/KE="
+        }
+        ```
+
+        :param request: Request instance for CreateRequestWithEncryption.
+        :type request: :class:`tencentcloud.ess.v20201111.models.CreateRequestWithEncryptionRequest`
+        :rtype: :class:`tencentcloud.ess.v20201111.models.CreateRequestWithEncryptionResponse`
+
+        """
+        try:
+            params = request._serialize()
+            headers = request.headers
+            body = self.call("CreateRequestWithEncryption", params, headers=headers)
+            response = json.loads(body)
+            model = models.CreateRequestWithEncryptionResponse()
+            model._deserialize(response["Response"])
+            return model
+        except Exception as e:
+            if isinstance(e, TencentCloudSDKException):
+                raise
+            else:
+                raise TencentCloudSDKException(type(e).__name__, str(e))
+
+
     def CreateRiskIdentificationTaskFeedback(self, request):
         r"""此接口（CreateRiskIdentificationTaskFeedback）用于创建合同审查任务结果反馈。
 
@@ -4608,16 +4710,16 @@ class EssClient(AbstractClient):
 
     def StartFlow(self, request):
         r"""此接口用于启动流程。它是模板发起合同的最后一步。
-        在[创建签署流程](https://qian.tencent.com/developers/companyApis/startFlows/CreateFlow)和[创建电子文档](https://qian.tencent.com/developers/companyApis/startFlows/CreateDocument)之后，用于开始整个合同流程,  推进流程进入到签署环节。
 
-        ![image](https://qcloudimg.tencent-cloud.cn/raw/1f38ebd7c5afed8763ad961741d81438.png)
-
-        注：
-        1.<font color="red">合同发起后就会扣减合同的额度</font>, 只有撤销没有参与方签署过或只有自动签署签署过的合同，才会返还合同额度。（过期，拒签，签署完成，解除完成等状态不会返还额度）
+        ## 1.1 接口调用流程
+        在[创建签署流程](https://qian.tencent.com/developers/companyApis/startFlows/CreateFlow)和[创建电子文档](https://qian.tencent.com/developers/companyApis/startFlows/CreateDocument)之后，用于开始整个合同流程,  推进流程进入到签署环节。
 
-        2.<font color="red">静默（自动）签署不支持非本企业合同签署方存在填写</font>功能
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/dbd2eba8200d812d76b7e9e34d739e75.svg)
 
-        3.<font color="red">在发起签署流程之前，建议等待 [PDF合成完成的回调](https://qian.tencent.com/developers/company/callback_types_contracts_sign#%E4%B9%9D-%E5%90%88%E5%90%8C%E6%96%87%E6%A1%A3%E5%90%88%E6%88%90%E5%AE%8C%E6%88%90%E5%9B%9E%E8%B0%83)</font>，尤其是当模板中存在动态表格等复杂填写控件时，因为合成过程可能会耗费秒级别的时间。
+        ### 1.2 注意事项
+        -  合同<font color="red">发起后就会扣减合同的额度</font> , 只有撤销没有参与方签署过或只有自动签署签署过的合同，且<font color="red">有撤销合同额度</font>的情形下，才会返还合同额度。（**过期，拒签，签署完成，解除完成等状态不会返还额度**）。具体可以参考[合同撤销返还额度说明](https://qian.tencent.com/developers/company/contract_cancel_quota)。
+        -  只要存在填写控件，填充时会触发 PDF 合成工作，文档合成完成后会收到[合同文档合成完成回调](https://qian.tencent.com/developers/company/callback_types_contracts_sign#%E4%B9%9D-%E5%90%88%E5%90%8C%E6%96%87%E6%A1%A3%E5%90%88%E6%88%90%E5%AE%8C%E6%88%90%E5%9B%9E%E8%B0%83)。**一定要等待该回调（或等待数秒）后再调用 [StartFlow](https://qian.tencent.com/developers/companyApis/startFlows/StartFlow) 接口发起签署**，以确保文档已合成完毕。，尤其是当模板中存在动态表格等复杂填写控件时，因为合成过程可能会耗费秒级别的时间。
+        - 调用 [CreateDocument](https://qian.tencent.com/developers/companyApis/startFlows/CreateDocument) 成功后，请<font color="red">在 5 分钟内调用本接口（StartFlow）启动合同</font> ，不要长时间暂存仅调用了 CreateDocument 而未发起的合同；否则会导致该合同长时间后无法再启动，且合同额度不再返还。
 
         :param request: Request instance for StartFlow.
         :type request: :class:`tencentcloud.ess.v20201111.models.StartFlowRequest`