tencentcloud-sdk-python-ess 3.1.141__tar.gz → 3.1.166__tar.gz

{tencentcloud_sdk_python_ess-3.1.141 → tencentcloud_sdk_python_ess-3.1.166}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tencentcloud-sdk-python-ess
-Version: 3.1.141
+Version: 3.1.166
 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.141
+Requires-Dist: tencentcloud-sdk-python-common<4.0.0,>=3.1.166
 
 ============================
 Tencent Cloud SDK for Python

{tencentcloud_sdk_python_ess-3.1.141 → tencentcloud_sdk_python_ess-3.1.166}/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.141,<4.0.0"],
+    install_requires=["tencentcloud-sdk-python-common>=3.1.166,<4.0.0"],
     
     version=tencentcloud.__version__,
     description='Tencent Cloud Ess SDK for Python',

{tencentcloud_sdk_python_ess-3.1.141 → tencentcloud_sdk_python_ess-3.1.166}/tencentcloud/__init__.py

@@ -14,4 +14,4 @@
 # limitations under the License.
 
 
-__version__ = '3.1.141'
+__version__ = '3.1.166'

{tencentcloud_sdk_python_ess-3.1.141 → tencentcloud_sdk_python_ess-3.1.166}/tencentcloud/ess/v20201111/ess_client.py

@@ -90,7 +90,14 @@ class EssClient(AbstractClient):
         - **可撤回合同状态**：未全部签署完成
         - **不撤回合同状态**：已全部签署完成、已拒签、已过期、已撤回、拒绝填写、已解除等合同状态。
 
-        注:
+
+        **合同额度返还规则**:
+
+        1.撤销服务按照合同份额 1:1赠送免费撤销次数。例如购买 100 份合同，赠送 100 次免费撤销额度。
+        2.仅当没有任何参与方签署过，或仅自动签署完成的合同，撤销后才会使用免费撤销额度。
+        3.当赠送的免费撤销额度使用完后，后续仍可撤销合同，但不会返还合同额度。
+
+        **注**:
         1. 如果合同流程中的参与方均已签署完毕，则无法通过该接口撤销合同，签署完毕的合同需要双方走解除流程将合同作废，可以参考<a href="https://qian.tencent.com/developers/companyApis/operateFlows/CreateReleaseFlow" target="_blank">发起解除合同流程</a>接口。
 
         2. 有对应合同撤销权限的人:
@@ -102,10 +109,6 @@ class EssClient(AbstractClient):
         - 其它员工<font color='red'>（并已经授予撤销我发起的合同后）</font>：
             - 撤销人与发起人<font color='red'>**不在**</font>同一个部门：<font color='red'>（确保已授予查询合同 - 企业全部合同权限）</font>
             - 撤销人与发起人<font color='red'>**在**</font>用一个部门：<font color='red'>（确保授予查询合同 - 本部门全部合同权限 或 企业全部合同权限）</font>
-
-
-        3. <font color='red'>**只有撤销没有参与方签署过或只有自动签署签署过的合同，才会返还合同额度。**</font>
-
         4.  撤销后可以看合同PDF内容的人员： 发起方的超管， 发起方自己，发起方撤销合同的操作人员，已经签署合同、已经填写合同、邀请填写已经补充信息的参与人员， 其他参与人员看不到合同的内容。
 
         :param request: Request instance for CancelFlow.
