调用说明

调用服务端 API 时一些公共的全局配置、公共参数、签名过程、错误码等在这里统一定义和说明，具体接口不再赘述。

全局配置

以下配置说明为接口全局的配置或变量，在具体接口文档中不再重复说明。

接口域名

https://miniapp.cloud.189.cn

路径前缀

/platform/

参数组成

HTTP API 接口的参数由两部分组成：

1、请求头参数：每个 API 接口调用时都需要包含的参数叫功能参数。公共参数均放在请求头中，业务参数放在请求体中，在服务端接入的 API，公共参数包括X-H5App-ID、X-H5-Timestamp和X-H5-Signature。

2、业务请求参数：各个 API 接口由于业务差异性而特有的参数叫业务参数，业务请求参数均放在请求体中，具体各个 API 接口的业务参数见下文。

调用说明

（1）所有 API 接口全部以 HTTPS 协议访问，目前支持的 HTTP Method 包括GET和POST，具体接口中会说明调用方法GET或POST，同一个接口不会同时支持GET和POST；

（2）接口返回的数据都是 JSON 格式（接口的Content-Type响应头是固定值application/json;charset=UTF-8）；

（3）接口请求和响应数据使用的编码都是UTF-8；

（4）GET 请求参数全部在 URL 的查询参数中，以key1=value1&key1=value1&...的形式标识。如

https://miniapp.cloud.189.cn/platform/h5auth/api/open/getJsTicket?accessToken=XXX

（5）POST 请求参数在 Body 中，HTTP POST API 请求的 Content-Type 请求头必须设置如下：

application/x-www-form-urlencoded; charset=UTF-8

签名生成过程

API 调用时签名参数X-H5-Signature生成步骤：

（1）将除了X-H5-Signature以外的所有请求参数（公共参数和业务参数）的原始值（即不做任何处理的参数值，如不能进行 URL 编码）按照参数名的字典序排序（即 Java 中的 TreeMap 排序）；

（2）将排序后的参数键值对用&拼接，即拼接成key1=val1&key2=val2&...，假设这个值为paramsString；

（3）将步骤（2）得到的字符串paramsString使用小程序秘钥appSecret进行签名算法加密后，即为签名X-H5-Signature的值。用伪代码表示即

// 签名过程伪代码
X-H5-Signature = HMAC-SHA1(paramsString, appSecret).toUpperCase();

下面演示一个签名计算实例

appSecret: 643622e79d7bd9c94aed08445c6

假设本次请求的请求头公共参数如下：

X-H5-ID: 5e2a6363
X-H5-Timestamp: 1577925104661

假设本次请求的业务参数的如下：

h5appCode: F9509937DBB1DA6409E73584FC3BD35A2814AA679264837216BBEAD8C64223A329FE186D66AF691FA14EC51D499BC7D0E08DB5EE8410184003B564668DFA5076DC0A1C9EC9869ED65554D29BE4795CD7E31D2166E5612FC0F2EFA577E8247736A28C3229671F3A12`

（1）将以上参数进行字典序排序得到拼接的字符串

X-H5App-ID=5e2a6363&X-H5App-Timestamp=1577925104661&h5appCode=F9509937DBB1DA6409E73584FC3BD35A2814AA679264837216BBEAD8C64223A329FE186D66AF691FA14EC51D499BC7D0E08DB5EE8410184003B564668DFA5076DC0A1C9EC9869ED65554D29BE4795CD7E31D2166E5612FC0F2EFA577E8247736A28C3229671F3A12

（2）将以上参数进行HMAC-SHA1算法加密得到加密串并转为全部大写，得到X-H5-Signature的值为

FBBD2DB61B9BFF21FAEE98A5CE59D4306363A503

提示：可以通过 HMAC 在线签名工具 调试和验证签名算法的结果。

另外，我们还提供了针对不同开发语言的小程序签名签名和加解密算法封装实现的 SDK 工具包（ Java SDK、Node.js SDK），简化开发者的接入调试，开箱即用。

正常响应

所有接口都包含以下两个字段，用来说明接口返回数据的状态。

特殊响应及错误码

当接口无法非正常的返回业务数据时，仍会在 HTTP 200 里面响应结果，并在 Response Body 中带上错误响应 JSON 来指示错误信息，包含固定的错误码和错误描述说明。

以下是错误信息响应的示例

• 缺少参数

{
    "code": 400,
    "error": "InvalidParameters",
    "msg": "缺少参数 appId，请补充"
}

• 应用不存在

  { "code": 404, "error": "AppNotFound", "msg": "H5 应用不存在" }

• 签名校验不通过

{
    "code": 401,
    "error": "InvalidSignature",
    "msg": "签名校验不通过"
}

• 权限不足

{
    "code": 412,
    "error": "NoPermission",
    "msg": "无访问该接口的权限"
}