开发前必读

更新时间：2022-01-14 16:17:04

接口请求域名说明

所有的接口请求调用时需使用HTTPS协议、JSON数据格式、UTF8编码。

域名信息如下：

环境	域名	公网IP	端口
正式生产环境	https://openapi.esign.cn	118.31.181.75	443
沙箱模拟环境	https://smlopenapi.esign.cn	114.55.17.44	443

环境说明

1. 若开发者需要配置防火墙后才可以访问互联网资源，请点击链接查看更多e签宝域名信息。

2. 调用 smlopenapi.esign.cn 下的接口全都属于沙箱模拟环境，正式生产调用请使用 openapi.esign.cn。

3. 沙箱模拟环境下签署的合同属于测试文件，不具备任何法律效力。正式上线请务必切换到正式生产环境使用。

4. 沙箱模拟环境与正式生产环境数据不互通，正式使用时请注意重新创建相关账号及数据。

接口错误码说明

e签宝会对 message 进行文案调整，请不要根据 message 进行业务逻辑判断。
code 非0时均可代表业务失败或异常，开发者可使用 code 进行业务逻辑判断。

接口调用出现报错时，开发者可通过错误码查询工具查找错误排查方法。

接口QPS限制说明

开发者在开放平台上创建应用时，其QPS默认值是50次/秒，即每秒最高可同时调用50次e签宝接口。

若贵司有更高的并发需求，需要付费提高QPS。QPS购买可联系客户成功经理或交付顾问。

电子签名 SaaS API 标准版接口调用说明

为保证API调用过程的安全可靠，e签宝开放平台openapi统一采用HTTPS传输协议，并提供了两种安全接入鉴权方式，开发者可根据自身情况任选一种方式。

1. 请求签名鉴权方式请求头（优先推荐）

安全接入选择请求签名鉴权方式，请点击请求签名鉴权方式调用接口说明查阅详情。

2. OAuth2.0鉴权接口调用方式（不推荐使用）

安全接入选择OAuth2.0鉴权方式，请点击OAuth2.0鉴权方式调用接口说明查阅详情。

请求参数类型说明

电子签名 SaaS API 标准版中接口请求参数会涉及query、path和body这三种类型。

请求参数类型：

参数名称	参数类型说明	参数类型	是否必填	类型
a123	query类型参数	query	true	string
b123	path类型参数	path	true	string
c123	body类型参数	body	true	string

1. Path类型

path是指请求参数需要拼接在url中即可。

举例：

请求参数accountId为path类型，接口地址为/v1/accounts/{accountId}。

例如：

https://openapi.xxx.cn/v1/accounts/229

注：例子中accountId值为229

2. Query类型

query是指请求的参数，一般是指URL中 ? 字符后面的参数。简单说请求时参数可以拼接在 ? 后面。

举例：请求参数thirdPartyUserId为query类型，接口地址为/v1/accounts/getByThirdId?thirdPartyUserId={accountId}

例如：

https://openapi.xxx.cn/v1/accounts/getByThirdId?thirdPartyUserId=229

注：例子中thirdPartyUserId值为229

3. Body类型

body是指请求体中的数据。通常情况下为接口具体入参数据的json字符串。

举例：

请求地址为

https://openapi.xxx.cn/v1/accounts/createByThirdPartyUserId

Body请求体中数据为

{
    "thirdPartyUserId":"229",
    "name":"xx",
    "idType":"CRED_PSN_CH_IDCARD",
    "idNumber":"xxxx",
    "mobile":"182681xxxxx",
    "email":"xxx@tsign.com"
}

则在PostMan中示例如下：

4. Path类型+Body类型示例

举例：

请求参数accountId为path类型

接口地址为/v1/accounts/{accountId}/seals/personaltemplate

请求地址为

https://openapi.xxx.cn/v1/accounts/229/seals/personaltemplate

注：例子中accountId值为229

Body请求体中数据为

{"alias": "芜浣的印章别名","color": "RED","height": 100,"type": "SQUARE","width": 100}

则在PostMan中示例如下：

5. Path类型+Query类型示例

举例：

请求参数fileId为path类型，keywords为query类型。

接口地址为/v1/documents/{fileId}/searchWordsPosition

请求地址为

https://openapi.xxx.cn/v1/documents/4c2h/searchWordsPosition?keywords=k1,k2

注：例子中fileId值为4c2h，keywords值为k1和k2。

则在PostMan中示例如下：