获取公司列表

该接口用于一次获取多个客户公司信息

请求方法

GET /organizations

请求参数（Query String）

参数名 必填 类型 说明 限制
filter_id 否 整型 公司过滤器id 过滤器存在
query 否 字符串 查询关键字
page 否 整型 页码，从1开始，默认为1 1至100
per_page 否 整型 每页数量，默认100 1至100

返回数据

属性名 类型 说明
code 整型 执行结果码，1000代表成功
meta 对象 分页信息，详见通用数据
organizations 数组 客户公司列表，详见公司数据

示例

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

返回

{
    "code": 1000,
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 1
    },
    "organizations": [
        {
            "id": 1,
            "name": "测试公司1",
            "domains": "https://www.test1.com",
            "level": "normal",

            "custom_fields": {
                "TextField_1": "测试文本",
                "SelectField_1": ["0"]
            },
            "updated_at": "2017-08-18T12:06:02.000+08:00",
            "description": "该公司仅用来举例",
            "token": "123456s7hgfd",
            "cellphones": [
              {"id":173,"content":"13111111111"}
            ]
        }
    ]
}

获取公司详情

该接口用于获取符合指定条件的客户公司信息

请求方法

GET /organizations/show_org

请求参数（Query String）

参数名 必填 类型 说明 限制
type 是 字符串 条件类型 不超过255个字符
content 是 字符串 条件内容 不超过255个字符

type取值范围

取值 含义
id 公司id
name 公司名称
token 公司外部标识

例如

type = id，content = 1 type = name，content = test_name type = token，content = test_token

返回数据

属性名 类型 说明
code 整型 执行结果码，1000代表成功
organization 对象 客户公司信息，详见公司数据

示例

curl https://demo.udesk.cn/open_api_v1/organizations/show_org?type=name&content=测试公司1&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

返回

{
    "code": 1000,
    "organization": {
        "id": 1,
        "name": "测试公司1",
        "domains": "https://www.test1.com",
        "custom_fields": {
            "TextField_1": "测试文本",
            "SelectField_1": ["0"]
        },
        "updated_at": "2017-08-18T12:06:02.000+08:00",
        "description": "该公司仅用来举例",
        "token": "123456s7hgfd"
    }
}

获取公司客户列表

该接口用于获取符合指定条件的公司的客户信息

请求方法

GET /organizations/customers

请求参数（Query String）

参数名 必填 类型 说明 限制
type 是 字符串 条件类型，参见获取公司详情接口 不超过255个字符
content 是 字符串 条件内容，参见获取公司详情接口 不超过255个字符
page 否 整型 页码，从1开始，默认为1
page_size 否 整型 每页数量，默认20，最大100

返回数据

属性名 类型 说明
code 整型 执行结果码，1000代表成功
meta 对象 分页信息，详见通用数据
customers 数组 客户列表，详见客户数据

示例

curl https://demo.udesk.cn/open_api_v1/organizations/customers?type=id&content=1&page=1&page_size=10&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

返回

{
    "code": 1000,
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 1
    },
    "customers": [
        {
            "id": 3,
            "nick_name": "大大1",
            "level": "normal",
            "description": null,
            "tags": [],
            "first_contact_at": null,
            "last_contact_at": null,
            "first_contact_at_via_phone": null,
            "last_contact_at_via_phone": null,
            "first_contact_at_via_im": null,
            "last_contact_at_via_im": null,
            "owner_id": null,
            "owner_group_id": null,
            "custom_fields": {},
            "open_api_token": null,
            "email": "",
            "other_emails": [],
            "organization_id": 1,
            "cellphones": [
                {"id": 5, "content": "12333334444"}
            ],
            "wechat": [],
            "weibo": []
        }
    ]
}

创建公司

该接口用于创建客户公司

请求方法

POST /organizations

请求参数（Request Body）

参数名 类型 必填 说明
organization 对象 是 公司信息

organization

参数名 类型 必填 说明 限制
name 字符串 是 名称 不超过255个字符
description 字符串 否 描述 不超过255个字符
domains 字符串 否 域名
custom_fields 对象 否 自定义字段

返回数据

与获取公司详情相同。

示例

curl https://demo.udesk.cn/open_api_v1/organizations?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 '
{
    "organization": {
        "name": "测试公司1",
        "description": "测试公司1描述",
        "notes": "",
        "domains": "https://www.test1.com",
        "custom_fields": {
            "TextField_1": "测试文本",
            "SelectField_1": ["0"]
        },
        "token": "123456s7hgfd"
    }
}'

返回

