服务端接口API
  1. 展现位置
  2. 发布上线
  3. 建立连接
    1. 获取access_token
  4. 通讯录管理
    1. 部门管理
      1. 获取部门详情
      2. 获取部门列表
      3. 获取部门成员
    2. 用户管理
      1. 创建用户
      2. 获取用户
    3. 分组管理
      1. 创建标签
      2. 更新标签
      3. 删除标签
      4. 添加成员
      5. 删除成员
      6. 获取成员
      7. 获取标签列表
    4. 用户别名
      1. 设置别名
      2. 解除别名
  5. 多媒体文件管理
    1. 上传多媒体文件
    2. 下载多媒体文件
  6. 发送消息
    1. 普通消息格式
      1. 文本消息
      2. 图文消息
      3. 链接消息
    2. 选择消息格式
      1. 单选消息
      2. 多选消息
      3. 获取用户反馈
  7. oauth认证
    1. 获取认证code
    2. 获取员工信息
    3. 获取二维码地址
  8. 其他接口
    1. 接入IP
  9. 运行
    1. 运行app

1.展现位置

口袋助理动支持接入H5开发的Web应用,成功通过口袋助理授权及审核后,将会在应用TAB页显示。

2.发布上线

需要上架应用,请提供应用的URL地址给口袋助理即可。

3.建立连接

获取access_token

access_token为api调用的凭证,在任何口袋助理的api调用都需要携带access_token。因此,在应用上线后,为了使用后续的api接口,需要先获取access_token。应用向口袋助理发送GET请求获取access_tocken。

GET

https://api.kd77.cn/cgi-bin/oauth/access_token?appid=21363&did=10000&secret=8732452&expire=3600

参数说明

参数

描叙

appid

第三方应用在口袋助理中的标识,应用在口袋助理注册成功后可以在应用管理中心看到。

did

公司帐号 id

secret

第三方应用在 口袋助理中的密钥,应用在口袋助理注册成功后可以在应用管理中心看到。

expire

凭证的有效期,单位秒,从凭证获取成功开始计数,经历expire秒后该凭证失效。如果expire不指定或者值为0,则凭证为永久凭证(ps:永久凭证只能最多存在一个,一旦获取新永久凭证,旧的永久凭证立即失效。而存在有效期的凭证可以同时存在多个,只有在有效期到了时候才会失效)

返回说明

正常情况下,口袋助理返回下述JSON包给第三方应用

{“result”:0,”errmsg”:”ok”, "access_token":"235acdfa61vdae1546"}

错误时,返回下述JSON包

{"result":80000013,"errmsg":"secret error"}

4.通讯录管理

部门管理

每个部门有自己的部门id标识,根部门的id标识为1.

获取部门详情

应用向口袋助理系统发送请求

GET

https://api.kd77.cn/cgi-bin/roster/department/get?access_token=234578fe23d4&department_id=32

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

department_id

部门id

返回说明

正常情况下,口袋助理系统返回下述JSON包

{
    "result":"0",
    "errmsg":"ok",
    "department":  
    {
        "id":”32”,
        "name":"moa",
        "parentid":”3”,
        “user_member”:[“7523”,”98543”],
        “sub_member”:[“56”,”39”]
    }
}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

department

部门信息

id

部门id

name

部门名称

parentid

父部门。1为根部门,根部门的父部门为0.

user_member

这个部门的直属用户userid

sub_member

这个部门的子部门department_id

获取部门列表

获取指定部门下的子部门列表。若需要获取全部部门的列表,指定department_id参数为0。 应用向口袋助理系统发送请求

GET

https://api.kd77.cn/cgi-bin/roster/department/list?access_token=234578fe23d4&department_id=1&fetch_child=0

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

department_id

需要获取子部门的列表。若不指定,默认为0。当值为0时,忽略fetch_child参数,返回所有部门的列表。当值不为0时,返回department_id指定的部门的子部门。

fetch_child

是否递归获取子部门下面的子部门

返回说明

正常情况下,口袋助理系统返回下述JSON包

