云桥第三方系统接入文档

概述
企业应用接入指南
- Step1：创建企业
- Step2：添加应用
- Step3：接入应用
开发应用
- 建立连接
- 主动调用
- 全局返回码
- 免登服务
- 管理多媒体文件
- 消息接口
- 用户信息接口
- 企业接口
- 员工接口
- 部门接口
- 普通群接口
调试工具
demo下载
全局返回码说明

概述

企业在云桥平台上可将现有系统或应用、常用网站等添加为企业自建应用，供企业内部员工快速方便的使用。自建应用可以使用云桥平台提供的如免登录、发送应用通知、获取员工及部门结构数据等标准接口，更好的将云桥员工数据与既有系统进行对接，帮助企业高速度、低成本地实现高质量的信息化、智能化、移动化办公，让企业沟通彻底与工作流程相融合，确保企业高效、有序运转。

企业应用接入指南

Step1：创建企业

1、打开云桥官网 https://yunqiao.cn ，点击账号注册；（已经注册跳过此步骤）

2、填写注册人手机号和基本信息完成注册过程

3、登录客户端，点击企业通讯录-创建企业，输入企业名称即可创建企业

4、登录企业管理后台开始添加员工账号

你可以通过三种方式添加员工：

①单个添加员工

②批量导入大量员工

③通过邀请链接或二维码的方式邀请员工加入企业

Step2：添加应用

1、在企业管理后台应用管理页面添加新应用

2、进入创建应用页面，按步骤填写信息，点击确定后可以新增微应用

应用LOGO：应用图标会展示在客户端，支持JPG/PNG/BMP/GIF格式，1M以内

应用名称：应用名称会展示在PC客户端和移动端应用tab，20个字以内

功能介绍：介绍该应用的主要功能和作用，50个字符内

首页地址：云桥客户端点击该应用时的跳转URL地址

后台地址：云桥企业管理后台点击该应用时跳转的URL地址

提示：应用添加后，新应用待云桥审核通过后方能正常使用

3、添加成功并通过云桥审核后，在企业管理后台企业该应用，员工可以在电脑或手机端应用界面看到新建的应用，通过启动该应用即可访问相应的应用页面开始使用。

如果需要实现免登服务、发送应用通知消息、获取员工及部门结构等信息，请参考接入应用内容

Step3：接入应用

1、获取开发授权码

1）进入应用编辑页面

2）获取接口授权码，需提交开发者资料。申请开启开发模式并认真填写，待云桥官方联系您审核过后，即可获取API接口授权码。

3）成功启用授权码，企业自建应用具备调用云桥平台提供的开放接口的功能。

2、开发应用

详见开发应用文档

3、调试应用

对企业自建应用和云桥进行调试，保障连通无误，详见调试工具

开发应用

建立连接

作为企业应用的开发者，你可以使用以下方式连接你开发的企业应用和云桥平台:
企业应用调用云桥平台提供的接口，查询或操作云桥平台所管理的资源，给成员发送消息等，以下称主动调用模式。

主动调用

1、访问云桥接口需使用HTTPS协议、JSON数据格式、UTF8编码，访问域名为https://api.yunqiao.cn。

2、POST请求需在HTTP Header中设置 Content-Type为application/json，否则接口调用失败。

主动调用云桥接口，开发者可按照以下步骤完成：

填写服务器配置

登录云桥企业后台，在应用管理页面，点击应用的编辑按钮，填写IP白名单。
IP白名单为该企业应用调用云桥接口的合法IP列表，多个IP请以“,”隔开，如果IP有变化，请立即更新。

获取AppToken

1、app_token是企业应用身份的唯一标志，当企业应用调用云桥平台接口时，需带上app_token，云桥平台会根据此次访问的app_token，校验访问的合法性并返回相应的结果。
2、正常情况下app_token有效期为2小时，有效期内多次获取返回相同结果并自动重置为2小时。

app_token可以通过以下接口获取：
https请求方式:Post
请求URL:https://host:port/get_app_token

请求参数说明:

参数
类型
必须
说明

acct
int
是
开发者账号

psword
string
是
开发者密码

app_type
int
是
应用类型

本接口参数可在企业后台->更多->应用管理界面中在第三方应用编辑页面中查看。

请求参数样例:

{
	"acct": 10086, 
	"psword": "psword",
	"app_type": 131474
}

返回参数说明：

参数
类型
说明

result
int
返回码

app_token
string
应用token

返回参数样例:
成功样例:

{
	"result": 0,
	"app_token": "THRXTyUetJVEh16DRn5V"
}

demo下载

为了验证调用者的合法性，云桥接口增加了消息体签名，开发者需按照消息体签名中指定的格式，封装好请求参数调用接口，包括上述获取app_token的接口。

消息体签名

需要开发者在企业后台的应用编辑页面查看sig_token，用于生成消息体签名，签名以参数signature标识。

主动调用云桥接口需按照以下格式封装好请求内容：

参数
类型
必须
说明

timestamp
string
是
当前unix时间戳

nonce
string
是
16位随机字符串

content
string
是
请求内容，字典类型的对象经json序列化获得的字符串

signature
string
是
消息体签名

云桥平台会根据此次请求的参数，计算出对应的signature ，与请求中的signature 相比较，相等则表示验证通过。对于签名不匹配的请求，云桥平台将返回对应的返回码。
signature计算方法：

