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

接口QPS限制说明

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

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

API 接口调用说明

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

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

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

采用标准的 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中示例如下：