@@ -323,7 +326,13 @@ class EssClient(AbstractClient):
         批量撤销结果可以通过接口返回的TaskId关联[批量撤销任务结果回调](https://qian.tencent.com/developers/company/callback_types_contracts_sign#%E4%B9%9D-%E6%89%B9%E9%87%8F%E6%92%A4%E9%94%80%E7%BB%93%E6%9E%9C%E5%9B%9E%E8%B0%83)或通过接口[查询批量撤销签署流程任务结果](https://qian.tencent.com/developers/companyApis/operateFlows/CreateBatchCancelFlowUrl)
 
 
-        注：
+        **合同额度返还规则**:
+
+        1.撤销服务按照合同份额 1:1赠送免费撤销次数。例如购买 100 份合同，赠送 100 次免费撤销额度。
+        2.仅当没有任何参与方签署过，或仅自动签署完成的合同，撤销后才会使用免费撤销额度。
+        3.当赠送的免费撤销额度使用完后，后续仍可撤销合同，但不会返还合同额度。
+
+        **注**：
         1. 如果合同流程中的参与方均已签署完毕，则无法通过该接口撤销合同，签署完毕的合同需要双方走解除流程将合同作废，可以参考<a href="https://qian.tencent.com/developers/companyApis/operateFlows/CreateReleaseFlow" target="_blank">发起解除合同流程</a>接口。
 
         2. 有对应合同撤销权限的人:
@@ -336,9 +345,6 @@ class EssClient(AbstractClient):
             - 撤销人与发起人<font color='red'>**不在**</font>同一个部门：<font color='red'>（确保已授予查询合同 - 企业全部合同权限）</font>
             - 撤销人与发起人<font color='red'>**在**</font>用一个部门：<font color='red'>（确保授予查询合同 - 本部门全部合同权限 或 企业全部合同权限）</font>
 
-
-        3. <font color='red'>**只有撤销没有参与方签署过或只有自动签署签署过的合同，才会返还合同额度。**</font>
-
         4. 撤销后可以看合同PDF内容的人员： 发起方的超管， 发起方自己，发起方撤销合同的操作人员，已经签署合同、已经填写合同、邀请填写已经补充信息的参与人员， 其他参与人员看不到合同的内容。
 
         :param request: Request instance for CreateBatchCancelFlowUrl.
@@ -528,9 +534,8 @@ class EssClient(AbstractClient):
         1. 该接口可生成签署人的批量、合同组签署/查看链接 。
         2. 该签署链接**默认有效期为30分钟**，过期后将失效，如需签署可重新创建批量签署链接 。
         3. 该接口返回的签署链接适用于APP集成的场景，支持APP打开或浏览器直接打开，**不支持微信小程序嵌入**。
-        跳转到小程序的实现，参考微信官方文档(分为<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>。
         4. 因h5涉及人脸身份认证能力基于慧眼人脸核身，对Android和iOS系统均有一定要求， 因此<font color='red'>App嵌入H5签署合同需要按照慧眼提供的<a href="https://cloud.tencent.com/document/product/1007/61076">慧眼人脸核身兼容性文档</a>做兼容性适配</font>。
-        5. H5签署现在仅支持中国大陆身份证和中国港澳台居民居住证。
+        5. <font color='red'>iframe 嵌入暂不支持人脸相关操作</font>，包括设置密码等需要进行的人脸核验。
 
         :param request: Request instance for CreateBatchQuickSignUrl.
         :type request: :class:`tencentcloud.ess.v20201111.models.CreateBatchQuickSignUrlRequest`
@@ -1005,6 +1010,9 @@ class EssClient(AbstractClient):
         1. `支持的文件类型有doc、docx、xls、xlsx、html、jpg、jpeg、png、bmp、txt`
         2. `可通过发起合同时设置预览来检查转换文件是否达到预期效果`
 
+        整体流程如下图
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/bb35c9cfa453d28eade16df36221f313.png)
+
         :param request: Request instance for CreateFileConvertTask.
         :type request: :class:`tencentcloud.ess.v20201111.models.CreateFileConvertTaskRequest`
         :rtype: :class:`tencentcloud.ess.v20201111.models.CreateFileConvertTaskResponse`
@@ -1318,9 +1326,8 @@ class EssClient(AbstractClient):
         注意：
         1. 转交的目标经办人需要已经加入企业，且完成实名。
         2. 仅企业拥有`超管`、`法人`或者`合同管理员`角色的员工才有调用本接口的权限。如果使用主带子方式调用，请确保您已经加入子企业，且账号在子企业中担任任一上述角色。
-        3. 仅支持当前经办人为待签署或待填写状态时进行转交操作。
-        4. 若原合同有填写控件，且当前经办人已经完成填写，则不支持进行转交。
-        5. 若当前经办人已签署完成，或者处于签署流程中，则不支持进行转交。
+        5. 若原合同有填写控件，且当前经办人已经完成填写，则不支持进行转交。
+        6. 若当前经办人已签署完成，或者处于签署流程中，或合同处于完成态（例如：签署完成，拒签，撤销，过期等），则不支持进行转交。
 
         :param request: Request instance for CreateFlowForwards.
         :type request: :class:`tencentcloud.ess.v20201111.models.CreateFlowForwardsRequest`
@@ -1620,9 +1627,8 @@ class EssClient(AbstractClient):
         **注意**
         1. 该签署链接**默认有效期为30分钟**，过期后将失效，如需签署可重新创建签署链接。
         2. 该接口返回的签署链接适用于APP集成的场景，支持APP、支付宝打开或浏览器直接打开，**不支持微信小程序嵌入**。配置方式请参考：<a href="https://qian.tencent.com/developers/company/openqianh5/">跳转电子签H5</a>。
-        如需跳转到小程序的实现，参考微信官方文档（分为<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>。
         3. 因h5涉及人脸身份认证能力基于慧眼人脸核身，对Android和iOS系统均有一定要求， 因此<font color='red'>App嵌入H5签署合同需要按照慧眼提供的<a href="https://cloud.tencent.com/document/product/1007/61076">慧眼人脸核身兼容性文档</a>做兼容性适配</font>。
-        4. H5签署现在**仅支持中国大陆身份证、中国港澳台居民居住证**。
+        4. <font color='red'>iframe 嵌入暂不支持人脸相关操作</font>，包括设置密码等需要进行的人脸核验。
 
         :param request: Request instance for CreateFlowSignUrl.
         :type request: :class:`tencentcloud.ess.v20201111.models.CreateFlowSignUrlRequest`
@@ -2390,6 +2396,143 @@ 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. 组装外层请求参数（三段均为标准 Base64）
+            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）用于创建合同审查任务结果反馈。
 
@@ -3374,6 +3517,9 @@ class EssClient(AbstractClient):
         1. `大文件转换所需的时间可能会比较长`
         2.  `本接口返回的文件资源ID就是PDF资源ID，可以直接用于【用PDF文件创建签署流程】接口发起合同。`
 
+        整体流程如下图
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/bb35c9cfa453d28eade16df36221f313.png)
+
         :param request: Request instance for DescribeFileConvertTask.
         :type request: :class:`tencentcloud.ess.v20201111.models.DescribeFileConvertTaskRequest`
         :rtype: :class:`tencentcloud.ess.v20201111.models.DescribeFileConvertTaskResponse`

