API调用说明

一、基本规则

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

二、接口请求域名

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

域名信息如下：

三、公共请求头格式

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

采用请求数据签名方式进行接口鉴权，防止请求数据被篡改，详见请求签名鉴权方式调用接口说明。

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

通过OAuthToken鉴权，可以确保API请求是由持有应用密钥（AppSecret ）的开发者发送，但 Token 访问令牌仅120分钟有效。多次获取 Token 访问令牌会造成旧 Token 访问令牌有效期变为5分钟，若开发者属于分布式部署，同时有多台服务器调用 API 接口时，需要集中管理 Token 访问令牌的获取和共享，确保所有服务器使用的 Token 访问令牌唯一。

因此，e签宝不推荐开发者使用 OAuthToken 鉴权方式调用 API 接口。

采用标准的 OAuth2.0 Client Credentials 方式进行接口鉴权，详见OAuth2.0鉴权方式调用接口说明。

四、请求参数类型及示例

接口请求参数分为 query、path 和 body 这三种类型。如下所示：

不同类型的请求参数具体传值方式说明如下：

1. Path类型示例

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

举例：

请求参数flowId为path类型，接口地址为：/v2/identity/auth/api/common/{flowId}/detail

完整请求：

https://openapi.esign.cn/v2/identity/auth/api/common/3611134459208242856/detail

注：例子中flowId值为：3611134459208242856

2. Query类型示例

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

举例：

请求参数keyWord为query类型，接口地址为：/v2/identity/auth/pub/organization/{flowId}/subbranch?keyWord={keyWord}

完整请求：

https://openapi.esign.cn/v2/identity/auth/pub/organization/3611134459208242856/subbranch?keyWord=平安银行杭州高新支行

注：例子中keyWord值为：平安银行杭州高新支行

3. Body类型示例

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

举例请求地址为：

https://openapi.esign.cn/v2/identity/auth/api/individual/face

Body请求体中数据为

{
    "name":"张三",
    "idNo":"320926xxxxxxxx5276",
    "faceauthMode": "TENCENT",
    "callbackUrl":"https://www.xx.cn/",
    "contextId": "f0a7927dxxxxd86c8fa8",
    "notifyUrl": "http://172.xx.xx.10:8080/notify/msgRecive"
}

则在PostMan中示例如下：

4. Path类型+Body类型示例

举例：

请求参数flowId为path类型，接口地址为/v2/identity/auth/api/organization/{flowId}/legalRepSign

完整请求：

https://openapi.esign.cn/v2/identity/auth/api/organization/3611134459208242856/legalRepSign

注：例子中flowId值为：3611134459208242856

Body请求体中数据为

{
    "agentIdNo": "101101********1121",
    "agentName": "张三",
    "mobileNo":"188****8888",
    "legalRepIdNo": "320926********5276",
  	"redirectUrl":"http://www.xx.cn/"
}

则在PostMan中示例如下：

5. Path类型+Query类型示例

举例：

请求参数flowId为path类型、keyWord为query类型，接口地址为：/v2/identity/auth/pub/organization/{flowId}/subbranch?keyWord={keyWord}

完整请求：

https://openapi.esign.cn/v2/identity/auth/pub/organization/3611134459208242856/subbranch?keyWord=平安银行杭州高新支行

注：例子中flowId值为：3611134459208242856，keyWord值为：平安银行杭州高新支行

则在PostMan中示例如下：

五、接口错误码说明

1. e签宝会对 message 进行文案调整，请不要根据 message 进行业务逻辑判断。
2. code 非0时均可代表业务失败或异常，开发者可使用 code 进行业务逻辑判断。
3. 接口调用出现报错时，开发者可通过错误码查询工具查找错误排查方法。

六、接口QPS限制说明

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

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