系统公有云API调用说明

更新时间:2024-07-02 15:08:34

本文目录导航指引

锚点跳转定位可能存在轻微页面滚动偏差,跳转后请上下滚动页面查看。

1.基本规则

2.接口请求域名

3.公共请求头格式

4.公共响应参数格式

1.基本规则

  • 所有 API 接口调用请求时必须使用 HTTPS 协议,发送 HTTPS 请求时所用 JDK/HTTPClient 或其他类库需保证支持 TLS1.2(安全加密协议)。
  • 所有 API 接口调用请求时必须使用 UTF8 字符编码。
  • 无特别声明时,所有 API 接口均使用 JSON 进行数据交换。
  • 请不要依赖接口响应参数中的 message 进行业务处理,因为 系统可能会对 message 进行文案优化调整,请根据 code 进行业务处理。
  • API 接口中可能在响应中新增 JSON 键值对,开发者需考虑参数兼容性,点击查看参数容错建议。
  • API 接口入参和出参有可能包含用户输入的信息,为避免 XSS 攻击,开发者应该对数据进行适当的处理,增强用户输入校验,如使用 WAF 进行系统防护。
  • 开发者应妥善保管 应用密钥(AppSecret) 防止泄露,如上传 Github 或 Gitee 时代码及注释需注意检查是否已删除AppSecret、身份证号、银行卡号等敏感信息。
  • 为保障服务稳定性,系统正式生产环境禁止进行性能压测和安全渗透测试。系统沙箱模拟环境进行性能压测和安全渗透测试时,需先向系统技术顾问报备,获得许可后才能进行相关操作。否则,系统安全团队有权采取相关措施进行拦截,影响严重时系统安全团队将上报网警。

2.接口请求域名

API 接口请求地址域名信息如下:

环境

域名

公网IP

端口

正式生产环境

https://esignapi.bestcert.net

120.25.168.36

443

沙箱模拟环境

https://esigndemo.bestcert.net

120.25.168.36

443

【说明/提示】

  • 若开发者所处网络需配置防火墙后才可以正常访问互联网资源,除上述域名信息外请结合系统公有云API更多的相关域名并按需进行配置。
  • demo.bestcert.net 下的接口均属于沙箱模拟环境,此环境仅用于开发调试,所签合同文件及认证等操作均不具备法律效力。正式上线使用时请务必切换到正式生产环境使用 bestcert.net 调用相关接口。
  • 沙箱模拟环境中所创建的数据不可以直接使用到正式生产环境中,正式上线使用时请注意重新创建相关数据。

3.公共请求头格式

请求签名鉴权方式-请求头格式

请联系您的账户经理,获取AppId以及配对AppSecret。

通过请求参数签名鉴权,可以确保API请求是由持有应用密钥(AppSecret )的开发者发送,还可以防止请求参数在传输中被篡改。

下方请求头格式为请求签名鉴权方式,点击查看请求签名鉴权方式的详细说明。

参数名称

参数

类型

参数必选

参数说明

(左右拖动查询完整描述)

X-Tsign-Open-App-Id

string

是

应用ID

X-Tsign-Open-Auth-Mode

string

是

接口鉴权方式,请填写固定值 Signature 。

X-Tsign-Open-Ca-Signature

string

是

请求签名值,点击查看请求签名值计算说明。

X-Tsign-Open-Ca-Timestamp

string

是

接口调用时的Unix时间戳,单位毫秒。

时间戳有效期为15分钟,但建议传入每次接口调用时的当前时间戳。

Accept

string

是

响应数据类型,建议统一填写 */*

Content-Type

string

是

请求Body体数据的格式类型

建议填写 application/json; charset=UTF-8

GET 和 DELETE 请求且Body体无数据时,参数值可为""空字符串或不传此参数。

Content-MD5

string

否

请求Body体数据的 Content-MD5 值,点击查看 Content-MD5 计算方法

GET 和 DELETE 请求且Body体无数据时,此参数可为 ""(空字符串)或不传此参数。

4.公共响应参数格式

展开全部参数参数名称

参数

类型

必选

参数说明

(左右拖动查看完整描述)

code

int32

是

业务码,0表示成功

message

string

否

业务信息

请根据 code 来判断错误情况,不应该依赖 message

匹配,因为 message 可能会调整。

data

object

否

业务数据

……

……

……

……


……

……

……

……

【说明/提示】

  • 系统可能会对 message 进行文案调整,请不要根据 message 进行业务逻辑判断。
  • code 非0时代表业务失败或异常,开发者可使用 code 进行业务逻辑判断。
  • API 接口中可能在响应中新增 JSON 键值对,开发者需考虑参数兼容性,点击查看参数容错建议。