tencentcloud-sdk-python-ess 3.1.155__tar.gz → 3.1.171__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/PKG-INFO +2 -2
  2. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/setup.py +1 -1
  3. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud/__init__.py +1 -1
  4. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud/ess/v20201111/ess_client.py +215 -107
  5. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud/ess/v20201111/ess_client_async.py +210 -107
  6. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud/ess/v20201111/models.py +279 -348
  7. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud_sdk_python_ess.egg-info/PKG-INFO +2 -2
  8. tencentcloud_sdk_python_ess-3.1.171/tencentcloud_sdk_python_ess.egg-info/requires.txt +1 -0
  9. tencentcloud_sdk_python_ess-3.1.155/tencentcloud_sdk_python_ess.egg-info/requires.txt +0 -1
  10. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/README.rst +0 -0
  11. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/setup.cfg +0 -0
  12. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud/ess/__init__.py +0 -0
  13. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud/ess/v20201111/__init__.py +0 -0
  14. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud/ess/v20201111/errorcodes.py +0 -0
  15. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud_sdk_python_ess.egg-info/SOURCES.txt +0 -0
  16. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud_sdk_python_ess.egg-info/dependency_links.txt +0 -0
  17. {tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud_sdk_python_ess.egg-info/top_level.txt +0 -0
{tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: tencentcloud-sdk-python-ess
3
- Version: 3.1.155
3
+ Version: 3.1.171
4
4
  Summary: Tencent Cloud Ess SDK for Python
5
5
  Home-page: https://github.com/TencentCloud/tencentcloud-sdk-python
6
6
  Author: Tencent Cloud
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 2.7
15
15
  Classifier: Programming Language :: Python :: 3
16
16
  Classifier: Programming Language :: Python :: 3.6
17
17
  Classifier: Programming Language :: Python :: 3.7
18
- Requires-Dist: tencentcloud-sdk-python-common<4.0.0,>=3.1.155
18
+ Requires-Dist: tencentcloud-sdk-python-common<4.0.0,>=3.1.171
19
19
 
20
20
  ============================
21
21
  Tencent Cloud SDK for Python
{tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/setup.py RENAMED
@@ -8,7 +8,7 @@ ROOT = os.path.dirname(__file__)
8
8
 
9
9
  setup(
10
10
  name='tencentcloud-sdk-python-ess',
11
- install_requires=["tencentcloud-sdk-python-common>=3.1.155,<4.0.0"],
11
+ install_requires=["tencentcloud-sdk-python-common>=3.1.171,<4.0.0"],
12
12
 
13
13
  version=tencentcloud.__version__,
14
14
  description='Tencent Cloud Ess SDK for Python',
{tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud/__init__.py RENAMED
@@ -14,4 +14,4 @@
14
14
  # limitations under the License.
15
15
 
16
16
 
17
- __version__ = '3.1.155'
17
+ __version__ = '3.1.171'
{tencentcloud_sdk_python_ess-3.1.155 → tencentcloud_sdk_python_ess-3.1.171}/tencentcloud/ess/v20201111/ess_client.py RENAMED
@@ -534,8 +534,8 @@ class EssClient(AbstractClient):
534
534
  1. 该接口可生成签署人的批量、合同组签署/查看链接 。
535
535
  2. 该签署链接**默认有效期为30分钟**，过期后将失效，如需签署可重新创建批量签署链接 。
536
536
  3. 该接口返回的签署链接适用于APP集成的场景，支持APP打开或浏览器直接打开，**不支持微信小程序嵌入**。
537
- 跳转到小程序的实现，参考微信官方文档(分为<a href="https://developers.weixin.qq.com/miniprogram/dev/api/navigate/wx.navigateToMiniProgram.html">全屏</a>、<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/openEmbeddedMiniProgram.html">半屏</a>两种方式)，如何配置也可以请参考: <a href="https://qian.tencent.com/developers/company/openwxminiprogram">跳转电子签小程序配置</a>。
538
537
  4. 因h5涉及人脸身份认证能力基于慧眼人脸核身，对Android和iOS系统均有一定要求， 因此<font color='red'>App嵌入H5签署合同需要按照慧眼提供的<a href="https://cloud.tencent.com/document/product/1007/61076">慧眼人脸核身兼容性文档</a>做兼容性适配</font>。
538
+ 5. <font color='red'>iframe 嵌入暂不支持人脸相关操作</font>，包括设置密码等需要进行的人脸核验。
539
539
 
540
540
  :param request: Request instance for CreateBatchQuickSignUrl.
541
541
  :type request: :class:`tencentcloud.ess.v20201111.models.CreateBatchQuickSignUrlRequest`
@@ -755,49 +755,43 @@ class EssClient(AbstractClient):
755
755
 
756
756
 
757
757
  def CreateDocument(self, request):
758
- r"""创建签署流程电子文档<br />
758
+ r"""本接口用于基于**模板**创建合同的电子文档，并填充模板中由发起方补充的信息（归属发起方填写控件）。
759
759
 
760
- ### 调用流程
761
- 该接口需要给对应的流程指定一个模板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>接口使用。具体逻辑可以参考下图:
760
+ ### 1.1 调用流程
762
761
 
763
- ![image](https://qcloudimg.tencent-cloud.cn/raw/1f38ebd7c5afed8763ad961741d81438.png)
762
+ 本接口需指定一个模板 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>接口配合使用，完整调用顺序如下：
763
+ ![image](https://qcloudimg.tencent-cloud.cn/raw/dbd2eba8200d812d76b7e9e34d739e75.svg)
764
764
 
765
+ ### 1.2 发起方填写控件
765
766
 
766
- ### 填充模板中定义的填写控件
767
- 模板中配置的<font color="red">发起人填充控件</font>可以通过本接口的**FormFields数组**字段填充。
768
-
769
- **<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>**
767
+ 模板中配置的<font color="red">发起人填充控件</font>，可通过本接口的 **FormFields 数组**字段填充。
770
768
 
771
769
  ![image](https://qcloudimg.tencent-cloud.cn/raw/37457e0e450fc221effddfcb8b1bad55.png)
772
770
 
773
- 填充的传参示例如下
774
-
771
+ 填充的传参示例如下（以 ComponentName 匹配模板中的控件名）：
772
+
773
+ ```json
774
+ [
775
+ { "ComponentName": "项目的名字", "ComponentValue": "休闲山庄" },
776
+ { "ComponentName": "项目的地址", "ComponentValue": "凤凰山北侧" },
777
+ { "ComponentName": "范围", "ComponentValue": "凤凰山至107国道" },
778
+ { "ComponentName": "面积", "ComponentValue": "100亩" },
779
+ { "ComponentName": "基本情况", "ComponentValue": "完好" },
780
+ { "ComponentName": "用途", "ComponentValue": "经营农家乐" }
781
+ ]
775
782
  ```
776
- request.FormFields = [{
777
- "ComponentName": "项目的名字",
778
- "ComponentValue": "休闲山庄"
779
- }, {
780
- "ComponentName": "项目的地址",
781
- "ComponentValue": "凤凰山北侧",
782
- }, {
783
- "ComponentName": "范围",
784
- "ComponentValue": "凤凰山至107国道",
785
- }, {
786
- "ComponentName": "面积",
787
- "ComponentValue": "100亩",
788
- }, {
789
- "ComponentName": "基本情况",
790
- "ComponentValue": "完好",
791
- }, , {
792
- "ComponentName": "用途",
793
- "ComponentValue": "经营农家乐",
794
- }
795
- ]
796
- ```
797
- 合成后合同样子示例
783
+
784
+ 合成后的合同样例：
798
785
 
799
786
  ![image](https://qcloudimg.tencent-cloud.cn/raw/140a2fb771ac66a185d0a000d37485f6.png)
800
787
 
788
+ ### 1.3 注意事项
789
+
790
+ - 本接口<font color="red">只能填充分配给发起方的填写控件</font>，不能填充分配给签署方的签署控件。
791
+ - <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，不能用于发起。
792
+ - 只要存在发起方的填写控件，填充时会触发 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>，以确保文档已合成完毕。
793
+ - 调用本接口（CreateDocument）成功后，请**在 5 分钟内调用 [StartFlow](https://qian.tencent.com/developers/companyApis/startFlows/StartFlow) 启动合同**，不要长时间暂存仅调用了 CreateDocument 而未发起的合同；否则会导致该合同长时间后无法再启动，且合同额度不再返还。
794
+
801
795
  :param request: Request instance for CreateDocument.
802
796
  :type request: :class:`tencentcloud.ess.v20201111.models.CreateDocumentRequest`
803
797
  :rtype: :class:`tencentcloud.ess.v20201111.models.CreateDocumentResponse`
@@ -1010,6 +1004,9 @@ class EssClient(AbstractClient):
1010
1004
  1. `支持的文件类型有doc、docx、xls、xlsx、html、jpg、jpeg、png、bmp、txt`
1011
1005
  2. `可通过发起合同时设置预览来检查转换文件是否达到预期效果`
1012
1006
 
1007
+ 整体流程如下图
1008
+ ![image](https://qcloudimg.tencent-cloud.cn/raw/bb35c9cfa453d28eade16df36221f313.png)
1009
+
1013
1010
  :param request: Request instance for CreateFileConvertTask.
1014
1011
  :type request: :class:`tencentcloud.ess.v20201111.models.CreateFileConvertTaskRequest`
1015
1012
  :rtype: :class:`tencentcloud.ess.v20201111.models.CreateFileConvertTaskResponse`
@@ -1057,40 +1054,26 @@ class EssClient(AbstractClient):
1057
1054
 
1058
1055
  def CreateFlow(self, request):
1059
1056
  r"""通过模板创建签署流程<br/>
1060
- 适用场景：在标准制式的合同场景中，可通过提前预制好模板文件，每次调用模板文件的id，补充合同内容信息及签署信息生成电子合同。
1061
- <table>
1062
- <thead>
1063
- <tr>
1064
- <th>签署人类别</th>
1065
- <th>需要提前准备的信息</th>
1066
- </tr>
1067
- </thead>
1068
- <tbody>
1069
- <tr>
1070
- <td>自己企业的员工签署（未认证加入或已认证加入）</td>
1071
- <td>签署企业的名字、员工的真实名字、员工的触达手机号、员工的证件号（证件号非必传）</td>
1072
- </tr>
1073
- <tr>
1074
- <td>自己企业的员工签署（已认证加入）</td>
1075
- <td>签署企业的名字、员工在电子签平台的ID（UserId）</td>
1076
- </tr>
1077
- <tr>
1078
- <td>其他企业的员工签署</td>
1079
- <td>签署企业的名字、员工的真实名字、员工的触达手机号、员工的证件号（证件号非必传）</td>
1080
- </tr>
1081
- <tr>
1082
- <td>个人（自然人）签署</td>
1083
- <td>个人的真实名字、个人的触达手机号、个人的身份证（证件号非必传）</td>
1084
- </tr>
1085
- </tbody>
1086
- </table>
1087
-
1088
-
1089
- 注：配合<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>接口使用。整体的逻辑如下图
1090
-
1091
- ![image](https://qcloudimg.tencent-cloud.cn/raw/1f38ebd7c5afed8763ad961741d81438.png)
1092
-
1093
- 注：**静默（自动）签署不支持合同签署方存在填写**功能
1057
+ 适用场景：在标准制式的合同场景中，可通过提前预制好模板文件，每次使用这个配置好的模板，补充合同内容信息及签署信息生成电子合同。
1058
+ ## 1.1 传参方式指引
1059
+
1060
+ | 签署方类型 | ApproverType | 需要提前准备的信息 | 对应 Approvers 关键字段 |
1061
+ |------|------|------|------|
1062
+ | 本企业员工（未认证加入） | 0 | 签署企业名、员工真实姓名、员工触达手机号、证件号（非必传） | OrganizationName + ApproverName + ApproverMobile |
1063
+ | 本企业员工（已认证加入） | 0 | 签署企业名、员工在电子签平台的 ID（UserId） | OrganizationName + UserId |
1064
+ | 他方企业员工 | 0 | 签署企业名、员工真实姓名、员工触达手机号、证件号（非必传） | OrganizationName + ApproverName + ApproverMobile |
1065
+ | 个人（自然人） | 1 | 个人真实姓名、个人触达手机号、身份证号（非必传） | ApproverName + ApproverMobile |
1066
+
1067
+ ## 1.2 接口调用流程
1068
+ 此接口需<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> 。整体的逻辑如下图
1069
+
1070
+ ![image](https://qcloudimg.tencent-cloud.cn/raw/dbd2eba8200d812d76b7e9e34d739e75.svg)
1071
+
1072
+ ## 1.3 注意事项
1073
+ - 合同<font color="red">发起后就会扣减合同的额度</font> , 只有撤销没有参与方签署过或只有自动签署签署过的合同，且<font color="red">有撤销合同额度</font>的情形下，才会返还合同额度。（**过期，拒签，签署完成，解除完成等状态不会返还额度**）。具体可以参考[合同撤销返还额度说明](https://qian.tencent.com/developers/company/contract_cancel_quota)。
1074
+ - 支持的证件类型可以参考[支持的证件类型](https://qian.tencent.com/developers/company/id_card_support)。
1075
+ - 合同发起方需要【组织管理】->【角色管理】中拥有<font color="red">接口发起合同</font>的权限
1076
+ ![image](https://qcloudimg.tencent-cloud.cn/raw/c8553d1823ca1323e82c11f01c86e8cd.png)
1094
1077
  <br>
1095
1078
 
1096
1079
  <font color="red">相关视频指引</font> <br>
@@ -1221,43 +1204,26 @@ class EssClient(AbstractClient):
1221
1204
  r"""此接口（CreateFlowByFiles）用来通过上传后的pdf资源编号来创建待签署的合同流程。<br/>
1222
1205
  适用场景：适用非制式的合同文件签署。一般开发者自己有完整的签署文件，可以通过该接口传入完整的PDF文件及流程信息生成待签署的合同流程。<br/>
1223
1206
 
1224
- <table>
1225
- <thead>
1226
- <tr>
1227
- <th>签署人类别</th>
1228
- <th>需要提前准备的信息</th>
1229
- </tr>
1230
- </thead>
1231
- <tbody>
1232
- <tr>
1233
- <td>自己企业的员工签署（未认证加入或已认证加入）</td>
1234
- <td>签署企业的名字、员工的真实名字、员工的触达手机号、员工的证件号（证件号非必传）</td>
1235
- </tr>
1236
- <tr>
1237
- <td>自己企业的员工签署（已认证加入）</td>
1238
- <td>签署企业的名字、员工在电子签平台的ID（UserId）</td>
1239
- </tr>
1240
- <tr>
1241
- <td>其他企业的员工签署</td>
1242
- <td>签署企业的名字、员工的真实名字、员工的触达手机号、员工的证件号（证件号非必传）</td>
1243
- </tr>
1244
- <tr>
1245
- <td>个人（自然人）签署</td>
1246
- <td>个人的真实名字、个人的触达手机号、个人的身份证（证件号非必传）</td>
1247
- </tr>
1248
- </tbody>
1249
- </table>
1250
-
1207
+ ## 传参方式指引
1251
1208
 
1209
+ | 签署方类型 | ApproverType | 需要提前准备的信息 | 对应 Approvers 关键字段 |
1210
+ |------|------|------|------|
1211
+ | 本企业员工（未认证加入） | 0 | 签署企业名、员工真实姓名、员工触达手机号、证件号（非必传） | OrganizationName + ApproverName + ApproverMobile |
1212
+ | 本企业员工（已认证加入） | 0 | 签署企业名、员工在电子签平台的 ID（UserId） | OrganizationName + UserId |
1213
+ | 他方企业员工 | 0 | 签署企业名、员工真实姓名、员工触达手机号、证件号（非必传） | OrganizationName + ApproverName + ApproverMobile |
1214
+ | 个人（自然人） | 1 | 个人真实姓名、个人触达手机号、身份证号（非必传） | ApproverName + ApproverMobile |
1252
1215
 
1253
- 该接口需要依赖[上传文件](https://qian.tencent.com/developers/companyApis/templatesAndFiles/UploadFiles)接口生成pdf资源编号（FileIds）进行使用。（如果非pdf文件需要调用[创建文件转换任务](https://qian.tencent.com/developers/companyApis/templatesAndFiles/CreateConvertTaskApi)接口转换成pdf资源）<br/>
1254
1216
 
1217
+ 该接口需要依赖[上传文件](https://qian.tencent.com/developers/companyApis/templatesAndFiles/UploadFiles)接口生成pdf资源编号（FileIds）进行使用。（如果非pdf文件需要调用[创建文件转换任务](https://qian.tencent.com/developers/companyApis/templatesAndFiles/CreateFileConvertTask)接口转换成pdf资源）<br/>
1255
1218
 
1256
- ![image](https://qcloudimg.tencent-cloud.cn/raw/f097a74b289e3e1acd740936bdfe9843.png)
1219
+ ## 整体流程图
1220
+ ![image](https://qcloudimg.tencent-cloud.cn/raw/9bf547fe0bc738f9a97b4b619dea0633.svg)
1257
1221
 
1258
1222
  注：
1259
- - 合同**发起后就会扣减合同的额度**, 只有撤销没有参与方签署过或只有自动签署签署过的合同，才会返还合同额度。（**过期，拒签，签署完成，解除完成等状态不会返还额度**）
1260
- - **静默（自动）签署不支持合同签署方存在填写**功能
1223
+ - 合同<font color="red">发起后就会扣减合同的额度</font> , 只有撤销没有参与方签署过或只有自动签署签署过的合同，且<font color="red">有撤销合同额度</font>的情形下，才会返还合同额度。（**过期，拒签，签署完成，解除完成等状态不会返还额度**）。具体可以参考[合同撤销返还额度说明](https://qian.tencent.com/developers/company/contract_cancel_quota)。
1224
+ - 支持的证件类型可以参考[支持的证件类型](https://qian.tencent.com/developers/company/id_card_support)。
1225
+ - 合同发起方需要【组织管理】->【角色管理】中拥有<font color="red">接口发起合同</font>的权限
1226
+ ![image](https://qcloudimg.tencent-cloud.cn/raw/c8553d1823ca1323e82c11f01c86e8cd.png)
1261
1227
 
1262
1228
 
1263
1229
  <font color="red">相关视频指引</font> <br>
@@ -1624,8 +1590,8 @@ class EssClient(AbstractClient):
1624
1590
  **注意**
1625
1591
  1. 该签署链接**默认有效期为30分钟**，过期后将失效，如需签署可重新创建签署链接。
1626
1592
  2. 该接口返回的签署链接适用于APP集成的场景，支持APP、支付宝打开或浏览器直接打开，**不支持微信小程序嵌入**。配置方式请参考：<a href="https://qian.tencent.com/developers/company/openqianh5/">跳转电子签H5</a>。
1627
- 如需跳转到小程序的实现，参考微信官方文档（分为<a href="https://developers.weixin.qq.com/miniprogram/dev/api/navigate/wx.navigateToMiniProgram.html">全屏</a>、<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/openEmbeddedMiniProgram.html">半屏</a>两种方式），如何配置也可以请参考: <a href="https://qian.tencent.com/developers/company/openwxminiprogram">跳转电子签小程序配置</a>。
1628
1593
  3. 因h5涉及人脸身份认证能力基于慧眼人脸核身，对Android和iOS系统均有一定要求， 因此<font color='red'>App嵌入H5签署合同需要按照慧眼提供的<a href="https://cloud.tencent.com/document/product/1007/61076">慧眼人脸核身兼容性文档</a>做兼容性适配</font>。
1594
+ 4. <font color='red'>iframe 嵌入暂不支持人脸相关操作</font>，包括设置密码等需要进行的人脸核验。
1629
1595
 
1630
1596
  :param request: Request instance for CreateFlowSignUrl.
1631
1597
  :type request: :class:`tencentcloud.ess.v20201111.models.CreateFlowSignUrlRequest`
@@ -2393,6 +2359,145 @@ class EssClient(AbstractClient):
2393
2359
  raise TencentCloudSDKException(type(e).__name__, str(e))
2394
2360
 
2395
2361
 
2362
+ def CreateRequestWithEncryption(self, request):
2363
+ r"""该接口支持对请求内容进行加密传输。调用方需使用约定的 AES-CBC 或 SM4-CBC 算法对请求内容进行加密，并使用 HMAC-SHA256 或 HMAC-SM3 算法对 IV 和加密后的数据进行完整性校验，防止请求内容被篡改。
2364
+
2365
+ ![image](https://qcloudimg.tencent-cloud.cn/raw/391df0a37c2b213445c4909ba98824ac.svg)
2366
+
2367
+ **请求端加密流程**
2368
+ 1. 每次请求使用密码学安全的随机源生成 16 字节 的 IV。每次请求必须重新生成，严禁复用。
2369
+ 2. 使用约定的 AES-CBC 或 SM4-CBC 算法对原始请求体进行加密，使用 PKCS#7 Padding。
2370
+ 3. 将加密后的密文原始字节进行标准 Base64 编码，作为 EncryptedData 参数。
2371
+ 4. 将 IV 原始字节进行标准 Base64 编码，作为 IV 参数。
2372
+ 5. 对 IV 原始字节和密文原始字节直接拼接（不添加分隔符），计算 HMAC-SHA256 或 HMAC-SM4：HMAC(Key, IVBytes || CiphertextBytes)
2373
+ 6. 将 HMAC 的结果进行 标准 Base64 编码，作为 EncryptionSignature 参数。
2374
+
2375
+ **响应端解密流程**
2376
+ 1. 先判断本接口自身是否返回外层错误，此时错误为明文（标准腾讯云错误体），有则直接失败处理。
2377
+ 2. 分别对 IV、EncryptedData、EncryptionSignature 做标准 Base64 解码，得到原始字节。
2378
+ 3. 将 IV 与密文原始字节直接拼接（无分隔符），计算 HMAC-SHA256 或 HMAC-SM4：HMAC(Key, IVBytes || CiphertextBytes)。
2379
+ 4. 与响应中 EncryptionSignature 解码后的字节做恒定时间比较，不一致立即失败，不得继续解密。
2380
+ 5. 使用约定的 AES-CBC 或 SM4-CBC，以 IV 和密钥解密 EncryptedData，去除 PKCS#7 Padding 得到明文。
2381
+ 6. 先用腾讯云标准错误体反序列化明文，判断被加密业务接口是否返回 Error。
2382
+ 7. 无业务错误时，再用目标业务接口的响应结构体反序列化明文，取出实际业务参数。
2383
+
2384
+ **响应端错误处理**
2385
+ 1. 外层错误（本接口本身调用失败）：返回标准腾讯云错误 JSON（含 Error.Code / Error.Message），无 EncryptedData，不需要解密即可处理。
2386
+ 2. 内层错误（业务接口执行失败）：外层成功，但解密后的明文里包含 Error.Code / Error.Message，按目标业务接口的错误规范处理。
2387
+
2388
+ **处理过程示例**
2389
+ ```
2390
+ # ========== 前置约定 ==========
2391
+ AESKey : 加密 密钥（AES 32 字节，SM4 16 字节）
2392
+ HMACKey : HMAC 密钥（与加密密钥需要不同）
2393
+ ALGO : AES-CBC 或 SM4-CBC，双方约定
2394
+ HMAC : ALGO == AES-CBC ? HMAC-SHA256 : HMAC-SM3
2395
+
2396
+ # ========== 请求端：加密并调用 ==========
2397
+ function CallWithEncryption(bizAction, bizRequestObj):
2398
+ # 1. 序列化业务请求
2399
+ plaintext = JSON.stringify(bizRequestObj)
2400
+ # 2. 生成 16 字节随机 IV（每次新生成，禁止复用）
2401
+ iv = SecureRandom(16)
2402
+ # 3. 对称加密（PKCS#7 Padding）
2403
+ ciphertext = SymmetricEncrypt(ALGO, AESKey, iv, plaintext)
2404
+ # 4. 计算完整性签名：HMAC(Key, IV || Ciphertext)
2405
+ signature = HMAC(HMACKey, concat(iv, ciphertext))
2406
+ # 5. 组装外层请求参数
2407
+ encReq = {
2408
+ RequestAction: bizAction,
2409
+ IV: Base64(iv),
2410
+ EncryptedData: Base64(ciphertext),
2411
+ EncryptionSignature: Base64(signature),
2412
+ }
2413
+ # 6. 调用 CreateRequestWithEncryption
2414
+ # TC3-HMAC-SHA256 鉴权由官方 SDK 自动完成
2415
+ encResp = CloudAPI.CreateRequestWithEncryption(encReq)
2416
+ # 7. 外层错误：明文，直接抛出
2417
+ if encResp.Error != nil:
2418
+ raise OuterError(encResp.Error)
2419
+ # 8. 解密并返回业务响应
2420
+ return DecryptResponse(encResp.Response)
2421
+
2422
+ # ========== 响应端：校验并解密 ==========
2423
+ function DecryptResponse(resp):
2424
+ # 1. Base64 解码
2425
+ ivBytes = Base64Decode(resp.IV)
2426
+ ctBytes = Base64Decode(resp.EncryptedData)
2427
+ sigBytes = Base64Decode(resp.EncryptionSignature)
2428
+ # 2. 重新计算 HMAC
2429
+ expected = HMAC(HMACKey, concat(ivBytes, ctBytes))
2430
+ # 3. 恒定时间比较，失败立即终止（不得继续解密）
2431
+ if not ConstantTimeEqual(expected, sigBytes):
2432
+ raise SignatureMismatch
2433
+ # 4. 对称解密，去除 PKCS#7 Padding
2434
+ plaintext = SymmetricDecrypt(ALGO, AESKey, ivBytes, ctBytes)
2435
+ # 5. 先按腾讯云错误体解析，判断业务是否失败
2436
+ bizErr = TryParseTencentCloudError(plaintext)
2437
+ if bizErr != nil:
2438
+ raise BusinessError(bizErr)
2439
+ # 6. 按目标业务接口的响应结构反序列化
2440
+ return JSON.parse(plaintext, BizResponseSchema)
2441
+ ```
2442
+
2443
+ **AES-CBC 示例**
2444
+
2445
+ 以下示例参数及结果可用于验证 AES-CBC 加密和 HMAC-SHA256 签名算法的实现是否正确。
2446
+
2447
+ 加密密钥：AES-CBC-Key-1234
2448
+ 签名密钥：AES-HMAC-Key-123
2449
+ IV：1234567890abcdef
2450
+ 请求内容：{"Request": "This is a test."}
2451
+
2452
+ 最终请求参数：
2453
+ ```
2454
+ {
2455
+ "RequestAction": "DescribeFlowComponents",
2456
+ "IV": "MTIzNDU2Nzg5MGFiY2RlZg==",
2457
+ "EncryptedData": "Iqp2W1jislwMNmE7bH9dKZZiMQsfkAPyvAAqDFRnWLw=",
2458
+ "EncryptionSignature": "4TT3PUCZgZT7YmEPtXDm5PDcM6xT7FoYHfMW8xunB5I="
2459
+ }
2460
+ ```
2461
+
2462
+ **SM4-CBC 示例**
2463
+
2464
+ 以下示例参数及结果可用于验证 SM4-CBC 加密和 HMAC-SM4 签名算法的实现是否正确。
2465
+
2466
+ 加密密钥：SM4-CBC-Key-1234
2467
+ 签名密钥：SM4-HMAC-Key-123
2468
+ IV：fedcba0987654321
2469
+ 请求内容：{"Request": "This is a test."}
2470
+
2471
+ 最终请求参数：
2472
+ ```
2473
+ {
2474
+ "RequestAction": "DescribeFlowComponents",
2475
+ "IV": "ZmVkY2JhMDk4NzY1NDMyMQ==",
2476
+ "EncryptedData": "GwUovQhNUPaUnVM/UDXMtPOYTpTSi2B1oyZDFbyyvns=",
2477
+ "EncryptionSignature": "nHB/v/AvOaDCQ66esFNnp12lHKcGkwaLGid0Warl/KE="
2478
+ }
2479
+ ```
2480
+
2481
+ :param request: Request instance for CreateRequestWithEncryption.
2482
+ :type request: :class:`tencentcloud.ess.v20201111.models.CreateRequestWithEncryptionRequest`
2483
+ :rtype: :class:`tencentcloud.ess.v20201111.models.CreateRequestWithEncryptionResponse`
2484
+
2485
+ """
2486
+ try:
2487
+ params = request._serialize()
2488
+ headers = request.headers
2489
+ body = self.call("CreateRequestWithEncryption", params, headers=headers)
2490
+ response = json.loads(body)
2491
+ model = models.CreateRequestWithEncryptionResponse()
2492
+ model._deserialize(response["Response"])
2493
+ return model
2494
+ except Exception as e:
2495
+ if isinstance(e, TencentCloudSDKException):
2496
+ raise
2497
+ else:
2498
+ raise TencentCloudSDKException(type(e).__name__, str(e))
2499
+
2500
+
2396
2501
  def CreateRiskIdentificationTaskFeedback(self, request):
2397
2502
  r"""此接口（CreateRiskIdentificationTaskFeedback）用于创建合同审查任务结果反馈。
2398
2503
 
@@ -3377,6 +3482,9 @@ class EssClient(AbstractClient):
3377
3482
  1. `大文件转换所需的时间可能会比较长`
3378
3483
  2. `本接口返回的文件资源ID就是PDF资源ID，可以直接用于【用PDF文件创建签署流程】接口发起合同。`
3379
3484
 
3485
+ 整体流程如下图
3486
+ ![image](https://qcloudimg.tencent-cloud.cn/raw/bb35c9cfa453d28eade16df36221f313.png)
3487
+
3380
3488
  :param request: Request instance for DescribeFileConvertTask.
3381
3489
  :type request: :class:`tencentcloud.ess.v20201111.models.DescribeFileConvertTaskRequest`
3382
3490
  :rtype: :class:`tencentcloud.ess.v20201111.models.DescribeFileConvertTaskResponse`
@@ -4602,16 +4710,16 @@ class EssClient(AbstractClient):
4602
4710
 
4603
4711
  def StartFlow(self, request):
4604
4712
  r"""此接口用于启动流程。它是模板发起合同的最后一步。
4605
- 在[创建签署流程](https://qian.tencent.com/developers/companyApis/startFlows/CreateFlow)和[创建电子文档](https://qian.tencent.com/developers/companyApis/startFlows/CreateDocument)之后，用于开始整个合同流程, 推进流程进入到签署环节。
4606
4713
 
4607
- ![image](https://qcloudimg.tencent-cloud.cn/raw/1f38ebd7c5afed8763ad961741d81438.png)
4608
-
4609
- 注：
4610
- 1.<font color="red">合同发起后就会扣减合同的额度</font>, 只有撤销没有参与方签署过或只有自动签署签署过的合同，才会返还合同额度。（过期，拒签，签署完成，解除完成等状态不会返还额度）
4714
+ ## 1.1 接口调用流程
4715
+ 在[创建签署流程](https://qian.tencent.com/developers/companyApis/startFlows/CreateFlow)和[创建电子文档](https://qian.tencent.com/developers/companyApis/startFlows/CreateDocument)之后，用于开始整个合同流程, 推进流程进入到签署环节。
4611
4716
 
4612
- 2.<font color="red">静默（自动）签署不支持非本企业合同签署方存在填写</font>功能
4717
+ ![image](https://qcloudimg.tencent-cloud.cn/raw/dbd2eba8200d812d76b7e9e34d739e75.svg)
4613
4718
 
4614
- 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>，尤其是当模板中存在动态表格等复杂填写控件时，因为合成过程可能会耗费秒级别的时间。
4719
+ ### 1.2 注意事项
4720
+ - 合同<font color="red">发起后就会扣减合同的额度</font> , 只有撤销没有参与方签署过或只有自动签署签署过的合同，且<font color="red">有撤销合同额度</font>的情形下，才会返还合同额度。（**过期，拒签，签署完成，解除完成等状态不会返还额度**）。具体可以参考[合同撤销返还额度说明](https://qian.tencent.com/developers/company/contract_cancel_quota)。
4721
+ - 只要存在填写控件，填充时会触发 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) 接口发起签署**，以确保文档已合成完毕。，尤其是当模板中存在动态表格等复杂填写控件时，因为合成过程可能会耗费秒级别的时间。
4722
+ - 调用 [CreateDocument](https://qian.tencent.com/developers/companyApis/startFlows/CreateDocument) 成功后，请<font color="red">在 5 分钟内调用本接口（StartFlow）启动合同</font> ，不要长时间暂存仅调用了 CreateDocument 而未发起的合同；否则会导致该合同长时间后无法再启动，且合同额度不再返还。
4615
4723
 
4616
4724
  :param request: Request instance for StartFlow.
4617
4725
  :type request: :class:`tencentcloud.ess.v20201111.models.StartFlowRequest`
@@ -4717,7 +4825,7 @@ class EssClient(AbstractClient):
4717
4825
 
4718
4826
  适用场景：用于合同，印章的文件上传。文件上传以后，
4719
4827
  如果是PDF格式文件可配合<a href="https://qian.tencent.com/developers/companyApis/startFlows/CreateFlowByFiles" target="_blank">用PDF文件创建签署流程</a>接口进行合同流程的发起
4720
- 如果是其他类型可以配合<a href="https://qian.tencent.com/developers/companyApis/templatesAndFiles/CreateConvertTaskApi" target="_blank">创建文件转换任务</a>接口转换成PDF文件
4828
+ 如果是其他类型可以配合<a href="https://qian.tencent.com/developers/companyApis/templatesAndFiles/CreateFileConvertTask" target="_blank">创建文件转换任务</a>接口转换成PDF文件
4721
4829
 
4722
4830
  注:
4723
4831
  1. 图片类型(png/jpg/jpeg)限制大小为5M以下, PDF/word/excel等其他格式限制大小为60M以下