调用格式
HTTP 方法
Udesk 开放接口（v1）可能会使用到以下 HTTP 方法：
- GET：用于获取数据接口
- POST：用于创建接口
- PUT：用于修改接口
- DELETE：用于删除接口
每个接口的文档中都会注明所使用的 HTTP 方法，调用接口时请以具体的接口文档为准。
调用地址
Udesk 开放接口（v1）的调用地址符合以下格式：
https://[子域名].udesk.cn/api/[版本]/[接口相对地址]?[Query String]&sign=[签名]
其中被中括号包含部分的含义如下：
| 变量 | 说明 |
|---|---|
| 子域名 | 您使用 Udesk 客服系统时，分配给您的子域名 |
| 版本 | 接口的版本。Udesk 开放接口（v1）有过一次小的升级，所以该值可能是 v1 或 v2，分别代表1.1版和1.2版 |
| 接口相对地址 | 接口的相对地址 |
| Query String | 地址的参数部分。该部分要参与签名计算，详见鉴权方法 |
| 签名 | 身份验证签名，除非明确说明，否则每次接口调用都需要携带，计算方法参见[身份校验][] |
每个接口文档中都会给出类似以下的调用方法：
GET /api/v1/tickets其中包含了 HTTP 方法、接口版本及接口相对地址，其他部分则需要根据具体情况替换。
参数
接口文档中可能会出现以下三种参数类型：
- URL 中：嵌入在调用地址中的参数，如
/tickets/:id中的:id； - Query String：调用地址 Query String 部分的参数，如
/tickets?page=2中的page； - Request Body：请求体中的内容。
当调用创建、修改类接口时，需要将请求数据按照 JSON 格式转换为 UTF-8 文本，将编码后的字符串作为 Request Body 类参数传给对应的接口。 同时将请求头中的 Content-Type 字段设置为 application/json 。(呼叫中心坐席外呼接口和获取通话记录接口无需此设置)
返回结果
Udesk 开放接口（v1）的返回数据同样为 JSON 格式编码的 UTF-8 字符串。
鉴权方法
所有接口调用需要携带签名参数 sign，只有当 sign 值合法时请求才会被接受。
sign 的计算方法如下：
sign=MD5(QueryString + "&" + Secret)
其中：
- QueryString 为URL中的参数（不包含参数 sign），格式为“&”分割的“key=value”字符串，顺序为参数在调用地址中的顺序；
- Secret 为单点登录共享秘钥，您可以在网站后台【管理中心】->【管理】->【单点登录】->【共享的秘钥】中找到。
当 QueryString 为空时，“sign=MD5(Secret)”，因此 V1 版本的接口存在安全隐患，所以我们建议您尽量采用新版接口； 如果某些参数没有 value，需要组合为“key=key”的形式，具体参看示例。
示例
假设共享秘钥为：
99d80d18b0b9a994a8d0283e830e5099
原始请求地址为：
https://demo.udesk.cn/api/v1/tickets?per_page=20&page=1&no_value
计算sign(32位小写)：
md5("per_page=20&page=1&no_value=no_value&99d80d18b0b9a994a8d0283e830e5099")
#=> c029b77b0da250875d89d52c7ab582a0
最终请求URL：
https://demo.udesk.cn/api/v1/tickets?per_page=20&page=1&no_value&sign=c029b77b0da250875d89d52c7ab582a0