{tencentcloud_sdk_python_ess-3.1.141 → tencentcloud_sdk_python_ess-3.1.166}/tencentcloud/ess/v20201111/ess_client_async.py

@@ -84,7 +84,14 @@ class EssClient(AbstractClient):
         - **可撤回合同状态**：未全部签署完成
         - **不撤回合同状态**：已全部签署完成、已拒签、已过期、已撤回、拒绝填写、已解除等合同状态。
 
-        注:
+
+        **合同额度返还规则**:
+
+        1.撤销服务按照合同份额 1:1赠送免费撤销次数。例如购买 100 份合同，赠送 100 次免费撤销额度。
+        2.仅当没有任何参与方签署过，或仅自动签署完成的合同，撤销后才会使用免费撤销额度。
+        3.当赠送的免费撤销额度使用完后，后续仍可撤销合同，但不会返还合同额度。
+
+        **注**:
         1. 如果合同流程中的参与方均已签署完毕，则无法通过该接口撤销合同，签署完毕的合同需要双方走解除流程将合同作废，可以参考<a href="https://qian.tencent.com/developers/companyApis/operateFlows/CreateReleaseFlow" target="_blank">发起解除合同流程</a>接口。
 
         2. 有对应合同撤销权限的人:
@@ -96,10 +103,6 @@ class EssClient(AbstractClient):
         - 其它员工<font color='red'>（并已经授予撤销我发起的合同后）</font>：
             - 撤销人与发起人<font color='red'>**不在**</font>同一个部门：<font color='red'>（确保已授予查询合同 - 企业全部合同权限）</font>
             - 撤销人与发起人<font color='red'>**在**</font>用一个部门：<font color='red'>（确保授予查询合同 - 本部门全部合同权限 或 企业全部合同权限）</font>
