通用说明

调用限制

使用 Udesk 开放接口(v2),需要遵循以下规则:


调用格式

HTTP 方法

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

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

调用地址

Udesk 开发接口的调用地址都符合以下格式:

http://[子域名].udesk.cn/open_api_v1/[接口相对地址]?[URL参数]&email=[管理员邮箱]&timestamp=[时间戳]&sign=[签名]

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

变量 说明
子域名 您访问Udesk客服系统时使用的子域名
接口相对地址 您调用的具体API的相对URL,会在每个API中注明
URL参数 接口所需的Query String参数
管理员邮箱 您的超级管理员邮箱
时间戳 发起请求时的时间戳,格式为Unix Time,即从“1970-01-01 00:00:00”至今的秒数
签名 身份验证签名,除非明确说明,否则每次API调用都需要携带,计算方法参见鉴权方法

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

参数

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

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

返回结果

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


鉴权方法

规则说明

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

sign 的计算方法如下:

sign=SHA1(email&open_api_token&timestamp)

其中:

示例

假设要调用以下接口:

http://demo.udesk.cn/open_api_v1/customers

鉴权所需数据如下:

名称 数据
管理员email admin@udesk.cn
API Token 233df89e-b4a2-42e0-89af-f295b1078686
timestamp 1494474404

计算sign

sha1("admin@udesk.cn&233df89e-b4a2-42e0-89af-f295b1078686&1494474404")
#=> d102aeb2163da2d40f8c1f1ecec590ea23fb7a60

最终请求URL:

http://demo.udesk.cn/open_api_v1/customers?email=admin@udesk.cn&timestamp=1494474404&sign=d102aeb2163da2d40f8c1f1ecec590ea23fb7a60

获取鉴权 Token 接口

该接口用于获取鉴权所需的 token
鉴权:不需要

请求方法

POST /log_in

请求参数(Request Body)

参数名 必填 说明
email 超级管理员邮箱
password 超级管理员密码

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
open_api_auth_token 字符串 API 鉴权 token

示例

curl https://demo.udesk.cn/open_api_v1/log_in \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "email": "admin@udesk.cn",
    "password": "password"
}'

返回

{
    "code": 1000,
    "open_api_auth_token": "c5304da7632e3ba54964b57304c189f9"
}

设置通知回调地址接口

用于批量新建客户和批量新建公司接口,执行结束后通知调用者执行结果。
鉴权:参看鉴权方法

请求方法

POST /set_notice_url

请求参数(Request Body)

参数名 类型 必填 说明
notice_url 对象 通知地址

notice_url

参数名 类型 必填 说明
organization 字符串 导入公司通知地址
customer 字符串 导入客户通知地址

返回数据

参数名 类型 说明
code 整型 返回码,1000表示成功
notice_url 对象 通知地址,结构与参数相同

示例

curl http://demo.udesk.cn/open_api_v1/set_notice_url?email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "notice_url": {
        "organization": "http://www.demo.com/import/organizations/finish",
        "customer": "http://www.demo.com/import/customers/finish"
    }
}'

返回

{
    "code": 1000,
    "notice_url": {
        "organization": "http://www.demo.com/import/organizations/finish",
        "customer": "http://www.demo.com/import/customers/finish"
    }
}

通用数据

分页信息

获取列表等接口,在返回数据中通常都会携带分页信息(meta),其内容如下:

属性名 类型 说明
current_page 整型 当前页号
total_pages 整型 总页数
total_count 整型 数据总量