服务端接口API
  1. 发布应用
  2. 获取访问凭证
  3. oauth认证
    1. 获取口袋助理用户信息
    2. 用口袋助理账号登陆
    3. 用口袋助理扫码登陆
  4. 通讯录管理
    1. 部门管理
      1. 获取部门详情
      2. 获取部门列表
      3. 获取部门成员
    2. 用户管理
      1. 获取用户
    3. 分组管理
      1. 创建标签
      2. 更新标签
      3. 删除标签
      4. 添加成员
      5. 删除成员
      6. 获取成员
      7. 获取标签列表
    4. 用户别名
      1. 设置别名
      2. 解除别名
  5. 多媒体文件管理
    1. 上传多媒体文件
  6. 发送消息
    1. 普通消息格式
      1. 文本消息
      2. 图文消息
      3. 链接消息
  7. 客户管理
    1. 导出客户
  8. 流程管理
    1. 流程导出
  9. 考勤管理
    1. 获取考勤历史
  10. 销售订单
    1. 导出订单
  11. 商品管理
    1. 导出商品
    2. 批量获取商品详情

1.发布应用

上架应用的时候,您需要联系口袋助理客服人员,提供您的应用URL地址、应用名称和应用图标,添加完成后会反馈给您appid和secret,用于后续的操作。发布后您的应用会如下展现,应用的分类和顺序可以调整,也可以隐藏应用(只需要调用接口获取数据的时候):

2.获取访问凭证

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

GET

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

参数说明

参数

描叙

appid

第三方应用唯一标识ID1.添加应用之后得到

did

公司帐号ID,可以在口袋助理app的“我 -> 公司”里面看到,后续其他接口用到did均为此值,不再赘述

secret

第三方应用在口袋助理中的秘钥,即1.中的sercret

expire

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

返回说明

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

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

错误时,返回下述JSON包,其他接口错误返回样式相同,没有特别情况后续接口不再描述错误返回

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

3.oauth认证

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

3.1 获取口袋助理用户信息

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

GET

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

参数说明

参数

是否必须

描叙

access_token

应用的访问凭证

code

用户在口袋助理点击启动第三方应用,跳转到应用地址的时候会携带code参数,此code仅在5分钟内一次有效。其他情况也会有code码,在后续具体接口描述

detail

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

返回说明

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

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

3.2 用口袋助理账号登陆

本接口主要用于非口袋助理应用跳转,而是其他访问路径需要使用口袋助理账号登陆,第三方个应用构造url连接嵌入需要认证的页面:

https://api.kdzl.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分钟内一次有效。

3.3 用口袋助理扫描登陆

本接口主要用于非口袋助理应用跳转,而是其他访问路径需要使用口袋助理扫码登陆,应用构造url向口袋助理系统发送请求:

GET

https://api.kdzl.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.kdzl.cn/clogin?did=1000&session=dasfsafsdf123213dsf"//url有效时间1个小时,一次扫码成功后失效,第三方直接访问url,会显示二维码,扫描完后见:请求二维码地址后返回说明
    }
}

错误时,返回下述JSON包


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

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

返回结果中url在1小时后或者一次扫描后失效,第三方应用将url嵌入在需要用口袋助理扫描的地方,即可显示二维码。用户在使用口袋助理扫描后,则页面跳转至redirect_uri?code=23eabf22&state=ad9238,应用可用code获取到用户的信息

注意:code码在5分钟内一次有效。

4.通讯录管理

部门管理

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

获取部门详情

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

GET

https://api.kdzl.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参数为1,并设置fetch_child为1。

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

GET

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

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

department_id

需要获取子部门的列表。若不指定,默认为1,即为根部门

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.kdzl.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.2 获取用户

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

GET

https://api.kdzl.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.kdzl.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.kdzl.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.kdzl.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.kdzl.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.kdzl.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.kdzl.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.kdzl.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.kdzl.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.kdzl.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

错误信息

5.多媒体文件管理

5.1 上传多媒体文件

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

POST

https://api.kdzl.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.发送消息

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

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

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

POST

https://api.kdzl.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

6.1 普通消息格式

6.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编码

6.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.kdzl.cn”,
		“picture”:{
			“media_id”:”3D12211446F2”,
			“height”:”356”,
			“width”:”640”,
			“size”:”29666”,
		}
	}
}

media_id由上传图片文件接口获得,见5.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

图文消息-图片的大小

6.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.kdzl.cn”,
	}
}

参数说明

1.图文消息接口参数

参数

是否必须

描叙

to_user

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

to_alias

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

to_department