signature = sha1（sort(sig_token, timestamp, nonce, content))。
sort的含义是将参数按照字典序排序，然后从小到大拼接成一个字符串。

content的具体格式参考每个接口的请求参数说明。
文档仅列出了请求参数样例content参数内容，需要开发者自行补齐消息体签名的格式内容。

demo下载

例如：
开发者请求云桥平台提供的接口为https://api.yunqiao.cn/get_app_token
在企业后台的应用编辑页面获取到的app_type为10086，sig_token为'123456'

请求参数要求：

参数
类型
必须
说明

acct
int
是
开发者账号

psword
string
是
开发者密码

app_type
int
是
应用类型

则请求内容为:

{
	"acct": 'acct', 
	"psword": 'psword',
	"app_type": 10086
}

content为经json序列化获得的字符串"{'acct': 'acct', 'app_type': 10086, 'psword': 'psword'}"
计算signature得到'8a0e26b0b622c32ebc837dc493b5c2b806f732c2'

则开发者传给云桥平台的数据格式为：

{
	"nonce": "23ialsu90ujdqi01ik3wdfk", 
	"timestamp": 1466588281,
	"content": "{'acct': 'acct', 'app_type': 10086, 'psword': 'psword'}",
	"signature": "8a0e26b0b622c32ebc837dc493b5c2b806f732c2"
}

云桥平台返回结果的数据格式为：

{
	"result": 0, 
	"desc": "success",
	"app_token": "app_token"
}

以上完整的主动调用流程图为：

接口限制

1、频率限制
为了防止企业应用的程序错误而引发云桥服务器负载异常，默认情况下，每个企业应用调用接口都有一定的频率限制，当超过此限制时，调用对应接口会收到相应返回码。
以下是当前默认的频率限制，云桥平台可能会根据运营情况调整此阈值：

·基础频率
每个IP调用的业务接口频率不可超过100000次/小时

·消息频率
对每个企业调用的业务接口频率不可超过30000次/小时

2、请求数限制
限定最大请求数为100，在前100个请求云桥平台未返回结果之前，拒绝之后的所有请求。

3、POST主体限制
限制10M，超过限制长度云桥台平台将拒绝该请求。

全局返回码

每次调用接口时，都会获取全局返回码和错误描述，企业应用可以根据该信息进行调试接口，排查问题。
约定全局返回码字段为"result",错误描述字段为"desc"。每个接口均会返回这两个值，其他字段仅在result=0，即接口调用成功时才有效。
更新时间：2016-05-05 14:49
详见全局返回码

免登服务

企业应用通过以下步骤，可以使用用户账号登录自有的系统，并获取用户的个人及企业数据。

获取免登授权码

1）获取客户端免登授权码CODE

用户点击云桥客户端上的该应用，由云桥平台生成客户端免登授权码CODE，并在企业应用提供的主页URL后边拼接上参数CODE返回给云桥客户端。
例如企业应用提供的主页URL为http://api.yunqiao.cn/login
则云桥客户端访问的地址为http://api.yunqiao.cn/login?code=xxxxxx

2）获取企业后台免登授权码CODE

管理员登录企业后台，在应用管理页面点击该应用的"进入后台"，由云桥平台生成企业后台免登授权码CODE，并在企业应用提供的后台URL后边拼接上参数CODE返回，前端访问该地址。
例如企业应用提供的后台URL为http://api.yunqiao.cn/background_login
则前端访问的地址为http://api.yunqiao.cn/background_login?code=xxxxxx

根据免登授权码获取用户身份

企业应用收到免登授权码后，通过本API即可用免登授权码获取登录用户的信息。

1）通过客户端免登授权码CODE换取身份信息

https请求方式:POST
请求URL:https://host:port/client_login_info

请求参数说明：

参数
类型
必须
说明

app_token
string
是
应用token

code
string
是
免登授权码

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"code": "YvqBpTPuzk12uzJet3tv"
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

digitid
string
云桥ID

company_id
int
企业ID

nick
string
昵称

cellphone
string
绑定手机号

name
string
姓名

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"digitid": "17316",
	"company_id": 7555,
	"nick": "客户端昵称Zero",
	"cellphone": "13570233000",
	"name": "姓名"
}

2）通过企业后台免登授权码CODE换取身份信息

https请求方式:POST
请求URL:https://host:port/web_login_info

请求参数说明：

参数
类型
必须
说明

app_token
string
是
应用token

code
string
是
免登授权码

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"code": "YvqBpTPuzk12uzJet3tv"
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

digitid
string
云桥ID

company_id
int
企业ID

is_admin
int
是否管理员(0:否 1:是)

nick
string
昵称

cellphone
string
绑定手机号

name
string
姓名

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"digitid": "17316",
	"company_id": 7555,
	"is_admin": 1,
	"nick": "客户端昵称Zero",
	"cellphone": "13570233000",
	"name": "姓名"
}

以上完整的免登流程图为：

通过CODE获取用户身份会有一定的时间开销。对于频繁获取用户身份的场景，建议采用如下方案：

·用户跳转到企业应用页面时，企业应用校验是否有代表用户身份的cookie，此cookie由企业应用生成

