API接口调用
接入前常见问题
应用号是什么？
应用号是您企业账号下每款应用的唯一标识符，用于快速标记您企业下的各款应用。 当您在腾讯电子签创建企业后，可通过申请应用号的方式对您企业下的若干款应用进行标记，以区分企业下不同应用之间的数据及请求。各应用号之间的数据相互隔离。
通过小程序注册的企业，如何查看对应企业的 API 密钥信息？
通过小程序注册的企业，单击查询密钥，即可查看对应企业的 API 密钥信息。
!
- API 密钥是构建腾讯云 API 请求的重要凭证，请妥善保管。
- 查询密钥过程中，可能需要通过短信验证码进行安全校验，如您不是该手机号所有人，请与企业超级管理员联系。
- 此入口当前仅小程序注册的企业可见，电脑端注册企业的 API 密钥查看方式请参见 访问密钥 文档。
子账号可以调用开放平台的 API 吗？
可以，您可使用主账号登录腾讯云访问管理，为子账号授权绑定电子签策略 QcloudESSBASICFullAccess，授权之后即可使用子账号调用腾讯电子签集成版 API 接口。授权指引请参见 授权指引文档。
SDK 相关
如何获取 SDK 调用样例？
电子签集成版目前提供了 PHP 、Python 、Java 、Go、.NET 等语言的调用 Demo 供您在接入时参考，已上传至 GitHub 腾讯云官方 SDK 项目。
如何导入 SDK ？
目前官方提供了 PHP、Python、Java、Go、.NET、Node.js、C++、Ruby 等语言的 SDK 支持，请根据您的实际需要进行导入，请参见 SDK 导入指引 。
JDK1.7 使用 SDK 调用上传文件接口报 javax.net.ssl.SSLException-Received fatal alert: protocol_version？
JDK1.7 默认使用 TLSv1.0，需要强制设置成 TLSv1.2，官方使用的 HTTP 客户端是 okhttp，需要自行修改官网 SDK 源码。 在 com.tencentcloudapi.common.http.HttpConnection 类中修改构造函数如下：
public HttpConnection(Integer connTimeout, Integer readTimeout, Integer writeTimeout) {
this.client = new OkHttpClient();
SSLContext sslContext = null; //这边指定tls版本
try {
sslContext = SSLContext.getInstance("TLSv1.2");
sslContext.init(null, null,null);
} catch (Exception e) {
e.printStackTrace();
throw new RuntimeException(e.getMessage());
}
SSLSocketFactory factory = sslContext.getSocketFactory();
this.client.setSslSocketFactory(factory);
this.client.setConnectTimeout(connTimeout, TimeUnit.SECONDS);
this.client.setReadTimeout(readTimeout, TimeUnit.SECONDS);
this.client.setWriteTimeout(writeTimeout, TimeUnit.SECONDS);
}
小程序相关
客户小程序如何跳转到电子签小程序完成签署？
请参见小程序 官方文档 。小程序支持直接跳转到签署页面，完成签署后可返回客户小程序。可参见以下代码：
wx.navigateToMiniProgram({
appId:'wxa023b292fd19d41d', // 电子签小程序的appId
path:'pages/guide?from=SFY&to=CONTRACT_DETAIL&id=${flowId}&name=%E6%9D%A8%E5%B8%88&phone=MTc2MTI3Nzg1Mjk%3D', //${flowId}为流程 id，name、phone 按需给
envVersion:'release’,
success(res){
// 打开成功
}
})
path 里的参数（name，phone）均使用 ~${base64url(value)} 统一编码。
客户 App 如何跳转到电子签小程序完成签署？
- Android App 请参见 官方文档 。
- iOS App 请参见 官方文档 。
- 所需参数：
电子签小程序 Appid：
wxa023b292fd19d41d。 电子签小程序原始 ID：gh_da88f6188665。 电子签小程序合同详情页：path：pages/guide?from=app&to=CONTRACT_DETAIL&id=${flowId}&name=&phone=。
- 测试环境： 电子签小程序 Appid：wx371151823f6f3edf。 电子签小程序原始 ID：gh_39a5d3de69fa。 电子签小程序合同详情页：path：pages/guide?from=app&to=CONTRACT_DETAIL&id=${flowId}&name=&phone=。
为什么客户在小程序中无法找到自己的合同？
请确认客户有使用和发起时相同的姓名、手机号进行小程序登录。且在个人中心 > 切换身份确认已切换为签署时要求的身份。
如何选择通过全屏或半屏方式打开电子签小程序？
可参见微信官方文档：
如何配置跳转至电子签小程序的不同页面？
请参见以下表格及说明：
参数说明
下表描述的是外部小程序拉起电子签小程序首页、列表页、个人中心页、合同封面页、合同详情页的参数配置。
| 参数 | 类型 | 默认值 | 必填 | 描述 |
|---|---|---|---|---|
| path | string | - | 是 | 目标页面路由。 |
| login | number | 0 | 否 | 是否需要登录。 |
| verify | number | 0 | 否 | 是否需要实名。 |
| accountType | string | - | 否 | personal：切换个人身份。 |
| userIds | string | - | 否 | 如果该链接目标用户只有一个人使用，则直接取该用户的 userId；如果该链接目标用户多人使用，可以将 userId1，userId2 这样赋值：[userId1，userId2]。 |
| organizationId | string | - | 否 | 企业账号的企业 ID，如果添加此参数则还要同步携带 orgName。 |
| orgName | string | - | 否 | 企业账号的名称，如果添加 organizationId 则还要同步携带此参数。 |
| id | string | - | 否 | 合同 ID，如果是到合同封面页或者合同详情页，此参数必填。 |
| channel | string | - | 否 | 其他小程序渠道的标记，方便统计使用。 |
| quickSponsor | string | false | 否 | 到首页是否需要立即拉起快速发起合同弹框。 true：出现快速发起弹框。 false：不出现。 |
首页
C 端用户进入首页
- pages/guide/index?path=/pages/home/home-index&accountType=personal&channel=${channel}
C 端用户进入首页-快速发起合同
- pages/guide/index?path=/pages/home/home-index&login=1&accountType=personal&channel=${channel}&quickSponsor=true
B 端用户进入首页
进入 B 端首页必须已登录已实名，可指定用户的 userIds 合集，或者 organizationId（指定了 organizationId，则需要同步携带 orgName 以下两种方式均可：
- pages/guide/index?path=/pages/home/home-index&login=1&verify=1&userIds=${userIds}&channel=${channel}
- pages/guide/index?path=/pages/home/home-index&login=1&verify=1&organizationId=${organizationId}&orgName=${orgName}&channel=${channel}
B 端用户进入首页-快速发起合同
- pages/guide/index?path=/pages/home/home-index&login=1&verify=1&userIds=${userIds}&channel=${channel}&quickSponsor=true
- pages/guide/index?path=/pages/home/home-index&login=1&verify=1&organizationId=${organizationId}&orgName=${orgName}&channel=${channel}&quickSponsor=true
列表页
C 端进入用户列表页
- pages/guide/index?path=/pages/home/home-list&login=1&verify=1&accountType=personal&channel=${channel}
B 端进入用户列表页
进入 B 端首页必须已登录已实名，可指定用户的 userIds 合集，或者 organizationId（指定了 organizationId，则需要同步携带 orgName。）。 以下两种方式均可：
- pages/guide/index?path=/pages/home/home-list&login=1&verify=1&userIds=${userIds}&channel=${channel}
- pages/guide/index?path=/pages/home/home-list&login=1&verify=1&organizationId=${organizationId}&orgName=${orgName}&channel=${channel}
个人中心
C 端进入用户个人中心
- pages/guide/index?path=/pages/home/home-user&accountType=personal&channel=${channel}
B 端进入用户个人中心
进入 B 端首页必须已登录已实名，可指定用户的 userIds 合集，或者 organizationId（指定了 organizationId，则需要同步携带 orgName。）。 以下两种方式均可：
- pages/guide/index?path=/pages/home/home-user&login=1&verify=1&userIds=${userIds}&channel=${channel}
- pages/guide/index?path=/pages/home/home-user&login=1&verify=1&organizationId=${organizationId}&orgName=${orgName}&channel=${channel}
合同封面页
C 端用户进入合同封面页或 B 端用户合同封面页
未登录或者未实名的用户也可进入到合同封面页，切换到个人身份可以使用两种方式，使用 accountType=personal，或者使用 userIds 赋值个人身份的 userId。
- pages/guide/index?path=/pages/mvp/contract-preview&accountType=personal&id=${id}&channel=${channel}
- pages/guide/index?path=/pages/mvp/contract-preview&userIds=${userIds}&id=${id}&channel=${channel}
合同详情页
无论是 C 端还是 B 端，进入合同详情页均必须已登录已实名。
C 端进入合同详情页
以下方式进入：
- 可以设置 accountType=personal 进入。
- 也可指定 C 端用户的个人身份的 userId。
- pages/guide/index?path=/pages/contracts/contract-detail&login=1&verify=1&id=${id}&accountType=personal&channel=${channel}
- pages/guide/index?path=/pages/contracts/contract-detail&login=1&verify=1&id=${id}&userIds=${userIds}&channel=${channel}
!
- 如果 B2C 合同发起，对方签署方 C 是新用户，则 C 没有 userId，可指定参数 accountType=personal。
- 如果 B2C 合同发起，对方签署方 C 是老用户，则以上两种方式均可。
B 端进入合同详情页
可指定用户的 userIds 合集，或者 organizationId（指定了 organizationId，则需要同步携带 orgName。）。
- 以下两种常用方式均可：
- pages/guide/index?path=/pages/contracts/contract-detail&login=1&verify=1&id=${id}&userIds=${userIds}&channel=${channel}
- pages/guide/index?path=/pages/contracts/contract-detail&login=1&verify=1&id=${id}&organizationId=${organizationId}&orgName=${orgName}&channel=${channel}
- 特殊情形：
- pages/guide/index?path=/pages/contracts/contract-detail&login=1&verify=1&id=${id}&accountType=personal&channel=${channel}
!
- 如果 B2B 合同发起，对方签署方 B 所在的企业没有注册，那么使用特殊情形，切换到个人身份可查看合同，合同详情页会引导用户申请企业注册。
- 如果 B2B 合同发起，对方签署方 B 没有加入该企业，那么使用特殊情形，切换到个人身份可查看合同，合同详情页会引导用户申请加入企业。
- 如果 B2B 合同发起，对方签署方 B 是该企业的员工，那么以上两种常用方式均可使用。
接口报错相关
接口调用报错如何处理？
您可以尝试按照接口返回的 message 的提示进行修改，或者记录下 requestId 并提供给对接人员进行处理。
接口调用返回签名错误？
请先检查 SecretId 和 SecretKey 是否正确。如果您未使用 SDK 进行接入，请参见腾讯云官方 开发指南 中的样例代码进行签名计算。
StartFlow（发起流程）接口报错，提示“文档不可用”？
在调用 CreateDocument 接口后，需要等待文档的异步合成，所以不能立即调用 StartFlow 接口；如果调用 StartFlow 报错，可以尝试等待后重试。
CreateDocument（创建电子文档）接口报错，提示“流程已关联文档”？
每个流程有且仅有一次能用于绑定文档，请重新使用 CreateFlow 接口创建新的流程。
接口调用时返回没有权限，该如何处理？
如接口调用时返回没有权限，此接口可能为白名单接口，需添加白名单权限。
短信相关
为什么客户收不到短信通知？
根据签署类型，可以分为个人签署用户和企业签署用户。
- 如果为个人签署用户，电子签默认会发送短信。建议引导客户查看手机拦截记录，检查短信是否被拦截。
- 如果为企业签署用户，自建应用和第三方应用的规则不同：自建应用不会给发起人发短信；第三方应用默认给渠道外SaaS企业发短信（可在第三方应用管理中关闭），而不会给子客企业发。
- 只有从小程序发起的合同，才会给所有签署方发送【签署完成】短信。
如何在发起流程时不对签署方发送短信?
在调用 CreateFlowByFiles 或者 CreateFlow 接口时，签署人信息设置 NotifyType 参数为“none”。
输入手机号码获取验证码提示发送频率超过限制，短信发送的限制规则是什么？
目前腾讯电子签集成版针对单个应用号做了短信的限额，同一个应用号下：
- 对同一个手机号，30 秒内发送短信条数不超过 1 条。超出限额会提示：短信发送频率超出限制，请等待一分钟后重试。
- 对同一个手机号，1 小时内发送短信条数不超过 10 条。超出限额会提示：本小时验证码发送数量超出限制，请稍后重试。
!1 小时为每自然小时，如 13 点 ~ 14 点为 1 个自然小时。
- 对同一个手机号，1 自然日内发送短信条数不超过 20 条。超出限额会提示：今日验证码发送量已超出限制，请联系工作人员处理。
?如需调整频控策略，请联系客户经理或邮件至 e-contract@tencent.com 与我们联系。
印章相关
如何查看印章审核状态？
请登录 腾讯电子签控制台 ，访问印章管理单击印章详情对印章审核状态进行查看。
为什么印章审核通不过？
请确认印章为非绘制印章，且在图片中清晰完整。目前电子签提供以下生成印章的方式：
- 新建印章时，选择模板印章的创建方式，即可自动生成企业电子印章。
- 上传印章前在白纸上清晰盖章后拍照，确保印章在图片中清晰完整，在新建印章时，选择本地上传并上传图片。
请确保印章有按照以上方生成。具体失败原因以审核人提供的拒绝理由为准。
创建流程提示“无权限操作该印章”?
请登录 腾讯电子签控制台 ，访问印章管理单击印章详情确认已添加用户为印章持有人，只有持有人才拥有印章使用权限。
如何添加企业印章？
- 小程序端：超级管理员可在小程序首页选择印章管理选择自动生成“企业公章”的电子印章。
- 电脑端：
- 企业超管可 登录腾讯电子签 ，通过印章管理入口通过模板创建或上传图片作为印章。
- 此外，有印章管理权限的企业员工可选择上传真实印章图片作为企业电子印章，提交后我们将在 1-3 个工作日进行审核，审核通过后即可使用（请确保印章信息内容正确）。
在使用电子签的时候，签署合同时提示没有可用印章，但我已经上传了印章并且审核通过了？
提交印章但是没有可用印章的话，请先与管理员确认您是否已拥有印章权限，管理员可前往印章管理对印章持有人进行设置。详细教程请参见 印章管理。
除了超管之外是否可以设置其他员工添加印章权限？
您可参见 角色管理 文档教程，给相应员工授予印章管理权限即可。
PDF 相关
如何计算 PDF 签名位置？
1. Adobe阅读器：
- 单击准备表单。
- 单击添加文本域。
> !此处仅做定位使用。 - 单击文本域属性 > 位置，单位选点。
!此时下方位置显示坐标值，注意此坐标值以页面左下角为原点。
- 坐标计算 ComponentPosX = 左对齐坐标 39.4847 ComponentPosY = 页面高度 - 上对齐坐标 37.3135 页面高度获取：可先将控件移至页面顶部，此时上对齐坐标值即为页面高度。
2. 福昕阅读器：
软件安装：访问福昕PDF阅读器官网，选择“个人版下载”，下载后直接安装。
软件设置：以mac版本为例，进人菜单，福昕PDF编辑器->偏好设置，左侧菜单选“测量”，度量单位选择“点”，然后点击确定。
设置目标编辑区域：打开目标PDF文档，菜单选择编辑->编辑对象->添加形状->矩形，然后在目标区域拖动鼠标，画出一个矩形。
画出矩形后，鼠标右击矩形框，选择“属性”。
可以看到矩形相关坐标信息，注意这里X/Y轴缩放为100%。
计算坐标：属性这里对应的坐标含义为页面右下角为原点的坐标系，我们创建的矩形框的左下角的坐标为（x,y）。
目标坐标系原点为页面的左上角，目标位置为矩形框的左上角点（x',y'）
可以看出，ComponentPosX（x'）=x坐标=175.06
将矩形框拖动到当前页面的顶部左上角处，可以获得页面顶部坐标y(顶部)
于是可以计算得到ComponentPosY(y')=y(顶部) - y坐标 = 811.93-472.69=339.24
ComponentWidth =宽度 = 137
ComponentHeight = 30
ComponentPage为当前文档的页面序号，页码编号是从1开始编号的。
控件相关
在调用 CreateFlowByFiles（用 PDF 文件创建签署流程）时，经办人内容控件中 ComponentName 是否为必传值？
ComponentId 和 ComponentName 选择传入一项即可，此处建议传入 ComponentName。
在调用 CreateFlowByFiles（用 PDF 文件创建签署流程）时，如何获取经办人内容控件中 ComponentName 值？
在 腾讯电子签控制台 进行模板新建或者编辑时，于指定签约区域步骤，可以查看控件属性，属性值“控件名称”即为 ComponentName 值。
在调用 CreateFlowByFiles（用 PDF 文件创建签署流程）接口时，签署者信息入参 SignComponents，能否支持传入填写控件和签署控件两种？
此处只能传入签署控件，如果需要为签署者添加填写控件，请使用模板发起流程。
控件如何进行关键字定位？
Component 入参时，GenerateMode 参数选择填入 KEYWORD，并使用 ComponentId 指定关键字。
关键字定位如何调整控件位置？
使用关键字定位时，控件区域的左上角和关键字区域的左上角为重叠关系，可以通过 Component 的入参 OffsetX 以及 OffsetY 来完成控件在横纵坐标上的偏移。
控件如何进行表单域定位？
Component 入参时，GenerateMode 参数选择填入 FIELD，并使用 ComponentName 指定关键字。