-
-
-        3. <font color='red'>**只有撤销没有参与方签署过或只有自动签署签署过的合同，才会返还合同额度。**</font>
-
         4.  撤销后可以看合同PDF内容的人员： 发起方的超管， 发起方自己，发起方撤销合同的操作人员，已经签署合同、已经填写合同、邀请填写已经补充信息的参与人员， 其他参与人员看不到合同的内容。
         """
         
@@ -282,7 +285,13 @@ class EssClient(AbstractClient):
         批量撤销结果可以通过接口返回的TaskId关联[批量撤销任务结果回调](https://qian.tencent.com/developers/company/callback_types_contracts_sign#%E4%B9%9D-%E6%89%B9%E9%87%8F%E6%92%A4%E9%94%80%E7%BB%93%E6%9E%9C%E5%9B%9E%E8%B0%83)或通过接口[查询批量撤销签署流程任务结果](https://qian.tencent.com/developers/companyApis/operateFlows/CreateBatchCancelFlowUrl)
 
 
-        注：
+        **合同额度返还规则**:
+
+        1.撤销服务按照合同份额 1:1赠送免费撤销次数。例如购买 100 份合同，赠送 100 次免费撤销额度。
+        2.仅当没有任何参与方签署过，或仅自动签署完成的合同，撤销后才会使用免费撤销额度。
+        3.当赠送的免费撤销额度使用完后，后续仍可撤销合同，但不会返还合同额度。
+
+        **注**：
         1. 如果合同流程中的参与方均已签署完毕，则无法通过该接口撤销合同，签署完毕的合同需要双方走解除流程将合同作废，可以参考<a href="https://qian.tencent.com/developers/companyApis/operateFlows/CreateReleaseFlow" target="_blank">发起解除合同流程</a>接口。
 
         2. 有对应合同撤销权限的人:
@@ -295,9 +304,6 @@ class EssClient(AbstractClient):
             - 撤销人与发起人<font color='red'>**不在**</font>同一个部门：<font color='red'>（确保已授予查询合同 - 企业全部合同权限）</font>
             - 撤销人与发起人<font color='red'>**在**</font>用一个部门：<font color='red'>（确保授予查询合同 - 本部门全部合同权限 或 企业全部合同权限）</font>
 
-
-        3. <font color='red'>**只有撤销没有参与方签署过或只有自动签署签署过的合同，才会返还合同额度。**</font>
-
         4. 撤销后可以看合同PDF内容的人员： 发起方的超管， 发起方自己，发起方撤销合同的操作人员，已经签署合同、已经填写合同、邀请填写已经补充信息的参与人员， 其他参与人员看不到合同的内容。
         """
         
@@ -457,9 +463,8 @@ class EssClient(AbstractClient):
         1. 该接口可生成签署人的批量、合同组签署/查看链接 。
         2. 该签署链接**默认有效期为30分钟**，过期后将失效，如需签署可重新创建批量签署链接 。
         3. 该接口返回的签署链接适用于APP集成的场景，支持APP打开或浏览器直接打开，**不支持微信小程序嵌入**。