{
    "result":"0",
    "errmsg":"ok",
    "departments": [ 
    {
        "id":”1”,
        "name":"/",
        "parentid":0
    },
    {
        "id":”2”,
        "name":"口袋助理研发",
        "parentid":1
    }]
}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

departments

部门列表数据

id

部门id,为1表示根部门

name

部门名称

parentid

父部门。1为根部门,根部门的父部门为0.

4.1.3 获取部门成员

应用向口袋助理系统发送请求

GET

https://api.kd77.cn/cgi-bin/roster/department/get_member?access_token=234578fe23d4&department_id=3241&fetch_child=0

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

department_id

要获取的部门id。当department_id1,并且fetch_child1时,将返回所有用户。

fetch_child

否,不指定默认为0

是否递归获取子部门的成员

返回说明

正常情况下,口袋助理系统返回下述JSON包

{
    "result":"0",
    "errmsg":"ok",
    "member": [ 
    {
        "userid":”268568”,
        "alias":”myname1”,
        "name":"张三",
    },{
        "userid":”268569”,
        "alias":”myname2”,
        "name":"李四",
    },]
}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

member

部门成员列表数据

userid

用户id

alias

应用为用户设置的别名。若有设置别名则有该字段,否则没有。

name

用户名称

4.2 用户管理

4.2.1 创建用户

应用向口袋助理系统发送请求

POST

https://api.kd77.cn/cgi-bin/roster/user/create?access_token=234578fe23d4

请求包结构体


{
    "create": [
        {
            "username": "张三",
            "account": "12345678911""sex": "男",
            "department_id": "1",
            "position": "软件工程师",
            "employee_id": "56868",
            "address": "广东省深圳市南山区科技园科发路8号金融基地2栋4楼",
            "phone": [
                {
                    "type": "MOBILE",
                    "number": "13450099718"
                },
                {
                    "type": "WORK",
                    "number": "0755-22864268"
                }
            ],
            "email": [
                {
                    "type": "WORK",
                    "number": "abc@sangfor.com.cn"
                },
                {
                    "type": "PERSON",
                    "number": "2040490@qq.com"
                }
            ],
            "extend": [
                {
                    "name": "entry_date",
                    "value": "2008-07-07"
                },
                {
                    "name": "create_time",
                    "value": "2008-07-06"
                }
            ]
        },
        {
            "username": "李四",
            "account": "12345678922""sex": "女",
            "department_id": "2",
            "position": "女",
            "employee_id": "56869",
            "address": "广东省深圳市南山区科技园科发路8号金融基地2栋4楼",
            "phone": [
                {
                    "type": "MOBILE",
                    "number": "13951199766"
                },
                {
                    "type": "WORK",
                    "number": "0755-22864290"
                }
            ],
            "email": [
                {
                    "type": "WORK",
                    "number": "def@sangfor.com.cn"
                },
                {
                    "type": "PERSON",
                    "number": "862190@qq.com"
                }
            ],
            "extend": [
                {
                    "name": "entry_date",
                    "value": "2008-07-08"
                },
                {
                    "name": "create_time",
                    "value": "2008-07-07"
                }
            ]
        }
    ]
}

4.2.2 获取用户

应用向口袋助理系统发送请求

GET

https://api.kd77.cn/cgi-bin/roster/user/get?access_token=234578fe23d4&userid=213634&alias=myname

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

userid

否,但和alias二者必须有其一

口袋助理系统中的唯一用户标识,对当前应用唯一。openid可以在启动时获取到。

alias

否,但和alias二者必须有其一

应用对用户绑定的别名,必须能够唯一索引到用户,即不同的用户不能重名。

返回说明

正常情况下,口袋助理系统返回下述JSON包

