1.概述编辑
数知鸟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.鉴权编辑
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
查询参数
| 字段 | 类型 | 备注 |
|---|---|---|
| grant_type | String | 授予类型，固定client_credentials |
| client_id | String | API管理的ID |
| client_secret | String | API管理的Secret |
请求示例
https://api_root/oauth2/token?grant_type=client_credentials&client_id=F65nd3uUty&client_secret=9e165ec4d33f4de082625334f98744fb
请求结果
{
"access_token": "",
"token_type": "Bearer",
"expires_in": 7200
}3.工单编辑
工单接口可用于在第三方系统（比如内部员工管理系统、论坛网站等）中收集和查看当前登录用户（称之为第三方用户）提交的需求。要实现此能力，需要先取得工单Token，拼接到工单查看链接（或反馈链接）提供给第三方用户即可,如：
https://server/#/ticket/{ticketId}?ticketToken={ticketToken}工单Token不是一个实际的数知鸟账户，而是根据第三方用户信息生成的一个临时凭证，用于将第三方用户与数知鸟表单的自定义字段进行关联。
3.1 获取工单Token
工单Token有效期2小时，建议集成到业务系统时，每次访问工单页面都使用由业务系统后端最新生成的工单token。
POST https://api_root/ticket/token
请求体
| 字段 | 类型 | 必填 | 备注 |
|---|---|---|---|
| ticket_id | String | 是 | 工单ID，可从工单查看链接中提取，如对于工单链接https://server/#/ticket/0c55abfd296145018d5c21e544192122，那么工单ID就是“0c55abfd296145018d5c21e544192122” |
| fields | Object | 是 | 用于表示工单用户的字段键值对，用于表单填写时自动填充对应值。其中key表示需求表单的自定义字段名称，value为该字段的默认值。 如业务系统使用工号和姓名标识提出人信息，那么可在需求类型表单中增加名称为“工号”和“姓名”的两个自定义文本字段，那么fields值可为： {
"工号": "001"，
"姓名": "张三"
} |
| filterFields | Array | 否 | 工单筛选字段名称列表，默认为fields的所有key。如仅需要部分字段作为唯一标识，可指定filterFields。如仅以“工号”作为筛选条件，那么filterFields即为["工号"] |
示例请求
{
"ticketId": "0c55abfd296145018d5c21e544292122",
"fields": {
"工号": "001",
"员工姓名":"张三"
},
"filterFields":["工号"]
}请求结果
{
"success": true,
"code": 200,
"message": "successful",
"data": "{ticketToken}"
}特别的，如果想在工单提交时隐藏部分字段，可在工单链接中拼接hiddenFields参数，如：
https://server/#/ticket/{ticketId}?ticketToken={ticketToken}&hiddenFields=工号,员工姓名