{
    "code": 1000,
    "organization": {
        "id": 1,
        "name": "测试公司1",
        "domains": "https://www.test1.com",
        "created_at": "2015-01-02T15:04:05.000+08:00",
        "token": "123456s7hgfd",
        "custom_fields": {
            "TextField_1": "测试文本",
            "SelectField_1": ["0"]
        },
        "description": "测试公司1描述",
        "customer_count": 0
    }
}

更新公司

该接口用于修改符合指定条件的客户公司

请求方法

PUT /organizations/update_org

请求参数（Query String）

与获取公司详情接口相同。

请求参数（Request Body）

参数名 类型 必填 说明
organization 对象 是 公司信息，参见公司数据

公司的token存在则不可更改，不存在则可修改

返回数据

与[获取公司详情][]相同。

示例

请求

curl https://demo.udesk.cn/open_api_v1/organizations/update_org?type=name&content=测试公司1&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type: application/json' \
-d '
{
    "organization": {
        "description": "测试公司1描述文字",
    }
}'

返回

{
    "code": 1000,
    "organization": {
        "id": 1,
        "name": "测试公司1",
        "domains": "https://www.test1.com",
        "created_at": "2015-01-02T15:04:05.000+08:00",
        "custom_fields": {
            "TextField_1": "测试文本",
            "SelectField_1": ["0"]
        },
        "description": "测试公司1描述文字",
        "token": "123456s7hgfd",
        "customer_count": 0
    }
}

删除公司

该接口用于删除符合指定条件的客户公司

请求方法

DELETE /organizations/destroy_org

请求参数（Query String）

与获取公司详情接口相同。

返回数据

属性名 类型 说明
code 整型 执行结果码，1000代表成功
id 整型 删除公司的id

示例

curl https://demo.udesk.cn/open_api_v1/organizations/destroy_org?type=name&content=测试公司1&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X DELETE

返回

{
    "code": 1000,
    "id": 1
}

获取公司自定义字段（废弃）

该接口用于获取全部公司自定义字段列表

请求方法

GET /organizations/custom_fields

请求参数

无

返回数据

属性名 类型 说明
code 整型 执行结果码，1000代表成功
custom_fields 数组 公司自定义字段列表，详见公司数据

示例

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

返回

{
    "code": 1000,
    "custom_fields": [
        {
            "id":10,
            "field_name":"TextField_10",
            "field_title":"浏览器",
            "content_type":"text",
            "comment":"",
            "options": null,
            "permission":3,
            "requirment":false
        },
        {
            "id":11,
            "field_name":"SelectField_11",
            "field_title":"及联城市",
            "content_type":"chained_droplist",
            "comment":"内容",
            "options": [{"0":["北京市", [["海淀区", [["知春路"]]]]]}, {"1":["天津市", [["和平区"]]]}],
            "permission":2,
            "requirment":false
        }
    ]
}

数据结构-公司

属性名 类型 可修改 说明
id 整型 否 唯一标识
name 字符串 是 名称
domains 字符串 是 域名
created_at 日期时间 否 创建时间
updated_at 日期时间 否 最后更新时间
custom_fields 对象 是 自定义字段
description 字符串 是 描述
customer_count 整型 否 客户数量
token 字符串 否 客户公司token
level 公司等级 否 取值范围normal、vip）客户所属的任一公司为vip时，视此客户为vip客户

Code错误码

错误码 message信息 exception:message信息 描述
2000 未知错误 invalid page: xxx page参数格式有误，例如负数、字母、空格等
未知错误 无 page_size参数格式有误
未知错误 无 如果在创建公司时添加了自定义字段，则有一些自定义字段必须设置
未知错误 名字重复 创建公司时，公司名和已有公司重复了
未知错误 Open api token已存在 创建公司时，Open api token和已有公司重复了
公司已经设置了token值,不可修改 无 公司的token存在则不可更改，不存在则可修改
2005 没有找到该资源 Couldn't find Organization with XXX 传入的id格式有误或根据所传id找不到对应资源
没有找到该资源 Couldn't find Organization with XXX 传入的name格式有误或根据所传name找不到对应资源
没有找到该资源 Couldn't find Organization with XXX 传入的token格式有误或根据所传token找不到对应资源
2015 非管理员不可以操作 非管理员不可以操作 调用接口时的邮箱必须为管理员邮箱，非管理员不可以操作
2059 open api签名不对 open api签名不对 open api签名不对，详细内容参考鉴权部分的文档
206201 参数page不合法 无 范围: 1至100
206202 参数per_page不合法 无 范围: 1至100