目标接收部门列表

to_tag

目标接收标签列表

type

消息类型。这里固定为amsg

info

链接消息

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

参数

是否必须

描叙

content

链接消息-内容

tag

链接消息-底部标签

url

链接消息-点击后的网址

7.客户管理

7.1 导出客户

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

GET

https://api.kdzl.cn/cgi-bin/customer/export?access_token=234578fe23d4&start=0&count=1000

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

start

开始导出客户的位置,不填默认从第一个开始

count

本次拉取最多返回的客户个数,不填默认值是1000.该值最小取1,最大取2000.

返回说明

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

{
  "result":"0",
  "errmsg":"ok",
  "customers": [ 
    {
      "custmid":1,
      "name":"口袋助理公司",
      "addr":”广东省深圳市南山科技园高新中三道软件园12栋501”,
      "note":”vip客户”,
      "contacts":[
        {
        “contactid”:”1”,
        “name”:”张三”,
        “titles”:[“总经理”],
        “mobiles”:[“13798559972”],
        “phones”:[“0755-28014436”],
        “ims”:[“665688”],
        “mails”:[“zhangsan@163.com”],
        “faxs”:[“0755-28014436”],
        “note”:”vip”,
        “wechats”:[”zhangsan”],
        “weibos”:[”zhangsan”],
        ......
        }],
      "followers":[{“pid”:12345,start_time:145234687}],
      "create_pid":12456,
      "create_alias":”56868”,
      "create_time":132548372,
      ..........
    }
  ],
  “next”:”230182”
}

参数说明

参数

描叙

result

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

errmsg

错误信息

customers

客户列表

custmid

客户id

name

客户名字

addr

客户地址

note

客户备注

contacts

联系人列表

contacts.contactid

联系人id

contacts.name

联系人姓名

contacts.titles

联系人职位(数组,可能多个职位)

contacts.mobiles

联系人手机号码(数组,可能多个号码)

contacts.phones

联系人座机号码(数组,可能多个座机号码)

contacts.ims

联系人qq号(数组,可能多个qq)

contacts.mails

联系人邮箱(数组,可能多个邮箱)

contacts.faxs

联系人传真(数组,可能多个传真)

contacts.note

联系人备注

contacts.wechats

联系人微信号(数组,可能多个微信)

contacts.weibos

联系人微博(数组,可能多个微博)

followers

跟进人列表

followers.pid

跟进人的userid,可以通过通讯录的获取用户接口得到详细的跟进人信息。

followers.start_time

跟进人开始跟进时间

create_pid

创建这个客户的用户的userid,可以通过通讯录获取用户接口得到详细的创建人信息。

create_alias

创建这个客户的用户的别名(如果有设置别名的话)

create_time

创建客户的时间

.......

口袋助理还会返回一些没有列出的字段,不关注忽略即可

next

本次导出的最后一个客户标识。若该字段为空,说明已经导出完了所有客户;若不为空,则下次再调用该接口时,把next的值放入请求的start参数中,能够从上一次的导出位置开始。

8.流程管理

8.1流程导出

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

POST

https://api.kdzl.cn/cgi-bin/workflow/exportProcess?access_token=234578fe23d4

请求结构体

{
    "type": "1",
    "status":"1",
    "satrtTime":"1520386759000",
    "endTime":"1520386759000",
    "pid":"8359",
    "start":"0",
    "limit":"30",
}

参数说明

参数

是否必须

描叙

Type

列表类型,0或者不传 全部 1 指定人申请 2 指定人审批 3 抄送给指定人

Status

流程状态 -1或者不传 0 驳回 1审批中 3 流程结束

satrtTime

筛选起始时间

endTime

筛选结束时间

Pid

筛选人,值为用户ID,指定人 type 为0 可以不传 type 不为0 必传

Start

筛选起始流程ID,不填为0

Limit

分页每页数量,最大1000

返回说明

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


{
    "result": 0,
    "errmsg": "xx",
    "retTime": 1520386759000,
    "list": {
        "submitUser": 8359,
        "submitUserName": "小商品",
        "submitTime": 1520386759000,
        "processDefineId": 456489,
        "processNameId": "proc1887_42503:2:187157",
        "processName": "普通3",
        "processInstId": 282886509,
        "processStatus": 1,
        "froms": [{
            "itemId": 1496593,
            "label": "理由",
            "xtype": "textfield",
            "data": "同意"
        }],
        "comments": [{
            "taskId": "282886513",
            "taskName": "提交申请",
            "reason": "1231231",
             "opt": 1,
             "opinion": 1,
             "dealTime": 1520299369000,
             "pid": 8359,
              "userName": "小商品"
        }]
    }
}