-        跳转到小程序的实现，参考微信官方文档(分为<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>。
         4. 因h5涉及人脸身份认证能力基于慧眼人脸核身，对Android和iOS系统均有一定要求， 因此<font color='red'>App嵌入H5签署合同需要按照慧眼提供的<a href="https://cloud.tencent.com/document/product/1007/61076">慧眼人脸核身兼容性文档</a>做兼容性适配</font>。
-        5. H5签署现在仅支持中国大陆身份证和中国港澳台居民居住证。
+        5. <font color='red'>iframe 嵌入暂不支持人脸相关操作</font>，包括设置密码等需要进行的人脸核验。
         """
         
         kwargs = {}
@@ -858,6 +863,9 @@ class EssClient(AbstractClient):
         注:
         1. `支持的文件类型有doc、docx、xls、xlsx、html、jpg、jpeg、png、bmp、txt`
         2. `可通过发起合同时设置预览来检查转换文件是否达到预期效果`
+
+        整体流程如下图
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/bb35c9cfa453d28eade16df36221f313.png)
         """
         
         kwargs = {}
@@ -1137,9 +1145,8 @@ class EssClient(AbstractClient):
         注意：
         1. 转交的目标经办人需要已经加入企业，且完成实名。
         2. 仅企业拥有`超管`、`法人`或者`合同管理员`角色的员工才有调用本接口的权限。如果使用主带子方式调用，请确保您已经加入子企业，且账号在子企业中担任任一上述角色。
-        3. 仅支持当前经办人为待签署或待填写状态时进行转交操作。
-        4. 若原合同有填写控件，且当前经办人已经完成填写，则不支持进行转交。
-        5. 若当前经办人已签署完成，或者处于签署流程中，则不支持进行转交。
+        5. 若原合同有填写控件，且当前经办人已经完成填写，则不支持进行转交。
+        6. 若当前经办人已签署完成，或者处于签署流程中，或合同处于完成态（例如：签署完成，拒签，撤销，过期等），则不支持进行转交。
         """
         
         kwargs = {}
@@ -1404,9 +1411,8 @@ class EssClient(AbstractClient):
         **注意**
         1. 该签署链接**默认有效期为30分钟**，过期后将失效，如需签署可重新创建签署链接。
         2. 该接口返回的签署链接适用于APP集成的场景，支持APP、支付宝打开或浏览器直接打开，**不支持微信小程序嵌入**。配置方式请参考：<a href="https://qian.tencent.com/developers/company/openqianh5/">跳转电子签H5</a>。
-        如需跳转到小程序的实现，参考微信官方文档（分为<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>。
         3. 因h5涉及人脸身份认证能力基于慧眼人脸核身，对Android和iOS系统均有一定要求， 因此<font color='red'>App嵌入H5签署合同需要按照慧眼提供的<a href="https://cloud.tencent.com/document/product/1007/61076">慧眼人脸核身兼容性文档</a>做兼容性适配</font>。
-        4. H5签署现在**仅支持中国大陆身份证、中国港澳台居民居住证**。
+        4. <font color='red'>iframe 嵌入暂不支持人脸相关操作</font>，包括设置密码等需要进行的人脸核验。
         """
         
         kwargs = {}
@@ -2049,6 +2055,138 @@ class EssClient(AbstractClient):
         
         return await self.call_and_deserialize(**kwargs)
         
+    async def CreateRequestWithEncryption(
+            self,
+            request: models.CreateRequestWithEncryptionRequest,
+            opts: Dict = None,
+    ) -> models.CreateRequestWithEncryptionResponse:
+        """
+        该接口支持对请求内容进行加密传输。调用方需使用约定的 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. 组装外层请求参数（三段均为标准 Base64）
+            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="
+        }
+        ```
+        """
+        
+        kwargs = {}
+        kwargs["action"] = "CreateRequestWithEncryption"
+        kwargs["params"] = request._serialize()
+        kwargs["resp_cls"] = models.CreateRequestWithEncryptionResponse
+        kwargs["headers"] = request.headers
+        kwargs["opts"] = opts or {}
+        
+        return await self.call_and_deserialize(**kwargs)
+        
     async def CreateRiskIdentificationTaskFeedback(
             self,
             request: models.CreateRiskIdentificationTaskFeedbackRequest,
@@ -2852,6 +2990,9 @@ class EssClient(AbstractClient):
         注：
         1. `大文件转换所需的时间可能会比较长`
         2.  `本接口返回的文件资源ID就是PDF资源ID，可以直接用于【用PDF文件创建签署流程】接口发起合同。`
+
+        整体流程如下图
+        ![image](https://qcloudimg.tencent-cloud.cn/raw/bb35c9cfa453d28eade16df36221f313.png)
         """
         
         kwargs = {}