·如果没有获取到cookie，调用身份验证接口，获取用户身份后，由企业应用生成代表用户身份的cookie

·根据cookie获取用户身份，进入相应的页面

云桥平台会在给应用发送的url里面提供扩展参数，以便于第三方实现版本控制等额外需求。

扩展参数说明：

参数
类型
说明

equipment
string
平台,取值pc、ios、android

ver
string
客户端版本

管理多媒体文件

在调用其他接口时，对涉及多媒体文件的获取和调用等操作，是通过media_id来进行的。

上传媒体文件

该API用于上传图片、语音等媒体资源文件以及普通文件，接口返回媒体文件的标识ID：media_id。
需注意，使用multipart/from-data上传媒体文件，返回的media_id是可复用的，且仅限制于上传该文件的应用可访问。
https请求方式:POST
请求URL:https://host:port/upload_media?app_token=APP_TOKEN&type=TYPE

请求参数说明:

参数
类型
必须
说明

app_token
string
是
APP_TOKEN

type
string
是
媒体文件类型，固定为image

media
string
是
Multipart/form-data
中媒体文件标识，有
filename、filelength、content-type等信息

上传的媒体文件限制
· 图片：1MB，支持JPG、PNG、GIF格式

demo下载

返回参数说明：

参数
类型
说明

result
int
返回码

desc
string
描述

media_id
int
媒体ID

upload_time
int
上传时间

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"media_id": 1,
	"upload_time": 1481253905
}

消息接口

发送单人消息

该API用于发送消息到指定的用户。
https请求方式:POST
请求URL:https://host:port/send_single_msg

请求参数说明:

参数
类型
必须
说明

sender
string
是
发送ID(云桥ID)

reader
string
是
接收ID(云桥ID)

msg_type
int
是
消息类型（0:纯文本 1:图片）

msg
string
是
消息

发送纯文本

{
	"msg_type":   int    消息类型，固定为0
	"msg":    string    纯文本
}

发送图片

{
	"msg_type":   int    消息类型，固定为1
	"msg":    string    媒体ID，多个ID用","隔开，上限为10张图片
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success"
}

发送普通群消息

该API用于发送消息到指定的普通群。
https请求方式:POST
请求URL:https://host:port/send_group_msg

请求参数说明:

参数
类型
必须
说明

sender
string
是
发送ID(云桥ID)

reader
int
是
接收ID(普通群ID)

company_id
int
是
企业ID

msg_type
int
是
消息类型（0:纯文本 1:图片）

msg
string
是
消息

发送纯文本

{
	"msg_type":   int    消息类型，固定为0
	"msg":    string    纯文本
}

发送图片

{
	"msg_type":   int    消息类型，固定为1
	"msg":    string    媒体ID，多个ID用","隔开，上限为10张图片
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success"
}

发送部门消息

该API用于发送消息到指定的部门。
https请求方式:POST 请求URL:https://host:port/send_branch_msg

请求参数说明:

参数
类型
必须
说明

sender
string
是
发送ID(云桥ID)

reader
int
是
部门群ID（咨询客服查询）

msg_type
int
是
消息类型（0:纯文本 1:图片）

msg
string
是
消息

company_id
int
是
企业ID

发送纯文本

{
	"msg_type":   int    消息类型，固定为0
	"msg":    string    纯文本
}

发送图片

{
	"msg_type":   int    消息类型，固定为1
	"msg":    string    媒体ID，多个ID用","隔开，上限为10张图片
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success"
}

发送应用消息

该API用于发送应用消息给指定的用户，客户端根据选定的模版将该消息显示在办公助手中。
https请求方式:POST 请求URL:https://host:port/send_app_msg

请求参数说明:

参数
类型
必须
说明

readers
list
是
接收id列表

msg
dict
是
应用消息

readers中元素为string类型的云桥ID，目前最多支持500人，如需发送超过限定人数的应用消息，可分多次调用本接口。

msg格式：

{
	"head":      #dict类型，为标题区
	"body" :      #dict类型，为内容区
	"buttons" :    #list类型，为按钮区
	"content_event" : #dict类型，移动端点击内容区触发事件
}

1.head标题区:

参数
类型
说明

title
str
标题内容

max_line
int
标题最大行数，范围以外显示...

{
	"title" :      "默认标题",
	"max_line" :      1
}

对应：

2.body内容区:

参数
类型
说明

content
list
内容控件列表。子项为dict格式的控件

max_content_length
int
内容控件最大行数，范围以外显示...

提供以下内容控件,均为dict类型：

a.纯文本行

{
	"type" : 1 ,      "#固定为1"
	"data" :"纯文本行",    #文本内容
	"max_line": 2       #内容最大行数，范围以外显示...
}

对应下图红框区域：

b.表单行

{
	"type" : 2 ,        #固定为2
	"data" :{
		"key" : {
			"data": "表单标题文本"  #表单标题
		} ,
		"value": {
			"data": "表单内容文本"  #表单内容
			}

	}
}

对应下图红框区域：

c.列表行

{
	"type": 3,					#固定为3
	"data": {
		"content": [],		#列表内内容集合，格式同本节所述content，可递归解析，但不再含有type=3的列表行
		"max_content": 1	#列表最大行数，范围以外显示...
	}
}

