调用限制

使用 Udesk 开放接口（v2），需要遵循以下规则：

调用格式

HTTP 方法

Udesk 开放接口（v2）可能会使用到以下 HTTP 方法：

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

调用地址

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

https://[子域名].udesk.cn/open_api_v1/[接口相对地址]?[URL参数]&email=[管理员邮箱]&timestamp=[时间戳]&sign=[签名]&nonce=[请求的唯一标识]&sign_version=[签名算法版本]

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

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

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

参数

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

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

返回结果

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

code错误码及说明

见code错误码说明

鉴权方法

规则说明

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

sign 的计算方法如下：

sign=SHA256(email&open_api_token&timestamp&nonce&sign_version)

注意: 若使用SHA256鉴权失败,请使用SHA1

其中：

示例

假设要调用以下接口：

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

鉴权所需数据如下：

名称 数据
管理员email admin@udesk.cn
API Token 233df89e-b4a2-42e0-89af-f295b1078686
timestamp 1494474404
nonce 2d931510-d99f-494a-8c67-87feb05e1594
sign_version v2

计算sign

sha256("admin@udesk.cn&233df89e-b4a2-42e0-89af-f295b1078686&1494474404&2d931510-d99f-494a-8c67-87feb05e1594&v2")
#=> 6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52

注意: 若使用sha256鉴权失败,请使用sha1

最终请求URL：

https://demo.udesk.cn/open_api_v1/customers?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

鉴权失败返回数据

属性名 值 说明 备注
code 2059 open api签名不对 鉴权未通过(鉴权参数错误)

获取鉴权 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": "233df89e-b4a2-42e0-89af-f295b1078686"
}

设置通知回调地址接口

用于客户批量导入接口,执行结束后通知调用者执行结果。 鉴权：参看鉴权方法

注：通知此地址的数据结构见下文

请求方法

POST /set_notice_url

请求参数（Request Body）

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

notice_url

参数名 类型 必填 说明
organization 字符串 是 导入公司通知地址
customer 字符串 是 导入客户通知地址
batch_create_ticket 字符串 否 批量创建工单通知地址
注：只填一个参数，另一个参数会默认设置为相同的通知地址

返回数据

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

示例

curl https://demo.udesk.cn/open_api_v1/set_notice_url?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "notice_url": {
        "organization": "https://www.demo.com/import/organizations/finish",
        "customer": "https://www.demo.com/import/customers/finish"
    }
}'

返回

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

客户导入后的通知数据

客户批量导入后，会发送一个json数据到本接口设置的通知回调地址，参数说明如下：

参数名 类型 说明
errors 数组 错误数据的信息，详见下文
success_count 字符串 导入成功数据的数量
failed_count 字符串 导入失败数据的数量

errors数据结构

参数名 说明
"0","1",... 导入客户数组中数组下标
"Mysql2::Error:...","Mysql2::Error:...",... 导入当前客户数据错误的原因

注：errors数据里的数组下标及错误信息全部采用逗号分割，详见示例

示例：

{
    "errors"=>
    [
        "0", "Mysql2::Error: Duplicate entry '1056_2@qq.com-28480' for key 'index_customers_on_email_and_company_id': UPDATE `customers` SET `customers`.`email` = '1056_2@qq.com' WHERE `customers`.`id` = 1492034492",
        "1", "Mysql2::Error: Duplicate entry '1056_3@qq.com-28480' for key 'index_customers_on_email_and_company_id': UPDATE `customers` SET `customers`.`email` = '1056_3@qq.com' WHERE `customers`.`id` = 1492034502"
    ],
        "success_count"=>"0",
        "failed_count"=>"2"
 }

批量创建工单后的通知数据

批量创建工单后，会发送一个json数据到本接口设置的通知回调地址，参数说明如下：

参数名 类型 说明
code 数值 请求状态,参见工单接口code码说明
data 对象 数据结果
success_count 数值 成功数量
success_unique_ids 数组 成功的标识数组
failed_count 数值 失败数量
failed_unique_ids 数组 失败的标识数组
result 数组 数据导入状态
message 字符串 成功或失败说明
ticket_id 数值 工单ID
unique_id 字符串 创建数据时传递的标识

示例：

{
    "code": 1000,
    "data": {
        "trace_id": "8ddade3a3c2a081d275f16002a19bd8d",
        "result": [
            {
                "code": 1000,
                "message": "工单创建成功",
                "trace_id": "8ddade3a3c2a081d275f16002a19bd8d",
                "ticket_id": 79211,
                "unique_id": "数据标识1"
            },
            {
                "code": 1000,
                "message": "工单创建成功",
                "trace_id": "8ddade3a3c2a081d275f16002a19bd8d",
                "ticket_id": 79212,
                "unique_id": "数据标识2"
            }
        ],
        "success_count": 2,
        "failed_count": 0,
        "success_unique_ids": [
            "数据标识1",
            "数据标识2"
        ],
        "failed_unique_ids": []
    }
}

通用数据

分页信息

获取列表等接口，在返回数据中通常都会携带分页信息（meta），其内容如下：

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

code错误码说明

错误码 message信息 exception:message信息 描述
2002 子域名无效 无 域名输入错误
2005 参数有误 无 密码输入错误
2015 非管理员不可操作 无 鉴权使用的身份非管理员
没有找到该资源 无 账号输入错误或无此账号
2058 您的公司不是专业版 无 公司未付费
2059 open api签名不对 无 鉴权参数错误
20621 时间戳格式不对 同message 必填参数{timestamp}未填写或格式错误
20622 时间戳误差不能超过5分钟 同message 参数{timestamp}与当前时间差超过5分钟
20623 请求仅一次有效, 15分钟内nonce值不能重复 同message 鉴权参数{nonce}在15分钟内已经使用过
20624 open api nonce为空 同message 鉴权参数{nonce}未填写或者为空
2000 未知错误 param is missing or the value is empty: notice_url notice_url参数为空 notice_url参数不能为空