参数说明

参数

描叙

result

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

errmsg

错误信息

retTime

最后一条记录时间

list.submitUser

提交人id

list.submitUserName

提交人姓名

list.submitTime

提交时间

list.processDefineId

流程定义id

list.processNameId

流程名字id

list.processName

流程名字

list.processInstId

流程类型id

list.processStatus

流程状态 0 驳回 1 审批中 3 流程结束

list.froms

表单项

list.froms.itemId

表单项id

list.froms.label

名称

list.froms.xtype

数据类型

list.froms.data

数据

list.comments

审批步骤

list.comments.taskId

当前步骤任务id

list.comments.taskName

步骤名称

list.comments.reason

审批理由 可能为空

list.comments.opt

步骤类型 1 提交 2 重新提交 3 正常审批 4 系统通过 5 系统驳回

list.comments.opinion

审批类型 1 同意 2 驳回

list.comments.dealTime

审批时间

list.comments.pid

审批人id

list.comments.userName

审批人姓名

9.考勤管理

9.1 获取考勤历史

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

POST

https://api.kdzl.cn/cgi-bin/workattendance/get_sign_result?access_token=234578fe23d4

请求结构体

{
  “gids”:[1],
  “pids”:[2],
  “start”:1,
  “count”:20,
}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

gids

部门id,获取该部门成员的考勤结果(无需考勤成员除外)

pids

成员id,获取该成员的考勤结果,gidspids为空则获取所有成员的考勤结果

start

分页使用,从第几条开始,第一次拉取时填1

count

一次拉取多少条,最大值不能超过2000条(后续支持,目前1000条),默认100条,1条表示一个人在筛选时间段内的所有考勤记录

stime

开始日期,时间戳,毫秒

etime

结束日期,时间戳,毫秒,开始日期与结束日期不能超过1年(后续支持,目前两个月内)

返回说明

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

{
    "result": 0,
    "errmsg": "ok",
    "reports": [{
        "pid": 2298,
        "sign_details": [{
            "pid": 2298,
            "sign_wa_time": 1531183744705,
            "position": {
                "longitude": 156.962184,
                "latitude": 16.580671,
                "address": "xx省xx市xx区xx路"
            },
            "range_type": 0,
            "time_type": 1,
            "auto_sign": 1,
            "wa_type": 0,
            "date": 20180710,
            "index": 0,
            "offset": 19.800000,
            "point_type": 0,
            "std_sign_time": 1531184400000,
            "bound_type": 0
        }],
        "not_sign_details": [{
            "pid": 2298,
            "date": 20180702,
            "type": 0,
            "index": 0
        }]
    }],
    "end": 0
}

参数说明

参数

描叙

result

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

errmsg

错误信息

reports

考勤结果

sign_details

正常签到签退结果

not_sign_details

未签到签退结果

pid

成员id

position

签到地址

std_position

考勤设置签到地址

longitude

经度

latitude

纬度

address

地址

date

考勤日期

index

多次考勤0:上午考勤 1:下午考勤

mode

0:正常模式 1:加班模式

wa_type, type

0:上班考勤 1:下班考勤

offset

用户签到签退位置离目标签到签退位置的偏移(单位米)

extra_type

0:休息日的加班 1:工作日的加班

sign_wa_time

签到签退时间

std_sign_time

考勤设置的签到签退时间

range_type

0:范围内 1:范围外

out_type

考勤范围外时设置的类型 0:出差 1:外勤 10:其他

bound_type

0:绑定的手机1:非绑定的手机

time_type

0:早退 1:准时 2:迟到

point_type

0:经纬度范围内 1:经纬端范围外

auto_sign

是否为自动签到0:1:

end

0:还有数据没有拉取 1:数据已经拉取完毕

10.销售订单

10.1 导出订单

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

POST

https://api.kdzl.cn/cgi-bin/saleorder/export?access_token=234578fe23d4

请求结构体

{
“start”:0,
“count”:20,
}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

start

开始导出销售订单的位置,不填默认从最新创建的订单开始拉取,获取当前页订单时,填上一页最后一个订单的order_id

count

本次拉取最多返回的客户个数,不填默认值是1000.该值最小取1,最大取1000.

返回说明

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