例如想创建一个列表最大行数为1行的审批表单，那么数据格式为：

{
	"type": 3,
	"data": {
	"content": [
			{
			"type": 2,
			"data": {
				"key": {
					"data": "表单标题文本1"
				},
				"value": {
					"data": "表单内容文本1"
				}
				}
			},
			{
				"type": 2,
				"data": {
					"key": {
						"data": "表单标题文本2"
					},
					"value": {
						"data": "表单内容文本2"
					}
				}
			}
	],
	"max_content": 1
	}
}

对应下图红框区域：

3.buttons按钮区:

提供以下内容控件,均为dict类型:

a.打开应用

{
	"type": 0,					#固定为0
	"title"："查看详情"			#按键名称
	"data": "&status=1&id=1"	#打开应用时在应用提供的主页URL末尾拼接的参数
	"id": 	"btnCheckDetail"	#按钮ID。开发者填写，确保在本消息样式里唯一即可。
}

当用户点击"查看详情"按钮时，此时触发免登事件，云桥平台在企业应用提供的主页URL后边拼接上参数code=免登授权码及字符串data返回，云桥客户端将尝试访问该URL。例如企业后台提供的主页URL为"http://api.yunqiao.cn/login",data字段为"&status=1&id=1"，则云桥客户端访问的地址为"http://api.yunqiao.cn/login?code=xxxxxx&status=1&id=1"

对应：

b.通过浏览器打开url

{
	"type": 1,						#固定为1
	"title": "打开百度",				#按键名称
	"data": "http://baidu.com",	#访问的URL
	"id": 	"btnOpenBaidu"			#按钮ID。开发者填写，确保在本消息样式里唯一即可。
}

对应下图红框区域：

c.下拉按键

{
	"type": 3,						#固定为2
	"title": "更多",					#按键名称
	"data": {
		"buttons": []			#按键集合，格式同本节所述buttons，可递归解析，其中不会再含有type=3的下拉按键
	},
	"id": 	"btnCheckMore"			#按钮ID。用于控制按钮的状态变化
}

示例:

{
	"type": 3,
	"title": "更多[下列选项]",
	"data": {
		"buttons": [
			{
			"type": 2,
			"title": "还原",
			"data": {
				"url":	"/api/interface.html",
				"data": {
					"test": 10000,
				}
			},
			"id": 	"btnRecover"	
			}
		]
	},
	"id": 	"btnCheckMore"
}

对应：

4.content_event:

移动端点击内容区触发事件，触发原理跟按钮一致

参数
类型
说明

type
int
同buttons的type

data
同buttons的type对应的data

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success"
}

用户信息接口

获取好友列表

该API用于获取操作者的好友列表
https请求方式:POST
请求URL:https://host:port/get_user_friends

请求参数说明:

参数
类型
必须
说明

operator
string
是
操作者(云桥ID)

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"operator": "3145299"
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

friends
list
好友信息

friends结构:

[
		{
			"fgid"			int		    分组ID
			"fgname"		string		分组名
			"fgmembers":[
				[
					digitid, 			string	    好友云桥ID
					name, 				string	    好友名
					company_id			int		    好友企业ID
				],
				...
			]
		},
		...
]

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"friends":[
		{
			"fgid":101,
			"fgname": "常用联系人",
			"fgmembers": [
                [
                    "7982482", 
                    "test10001", 
                    7555
                ], 
                [
                    "4675519", 
                    "email1231234", 
                    7555
                ]
            ]
		},
		{
            "fgid": 102, 
            "fgname": "陌生人", 
            "fgmembers": [
                [
                    "59944", 
                    "robot_YqVIo", 
                    7555
                ]
            ]
        }
	]
}

获取群组列表

该API用于获取操作者的普通群列表
https请求方式:POST
请求URL:https://host:port/get_user_groups

请求参数说明:

参数
类型
必须
说明

operator
string
是
操作者(云桥ID)

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"operator": "3145299"
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

groups
list
普通群信息

groups结构:

[
		{
			"gid"		int		普通群ID
			"name"	  string	群名
		},
		...
]

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"groups":[
		{
			"gid":5000769,
			"name": "123123"
		},
		{
            "gid": 5001283, 
            "name": "qqqqqqqqqqqqqqqqqqqq"
        },
		{
            "gid": 5001317, 
            "name": "12345"
        }
	]
}

获取企业通讯录

该API用于获取操作者的企业通讯录数据。企业通讯录的显示规则区别于获取部门可见成员列表接口，仅返回每个部门所属成员列表，且返回结果跟企业后台的隐私安全设置中的企业通讯录管理设置相关。本接口用于一次性加载完企业通讯录，附加index位置参数，需开发者自行排序。为避免下发过多数据，推荐用以下两个接口代替：先获取企业通讯录部门列表、再根据部门ID获取企业通讯录架构部门信息。
https请求方式:POST
请求URL:https://host:port/get_contact_book

请求参数说明:

参数
类型
必须
说明

operator
string
是
操作者(云桥ID)

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"operator": "3145299"
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

company_stringuct
list
可见的企业架构

branch_id
int
部门ID

branch_name
string
部门名

parent_id
int
父部门ID

index
int
位置序号

admin_list
list
管理员列表

common_list
list
普通成员列表

digitid
string
云桥ID

