# API调用说明

接口名称：
···

接口说明：
···

请求地址：
···

请求方式：
GET/POST(HTTPS)

请求类型：
Content-Type: application/json

请求头：
···

请求参数：
···

返回参数：
···

请求示例：
···

返回示例：
···

接口名称：接口的名称
接口说明：接口的详细介绍
请求地址：接口的请求地址
请求方式：标明接口调用的HTTP方法，区分GET/POST请求。所有的请求都为HTTPS协议
请求类型：发送HTTP请求时需要选择的类型
请求头：发送HTTP请求时需要放在Headers里面的参数字段
请求参数：标明请求参数示例及说明
返回参数：标明返回参数示例及说明。所有接口的返回结果里都有state、msg、msgCN、msgEN。开发者需根据state是否为0判断是否调用成功（state意义可查看全局错误码）。msg、msgCN、msgEN仅作参考，后续可能会有变动，因此不可作为是否调用成功的判据
请求示例：POST请求时，会标明需要放在Body里的参数示例。所有的请求都会标明JavaSdk的调用示例
返回示例：标明返回示例

# 以哪种方式调用API

我们支持以下两种方式调用API：

使用HTTP请求调用
使用Java SDK调用

# HTTP请求示例

1.HTTP请求需在Headers头里包含以下字段：

token：调用获取Token获得。

corp-id：详见查看权限信息。

xb-timestamp：北京时间时间戳，长整型。

xb-sign-method：加密方式，固定sha256。

xb-sign：见下文。

2.HTTP请求sign生成规则示例：

签名算法：固定sha256。

签名内容：由7部分组成，按顺序为：签名算法 + 请求类型（大写）+ accessKeyId + 时间戳（当前请求时间，长整型）+ 请求url（去掉域名及/符号）+ 请求体（get或post请求对应参数内容）+ accessKeySecret。

以获取行政班列表接口为例：

签名算法：sha256
请求类型：GET
accessKeyId：accessKeyId
时间戳：1595229375367
请求url：open-platformClassv2GetAdministrativeClassList
请求体：gradeCode=1&pageIndex=1&pageSize=1000
accessKeySecret：accessKeySecret

根据以上内容，可拼接出加密前的字符串：

sha256GETaccessKeyId1595229375367open-platformClassv2GetAdministrativeClassListgradeCode=1&pageIndex=1&pageSize=1000accessKeySecret

以sha256加密后：

15492225ac54501ef9ab9db578e91ef618fc86242a26705e6669c4694df3005e

如果请求类型为POST，请求体则为body内的所有字符，需精简成json串

以创建考勤机接口为例：

签名算法：sha256
请求类型：POST
accessKeyId：accessKeyId
时间戳：1595235364255
请求url：open-platformOcpv2CreateDevices
请求体：[{"deviceId":"string","name":"string","type":1,"state":1,"serialNumber":"string"}]
accessKeySecret：accessKeySecret

拼接出加密前的字符串：

sha256POSTaccessKeyId1595235364255open-platformOcpv2CreateDevices[{"deviceId":"string","name":"string","type":1,"state":1,"serialNumber":"string"}]accessKeySecret

以sha256加密后：

f1b14a32bb3ded93d06341d20ab235f39c5050ec8727d71b044ed8908739ad32

3.演示使用Postman请求创建考勤机接口：

Body示例

Header示例

# JavaSDK请求示例

1. 方法调用

TokenApi tokenApi = new TokenApi(String apiUrl);
TokenDTO dto = new TokenDTO();
dto.setAccessKeyId(String accessKeyId);
dto.setAccessKeySecret(String accessKeySecret);
String token = tokenApi.getToken(dto);
SchoolApi api = new SchoolApi(String apiUrl,String accessKeyId,String accessKeySecret, String token, String corpId);
api.getSchool(parameter [, parameter1, parameter2...])

2. 参数

apiUrl：接口的Java请求地址。

accessKeyId、accessKeySecret、corpId：详见查看权限信息。

3. SDK相关依赖包

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-web</artifactId>
        <version>4.3.20.RELEASE</version>
    </dependency>

    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.70</version>
    </dependency>

    <dependency>
        <groupId>commons-codec</groupId>
        <artifactId>commons-codec</artifactId>
        <version>1.10</version>
    </dependency>

    <dependency>
        <groupId>commons-lang</groupId>
        <artifactId>commons-lang</artifactId>
        <version>2.6</version>
    </dependency>

    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.12</version>
    </dependency>

    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>4.5.2</version>
    </dependency>

    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpmime</artifactId>
        <version>4.5.2</version>
    </dependency>

    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpcore</artifactId>
        <version>4.4.4</version>
    </dependency>
</dependencies>

# 关于Token持续时间

Token申请成功后，持续时间为2小时，持续时间内可重复使用。

# 关于接口调用频率限制

出于系统保护的考虑，我们对接口的调用做了频率限制。默认情况下，调用每个学校的接口都有一定的频率限制，当超过此限制时，调用对应接口会收到相应错误码。

以下是当前默认的频率限制，校宝智慧校园后台可能会根据运营情况调整此阈值：

调用每个学校的接口频率不可超过20次/秒，否则返回错误码9500

# SDK下载地址

由于接口更新，会同步更新SDK。为避免出错，开发之前，请务必下载最新版本的SDK使用。

下载地址：open-platform-sdk-1.0.8-RELEASE.jar