平台概述

云盯开放了平台的API接口能力，开发者可以通过这些接口，实现企业系统与云盯平台的互联互通。

接入流程

企业使用云盯平台API前，需要先申请开通API接入能力，并取得对接访问凭证账号和密钥。

协议说明

调用云盯平台API接口，需要使用HTTPS协议、JSON数据格式、UTF-8编码，接口基础地址为https://yd.yunding360.com/openapi/。

全局参数

所有的API请求需要在HTTP Header中设置：api-version: v1，除安全认证接口外的其他所有接口中还需要设置：Authorization: <token 由 tokenType + accessToken 拼接的字符串>，其中token由获取access_token接口取得。

POST、PUT、PATCH、DELETE命令请求需要在HTTP Header中设置Content-Type: application/json。

通用错误码

所有API接口以 HTTP 状态码作为响应状态的判断代码。

• 200：请求成功；
• 400：请求参数格式不正确或缺少必要字段，可通过 HTTP Body 中返回的 json 内容得到具体的错误；
• 401：未提供Token令牌或Token令牌有错误；
• 403：拒绝访问, Token已过期或没有访问该接口权限；
• 500：服务端错误，可通过 HTTP Body 中返回的 json 内容得到具体的错误信息；

HTTP 400、500状态码时，在 HTTP Body 中可以读取到错误的详细信息，格式为：

{
    "additionalInfo": {},   //附加信息
    "error": "",            //错误类型
    "errorDescription": "",  //错误描述
    "messages": [            //错误详细信息
        {
            "code": "",
            "description": ""
        }
    ]
}

注意事项：

在请求除获取access_token接口外的其他接口时，如果收到401或403错误响应时，应该重新请求获取access_token接口获取新的token后重新发起之前的接口请求。 如果在请求获取access_token接口时接收到401或403错误，则不再继续重试，应抛出错误并检查密钥是否正确、权限是否设置正确等错误原因。

频率限制

平台对某些接口的请求频率做了限制：

• 获取access_token接口中返回的token具有较长的有效期，接口使用方应将token做为全局变量进行缓存，在token有效期内不要频繁获取token或者刷新token有效期；

分页模型

某些接口使用了分页的方式来取得数据，这些接口返回的数据被包装为以下的格式：

{
    "content": [
        {
            //实际的数据
        }
    ],
    "metadata": {
        "page": 0,  //页数
        "size": 0,  //页大小
        "totalElements": 0,     //总记录数
        "totalPages": 0         //总页数
    }
}

FAQ问答

1. 是否必须使用HTTPS协议，不可以使用HTTP吗？

   为了防止通信过程中信息被窃取，保障用户信息安全性，必须使用HTTPS。