company_stringuct:

[
	{
		branch_id		 int		部门ID
		branch_name		 string	    部门名
		parent_id		 int		父部门ID，该ID为0时代表部门branch_id为总部
		index			 int		位置序号，各父部门下的同一层子部门位置序号独立递增
		admin_list		 list		管理员列表
		common_list		 list		普通成员列表
	},
	...
]

admin_list:

[
	{
		"digitid"		string   	管理员云桥ID
		"name"		    string	    用户名
		"index"		    int		    位置序号,每个部门下的员工位置序号独立递增
	},
	...
]

common_list:

[
	{
		"digitid"		string			普通成员云桥ID
		"name"			string			用户名
		"index"			int				位置序号,每个部门下的员工位置序号独立递增
	},
	...
]

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"company_stringuct": [
		{
			"branch_id": 19395,
			"parent_id": 1246,
			"index": 28,
			"admin_list": [],
			"branch_name": "研发部",
			"common_list": [
				{
					"digitid": "3145299",
					"name": "xjz",
					"index": 1
				}
			]
		},
		{
			"branch_id": 1246,
			"branch_name": "Zero",
			"parent_id": 0,
			"index": 1,
			"admin_list": [],
			"common_list": []
		}
	]
}

获取企业通讯录部门列表

该API用于获取操作者的企业通讯录的部门列表。
https请求方式:POST
请求URL:https://host:port/get_contact_book_stringuct

请求参数说明:

参数
类型
必须
说明

operator
string
是
操作者(云桥ID)

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"operator": "17316"
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

company_stringuct
list
可见的企业架构

company_stringuct：可见的企业架构列表，返回值跟企业后台隐私设置相关，若关闭则为空

定义部门结构unit:{
		"branch_id"		int			部门ID
		"branch_name"	string		部门名
		"sub_branchs"	list		子部门unit列表
	}

company_stringuct结构为

	[
		unit,
		...
	]

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"company_stringuct": {
			"branch_id": 19395,
			"branch_name": "总部",
			"sub_branchs": [
				{
					"branch_id": 19396, 
					"branch_name": "技术部", 
					"sub_branchs": [ ]
				},
				{
					"branch_id": 19397, 
					"branch_name": "运营部", 
					"sub_branchs": [ ]
       	   }
			]
		}
}

获取企业通讯录部门信息

该API用于获取操作者的企业通讯录的部门信息。
https请求方式:POST
请求URL:https://host:port/get_contact_book_members

请求参数说明:

参数
类型
必须
说明

operator
string
是
操作者(云桥ID)

branch_id
int
是
部门ID

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"operator": "17316",
	"branch_id": 1246
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

members
list
部门成员列表

members：部门成员列表，返回值跟企业后台隐私设置相关，若关闭则为空
members结构为

[
	{
		digitid		string	   云桥ID
		nick		string	   昵称
	},
	...
]

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"members": [
		{
			"nick": "test305", 
			"digitid": "5842712"
		},
		{
			"nick": "test307", 
			"digitid": "3145299"
		}
	]
}

企业接口

获取企业信息

该API用于获取企业详细信息。
https请求方式:POST
请求URL:https://host:port/company_info

请求参数说明:

参数
类型
必须
说明

company_id
int
否
企业ID(默认本企业)

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V"
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

company_id
int
企业ID

name
string
企业名

website
string
企业网站

logo
string
企业logo

fax
string
传真

tele
string
电话

email
string
邮箱

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"company_id": 7555,
	"name": "Zero",
	"website": "",
	"logo": "https://ip:port/image_upload/OUTER/pp/150514/10001/3055==.png",
	"fax": "",
	"tele": "",
	"email": ""
}

员工接口

获取在职员工列表

该API用于获取企业在职员工列表。
https请求方式:POST
请求URL:https://host:port/get_valid_staff

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 7555
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

staffs
list
员工列表

staffs结构为:

[
	{			
		digitid			string		云桥ID
		branch_ids		list		部门ID列表
		cellphone		string		绑定手机
		name			string		姓名
		reg_time		int			注册时间
		lock_status		int			成员的冻结状态（0：正常；1：冻结）
		status			int			成员状态（0：正常；1：未审核）
		activate		int			是否激活（0：未激活1：已激活）
	},
	...
]

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"staffs": [
		{
			"status":0,
			"cellphone": "13570233031", 
			"reg_time": 1461656648,
			"activate": 0,
			"name": "123",
			"branch_ids": [
				1246
			],			 
			"lock_status": 0, 
			"digitid": "8000160"
		}, 
		{
			"status":0,
			"cellphone": "", 
			"reg_time": 1438847572, 
			"activate": 1, 
			"name": "test10001", 
			"branch_ids": [
				1246
			], 
			"lock_status": 0, 
			"digitid": "7982482"
		},
		...
	]
}

获取离职员工列表

该API用于获取企业离职员工列表。
https请求方式:POST
请求URL:https://host:port/get_leavel_staff

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 7555
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

staffs
list
员工列表

staffs结构为:

[
	{			
		digitid			string		云桥ID
		branch_ids		list		部门ID列表
		cellphone		string		绑定手机
		name			string		姓名
		reg_time		int			注册时间
		leave_time		int			离职时间
		lock_status		int			成员的冻结状态（0：正常；1：冻结）
		activate		int			是否激活（0：未激活1：已激活）
	},
	...
]

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"staffs": [
		{
			"cellphone": "", 
			"reg_time": 1436162010, 
			"activate": 1, 
			"name": "pacadd1", 
			"branch_ids": [
				1246
			], 
			"lock_status": 0, 
			"digitid": "6841572", 
			"leave_time": 1453172196
		}, 
		{
			"cellphone": "", 
			"reg_time": 1447762240, 
			"activate": 0, 
			"name": "待删除", 
			"branch_ids": [
				8250
			], 
			"lock_status": 0, 
			"digitid": "4220999", 
			"leave_time": 1453172196
		},
		...
	]
}

获取员工信息

该API用于获取单个员工信息。
https请求方式:POST
请求URL:https://host:port/staff_info

请求参数说明:

参数
类型
必须
说明

digitid
string
是
云桥ID

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"digitid": "17316"
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

info
dict
详细信息

digitid
string
云桥ID

company_id
int
企业ID

branch_ids
list
所属部门ID列表

nick
string
昵称

name
string
姓名

sex
int
性别(0:未选择1:男2:女)

birth
int
生日(Unix时间戳)

email
string
邮箱

cellphone
string
绑定手机号

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"info": {
		"digitid":"17316",
		"company_id":7555,
		"branch_ids":[1251],
		"nick":"admin",
		"name":"admin",
		"sex":2,
		"birth":0,
		"email":"",
		"cellphone":"18666666611"
	}
}

批量获取员工信息(简略)

该API用于批量获取员工的简略信息，仅返回存在的员工信息。
https请求方式:POST
请求URL:https://host:port/staff_infos_simple

请求参数说明:

参数
类型
必须
说明

digitids
list
是
云桥ID列表

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"digitids": ["17316", "59944"]
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

info
list
详细信息

digitid
string
云桥ID

company_id
int
企业ID

branch_ids
list
所属部门ID列表

nick
string
昵称

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"info": [
		{
			"digitid":"17316",
			"company_id":7555,
			"branch_ids":[1251],
			"nick":"admin"
		},
		{
			"digitid":"59944",
			"company_id":7555,
			"branch_ids":[1251],
			"nick":"who"
		}
	]
}

批量获取员工信息(详细)

该API用于批量获取员工的详细信息，仅返回存在的员工信息。
https请求方式:POST
请求URL:https://host:port/staff_infos_detail

请求参数说明:

参数
类型
必须
说明

digitids
list
是
云桥ID列表

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"digitids": ["17316", "59944"]
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

info
list
详细信息

digitid
string
云桥ID

company_id
int
企业ID

branch_ids
list
所属部门ID列表

nick
string
昵称

name
string
姓名

sex
int
性别(0:未选择1:男2:女)

birth
int
生日(Unix时间戳)

email
string
邮箱

cellphone
string
绑定手机号

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"info": [
		{
			"digitid":"17316",
			"company_id":7555,
			"branch_ids":[1251],
			"nick":"admin",
			"name":"admin",
			"sex":2,
			"birth":0,
			"email":"",
			"cellphone":"18666666611"
		},
		{
			"digitid":"59944",
			"company_id":7555,
			"branch_ids":[1251],
			"nick":"who",
			"name":"who",
			"sex":2,
			"birth":0,
			"email":"",
			"cellphone":"186661232611"
		}
	]
}

部门接口

获取部门信息

该API用于获取单个部门的详细信息。
https请求方式:POST
请求URL:https://host:port/branch_info

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

branch_id
int
是
部门ID（联系云桥客服获取）

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 4061,
	"branch_id": 272
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

info
dict
详细信息

branch_id
int
部门ID

name
string
部门名称

address
string
部门地址

tele
string
部门电话

fax
string
部门传真

intro
string
部门简介

parent_id
int
父部门ID

index
int
位置序号

位置序号代表父部门下的位置，各父部门下的同一层子部门位置序号独立递增，若父部门ID为0，则代表该部门为总部。
返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"info": {
		"branch_id":1246,
		"fax":"",
		"intro":"",
		"tele":"",
		"name":"Zero",
		"parent_id":0,
		"address":"",
		"index":1
	}
}

批量获取部门信息(简略)

该API用于批量获取部门的简略信息，仅返回存在的部门信息。
https请求方式:POST
请求URL:https://host:port/branch_infos_simple

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

branch_ids
list
是
该企业下的部门ID列表

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 4061,
	"branch_ids": [272, 1246]
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

info
list
详细信息

branch_id
int
部门ID

name
string
部门名称

parent_id
int
父部门ID

index
int
位置序号

位置序号代表父部门下的位置，各父部门下的同一层子部门位置序号独立递增，若父部门ID为0，则代表该部门为总部。
返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"info": [
		{
			"branch_id":1246,
			"name":"Zero",
			"parent_id":0,
			"index":1
		},
		{
			"branch_id":272,
			"name":"Who",
			"parent_id":1246,
			"index":1
		}
	]
}

批量获取部门信息(详细)

该API用于批量获取部门的详细信息。
https请求方式:POST
请求URL:https://host:port/branch_infos_detail

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

branch_ids
list
是
该企业下的部门ID列表

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 4061,
	"branch_ids": [272, 1246]
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

