常见问题
接入开放平台时的高频问题汇总。更完整的说明见接入流程介绍与API概览。
开通与凭证
如何获取 apiKey？
apiKey 不能自助申请，请联系我们为企业开通开放应用。开通后由签签分配接口基址、apiKey 与回调密钥。
一把 key 对应一个企业，只能访问该企业已启用的模板，以及由该 key 创建的合同。详见接入凭证。
测试环境与生产环境怎么区分？
以开通时告知的 {baseUrl} 与 apiKey 为准，测试与生产可能使用不同基址与密钥。联调通过后再切换生产配置。
apiKey 泄露或需要停用怎么办？
请立即联系我们重置或停用。勿将 apiKey、回调密钥提交到代码仓库或写进前端页面。
创建与签署
创建合同有哪两种方式？
须且只能二选一：
| 方式 | 条件 |
|---|---|
| 文件地址 | 传 fileUrl，不传 templateId；盖章位置用 seals |
| 模板 | 传 templateId，不传 fileUrl；盖章位置以模板为准 |
同时传或都不传会返回 40001。详见创建合同。
签署链接由谁发给签署方？
平台创建合同后返回 signUrl（短链：落地页可选小程序或浏览器签署）与 h5SignUrl（浏览器直达），也可事后调用获取合同签署链接。只发短链即可。由接入方自行通知签署方，平台不代发短信或微信。
一份合同对应一条链接，全体签署方共用。链接形如 https://h5.xwkc.com/{短码}。
签署链接什么时候会失效？
取以下三者中最早的时刻：
- 创建后 30 天
- 合同截止时间
deadline - 合同离开进行中（完成 / 撤回 / 拒签 / 作废 / 过期）
建议 deadline 不要晚于创建后 30 天，否则链接可能先失效，而合同在截止前仍为 signing。不满足返回条件时，获取签署链接接口返回 40900。
模板在哪里维护？
模板在签签企业端维护，开放接口只读（模板列表、模板详情）。使用模板创建前，请先确认模板已启用，并按详情中的 templateSignatoryId 对齐签署方。
回调与查询
回调收不到怎么办？
请逐项排查：
- 回调地址须为 HTTPS，且开通时已登记
- 按状态回调校验
X-Timestamp、X-Signature - 业务处理成功后须在超时内返回 HTTP 2xx
- 未收到 2xx 时，平台按 1 分钟、5 分钟、30 分钟、2 小时重试
合同创建成功本身不产生回调；仅填信息方创建时直接 signed 也不单独回调，请以合同详情为准。
如何查询合同进度？
可调用合同详情或合同列表，也可依赖状态回调。建议两者结合：回调更新本地状态，详情做对账。状态枚举见状态。
文件与盖章
合同文件有什么限制？
- 合同正文：可访问的 HTTPS PDF 地址（
fileUrl），平台创建时拉取，不超过 50MB - 补充附件：最多 9 个，单个不超过 50MB，扩展名见合同可选项
- 地址不可达或超时：
40003；类型/大小不符：40002
盖章位置怎么填？
仅文件创建时由接入方传 seals。坐标为当前页比例，原点在左上角，x/y 取值 0～1。模板创建不传 seals。详见盖章规则与位置，也可用获取签章位置估算。
可以撤回合同吗？
仅状态为 signing 时可撤回。撤回后链接立即失效，并触发一条状态回调。已完成、已撤回、已拒签、已作废、已过期不可撤回，返回 40900。
调试与错误码
如何在线调试接口？
使用API在线调试：填写接口基址与 apiKey，选择接口后调用。凭证仅保存在本机浏览器。
错误码在哪里查？
见错误码查询。JSON 接口失败时 data 为 null，message 说明原因；常见如 40100（apiKey 无效）、40001（参数不符）、40400（资源不存在或不属于当前 key）。