api:callback

事件通知和跳转入口回调

与企业QQ整合进行系统整合后,第三方可能需要将组织架构数据,企业基本资料,员工基本资料,权限角色,上下级关系等与企业QQ的数据进行同步,在企业QQ侧,如上数据发生变更的时候,我们会发送通知给第三方。此回调为第三方用于接收通知的接口。

除此之外,当第三方应用需要使用到从企业QQ客户端面板点击图标跳转到自己的网站的时候,也是跳转到这个回调地址的。

请求地址

由第三方指定的一个URL,必须在公网可以访问,因为企业QQ服务器,会直接向该网址发送GET请求

该回调设置的位置,使用管理员帐号登录企业账户中心,进入【应用中心】→【开发者模式】:

请求方式

GET

请求参数

字段名称 字段类型 字段说明
notify_type_id int 更新类型:
1)企业基本信息
2)组织架构
3)员工信息
4)上下级关系发生变更
5)从客户端跳转
6)用户关闭应用
9)订单更新
notify_action_id int 动作类型:
101)企业基本信息更新
201)组织节点更新
202)新增组织节点
203)删除组织节点
301)员工基本资料修改
302)新增员工
303)删除员工
304)停用员工
305)启用员工
306)员工绑定手机
307)员工解绑手机
401)上级发生变化
402)下属发生变化
601)用户关闭应用
901)订单更新(附带参数:下表所示)
vkey string 校验请求的合法性,防止重放的一个签名,签名算法
md5(company_id + app_id + app_secret + timestamp)
第三方应用在收到回调的时候,应该使用相同算法,校验vkey的正确性,防止请求被重放或者被伪造
timestamp int 请求发起的时间戳,请参看vkey参数的签名算法,里面会用到这个值
company_id string 企业唯一标示符
open_id string 在 notify_type_id=5 的时候,有此字段,表示当前跳转进入第三方网站的员工的open_id
to_open_id string 在 notify_type_id=5 的时候,有此字段,在有些特殊的场景下,
跳转表示一个员工对另一个员工的动作时候,to_open_id表示另一个员工的open_id,
比如,在组织架构成员上右键菜单跳转时候,会传此参数,表示被右键点中的员工的open_id
hashskey string 在 notify_type_id=5 的时候,有此字段,表示open_id代表的员工,
当前的登录是否有效,可以使用/api/login/verifyhashskey来校验其有效性
object_list string 在 notify_type_id 的值为1到4的时候,有此字段,逗号分隔的id列表,
如果是组织节点更新,内容就是组织节点的id列表,如果是员工更新,
就是员工open_id的列表
returnurl string 跳转的目标key或者目标网址,在notify_type_id 为5的时候,包含此参数
hashkey string md5(company_id + app_id + app_secret),其中加号“+”为字符串连接符
该参数已经废除,因为里面不包含时间戳,容易被保存和录制

动作类型为901时,通知参数如下表所示:

字段名称 字段类型 字段说明
FCreateTime int 开通时间
FExpireTime int 过期时间
FLicense int 开通工号数
FCorpName string 企业简称
FProvince string 省份
FCity string 城市
FProductType int开通类型
1:新销售
2:续费
3:加工号
4:退费
FSalePrice string订单价格
FAgentName string经销商名

返回结果

在notify_type_id不为5,也即变更通知的时候,该回调,应该给企业QQ服务器,返回通知成功的消息,消息格式如下,
此返回主要用于帮助企业QQ服务器确认,通知已经被正确收到,否则企业QQ服务器会连续重复通知24次,每小时重试一次, 持续24小时。

字段名称 字段类型 字段说明
ret int 返回码:0 正常, >0 异常
msg string 状态信息

返回

api/callback.txt · 最后更改: 2016/04/22 17:05 (外部编辑)