其他常见问题
🧩 内容目录
1. 身份认证与权限配置
如何成为企业开发者？
要调用开放签 API，企业需完成以下流程：
- 注册个人账号；
- 完成企业实名认证；
- 使用管理员账号登录【运营管理后台】；
- 升级为“核心企业”；
- 在【开发者授权凭证】中创建凭证，下载
appAuthToken和私钥。
提示： 只有“核心企业”可发起合同和调用 API。
如何获取 appAuthToken 和私钥？
- 登录开放签平台；
- 进入【运营管理后台】；
- 打开【开发者授权凭证】，点击“新增”；
- 下载生成的
appAuthToken和私钥文件； - 若使用支付宝密钥工具，请选择加密算法为
RSA2。
普通企业与核心企业的区别
| 类型 | 权限说明 |
|---|---|
| 普通企业 | 仅能被动接收合同 |
| 核心企业 | 可主动发起合同、签署合同、调用 API |
只有核心企业可开通开发者权限，需升级后方可发起合同。
为什么无法调用某些接口？
常见原因如下：
- 未完成企业实名认证；
- 企业未升级为核心企业；
- API 凭证未正确配置；
- 请求参数不完整或签名错误；
- 缺乏相应业务线访问权限。
建议逐项检查企业角色、凭证配置及接口签名。
2. 接口调用与参数说明
如何上传合同附件？
- 接口：
/V2/annex/file - 支持格式：
.doc,.docx,.wps,.jpg,.png,.pdf,.xls,.xlsx,.zip,.rar - 文件大小：≤ 20MB
- 返回值：
fileId，可在发起合同时作为附件传入
如何下载签约后的文件？
- 登录开放签平台，在合同详情页手动下载；
- 或调用
/V2/contract/download接口，传入合同 ID 下载签约文件。
接口调用失败有哪些常见错误码？
详见下方 错误码速查表。
3. 模板与合同管理
模板参数填写顺序会影响签署吗？
不会影响最终签署结果。
合同签署后能否修改？
合同一旦签署完成，即进入不可变更状态。如果合同的所有签署方未全部签署完成，如需修改，需撤回合同重新发起。
合同签署失败有哪些可能原因？
| 原因 | 说明 |
|---|---|
| 模板参数未填全 | 签署前未完成所有必填项 |
| 签署方未配置 | 缺少签署人或盖章人 |
| 时间过期 | 超出签署截止时间 |
| 用户取消 | 签署人主动拒签或放弃签署 |
建议结合回调通知机制监听合同状态变化。
4. 接口签名与安全机制
为什么接口请求需要签名？
为确保接口请求来源真实、数据未被篡改，所有开放签 API 接口均需签名。
支持哪些签名算法？
- RSA2
如何生成签名字段？
签名字段一般为请求体参数拼接后，使用私钥签名的结果。
Java 示例：
String data = "appAuthToken=xxx&uniqueCode=yyy&signReId=zzz";
String sign = signByPrivateKey(data, privateKey);
签名失败常见原因及建议
- 私钥与凭证不匹配；
- 签名算法选择错误；
- 签名字段拼接顺序不对；
- 时间戳不在有效区间内。
建议：
- 检查私钥是否正确；
- 使用 Apifox 测试签名逻辑；
- 查看日志追踪错误码；
- 对照接口文档校验字段顺序和算法。
5. 常见问题与建议
- 所有接口文档均可在 Apifox 中查看并测试；
- 合同状态变更应及时同步至本地系统；
- 所有回调务必做幂等性处理，防止重复处理；
- 接口调用失败时应记录日志并分析 code 错误码。
💡 如需了解更多关于开放签 API 接口的操作细节或遇到问题，欢迎联系开放签技术支持团队，我们将为您提供专业的服务与指导。