info
list
详细信息

branch_id
int
部门ID

name
string
部门名称

address
string
部门地址

tele
string
部门电话

fax
string
部门传真

intro
string
部门简介

parent_id
int
父部门ID

index
int
位置序号

位置序号代表父部门下的位置，各父部门下的同一层子部门位置序号独立递增，若父部门ID为0，则代表该部门为总部。
返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"info": [
		{
			"branch_id":1246,
			"fax":"",
			"intro":"",
			"tele":"",
			"name":"Zero",
			"parent_id":0,
			"address":"",
			"index":1
		},
		{
			"branch_id":272,
			"fax":"",
			"intro":"",
			"tele":"",
			"name":"Who",
			"parent_id":1246,
			"address":"",
			"index":1
		}
	]
}

获取部门所属成员列表

该API用于获取部门的所属成员列表。部门的可见成员列表由该部门的所有成员组成，不包括上级部门及下级部门的成员信息。
https请求方式:POST
请求URL:https://host:port/branch_user_list

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

branch_id
int
是
部门ID

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 4061,
	"branch_id": 272
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

admins
list
管理员列表

members
list
普通成员列表

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"admins": ['10439', '12064', '78191', '5302010', '45036'],
	"members": ['9271408', '9367254', '49524', '3566605', '861387', '352052', '462781', '825393']
}

获取部门可见成员列表

该API用于获取部门的可见成员列表。部门的可见成员列表由该部门所有成员，以及上级部门负责人、下级部门所有成员组成。
https请求方式:POST
请求URL:https://host:port/branch_user_visiblelist

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

branch_id
int
是
部门ID

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 4061,
	"branch_id": 272
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

admins
list
管理员列表(上级部门负责人+本部门负责人)

members
list
普通成员列表(本部门普通成员+下级部门所有成员)

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"admins": ['10439', '12064', '78191', '5302010', '45036'],
	"members": ['9271408', '9367254', '49524', '3566605', '928097', '352052', '462781', '825393']
}

根据company_id 获取企业下的所有部门名称以及部门ID

该API用于获取企业下属部门的ID和名称
https请求方式:POST
请求URL: https://host:port/get_branch_by_company_id

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

请求参数样例:

{
"app_token": "THRXTyUetJVEh16DRn5V",
"company_id": 4061,
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

id
int
部门id

name
string
部门名称

返回参数样例:
成功样例:

{
	info: [
   { id: 1047, name: '胡萝卜烧烤公司' },
   { id: 1048, name: '市场部' },
   { id: 1049, name: '财务部' },
   { id: 1050, name: '研发部' },
   { id: 1051, name: '行政部' },
   { id: 1052, name: '第一部门' },
   { id: 1054, name: '开发2' },
   { id: 1055, name: '开发组' },
   { id: 1056, name: '开发组02' },
   { id: 1057, name: '开发组03' }
   ],
   result: 0, //返回码
   desc: 'success' //描述
}

根据company_id 部门名称获取部门ID

该API用于根据部门名称获取部门的ID
https请求方式:POST
请求URL:https://host:port/get_branch_by_branch_name

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

branch_name
int
是
部门名称

请求参数样例:

{
"app_token": "THRXTyUetJVEh16DRn5V",
"company_id": 4061,
"branch_name":"烤串" 
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

info
object
详细信息

id
int
部门id

name
string
部门名称

返回参数样例:
成功样例:

{ 
	
	info: { id: 1051, name: '行政部' }, 
	result: 0, 
	desc: 'success' 
}

普通群接口

获取普通群列表

该API用于获取企业的普通群列表。
https请求方式:POST
请求URL:https://host:port/get_group_list

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 7555
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

groups
list
普通群列表

groups结构：

[
	{
		"gid"     int     群ID,
		"name"     sting     群名
	},
	...
]

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"groups": [
		{
			"gid": 5000769, 
			"name": "123123"
		},
		{
			"gid": 5000848, 
			"name": "123"
		},
		{
			"gid": 5000974, 
			"name": "43434"
		},
		...
	]
}

获取普通群信息

该API用于获取单个普通群的详细信息。
https请求方式:POST
请求URL:https://host:port/group_info

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

gid
int
是
普通群ID

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 7555,
	"gid": 5001108
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

info
dict
详细信息

gid
int
群ID

name
string
群名称

open_flag
int
群公开属性

join_condition
int
入群选项(0:允许任何人1:需要身份验证2:不允许任何人)

note
string
群公告

create_time
int
创建时间(Unix时间戳)

delete_time
int
解散时间(Unix时间戳)

num
int
群人数

status
int
状态(0:正常1:解散)

lock_status
int
冻结状态(0:正常 1:冻结)

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"info": {
		"gid":5001108,
		"note":"",
		"open_flag":1,
		"name":"发发多个",
		"create_time":1434351076,
		"delete_time":1466076033,
		"join_condition":1,
		"num":2,
		"status":0,
		"lock_status":0
	}
}

批量获取普通群信息(简略)

该API用于批量获取普通群的简略信息，仅返回存在的普通群信息。
https请求方式:POST
请求URL:https://host:port/group_info_simple

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

gids
list
是
该企业下的普通群ID列表

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 7555,
	"gids": [5001283, 5001108]
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

