开放平台

数知鸟REST API用于通过HTTP将第三方系统与数知鸟集成，使用标准OAuth2授权协议。

1.1 URI结构

使用RESTFull风格的URI路径。根路径为：

https://shuzhiniao.com/web/api/

1.2 数据结构

平台所有接口（除OAuth2授权相关接口外）遵循以下数据结构：

正常请求：

{   
   "success":true,   
   "code":200,   
   "data": ...
}

失败请求：

{   
    "success": false,   
    "code": ..., // 错误码，如140000002表示接口参数校验失败   
    "message": "报错提示信息"
}

2.1 客户端凭据

目前数知鸟仅支持OAuth2 客户端凭据授权方式，通过客户端凭据获取的企业令牌（access_token）不区分用户身份，具有管理员权限，请谨慎使用。获取企业令牌需要提供client_id和client_secret，可从「设置」>「API管理」>「新建API」中取得。

取得令牌后，只需要在API请求的header中添加"Authorization": "Bearer {access_token}"即可。

强烈建议不可将客户端凭据的client_id、client_secret以及access_token暴露到前端。

2.2 获取企业令牌

令牌有效期默认2小时。删除API管理会导致access_token失效，数知鸟也可能出于运营目的随时失效access_token,建议开发者适配access_token过期场景。access_token过期会抛出401 HTTP状态码。

POST https://{api_root}/oauth2/token

查询参数

请求示例

https://{api_root}/oauth2/token?grant_type=client_credentials&client_id={id}&client_secret={secret}

请求结果

{    
   "access_token": "",
   "token_type": "Bearer",
   "expires_in": 7200
}

工单接口可用于在第三方系统（比如内部员工管理系统、论坛网站等）中收集和查看当前登录用户（称之为第三方用户）提交的需求。要实现此能力，需要先取得工单Token，拼接到工单查看链接（或反馈链接）提供给第三方用户即可。

工单查看链接：

https://{server}/#/ticket/{ticketId}?ticketToken={ticketToken}

工单反馈链接：

https://{server}/#/ticket/{ticketId}/form?ticketToken={ticketToken}

工单Token不是一个实际的数知鸟账户，而是根据第三方用户信息生成的一个临时凭证，用于将第三方用户与数知鸟表单的自定义字段进行关联。

3.1 获取工单Token

工单Token有效期2小时，建议集成到业务系统时，每次访问工单页面都使用由业务系统后端最新生成的工单token。

POST https://{api_root}/ticket/token

权限：企业令牌

请求体

{  
   "工号": "001"，  
   "姓名": "张三"
}

示例请求

{    
    "ticketId": "0c55abfd296145018d5c21e544292122",    
    "fields": {        
         "工号": "001",        
         "员工姓名":"张三"    
    },    
   "filterFields":["工号"]
}

请求结果

{    
    "success": true,    
    "code": 200,    
    "message": "successful",    
    "data": "{ticketToken}"
}

特别的，如果想在工单提交时隐藏部分字段，可在工单链接中拼接hiddenFields参数，如：

https://{server}/#/ticket/{ticketId}?ticketToken={ticketToken}&hiddenFields=工号,员工姓名

单点登录接口支持使用企业token换取成员个人token。

POST https://{api_root}/auth/sso/oauth?mobile={mobile}&username={username}

权限：企业token

URL参数：

手机号和成员ID至少提供一个。

返回值

{
    "success": true,
    "code": 200,
    "message": "successful",
    "data": {
        "accessToken": "" // token
    }
}