# 平台概述
OneThird开放平台是基于fitsleep各类硬件的开放平台，目前提供“fitsleep a1”硬件的接入，供合作伙伴或者第三方软件供应商与OneThird进行系统对接，打通与fitsleep a1产品之间的数据流，实现双方智能硬件产品的一体化，提升用户体验，实现与OneThird的双赢。
# 平台特点
### 1. 统一合作入口
OneThird开放平台为合作伙伴提供统一的开放的合作服务门户(open.onethird.com.cn)，合作伙伴可以在平台上了解整个OneThird的服务，从而加快双方的合作
### 2. 完善的服务支持
OneThird开放平台提供一系列针对不同需求客户的快速指引、完善的文档和API手册，让合作伙伴可以无缝、快速地接入OneThird的智能硬件产品
### 3. 7*24小时沙盒测试环境
onethird开放平台提供一套稳定的沙盒测试平台，提供7 * 24小时的自助测试服务，让合作伙伴能够随时进行自助测试，无需等待，降低接入的成本
### 4. 丰富的接口资源
我们提供数据拉取，数据推送以及蓝牙BLE-SDK等丰富接口
### 5. 安全交易流程
我们提供一套完整的安全机制保证合作伙伴交易中的安全稳定
没有获取到文档!
# 数据业务
开放fitsleep设备数据接口，以便快速集成合作伙伴自有的系统或者产品，从而打通合作伙伴与onethird之间的信息流，进而达到onethird与合作商户的双赢。
| 接口名称 | 接口说明 |
| :---- | :------------------------------------ |
| 实时数据推送接口 | 向合作伙伴平台推送设备实时产生的数据 |
| 睡眠报告拉取接口 | 合作伙伴拉取设备产生的健康数据报告 |
| 蓝牙BLE移动平台SDK | 合作伙伴使用该SDK集成到自己的移动APP中，可以直接与设备进行通讯。 |
没有获取到文档!
# 入驻标准 #
1. 必须为公司身份
2. 仅限于与onethird/格兰莫尔 签署协议，且具有开发能力的公司。
3. 公司接入仅限于本公司使用。
# 接入流程 #
没有获取到文档!
# 接入规范
### 1. 数据推送类接口
---
1. 开发者在开放平台WEB管理页面打开推送开关
2. 返回开启状态，加入推送队列
3. 开放平台推送服务将实时数据推送给客户业务服务器处理
4. 由于每个请求都要包含签名，因此业务服务器应当对收到的数据进行签名校验
5. 校验通过后返回接收结果(返回内容应当进行签名)
6. 开放平台将对返回结果进行签名验证，并根据验证结果决定下次是否继续推送
7. 业务服务器对收到的数据进行处理
### 2. 数据拉取类接口
---
1. 业务服务器请求调用日报API
2. 开放平台接收到数据拉取请求后校验签名和权限
3. 校验通过后将日报信息返回给业务服务器
4. 业务服务器接收到返回数据后根据需要进行响应的业务逻辑处理
### 3. 移动SDK
---
1. 业务应用自行调用业务服务器获取授权Token
2. 使用AppId和Token初始化SDK
3. 设备连接到应用后，SDK立即验证设备的有效性
4. 设备验证通过后在后台检查设备固件和同步批量数据
5. 当业务应用需要拉取日报时，需要回调SDK或者自行调用业务服务器拉取日报
6. 业务服务器从开放平台拉取日报数据并返回
没有获取到文档!
## 安全管理 ##
1. 系统通过APPID，AccessKey，以及SecretKey识别有效合法的合作伙伴，并控制响应的权限
2. 请妥善保管好APPID，AccessKey，以及SecretKey，如果发现疑似泄露，请及时修改
3. APPID，AccessKey，以及SecretKey请不要在公网上传输明文传输
4. 接入方callbak接口建议使用HTTPS协议
## 安全协议 ##
开放平台的所有API请求都需要进行签名验证和授权验证。更详细介绍请查看《数据格式及安全》请求安全部分。
### 签名验证
签名验证是双向的，双方的请求和响应都要求进行签名。签名方法有两种，一种是使用token进行签名，另一种是使用AK/SK。
两种方法都需要将数据按照指定格式组合AppId、请求内容、时间戳、Token或者AccessKey和SecretKey，并采用hmac_sha1算法进行数据摘要，最后对摘要结果进行Base64编码所得的结果即为签名。
签名验证需要将签名的内容、时间戳和签名方法放在API的请求头内。数据的接收双方都应该校验签名的正确性以确保请求的数据安全。
### 授权验证
授权验证是在发往开放平台的API的请求中加入Authorization头，格式如下：
```
参数名:authorization
参数值:Base64(APPID:TOKEN)
```
### TOKEN生成
1、token采用JWT格式，playload内包含APPID，sign key为APPID和AK/SK的组合。
2、token使用simpleen简单MD5的方式进行签名，推荐使用方法三进行授权签名。
详情请查看《数据格式及安全》。
没有获取到文档!
# 数据格式及安全
## 请求类型
开放平台目前有两种类型的API：
1. 一种是能主动推送(PUSH)数据的API，这种类型的API需要业务服务器提供可供回调的URL
2. 另一种是业务服务器根据需要主动请求的API
## 请求安全
开放平台的所有API的请求和响应都应该进行签名校验以确保数据的正确和安全。
### 开放平台签名算法
当前开放平台仅支持一种签名算法：hmac_sha1
#### 方法一:使用aksk的方式进行签名
采用签名算法对请求内容进行摘要运算，得到签名。签名内容按照以下格式进行组织：
```
[AccessKey] + [SecretKey] + [时间戳] + [RequestBody] + [APPID]
```
- 时间戳格式为: yyyyMMddHHmmss，如:2018-01-01 00:00:00====>20180101000000
假设accessKey为 **areyouok**，secretKey为 **helloworld**，当前时间为**2018-01-01 00:00:00**，请求体为 **bluesky**，APPID为 **huotui**。
使用 **hmac_sha1**签名方法 ，则签名结果为：
```
hmac_sha1Str = hmac_sha1("helloworld", areyouok + helloworld + 20180101000000 + bluesky + huotui)
hmac_sha1Str = "06936a4d61635e04654516be2f2d1a808a234e65"
# 最终签名为:
Base64(hmac_sha1Str) = "MDY5MzZhNGQ2MTYzNWUwNDY1NDUxNmJlMmYyZDFhODA4YTIzNGU2NQ=="
```
#### 方法二:使用token的方式进行签名
与开放平台的通讯除了Authorization的Token校验以外，还需要对请求的内容进行签名。签名的方式除了用上述签名方式以外，还可以使用Token进行签名。
Token签名的算法采用hmac_sha1，以Token为SecretKey，时间戳加请求内容加APPID为签名内容进行签名。
```
token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ"
signTimestamp = 20180101000000
APPID = "huotui"
RequestBody = "helloworld"
# 最终签名为:
signature = Base64(hmac_sha1(token, signTimestamp + RequestBody + APPID))
```
#### 方法三:使用simpleen简单的MD5方式进行签名
1、token通过私有的code使用MD5加密取32位小写而成：
```
token=MD5(code)
```
2、计算签名signature：
```
[AccessKey] + [SecretKey] + [时间戳] + [RequestBody] + [APPID]
```
- 时间戳格式为: yyyyMMddHHmmss，如:2018-07-03 10:10:23====>20180703101023
假设accessKey为 **accessKeyXX**，secretKey为 **secretKeyXX**，当前时间为**2018-07-03 10:10:23**，请求体为 **{"macId":"e0e5cf246db9","date":"2018-07-18"}**，APPID为 **huotui**。
使用 **hmac_sha1**签名方法 ，则签名结果为：
```
hmac_sha1Str = hmac_sha1("secretKeyXX", accessKeyXX + secretKeyXX + 20180703101023 + {"macId":"e0e5cf246db9","date":"2018-07-18"} + huotui)
hmac_sha1Str = "93202a13366215090e7bef86d95b10d4dacf7039"
# 最终签名为:
Base64(hmac_sha1Str) = "OTMyMDJhMTMzNjYyMTUwOTBlN2JlZjg2ZDk1YjEwZDRkYWNmNzAzOQ=="
```
### 请求头授权验证
对于每个主动请求的API，需要在头部增加Authorization验证权限，字段名及内容为：
```
字段名:authorization
内容:Base64(APPID值:TOKEN值)
```
### JWT生成TOKEN的算法
token采用JWT的形式由业务服务器产生，JWT的介绍、token组成及不同语言的实现版本点此查看[相关网页](https://jwt.io/)。
JWT的形式如下：
```
# 头部（Header）
{
"alg": "HS256",
"typ": "JWT"
}
将头部使用Base64编码可得到所示格式的字符串：eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
# 有效载荷（Playload）
{
"APPID": "[APPID]", 参数名注意大写
"iss": 签发者，String, 此处应为cn.com.onethird,
"exp": 有效时间, long, 截至加入了有效时间的毫秒数,
"sub": 主题, String, 应为open
}
有效载荷也使用Base64编码得到所示格式的字符串：
eyJBUXXXXXX6ImIwASDFNG3245Y5NTQ2MWE5MmU0ZmEyMmY4ODQw8955IiwiaXNzIjoiY24uY2234m9uZXRoaXJkIiwiZXhwIjoxNTE1MDM1OTkxMDAwLCJzdWIiOiJvcGVuIn0
# 尾部（Digest）
Header和Playload拼接(使用"."分隔)，签名则通过私有的key计算而成：
secretkey = 'secretkey'
signature = HMAC-SHA256(secretkey, encodeBase64(header) + '.' + encodeBase64(payload))
尾部也使用Base64编码得到所示格式的字符串：
gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI
token = encodeBase64(header) + '.' + encodeBase64(payload) + '.' + encodeBase64(signature)
token示例:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBUXXXXXX6ImIwASDFNG3245Y5NTQ2MWE5MmU0ZmEyMmY4ODQw8955IiwiaXNzIjoiY24uY2234m9uZXRoaXJkIiwiZXhwIjoxNTE1MDM1OTkxMDAwLCJzdWIiOiJvcGVuIn0.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI
```
以Java的实现包 *io.jsonwebtoken:jjwt:0.6.0* 为例：
要获取一个有效时间为**2小时**，APPID为**huotui**的Token，密钥secretkey为：**[APPID] + [AK] + [SK]**，则应该调用
```
Date exp = new Date(System.currentTimeMillis() + 1000L * 60 * 60 * 2);
Jwts.builder()
.setSubject("open").setIssuer("cn.com.onethird").claim("APPID", "huotui")
.setExpiration(exp)
.signWith(SignatureAlgorithm.HS256, [APPID] + [AK] + [SK])
.compact();
```
- HS256即Hmac SHA256
没有获取到文档!