info
list
详细信息

gid
int
群ID

name
string
群名称

num
int
群人数

status
int
状态(0:正常1:解散)

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"info": [
		{
			"gid":5001283,
			"name":"发发多个",
			"num":2,
			"status":0
		},
		{
			"gid":5001108,
			"name":"132123",
			"num":2,
			"status":0
		}
	]
}

批量获取普通群消息(详细)

该API用于批量获取普通群的详细信息，仅返回存在的普通群信息。
https请求方式:POST
请求URL:https://host:port/group_info_detail

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

gids
list
是
该企业下的普通群ID列表

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 7555,
	"gids": [5001283, 5001011]
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

info
list
详细信息

gid
int
群ID

name
string
群名称

open_flag
int
群公开属性

join_condition
int
入群选项(0:允许任何人1:需要身份验证2:不允许任何人)

note
string
群公告

create_time
int
创建时间(Unix时间戳)

delete_time
int
解散时间(Unix时间戳)

num
int
群人数

status
int
状态(0:正常1:解散)

lock_status
int
冻结状态(0:正常 1:冻结)

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"info": [
		{
			"gid":5001283,
			"note":"",
			"open_flag":1,
			"name":"发发多个",
			"create_time":1434351076,
			"delete_time":0,
			"join_condition":1,
			"num":2,
			"status":0,
			"lock_status":0
		},
		{
			"gid":5001108,
			"note":"",
			"open_flag":1,
			"name":"132123",
			"create_time":1434351076,
			"delete_time":0,
			"join_condition":1,
			"num":2,
			"status":0,
			"lock_status":0
		}
	]
}

获取普通群成员列表

该API用于获取普通群的成员列表。
https请求方式:POST
请求URL:https://host:port/group_user_list

请求参数说明:

参数
类型
必须
说明

company_id
int
是
企业ID

gid
int
是
普通群ID

请求参数样例:

{
	"app_token": "THRXTyUetJVEh16DRn5V",
	"company_id": 7555,
	"gid": 5001283
}

返回参数说明:

参数
类型
说明

result
int
返回码

desc
string
描述

owner
string
群主

admins
list
管理员列表

members
list
普通成员列表

返回参数样例:
成功样例:

{
	"result": 0,
	"desc": "success",
	"owner": "61820",
	"admin_list": ["5501969"],
	"common_list":  ["61820", "5501969", "8729922", "9541543"]
}

调试工具

应用开发完毕后，通过云桥官方提供的调试工具来调用API接口，输入对应参数进行测试，以此来检测自建应用调用云桥提供的开放接口是否成功。

进入调试工具

demo下载

demo下载

全局返回码说明

每次调用接口时，可能获得错误的返回码，企业应用可以根据返回返回码的信息调试接口，排查错误。

全局返回码说明如下：

返回码
说明

0
成功

1
服务器错误

2
路由项不存在

3
请求超时

4
请求过于频繁

5
请求被屏蔽

6
尝试次数达到上限

8
绑定手机失败

9
绑定邮箱失败

10
绑定手机、邮箱失败

11
用户为GM

12
无权限访问

100
企业不存在

101
企业被冻结

101
企业被冻结

102
企业未激活

103
企业已被删除

104
职位不存在

105
重复权限名

106
无法编辑超级管理员权限

107
权限信息不存在

109
普通群数量达到上限

110
应用不存在

111
认证状态错误

200
用户数据不存在

201
用户数据不存在

202
用户数据不存在

203
用户已离职

204
用户已删除

205
账号不存在

206
参数错误

207
密码错误

208
账号重复

209
绑定手机重复

210
绑定邮箱重复

211
获取云桥ID失败

212
添加用户失败

213
绑定手机、邮箱重复

214
无访问权限

215
手机格式错误

216
无法编辑CEO权限

217
无法编辑CEO身份

218
无法编辑CEO部门

219
客户端消息格式不存在

220
注册企业时缺少手机号

221
用户不在监控列表中

223
UID重复

224
手机绑定数量达到上限

225
用户没有绑定手机

226
不能设置为超级管理员身份

227
用户状态错误

228
用户部门数量达到上限

300
部门不存在

301
部门中不存在该成员

302
部门已被删除

303
部门中不存在该消息发布员

304
部门已被冻结

305
本部门仅允许负责人发言

306
移动目标部门达到最大数量

307
移动目标部门下已存在同名部门

308
禁止移动部门到该部门的子部门下

309
子部门数量达到上限

310
同级部门下已有同名部门

400
普通群不存在

401
普通群已被删除

402
普通群已被解散

403
普通群已被冻结

404
普通群成员数量达到上限

405
普通群成员不存在

500
云桥邮箱注册失败

600
讨论组不存在

601
创建讨论组时人数低于下限

602
讨论组人数达到上限

603
讨论组标题过长

604
PC更新弹窗版本号重复

605
PC更新弹窗记录不存在

606
移动端引导弹窗版本号重复

607
移动端引导弹窗记录不存在

608
帮助与反馈列表记录不存在

700
应用token错误或已过期

701
应用token错误或已过期

710
上传媒体文件大小限制

711
媒体ID不存在或无权访问

720
图片消息发送媒体ID数量错误

721
免登授权码过期或错误

722
消息签名未匹配