{
    "result":"0",
    "errmsg":"ok",
    "user": {
        "userid":"21364",
        "alias":"myname",
        "name":"张三",
        "account":"12345678901",
        "sex":“男”,
        "department_id": [“78”],
        "position":"软件设计师",
        "employee_id":"56868",
        "address":"广东省深圳市南山区科技园科发路8号金融基地2栋4楼",
        "phone":[{"type":"MOBILE","number":"13450099718"},{"type":””OFFICE","number":"0755-22864268"}],
        “extend”:[{“name”:”employe_id”,”value”:”56868”},{“name”:”entry_date”,”valud”:”2008-07-07”}]
    }
}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

alias

应用为用户设置的别名

userid

用户在moa中的唯一标识

name

用户名称

sex

性别

department_id

所在的部门id

position

职位

employee_id

工号

address

工作地点

email

电子邮箱

phone

电话号码。移动电话typemobile,办公电话typeofficeNumber指定号码

4.3 分组管理

引入分组是为了解决将不同部门的有同一样共性的成员归纳某个分组里面。举个例子:把各部门所有主管,可以归纳一个叫“主管”的分组。

4.3.1 创建标签

应用向口袋助理系统发送请求

POST

https://api.kd77.cn/cgi-bin/roster/tag/create?access_token=234578fe23d4

请求包结构体

{"tagname":"tag1",}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

tagname

新标签名字。

返回说明

正常情况下,口袋助理系统返回下述JSON包

{"result":"0","errmsg":"ok","tagid":”1” }

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

tagid

标签id

4.3.2 更新标签

只可以更新标签名字

应用向口袋助理系统发送请求

POST

https://api.kd77.cn/cgi-bin/roster/tag/update?access_token=234578fe23d4

请求包结构体

{“tagid”:”2”,"tagname":"tag1",}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

tagid

标签id

tagname

标签名字。

返回说明

正常情况下,口袋助理系统返回下述JSON包

{"result":"0","errmsg":"ok"}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

4.3.3 删除标签

应用向口袋助理系统发送请求

POST

https://api.kd77.cn/cgi-bin/roster/tag/delete?access_token=234578fe23d4

请求包结构体

{"tagid":"tag1",}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

tagid

标签id

返回说明

正常情况下,口袋助理系统返回下述JSON包

{"result":"0","errmsg":"ok"}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

4.3.4 添加成员

应用向口袋助理系统发送请求

POST

https://api.kd77.cn/cgi-bin/roster/tag/add_member?access_token=234578fe23d4

请求包结构体

{“tagid”:”2”,"userid":["1000", “1001”,”2345”],“alias”:[“myalias1”,”myalias2”]}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

tagid

标签id

userid

标签成员列表

alias

标签成员列表(使用别名)

返回说明

正常情况下,口袋助理系统返回下述JSON包

{"result":"0","errmsg":"ok",“invaliduserid”:[“2345”],“invalidalias”:[“myalias2”]}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

invaliduserid

添加失败的成员列表

invalidalias

添加失败的成员别名列表

4.3.5 删除成员

应用向口袋助理系统发送请求

POST

https://api.kd77.cn/cgi-bin/roster/tag/del_member?access_token=234578fe23d4

请求包结构体

{“tagid”:”2”,"userid":["1000", “1001”,”2345”],“alias”:[“myalias1”,”myalias2”]}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

tagid

标签id

userid

标签成员列表

alias

标签成员列表(使用别名)

返回说明

正常情况下,口袋助理系统返回下述JSON包

{"result":"0","errmsg":"ok",“invaliduserid”:[“2345”],“invalidalias”:[“myalias2”]}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

invaliduserid

添加失败的成员列表

invalidalias

添加失败的成员别名列表

4.3.6 获取成员

应用向口袋助理系统发送请求

GET

https://api.kd77.cn/cgi-bin/roster/tag/get?access_token=234578fe23d4&tagid=3241

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

tagid

标签id

返回说明

正常情况下,口袋助理系统返回下述JSON包

{
    "result":"0",
    "errmsg":"ok",
    “tagname”:”tag1”,
    "member": [{
        "userid":”268568”,
        "alias":”myname1”,
        "name":"张三",},{
        "userid":”268569”,
        "alias":”myname2”,
        "name":"李四",},
    ]
}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

member

部门成员列表数据

userid

用户id

alias

应用为用户设置的别名。若应用有设置别名则有该字段,否则没有。

name

用户名称

4.3.7 获取标签列表

应用向口袋助理系统发送请求

GET

https://api.kd77.cn/cgi-bin/roster/tag/list?access_token=234578fe23d4

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

返回说明

正常情况下,口袋助理系统返回下述JSON包

{
    "result":"0",
    "errmsg":"ok",
    "taglist": [{
        "tagid":”1”,
        "tagname":”tag1”
        },{
        "tagid":”2”,
        "tagname":”tag2”
        }
    ]
}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

taglist

标签列表数据

tagid

标签id

tagname

标签名字

4.4 用户别名

引入别名是为了解决某些已有的IT系统,已经使用了某个信息作为系统中用户的唯一标识。例如,sangfor公司中大量系统就使用了工号作为员工唯一标识,而口袋助理系统中使用了手机号作为人员的唯一标识。因此,为了兼容,口袋助理系统允许应用为口袋助理系统中的用户设置别名,以唯一的标识用户。为用户设置了别名的应用,每次口袋助理系统向应用发送信息时,都会携带上用户别名;并且口袋助理系统也接收应用以userid或者别名来唯一指定用户。

4.4.1 设置别名

应用向口袋助理系统发送请求

POST

https://api.kd77.cn/cgi-bin/roster/alias/set?access_token=234578fe23d4

请求包结构体为

{
    "set": [{
        "userid":"21364",
        "alias":"myname1"
    },{
        "userid":"21365",
        "alias":"myname2"
    },{
        "userid":"21366",
        "alias":"myname3"
    }]
}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

set

set_field二选一

要设置别名的列表

userid

用户id

alias

要设置的用户别名

或者这种格式

{"set_field": “employ_no”}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

set_field

set二选一

user的字段中选择一个字段作为别名

返回说明

正常情况下,口袋助理系统返回下述JSON包(注意,部分用户设置不成功也视为正常。设置别名不成功的用户列表和原因在error_list中返回。若用户已经有别名,设置则会覆盖).

{
    "result":"0",
    "errmsg":"ok",
    "error_list": [{
        "userid":"21364",
        "alias":"myname1",
        "errinfo":"user not exist",
    },{
        "userid":"21365",
        "alias":"myname2",
        "errinfo":"alias conflict",
    }]
}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

error_list

部分设置错误的用户列表

userid

用户id

alias

应用为用户设置的别名

errinfo

用户设置错误的信息

4.4.2 解除别名

应用向口袋助理系统发送请求

POST

https://api.kd77.cn/cgi-bin/roster/alias/unset?access_token=234578fe23d4

请求包结构体为

{"unset": [ {"userid":"21364",},{"userid":"21365",},{"userid":"21366",}]}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

unset

unset_field二选一

要解除别名的列表

userid

用户id

或者

{"unset_field": “1”}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

unset_field

unset二选一

表示解除字段别名

userid

用户id

返回说明

正常情况下,口袋助理系统返回下述JSON包.

{"result":"0","errmsg":"ok",}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

6.多媒体文件管理

6.1 上传多媒体文件

应用向口袋助理系统发送请求

POST

https://api.kd77.cn/cgi-bin/file/upload?access_token=234578fe23d4&type=voice

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

type

多媒体文件类型。可取值为voice(声音)video(视频)image(图片)file(普通文件)

MEDIA

多媒体文件数据,form-data中媒体文件标识,有filenamefilelengthcontent-type等信息。

返回说明

正常情况下,口袋助理系统返回下述JSON包

{"result":"0","errmsg":"ok","media_id": “e23ba843652d”,"created_at": “104568956”,}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

media_id

上传的多媒体文件在口袋助理系统中的id标识

created_at

媒体文件创建时间

上传的媒体文件的大小限制(暂定)

image(图片): 1MB

voice(语音):2MB

video(视频):10MB

file(普通文件):10MB

6.2 下载多媒体文件

应用向口袋助理系统发送请求

GET

https://api.kd77.cn/cgi-bin/file/get?access_token=234578fe23d4&media_id=e23ba843652d

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

media_id

媒体文件id

返回说明

正常情况下,口袋助理系统返回

{
    HTTP/1.1 200 OK
    Connection: close
    Content-Type: image/jpeg 
    Content-disposition: attachment; filename="test.jpg"
    Date: Mon, 22 Sep 2014 17:20:18 GMT
    Cache-Control: no-cache, must-revalidateContent-Length: 256073
    ......
}

错误时返回(省略了http头部)

{“result”:”80001103”,“errmsg”:”file not exist”}

7.发送消息

应用向员工发送消息,消息将以小助理在用户的终端显示。

调用接口时,使用https协议,数据包无需加密处理。

应用向口袋助理系统发送请求

POST

https://api.kd77.cn/cgi-bin/im/send?access_token=234578fe23d4

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

各个类型消息的发送格式见后面小节

返回说明

如果对应应用对部门、小组、个人无发送权限,消息将以失败返回;如果对应的部门、小组中部分不存在,发送仍然执行,返回出错的部分。

{
    "result":"0",
    "errmsg":"ok",
    "invalid_user": [”268568”,”268569”],
    "invalid_alias": [”myname1”,”myname2”],
    "invalid_department": [“234”, “128” ],
    "invalid_tag": [“2534”, “512” ]
}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

invalid_user

无效用户列表

invalid_alias

无效别名列表

invalid_department

无效部门的id

invalid_group

无效标签的id

7.1 普通消息格式

7.1.1 文本消息

{
    "to_user": [“342841”,”568148”],
    "to_alias": [“myname1”,”myname2”],
    "to_department": [“568”,”323”],
    "to_tag": [“3711”,”1121”],
    “type”:”text”,
    “content”:”DFA436ASDF”
}

参数

是否必须

描叙

to_user

目标接收用户id列表,与to_alias应该二选一

to_alias

目标接收用户别名列表,与to_user应该二选一

to_department

目标接收部门列表

to_tag

目标接收标签列表

type

消息类型。这里固定为text

content

消息内容。必须为UTF-8编码

7.1.2 图文消息

发送图文消息


{
	"to_user": [“342841”,”568148”],
	"to_alias": [“myname1”,”myname2”],
	"to_department": [“568”,”323”],
	"to_tag": [“3711”,”1121”],
	“type”:”itext”,
	“info”:{
		“title”:”标题”,
		“content”:”图文消息底部内容”,
		“url”:”www.kd77.cn”,
		“picture”:{
			“media_id”:”3D12211446F2”,
			“height”:”356”,
			“width”:”640”,
			“size”:”29666”,
		}
	}
}

media_id由上传图片文件接口获得,见6.1上传多媒体文件

参数说明

1.图文消息接口参数

参数

是否必须

描叙

to_user

目标接收用户id列表,与to_alias应该二选一

to_alias

目标接收用户别名列表,与to_user应该二选一

to_department

目标接收部门列表

to_tag

目标接收标签列表

type

消息类型。这里固定为itext

info

图文消息

2.图文消息info参数说明如下表

参数

是否必须

描叙

title

图文消息-标题

content

图文消息-底部内容

url

图文消息-点击后的网址

picture

图文消息-图片参数

media_id

图文消息-图片的媒体id,利用6.1操作获得

height

图文消息-图片的高

width

图文消息-图片的宽

size

图文消息-图片的大小

7.1.3 链接消息

发送链接消息


{
	"to_user": [“342841”,”568148”],
	"to_alias": [“myname1”,”myname2”],
	"to_department": [“568”,”323”],
	"to_tag": [“3711”,”1121”],
	“type”:”amsg”,
	“info”:{
		“content”:”XX总,IT部分申请报销需要你审批,点击即可完成审批”,
		“tag”:”财务系统”,
		“url”:”http://www.kd77.cn”,
	}
}

参数说明

1.图文消息接口参数

参数

是否必须

描叙

to_user

目标接收用户id列表,与to_alias应该二选一

to_alias

目标接收用户别名列表,与to_user应该二选一

to_department

目标接收部门列表

to_tag

目标接收标签列表

type

消息类型。这里固定为amsg

info

链接消息

2.图文消息info参数说明如下表

参数

是否必须

描叙

content

链接消息-内容

tag

链接消息-底部标签

url

链接消息-点击后的网址

7.2 选择消息格式

选择消息格式是发送多个选项供用户选择的消息

7.2.1 单选消息

{
    "to_user": [“342841”,”568148”],
    "to_alias": [“myname1”,”myname2”],
    "to_department": [“568”,”323”],
    "to_tag": [“3711”,”1121”],
    “type”:”Radio”,
    “content”:
    {
        “id”:”acdefasdBADs231”,
        “title”:”消息标题”,
        “items”:[{“name”:”项目一”,”value”:”bdyjy”},
                {“name”:”项目二”,”value”:”cjk”},
                {“name”:”项目三”,”value”:”lyf”}
        ]
    }
}

参数

是否必须

描叙

to_user

目标接收用户id列表,与to_alias应该二选一

to_alias

目标接收用户别名列表,与to_user应该二选一

to_department

目标接收部门列表

to_tag

目标接收标签列表

type

消息类型。这里为text,itext,amsg等

content

消息内容,包含单选内容

content.id

该单选项目的唯一标识,由调用方标识,口袋助理在结果时返回给调用方.

content.title

单选项目的描叙

content.items

单选项目

content.items.name

项目的描叙

content.items.value

项目的值

7.2.2 多选消息

{
    "to_user": [“342841”,”568148”],
    "to_alias": [“myname1”,”myname2”],
    "to_department": [“568”,”323”],
    "to_tag": [“3711”,”1121”],
    “type”:”checkbox”,
    “content”:
    {
        “id”:”acdefasdBADs232”,
        “title”:”消息标题”,
        “items”:[
            {“name”:”项目一”,”value”:”bdyjy”},
            {“name”:”项目二”,”value”:”cjk”},
            {“name”:”项目三”,”value”:”lyf”}
        ]
    }
}

参数

是否必须

描叙

to_user

目标接收用户id列表,与to_alias应该二选一

to_alias

目标接收用户别名列表,与to_user应该二选一

to_department

目标接收部门列表

to_tag

目标接收标签列表

type

消息类型。这里为text,itext,amsg等

content

消息内容,包含单选内容

content.id

该多选项目的唯一标识,由调用方标识,口袋助理在结果时返回给调用方.

content.title

多选项目的描叙

content.items

多选项目

content.items.name

项目的描叙

content.items.value

项目的值

7.2.3 获取用户反馈

用户的单选消息和多选消息的结果,会提交到口袋助理云端存储。应用要获取这些结果,发送如下消息

GET

https://api.kd77.cn/cgi-bin/select/feedback?access_token=234578fe23d4&start=0&count=100

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

start

开始id。如果是第一页调用,设置为0;后续页调用,则设置为响应中的next字段。

count

否,默认为100,最大值为1000,最小值为1

该页调用返回的最大记录数

返回说明

正常情况下,口袋助理系统返回下述JSON包

{
    "result":"0",
    "errmsg":"ok",
    "feedbacks": [ 
    {
        "type":”Radio”,
        "id":”acdefasdBADs231”,
        "userid":”234125”,
        "alias":”56868”,
        "feedback":["bdyjy"],
    },
    {
        "type":”checkbox”,
        "id":”acdefasdBADs232”,
        "userid":”234125”,
        "alias":”56868”,
        "feedback":["bdyjy”,”cjk"]
    }],
    “next”: “100”
}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

feedbacks

反馈结果列表

type

选择类型,Radiocheckbox

id

应用发送选择时的设置的id

userid

反馈的用户id

alias

反馈的用户别名(若有设置)

feedback

用户的反馈值。 

8.oauth认证

Oauth2.0是第三方授权协议,用以口袋助理授权第三方访问口袋助理中的用户资料。

8.1 获取认证code

应用构造url连接

https://api.kd77.cn/oauth2/authorize?did=10000&redirect_uri=http%3a%2f%2fwww.example.com&response_type=code&scope=kd77_base&state=ad9238#kd77_redirect

参数说明

参数

是否必须

描叙

did

企业帐号

redirect_uri

授权后的回调地址,需要使用urlcode编码。

response_type

返回类型,此时固定为code

scope

请求的授权范围。此时固定为kd77_base

state

应用携带的参数。在授权回调后,会原样以url返回给应用。

#kd77_redirect

若设置了此参数,在口袋助理中打开时,直接跳转到目标页面;否则会弹出登录框要求输入用户和密码登录。

返回说明

用户在口袋助理系统点击该连接,若用户确认授权,则页面跳转至redirect_uri?code=23eabf22&state=ad9238,应用可用code获取到用户的信息

注意:

code码会在5分钟后超时,若5分钟内没有使用,则code会失效。

code码在有效时间内只能使用一次,使用后即刻失效。

8.2 获取员工信息

应用构造url向口袋助理系统发送请求

GET

https://api.kd77.cn/cgi-bin/roster/user/get?access_token=1234adfb64&code=23832afd8&detail=0

参数说明

参数

是否必须

描叙

access_token

应用的访问凭证

code

上一步中获取到的code,此code仅在5分钟内有效,若需要继续获取用户资料,需要用户再次授权。也就是说一次授权仅允许5分钟内读取用户资料。

detail

是否返回详尽信息,默认detail=0,只返回简略的信息,包含三个字段useridaliasname。 若需要更详尽的用户信息,可以在请求时设置detail=1

返回说明

正常情况下,口袋助理系统返回下述JSON包.若需要用户的更详尽信息,可以携带上detail=1参数

{
    "result":"0",
    "errmsg":"ok",
    "user": 
    {
        "userid":"21364",
        "alias":"myname",
        "name":"张三",
    }
}

8.3 获取二维码地址

应用构造url向口袋助理系统发送请求

GET

https://api.kd77.cn/oauth2/QR_code?access_token=234578fe23d4&redirect_uri=http%3a%2f%2fwww.example.com&response_type=code&scope=kd77_base&state=ad9238

参数说明

参数

是否必须

描叙

access_token

应用的访问凭证

redirect_uri

授权后的回调地址,需要使用urlcode编码。

response_type

返回类型,此时固定为code

scope

请求的授权范围。此时固定为kd77_base

state

应用携带的参数。在授权回调后,会原样以url返回给应用。

返回说明

正常情况下,moa返回下述JSON包给第三方应用


{
    "result": 0,
    "errmsg”: "ok",
	"data":{
		"url": "https://web.kd77.cn/clogin?did=1000&session=dasfsafsdf123213dsf"//url有效时间1个小时,一次扫码成功后失效,第三方直接访问url,会显示二维码,扫描完后见:请求二维码地址后返回说明
    }
}

错误时,返回下述JSON包


{"result":80000013,"errmsg":"secret error"}

请求二维码地址后返回说明

用户在口袋助理系统点击扫描,则页面跳转至redirect_uri?code=23eabf22&state=ad9238,应用可用code获取到用户的信息 注意:

code码会在5分钟后超时,若5分钟内没有使用,则code会失效。

code码在有效时间内只能使用一次,使用后即刻失效。

9.其他接口

9.1 接入IP

应用向口袋助理系统发送请求

GET

https://api.kd77.cn/cgi-bin/getcallbackip?access_token=234578fe23d4

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

返回说明

正常情况下,moa返回下述JSON包给第三方应用


{
    "result": "0",
    "errmsg": "ok",
    "ip_list": ["127.0.0.1", "127.0.0.1"]
}

参数说明

参数

描叙

result

api调用结果值。为0表示成功,非0表示失败,失败信息见errmsg

errmsg

错误信息

ip_list

接入IP列表

10.运行

10.1 运行app

在手机客户端的应用图标点击时,手机客户端先发送一个请求消息到口袋助理后台,口袋助理后台则会构造应用的url返回到手机的app端,手机app端将在内置浏览器中打开该应用

GET

http://www.example.com/what?code=23832afd8

参数

描叙

code

用户信息。可以获取到访问的用户

其中www.example.com是注册时应用提交的url地址。 第三方应用若想要获取是哪个用户访问的,可以通过8.2章节的oauth接口获取访问的员工信息。

回到顶部
2016-11-23 14:55