通用说明

调用格式

HTTP 方法

Udesk 开放接口(v1)可能会使用到以下 HTTP 方法:

每个接口的文档中都会注明所使用的 HTTP 方法,调用接口时请以具体的接口文档为准。

调用地址

Udesk 开放接口(v1)的调用地址符合以下格式:

http://[子域名].udesk.cn/api/[版本]/[接口相对地址]?[Query String]&sign=[签名]

其中被中括号包含部分的含义如下:

变量 说明
子域名 您使用 Udesk 客服系统时,分配给您的子域名
版本 接口的版本。Udesk 开放接口(v1)有过一次小的升级,所以该值可能是 v1 或 v2,分别代表1.1版和1.2版
接口相对地址 接口的相对地址
Query String 地址的参数部分。该部分要参与签名计算,详见鉴权方法
签名 身份验证签名,除非明确说明,否则每次接口调用都需要携带,计算方法参见[身份校验][]

每个接口文档中都会给出类似以下的调用方法:
GET /api/v1/tickets
其中包含了 HTTP 方法、接口版本及接口相对地址,其他部分则需要根据具体情况替换。

参数

接口文档中可能会出现以下三种参数类型:

当调用创建、修改类接口时,需要将请求数据按照 JSON 格式转换为 UTF-8 文本,将编码后的字符串作为 Request Body 类参数传给对应的接口。 同时将请求头中的 Content-Type 字段设置为 application/json 。

返回结果

Udesk 开放接口(v1)的返回数据同样为 JSON 格式编码的 UTF-8 字符串。


鉴权方法

所有接口调用需要携带签名参数 sign,只有当 sign 值合法时请求才会被接受。

sign 的计算方法如下:

sign=MD5(QueryString + "&" + Secret)

其中:

当 QueryString 为空时,“sign=MD5(Secret)”,因此 V1 版本的接口存在安全隐患,所以我们建议您尽量采用新版接口;
如果某些参数没有 value,需要组合为“key=key”的形式,具体参看示例。

示例

假设共享秘钥为:

99d80d18b0b9a994a8d0283e830e5099

原始请求地址为:

http://demo.udesk.cn/api/v1/tickets?per_page=20&page=1&no_value

计算sign:

md5("per_page=20&page=1&no_value=no_value&99d80d18b0b9a994a8d0283e830e5099")
#=> c029b77b0da250875d89d52c7ab582a0

最终请求URL:

http://demo.udesk.cn/api/v1/tickets?per_page=20&page=1&no_value&sign=c029b77b0da250875d89d52c7ab582a0