通用规则

注意：尽量不要在 client 端使用该系列 API

安全及身份校验

采用 Http Basic Auth 方式，在请求头部添加身份验证信息，其中：

例如

curl https://mchat.udesk.cn/api/v1/merchants \
-X GET \
-u 'uuid:key' \ # 身份验证
-H 'content-type: application/json'

调用

返回数据

通过 HTTP Status Code 来判定接口返回结果：

错误时 Response Body 中的内容格式如下:

{
    "code": "tenant_not_found",
    "message": "您访问的租户“ab476257-5230-42f2-ae14-ea2a8e9ceb1d”不存在"
}

分页

基本所有获取列表类的接口都支持 page、per_page 参数：

属性 类型 必填 默认值 说明
page 整型 否 1 最小为1, 小于1视同为1
per_page 整型 否 30 最大值由各个接口决定, 大于最大值视同为最大值

支持分页的接口在返回时会带上分页信息：

meta:
    page: 当前页号
    per_page: 每页数量
    page_total: 总页数
    item_total: 数据总数

数据格式

类型 格式 空值 示例
时间日期 文本，ISO8601 null 2006-01-02T15:04:05.000+08:00
时间 文本，ISO8601 null 2006-01-02
日期 文本，ISO8601 null 15:04:05+08:00
时间戳 整数，UNIX时间戳 0 1136185445(2006-01-02 15:04:05)
字符串 文本 "" "Hello"、"示例"
整型 整数 0 1、1998
数值 实数 0 3.1415926
布尔 true/false false true、false
对象 JSON 对象 null {"age": 13}

数据示例

数据名称 示例
时间戳 1136185445
日期 2006-01-02
时间 15:04:05+08:00
日期时间 2006-01-02T15:04:05.000+08:00
租户 uuid ab476257-5230-42f2-ae14-ea2a8e9ceb1d
租户 key eba52e58c494cf68dd1077ddb174264c
商户 euid merchant01
商户 im_username demo_merchant_1@udeskchannel.com
商户 im_password 115b87a91d1af96d13ffe390660b5743
客户 euid customer01
客户 im_username demo_customer_1@udeskchannel.com
客户 im_password b0f61445454ed0e81aca820eb9ee264c
客户 openid 5e6c112f-772e-4ae2-a35f-338b961007d9
消息 uuid 0bbcd6ba-b8d6-4ad4-b90f-a634454e0d47

获取商户列表

GET /merchants

请求参数

# Query String
page: 页号
per_page: 每页数量, 最多100个

返回数据

merchants:
    id: 标识
    euid: 唯一标识
    name: 商户名称
    subdomain: udesk 客服系统的子域名
    im_agent_total: IM 坐席数量
    ticket_agent_total: 工单坐席数量
    created_at: 创建时间
    updated_at: 最后更新时间
meta:
    page: 当前页号
    per_page: 每页数量
    page_total: 总页数
    item_total: 数据总数

示例

curl https://mchat.udesk.cn/api/v1/merchants \
-X GET \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: application/json'

返回

{
    "merchants": [
        {
            "id": 1,
            "euid": "merchant01",
            "name": "测试商户1",
            "subdomain": "m01",
            "im_agent_total": 2,
            "ticket_agent_total": 2
            "created_at": "2006-01-02T15:04:05.000+08:00",
            "updated_at": "2006-01-02T15:04:05.000+08:00"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 10,
        "page_total": 1,
        "item_total": 1
    }
}

创建商户

POST /merchants

请求参数

# Request Body
merchant:
    euid: 外部唯一标识
    name: 商户名称
    subdomain: udesk 客服系统的子域名
    im_agent_total: IM 坐席数量
    ticket_agent_total: 工单坐席数量
admin:
    email: udesk 客服平台管理员邮箱
    password: udesk 客服平台管理员密码

返回数据

merchant:
    id: 标识
    euid: 唯一标识
    name: 商户名称
    subdomain: udesk 客服系统的子域名
    im_agent_total: IM 坐席数量
    ticket_agent_total: 工单坐席数量
    created_at: 创建时间
    updated_at: 最后更新时间

示例

curl https://mchat.udesk.cn/api/v1/merchants \
-X POST \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: application/json' \
-d '
{
    "merchant": {
        "euid": "merchant01",
        "name": "测试商户1",
        "subdomain": "m01",
        "im_agent_total": 2,
        "ticket_agent_total": 2
    },
    "admin": {
        "email": "admin@merchant01.com",
        "password": "password123"
    }
}'

返回

{
    "merchant": {
        "id": 1,
        "euid": "merchant01",
        "name": "测试商户1",
        "subdomain": "m01",
        "im_agent_total": 2,
        "ticket_agent_total": 2
        "created_at": "2006-01-02T15:04:05.000+08:00",
        "updated_at": "2006-01-02T15:04:05.000+08:00"
    }
}

修改商户

PUT /merchants/:id

请求参数

# URL
id: 商户外部标识

# Request Body
merchant:
    name: 商户名称
    im_agent_total: IM 坐席数量
    ticket_agent_total: 工单坐席数量

返回数据

与创建商户接口相同。

示例

curl https://mchat.udesk.cn/api/v1/merchants/1 \
-X PUT \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: application/json' \
-d '
{
    "merchant": {
        "name": "测试商户1",
        "im_agent_total": 2,
        "ticket_agent_total": 2
    }
}'

返回与创建商户接口相同。

修改商户头像

PUT /merchants/:id/logo

注意: 该接口的 Content-Type 为 image/jpeg 或 image/png

请求参数

# URL
id: 商户外部标识

# Request Body
图片文件内容

返回数据

与创建商户接口相同。

示例

curl https://mchat.udesk.cn/api/v1/merchants/1/logo \
-X PUT \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: image/png' \
--data-binary @filename.png

返回与创建商户接口相同。

删除商户

DELETE /merchants/:id

请求参数

# URL
id: 商户外部标识

返回数据

与创建商户接口相同。

示例

curl https://mchat.udesk.cn/api/v1/merchants/1 \
-X DELETE \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: application/json'

返回与创建商户接口相同。

获取客户未读消息数量

GET https://mchat.udesk.cn/client/v1/:uuid/customers/unread

该接口无需鉴权 uuid 为租户uuid

请求参数

euid: 客户euid, 必填

返回数据

unread: Boolean, 是否有未读消息

示例

curl https://mchat.udesk.cn/client/v1/ab476257-5230-42f2-ae14-ea2a8e9ceb1d/customers/unread?euid=1

返回

{
    "unread": true
}

Code错误码

错误码 message信息 exception:message信息 描述
unknown 未知错误 无 参数page或per_page的格式有误，例如为负数或字母
proj_internal_error 验证失败 无 注册邮箱已经被使用，或二级域名已经被使用
save_failed 商户保存失败 无 外部标识euid重复，IM或工单坐席总数超过租户即时通讯客服数量上限
record_not_found 没有找到商户 无 根据传入的id找不到对应商户
没有找到客户 无 根据传入的euid找不到客户
tenant_not_found “xxx”不存在 无 您访问的租户“xxx”不存在
2015 非管理员不可以操作 非管理员不可以操作 调用接口时的邮箱必须为管理员邮箱，非管理员不可以操作
2059 open api签名不对 open api签名不对 open api签名不对，详细内容参考鉴权部分的文档