{
"result":"0",
"errmsg":"ok",
"saleorders": [{
      "order_id": 84,
      "version":  1,
      "snumber":  "D2018052300004",
      "price":  213123,
      "create_time":  1527039243449,
      "ordered_time": 1527206400000,
      "create_pid": 40984,
      "owner_pid":  40984,
      "status": 1,
      "customer_id":  131,
      "products": [{
          "product_id": 20,
          "version":  3,
          "price":  23456,
          "discount": 100,
          "sell_count": 1,
          "sell_money": 23456,
          "stock_status": 0
        }],
      "custom_props": [{
          "prop_id":  1003,
          "prop_name":  "多选",
          "prop_value_type":  6,
          "prop_value": "{\"values\":[]}"
        }]
    }],
"end":  false
}

参数说明

参数

描叙

result

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

errmsg

错误信息

end

列表是否结束,若为false,可继续拉下一页

saleorders

销售订单列表

order_id

销售订单id

snumber

销售订单编号

price

销售订单销售金额

create_time

销售订单创建时间

ordered_time

销售订单下单时间

create_pid

创建这个销售订单的用户的userid,可以通过通讯录获取用户接口得到详细的创建人信息。

owner_pid

该销售订单归属人的userid,可以通过通讯录获取用户接口得到详细的归属人信息。

status

销售订单审批状态

customer_id

销售订单客户id,可以通过客户获取接口得到详细的客户信息

products

销售订单商品列表

products.product_id

销售订单商品id

products.version

销售订单商品版本

products.price

销售订单商品单价

products.discount

销售订单商品折扣,100 表示无折扣

products.sell_count

销售订单商品销售总数

products.sell_money

销售订单商品销售总金额

products.stock_status

销售订单商品出入库状态

custom_props

销售订单自定义属性

custom_props.prop_id

销售订单自定义属性id

custom_props.prop_name

销售订单自定义属性名称

custom_props.prop_value_type

销售订单自定义属性类型

0:文本/1:数字/2YYMMDD格式日期/ 3YYMMDDHHmm格式日期/4:单选框/5:其他/6:多选框

custom_props.prop_value

销售订单自定义属性具体值

11.商品管理

11.1 导出商品

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

POST

https://api.kdzl.cn/cgi-bin/product/export?access_token=234578fe23d4

请求结构体

{
“start”:0,
“count”:20,
}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

start

开始导出商品的位置,不填默认从最新创建的商品开始拉取,获取当前页商品时,填上一页最后一个商品的 product_id

count

本次拉取最多返回的商品个数,不填默认值是1000.该值最小取1,最大取1000.

返回说明

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

{
"result":"0",
"errmsg":"ok",
"products": [{
      "product_id": 9,
      "version":  1,
      "product_name": "423",
      "price":  432,
      "status": 1,
      "class_id": -1,
      "class_name": "无",
      "unit_id":  2,
      "unit_name":  "件",
      "create_time":  1514166868013,
      "create_pid": 40984
}],
"end":  false
}

参数说明

参数

描叙

result

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

errmsg

错误信息

end

列表是否结束,若为false,可继续拉下一页

products

商品列表

product_id

商品id

product_name

商品名称

price

商品单价

status

商品状态, 0: 已下架,  1: 上架中

class_id

商品分类id

class_name

商品分类名称

unit_id

商品单位id

unit_name

商品单位名称

create_time

商品创建时间

create_pid

创建这个商品的用户的userid,可以通过通讯录获取用户接口得到详细的创建人信息。

11.2 批量获取商品详情

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

POST

https://api.kdzl.cn/cgi-bin/product/details?access_token=234578fe23d4

请求结构体

{
  "product_infos":[{
  "product_id":9,
  "version":1
  }]
}

参数说明

参数

是否必须

描叙

access_token

调用接口凭证

product_infos

需要获取详情的商品信息

product_infos.product_id

商品id

product_infos.version

商品 version

返回说明

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

{
"result":"0",
"errmsg":"ok",
"products": [{
      "product_id": 9,
      "version":  1,
      "product_name": "423",
      "price":  432,
      "status": 1,
      "class_id": -1,
      "class_name": "无",
      "unit_id":  2,
      "unit_name":  "件",
      "create_time":  1514166868013,
      "create_pid": 40984
}]
}

参数说明

参数

描叙

result

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

errmsg

错误信息

products

商品列表

product_id

商品id

product_name

商品名称

price

商品单价

status

商品状态, 0表示已下架, 1表示上架中

class_id

商品分类id

class_name

商品分类名称

unit_id

商品单位id

unit_name

商品单位名称

create_time

商品创建时间

create_pid

创建这个商品的用户的userid,可以通过通讯录获取用户接口得到详细的创建人信息。

.......

口袋助理还会返回一些没有列出的字段,不关注忽略即可

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