口袋助理系统第三方应用接入
1.发布应用
golang语言示列代码托管：https://gitee.com/pocket-assistant/OpenApiExample
上架应用的时候，您需要联系口袋助理客服人员，提供您的应用url地址、应用名称和应用图标，添加完成后会反馈给您appid和secret，用于后续的操作。发布后您的应用会如下展现：
应用的分类和顺序可以调整，也可以隐藏应用（只需要调用接口获取数据的时候）。
golang语言示列代码托管：https://gitee.com/pocket-assistant/OpenApiExample
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 | 第三方应用唯一标识ID，1.添加应用之后得到 |
| did | 公司帐号ID，可以在口袋助理app的“我 -> 公司”里面看到，后续其他接口用到did均为此值，不再赘述 |
| secret | 第三方应用在口袋助理中的秘钥，即1.中的sercret |
| expire | 凭证的有效期，单位秒，从凭证获取成功开始计数，经历expire秒后该凭证失效。 有效时间最大为一天（86400秒），默认为2小时（7200秒） |
返回说明
正常情况下，moa返回下述JSON包给第三方应用
{"result":0,"errmsg":"ok", "access_token":"235acdfa61vdae1546"}
错误时，返回下述JSON包，其他接口错误返回样式相同，没有特别情况后续接口不再描述错误返回
xxxxxxxxxx{"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，只返回简略的信息，包含三个字段userid、alias、name。 若需要更详尽的用户信息，可以在请求时设置detail=1 |
返回说明
正常情况下，口袋助理系统返回下述JSON包。
xxxxxxxxxx{"result":"0","errmsg":"ok","user":{"userid":"21364","alias":"myname","name":"张三",}}
3.2 用口袋助理扫描登陆
本接口主要用于非口袋助理应用跳转，而是其他访问路径需要使用口袋助理扫码登陆，应用构造url向口袋助理系统发送请求：
GET
参数说明
| 参数 | 是否必须 | 描叙 |
|---|---|---|
| access_token | 是 | 应用的访问凭证 |
| redirect_uri | 是 | 授权后的回调地址，需要使用urlcode编码。 |
| response_type | 是 | 返回类型，此时固定为code |
| scope | 是 | 请求的授权范围。此时固定为kd77_base |
| state | 否 | 应用携带的参数。在授权回调后，会原样以url返回给应用。 |
返回说明
正常情况下，口袋助理返回下述JSON包给第三方应用
xxxxxxxxxx{"result":0,"errmsg":"ok"，"data"：{"url":"http://api.kd7.cn/tdc?did=1000&session=dasfsafsdf123213dsfa"}}
请求二维码地址后返回说明
返回结果中url在1小时后或者一次扫描后失效，第三方应用将url嵌入在需要用口袋助理扫描的地方，即可显示二维码。用户在使用口袋助理扫描后，则页面跳转至redirect_uri?code=23eabf22&state=ad9238，应用可用code获取到用户的信息
注意：code码在5分钟内一次有效。
4.通讯录管理
4.1 部门管理
每个部门有自己的部门id标识，根部门的id标识为1.
4.1.1 获取部门详情
应用向口袋助理系统发送请求
GET
https://api.kdzl.cn/cgi-bin/roster/department/get?access_token=234578fe23d4&department_id=32
参数说明
| 参数 | 是否必须 | 描叙 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
| department_id | 是 | 部门id，初始根部门ID 为1 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"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 |
4.1.2 获取部门列表
获取指定部门下的子部门列表。若需要获取全部部门的列表，指定department_id参数为1，并设置fetch_child为1。
应用向口袋助理系统发送请求
GET
参数说明
| 参数 | 是否必须 | 描叙 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
| department_id | 否 | 需要获取子部门的列表。若不指定，默认为1，即为根部门 |
| fetch_child | 否 | 是否递归获取子部门下面的子部门 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"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
参数说明
| 参数 | 是否必须 | 描叙 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
| department_id | 是 | 要获取的部门id。当department_id为1，并且fetch_child为1时，将返回所有用户。 |
| fetch_child | 否，不指定默认为0 | 是否递归获取子部门的成员 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"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 获取用户
应用向口袋助理系统发送请求
GET
https://api.kdzl.cn/cgi-bin/roster/user/get?access_token=234578fe23d4&userid=213634&alias=myname
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| userid | 否，但和alias二者必须有其一 | string | 系统中的唯一用户标识，对当前应用唯一, 这个一般通过其他结构拿到用户信息后，需要获取详细信息的时候用。 |
| alias | 否，但和alias二者必须有其一 | string | 应用对用户绑定的别名，必须能够唯一索引到用户，即不同的用户不能重名，现在支持用账号查询（即account）和 工号查询（即employee_id），需要通过别名查询的话需要找客服单独设置绑定到哪一个唯一键山上。 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result":"0","errmsg":"ok","user":{"userid":"21364","alias":"myname","name":"张三","account":"12345678901","sex":"男","photo": {"media_id": "FqUGaNk9JWu-tnRL1wbFP27I7Jbn"},"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中的唯一标识，后续如果有其接口的pid，op_pid, userid等字段，均为此值。 |
| name | 用户名称 |
| sex | 性别 |
| Photo | 头像图标，需要调用12.5 获取下载url |
| department_id | 所在的部门id |
| position | 职位 |
| employee_id | 工号 |
| address | 工作地点 |
| 电子邮箱 | |
| phone | 电话号码。移动电话type为mobile，办公电话type为office。Number指定号码 |
5.多媒体文件管理
5.1 下载多媒体文件
5.1.1 获取文件下载url
应用向口袋助理系统发送请求
POST
xxxxxxxxxx{"media_id":["FgFfu9fx51ofcaUgjSlgo_7sYv23","FgG4-Ho_B0RSUOTsHoxYlPFOJy2d"]}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| media_id | 是 | []string | 数组形式，文件(图片)的media_id数组 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result":0,"errmsg":"ok","urls":[{"result":0,"url":"http://oss.kdzl.cn/FgFfu9fx51ofcaUgjSlgo_7sYv23?e=1511858029&token=BDlsCI9C9xGl-aBysVoFl7-eu9c2j5JLredsogNl:13Q4IYRayKtB3xX0K7qISIyZ_3E=","media_id":"FgFfu9fx51ofcaUgjSlgo_7sYv23"},{"result":0,"url":"http://oss.kdzl.cn/FgG4-Ho_B0RSUOTsHoxYlPFOJy2d?e=1511858029&token=BDlsCI9C9xGl-aBysVoFl7-eu9c2j5JLredsogNl:n7KAJajhZGlMBZlAAlAM_BsPEc0=","media_id":"FgG4-Ho_B0RSUOTsHoxYlPFOJy2d"}]}
参数说明
| 参数 | 描叙 |
|---|---|
| result | api调用结果值。为0表示成功，非0表示失败，失败信息见errmsg |
| errmsg | 错误信息,以下是该数组内的内容 |
| urls | 数组形式 |
| result | 该hash的获取结果，成功>=0,失败<=0 |
| url | 下载的url |
| media_id | 对应req中的media_id |
6.发送消息
应用向员工发送消息，消息将以小助理在用户的终端显示。
调用接口时，使用https协议，数据包无需加密处理。
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/cgi-bin/im/send?access_token=234578fe23d4
参数说明
| 参数 | 是否必须 | 描叙 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
各个类型消息的发送格式见后面小节
返回说明
如果对应应用对部门、小组、个人无发送权限，消息将以失败返回；如果对应的部门、小组中部分不存在，发送仍然执行，返回出错的部分。
xxxxxxxxxx{"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 文本消息
xxxxxxxxxx{"to_user": ["342841","568148"],"to_alias": ["myname1","myname2"],"to_department": ["568","323"],"to_tag": ["3711","1121"],"type":"text","content":"DFA436ASDF"}
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| to_user | 否 | []string | 目标接收用户id列表，与to_alias应该二选一 |
| to_alias | 否 | []string | 目标接收用户别名列表，与to_user应该二选一 |
| to_department | 否 | []string | 目标接收部门列表 |
| to_tag | 否 | []string | 目标接收标签列表 |
| type | 是 | string | 消息类型。这里固定为text |
| content | 是 | string | 消息内容。必须为UTF-8编码 |
7.客户管理
7.0 客户结构
7.0.1 客户联系人
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| name | 否 | string | 联系人名字 |
| sex | 否 | int | 0:未知 1:男 2:女 |
| titles | 否 | []string | 联系人职位 |
| mobiles | 否 | []string | 联系人手机 会过滤掉非数字字符 |
| phones | 否 | []string | 联系人座机 会过滤掉非数字字符 |
| ims | 否 | []string | |
| mails | 否 | []string | 邮箱 |
| faxs | 否 | []string | 传真 |
| note | 否 | string | 备注 |
| address | 否 | string | 地址 |
| hobby | 否 | string | 兴趣 |
| wechats | 否 | []string | 微信 |
| weibos | 否 | []string | 微博 |
| birthday | 否 | int64 | 生日(格林威治时间戳 单位ms) |
| 其他 | 备注：客户联系人支持自定义的属性，需要在产品界面配置好后，导出一个客户查看相关自定义数据结构 |
7.0.2 客户跟进人
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| pid | 是 | int64 | 人员id |
| fctype | 否 | int32(0/1) | 用于修改跟进人0为添加，1为删除 |
7.0.3 客户信息
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| name | 是 | string | 客户名字，不能为空串 |
| addr | 否 | String | 客户地址 |
| contacts | 否 | []contact | 联系人 联系人信息 见 7.0.1 |
| followers | 是 | []follower | 跟进人 跟进人信息 见 7.0.2 |
| custmno | 否 | string | 客户编号 |
| websites | 否 | []string | 网址 |
| introduction | 否 | string | 备注 |
| create_pid | 否 | Int64 | 创建人在moa中的id 导入的时候使用op_pid |
| create_time | 否 | Int64 | 创建时间 导入的时候自动生成 |
| modify_pid | 否 | Int64 | 修改人在moa中的id 导入的时候使用op_pid |
| modify_time | 否 | Int64 | 修改时间 导入的时候自动生成 |
| custmid | 否 | Int64 | 客户id 导入时自动生成 |
| lbl_doc | 否 | label_doc | 客户标签的描述 见 7.0.4 对应的标签记录 只支持 父子，子标签只能有一个不可多选，对应的id和名字必须要和获取的标签中对应（获取标签见 7.3），否则无法显示 |
| 其他 | 备注：客户支持自定义的属性，标签等字段，需要在产品界面配置好后，导出一个客户查看相关自定义数据结构 |
7.0.4 客户标签文档
xxxxxxxxxxlabel_doc{"clbls": [{"lbl": {"lbl_id": 3,"lbl_name": "通话状态","sort_id": 0},"sub_lbls": [{"lbl": {"lbl_id": 650,"lbl_name": "已接听","sort_id": 0},"sub_lbls": []},{"lbl": {"lbl_id": 651,"lbl_name": "未接听","sort_id": 1},"sub_lbls": []}]}],"version": 18}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| clbls | 是 | []label_record | label_record 描述见 7.0.5 |
| version | 否 | Int64 | 标签版本号，只在获取标签的时候返回 |
7.0.5 客户标签记录
xxxxxxxxxxlabel_record{"lbl": {"lbl_id": 3,"lbl_name": "通话状态","sort_id": 0},"sub_lbls": [{"lbl": {"lbl_id": 650,"lbl_name": "已接听","sort_id": 0},"sub_lbls": []},{"lbl": {"lbl_id": 651,"lbl_name": "未接听","sort_id": 1},"sub_lbls": []}]}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| lbl | 否 | custm_label | custm_label 描述见 7.0.6 |
| sub_lbls | 否 | label_record | 标签记录 见 本节 |
7.0.6 客户标签
xxxxxxxxxxcustm_label{"lbl_id": 651,"lbl_name": "未接听"}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| lbl_id | 是 | Int32 | 父标签或者子标签id |
| lbl_name | 是 | string | 父标签或者子标签名称 |
7.0.7 客户信息修改控制结构
xxxxxxxxxx{"name": true,"addr": true,"contacts":[]contact_ctrol,"followers":true,"lbl":true,"custmno":true,"websites":true,"introduction":true,"follow_level":true}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| name | 否 | bool | true表示修改 客户名字 对应的 custm.name 为修改后的名字 |
| addr | 否 | bool | true表示修改 客户地址 对应 custm.addr 为修改后的地址 |
| contacts | 否 | contact_ctrol | 描述见7.0.8联系人修改控制结构， 对应的内容为 custm.contacts, 以contact_ctrol.contactid 为对应关系分一下情况，增量更新 |
| followers | 否 | bool | 表示跟进人是否需要修改，具体的新增或者删除参考7.0.2 的fctype的设置，fctype的默认值为0 |
| lbl | 否 | bool | 修改标签，增量更新 |
| custmno | 否 | bool | 修改客户编号 |
| websites | 否 | bool | 修改网址 |
| introduction | 否 | bool | 修改备注 |
| follow_level | 否 | bool | 修改跟进阶段 |
在修改请求中找到
旧的信息中未找到，为新增(contactid请置为-1)
旧的信息找到，为修改
在修改请求中未找到，旧的信息中找到为删除情况
在修改请求中 父子标签均有
原始客户信息中，没有则为新增，有则为修改
在修改请求中 只有父标签
原始客户信息中，有则为删除
7.0.8 联系人修改控制结构
xxxxxxxxxx{"contactid":0,"sex":true,"name":true,"note":true,"wechat":true,"weibo":true,"birthday":true,"address":true,"hobby":true,"title":true,"mobile":true,"phone":true,"im":true,"mail":true,"fax":true}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| contactid | 是 | Int64 | 表示需要修改的哪一个联系人 |
| sex | 否 | bool | 修改联系人性别 取值见客户联系人 7.0.1 |
| name | 否 | bool | 修改联系人名字 |
| note | 否 | bool | 修改联系人备注 |
| 否 | bool | 修改微信 | |
| 否 | bool | 修改微博 | |
| birthday | 否 | bool | 修改联系人生日 |
| address | 否 | bool | 修改联系人地址 |
| hobby | 否 | bool | 修改联系人兴趣爱好 |
| title | 否 | bool | 修改联系人职称 |
| mobile | 否 | bool | 修改联系人手机 |
| phone | 否 | bool | 修改座机 |
| im | 否 | bool | 修改qq |
| 否 | bool | 修改邮件 | |
| fax | 否 | bool | 修改传真 |
7.1 导出客户
应用向口袋助理系统发送请求
GET
https://api.kdzl.cn/cgi-bin/customer/export?access_token=234578fe23d4&start=0&count=1000
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| start | 否 | int32 | 开始导出客户的位置，不填默认从第一个开始 |
| count | 否 | int32 | 本次拉取最多返回的客户个数，不填默认值是1000.该值最小取1，最大取2000. |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result":"0","errmsg":"ok","custms": [{"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参数中，能够从上一次的导出位置开始。 |
7.2 导入客户
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/cgi-bin/customer/import?access_token=234578fe23d
请求包结构体，请求结构体里面的客户的参数字段，只列举的部分，全部字段和自定义字段，请导出后对应填写
xxxxxxxxxx{"op_pid": 11,"custms": [{"name": "test","addr": "深圳市南山区","contacts": [{"name": "我是一个联系人","mobiles": ["123456", "78910"]}],"followers": [{"pid": 11}],"lbl_doc": {"clbls": [{"lbl": {"lbl_id": 3,"lbl_name": "通话状态"},"sub_lbls": [{"lbl": {"lbl_id": 650,"lbl_name": "已接听"}}]}]}}]}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| op_pid | 是 | Int64 | moa中对应的操作人的人员id |
| custms | 是 | []customer | customer的描述 见7.0.3 |
| psid | 否 | int64 | 公海id |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"errmsg": "ok","infos": [{"result": 0,"errmsg": "ok","custmid": 30305}]}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| infos | []info | result 表示这个客户导入的情况, 不为0表示出错， errmsg 为出错信息 custmid 对应这个客户信息的唯一id, infos返回顺序与请求顺序一致 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -2147483640 | "db read faild" | 读数据失败 请重试 |
| -2147469820 | "custm dom not found" | 公司信息节点未找到 请重试 |
| -2147483642 | "custm name miss" | 客户名字未填写 |
| -2147469781 | "followers invalid" | 无效的跟进人 |
| -2147469808 | "alloc id faild." | 分配id失败 |
| 0 | "ok" | 成功 |
| -2147483639 | "db write failed." | 写数据库失败 |
7.3 获取公司客户标签设置
应用向口袋助理系统发送请求
GET
https://api.kdzl.cn/cgi-bin/customer/getlabel?access_token=234578fe23d
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"lbl_doc": {"clbls": [{"lbl": {"lbl_id": 3,"lbl_name": "通话状态","sort_id": 0},"sub_lbls": [{"lbl": {"lbl_id": 650,"lbl_name": "已接听","sort_id": 0},"sub_lbls": []},{"lbl": {"lbl_id": 651,"lbl_name": "未接听","sort_id": 1},"sub_lbls": []}]}],"version": 18},"errmsg": "ok"}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| lbl_doc | label_doc | label_doc 描述见 7.0.4 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -2147483640 | "db read faild" | 读数据失败 请重试 |
| 0 | "ok" | 成功 |
7.4 修改客户信息
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/cgi-bin/customer/modify?access_token=234578fe23d
请求包结构体（修改标签的一个例子），请求结构体里面的客户的参数字段，只列举的部分，全部字段和自定义字段，请导出后对应填写
xxxxxxxxxx{"custm": {"custmid": 30272,"lbl_doc": {"clbls": [{"lbl": {"lbl_id": 3,"lbl_name": "通话状态"}},{"lbl": {"lbl_id": 1,"lbl_name": "客户来源"},"sub_lbls": [{"lbl": {"lbl_id": 628,"lbl_name": "公司资源"}}]},{"lbl": {"lbl_id": 2,"lbl_name": "客户级别"},"sub_lbls": [{"lbl": {"lbl_id": 632,"lbl_name": "普通客户"}}]}]}},"custctrol": {"lbl": true},"op_pid": 11}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| custm | 是 | Int64 | 见客户信息 7.0.3 其中的客户id必填 根据对应的id修改对应的客户信息，需要被修改成的客户信息 |
| custctrol | 是 | modify_ctrol | ctrl的描述 见7.0.7 |
| op_pid | 是 | Int64 | 必须是对应客户信息的跟进人中的一个的pid，不然修改会没有权限 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"custm": {"custmid": 30272,"version": 4,"name": "测试5","contacts": [],"name_swords": [],"followers": [{"pid": 11,"start_time": 1550914763970}],"create_pid": 11,"create_time": 1550914763969,"modify_pid": 11,"modify_time": 1562146102472,"status": 1,"lbl_doc": {"clbls": [{"lbl": {"lbl_id": 1,"lbl_name": "客户来源"},"sub_lbls": [{"lbl": {"lbl_id": 628,"lbl_name": "公司资源"},"sub_lbls": []}]}, {"lbl": {"lbl_id": 2,"lbl_name": "客户级别"},"sub_lbls": [{"lbl": {"lbl_id": 632,"lbl_name": "普通客户"},"sub_lbls": []}]}]},"attrs": [],"websites": [],"properties": [],"fcnt": 0,"order_cnt": 0},"errmsg": "ok"}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| custm | customer | customer的描述 见7.0.3 修改后的客户信息 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -2147483642 | "invalid parameter" | 参数错误 |
| -2147469820 | "custm dom not found" | 公司信息节点未找到 请重试 |
| -2147469807 | "custm has been deleted" | 客户信息已删除 |
| -2147469803 | "no permission to modify" | 没有权限修改 |
| 0 | "ok" | 成功 |
| -2147483640 | "db read faild" | 读数据库失败 |
| -2147483639 | "db write failed" | 写数据库失败 |
7.5 查询客户id
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/cgi-bin/customer/query?access_token=234578fe23d
请求包结构体（修改标签的一个例子）
xxxxxxxxxx{"phones": ["456", "123"]}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| phones | 是 | []string | 需要查询的电话号码，联系人手机号码座机号码两个字段全匹配，没有匹配返回空 最多10条 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"infos": [{"phone": "456","custmids": []}, {"phone": "123","custmids": [30242]}],"errmsg": "ok"}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| infos | []info | "phone" 查询的电话号码 "custmids" 匹配的客户id |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -2147483642 | "invalid parameter" | 参数错误 |
| -2147469820 | "custm dom not found" | 公司信息节点未找到 请重试 |
| 0 | "ok" | 成功 |
7.6 查询客户信息
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/cgi-bin/customer/getcustm?access_token=234578fe23d
请求包结构体（修改标签的一个例子）
xxxxxxxxxx{"custmids": [30310, 123]}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| custmids | 是 | []int64 | 需要查询的客户id 最多查询50条 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"errmsg": "ok","custms": [{"errmsg": "ok","result": 0,"custm": {"custmid": 30310,"version": 1,"name": "test","addr": "深圳市南山区","contacts": [{"contactid": 1,"name": "我是一个联系人","titles": [],"mobiles": ["123456", "78910"],"phones": []}],"name_swords": [],"followers": [{"pid": 11,"start_time": 1562135201507}],"create_pid": 11,"create_time": 1562135201507,"modify_pid": 11,"modify_time": 1562135201507,"status": 1,"lbl_doc": {"clbls": [{"lbl": {"lbl_id": 3,"lbl_name": "通话状态"},"sub_lbls": [{"lbl": {"lbl_id": 650,"lbl_name": "已接听"},"sub_lbls": []}]}]},"attrs": [],"websites": [],"properties": []}},{"errmsg": "custm not found","result": -2147469821,"custm": {"custmid": 123,"contacts": [],"name_swords": [],"followers": [],"attrs": [],"websites": [],"properties": []}}]}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| custms | []custm_info | custm_info{ result int32 //错误码 errmsg string //错误描述 custm customer //客户信息 描述见 7.0.3 } |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -2147483642 | "invalid parameter" | 参数错误 |
| -2147469820 | "custm dom not found" | 公司信息节点未找到 请重试 |
| 0 | "ok" | 成功 |
| -2147469807 | "custm has been deleted" | 客户已经删除 |
| -2147469821 | "custm not found" | 客户不存在 |
| -2147483640 | "db read faild" | 读数据库失败 |
7.7 通过MD5查询客户信息
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/open/api/customer/findCustomerByMd5?access_token=234578fe23d
请求包结构体
xxxxxxxxxx{"md5": ["564a474f0b56ea46b2097b50e22da466","68873aaf11d2a433c9a993b708dfc506"]}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| md5 | 是 | []string | 需要查询的客户md5 最多查询2000条 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"data": {"md5": ["68873aaf11d2a433c9a993b708dfc506","564a474f0b56ea46b2097b50e22da466"]}}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| md5 | []string | 存在的客户MD5 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -2147483642 | "invalid parameter" | 参数错误 |
| -2147483640 | "db read faild" | 读数据库失败 |
7.8 查询公海列表
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/open/api/customer/getPubSeaList?access_token=234578fe23d
请求包结构体
xxxxxxxxxx{"rtype":1,"size":20,"opPid:1}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| rtype | 是 | int32 | 权限类型1 获取我管理的 2获取我作为成员的 3获取我管理的和我作为成员的 4获取我管理的和 我仅作为成员的并且可以领取的 5获取公司所有的 默认按照创建时间排序 |
| size | 是 | int32 | 获取数量范围1-5000 |
| startPsid | 否 | int64 | 起始psid |
| status | 否 | int32 | 2表示当前处于管理，1表示当前处于成员，第一页不填，分页需带上下发的 |
| opPid | 是 | int64 | 操作人 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"data": {"total":1,"ended":true,"list": []}}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| total | int32 | 总数 |
| list | []*PubSeaInfo | 公海列表PubSeaInfo{id:int64,name:string,gids:[]int64,pids:[]int64,managers:[]int64} |
| ended | bool | 是否结束 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -2147483642 | "invalid parameter" | 参数错误 |
| -2147483640 | "db read faild" | 读数据库失败 |
7.9 获取属性
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/open/api/customer/getCustomerAttrs?access_token=234578fe23d
请求包结构体
xxxxxxxxxx{"opPid":1}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| opPid | 是 | int64 | 操作人 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"data": {"attrs": [],"props":[]}}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| attrs | []*CustmAttr | 基础属性 |
| props | []*CustmProperty | 自定义属性 |
CustmProperty结构
| 参数 | 类型 | 描叙 |
|---|---|---|
| propId | int32 | 不等于0 表示发生了错误 |
| propPosition | string | 错误描述 正常返回 "ok" |
| propName | string | 属性名 |
| propValue | string | 属性值 |
| dataType | int32 | 0 文本，1 数字，2 时间年月日，3 时间年月日时分，4 单选框 5 多选框 6 邮箱 7 网址 8 快递单号 |
| mustFill | int32 | 是否必填,1 是 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -2147483642 | "invalid parameter" | 参数错误 |
| -2147483640 | "db read faild" | 读数据库失败 |
7.10 另一个导出客户
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/open/api/customer/exportCustomer?access_token=234578fe23d
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| start | 是 | int32 | 第一次导出传0，后续迭代传上一次获取到的客户列表最后一个客户的custmid |
| psid | 否 | int64 | 公海id |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result":"0","errmsg":"ok","custms": [{"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参数中，能够从上一次的导出位置开始。 |
7.11通过手机号前8位查询客户信息
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/open/api/customer/findCustomerByPhonePrefix?access_token=234578fe23d
请求包结构体
xxxxxxxxxx{"phone_prefix": "11111111"}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| phone_prefix | 是 | string | 需要查询的客户手机号前8位 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"data": {"md5": ["68873aaf11d2a433c9a993b708dfc506","564a474f0b56ea46b2097b50e22da466"]}}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| md5 | []string | 存在的客户MD5 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -2147483642 | "invalid parameter" | 参数错误 |
| -2147483640 | "db read faild" | 读数据库失败 |
7.12 aes加密导入客户
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/open/api/customer/importEncryptCustomer?access_token=234578fe23d
请求包结构体
xxxxxxxxxx{"decryptType": "aes","sign": "xxxxxx"}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| decryptType | 是 | string | 固定为ase加密解密模式 |
| sign | 是 | string | 对7.2接口json请求加密后的字符串 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"data": {"encryptSign": "rKaxdyS/Gys2GRMQhc7d7xGqViF9xgo6IfcImwW+GCkuzayMA9VyQJBSOJIzMspTZoVn/IWgKGLeY4K4nNOa8A=="}}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| data | object | 包含encryptSign加密后的字符串 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -1001 | "无效token" | token错误 |
| -2147483640 | "db read faild" | 读数据库失败 |
7.13 aes加密查询客户
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/open/api/customer/findEncryptCustomer?access_token=234578fe23d
请求包结构体
xxxxxxxxxx{"decryptType": "aes","sign": "xxxxxx"}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| decryptType | 是 | string | 固定为ase加密解密模式 |
| sign | 是 | string | 对7.7接口json请求加密后的字符串 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"data": {"encryptSign": "491HuEWdprxVb6cGRo5Xl0hou32NOdMJk8nncDO4T3yUMJpxpAPuTkvlaODeDOuI/pRwevhi6QE5Lg5I49KYs2wPjKI6h0YqWnBDxcBRzoJPNl5FfCRzaQBb5CYmOlu3O28RTKP0KXD+1KxfSzlMOhyr1z4G1I8BX3JBdlYVKZE="}}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| data | object | 包含encryptSign加密后的字符串 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -1001 | "无效token" | token错误 |
| -2147483640 | "db read faild" | 读数据库失败 |
7.14 aes加密手机号前8位查询客户
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/open/api/customer/findCustomerByEncryptPhonePrefix?access_token=234578fe23d
请求包结构体
xxxxxxxxxx{"decryptType": "aes","sign": "xxxxxx"}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| decryptType | 是 | string | 固定为ase加密解密模式 |
| sign | 是 | string | 对7.11接口json请求加密后的字符串 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"data": {"encryptSign": "491HuEWdprxVb6cGRo5Xl0hou32NOdMJk8nncDO4T3yUMJpxpAPuTkvlaODeDOuI/pRwevhi6QE5Lg5I49KYs2wPjKI6h0YqWnBDxcBRzoJPNl5FfCRzaQBb5CYmOlu3O28RTKP0KXD+1KxfSzlMOhyr1z4G1I8BX3JBdlYVKZE="}}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| data | object | 包含encryptSign加密后的字符串 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -1001 | "无效token" | token错误 |
| -2147483640 | "db read faild" | 读数据库失败 |
8.流程管理
8.1 流程导出
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/cgi-bin/workflow/exportProcess?access_token=234578fe23d4
请求包结构体
xxxxxxxxxx{"type": 1,"status":1,"satrtTime":1520386759000,"endTime":1520386759000,"pid":8359,"start":0,"limit":30,}
参数说明：
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| type | 否 | int32 | 列表类型，0或者不传 全部 1 指定人申请 2 指定人审批 3 抄送给指定人 |
| status | 否 | int32 | 流程状态， -1或者不传 0 驳回 1审批中 3 流程结束 |
| satrtTime | 否 | int64 | 筛选起始时间 |
| endTime | 否 | int64 | 筛选结束时间 |
| pid | 否 | int64 | 筛选人，值为用户ID，指定人 type 为0 可以不传 type 不为0 必传 |
| start | 否 | int32 | 筛选起始流程ID，不填为0 |
| limit | 否 | int32 | 分页每页数量，最大1000 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result":0,"retTime":1635817727000,"list":[{"processInstId":"105511","submitUser":11,"submitUserName":"张正龙","departmentName":"/","submitTime":1635817772000,"endTime":1635817772000,"processDefineId":5,"processNameId":"proc5_10000:1:100304","processName":"412312","processStatus":1,"workflowNum":"A202111020002","from":[{"itemId":9,"label":"加班时长","xtype":"totalhoursfield","data":"16小时"},{"itemId":11,"label":"加班时间","xtype":"timehourarray","data":"11月4日 09:00 - 11月5日 09:00"},{"itemId":13,"label":"理由","xtype":"textfield","data":"1212"},{"itemId":459,"label":"备注","xtype":"textfield","data":"12121"}],"comments":[{"taskId":"105515","taskName":"提交申请","reason":"","opt":1,"opinion":1,"dealTime":1635817772000,"pid":11,"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
请求包结构体
xxxxxxxxxx{"gids":[1],"pids":[2],"start":1,"count":20,}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| gids | 否 | []int64 | 部门id，获取该部门成员的考勤结果(无需考勤成员除外) |
| pids | 否 | []int64 | 成员id，获取该成员的考勤结果，gids与pids为空则获取所有成员的考勤结果 |
| start | 是 | int32 | 分页使用，从第几条开始，第一次拉取时填1 |
| count | 是 | int32 | 一次拉取多少条，最大值不能超过2000条（后续支持，目前1000条），默认100条，1条表示一个人在筛选时间段内的所有考勤记录 |
| stime | 是 | int64 | 开始日期，时间戳，毫秒 |
| etime | 是 | int64 | 结束日期，时间戳，毫秒，开始日期与结束日期不能超过1年（后续支持，目前两个月内） |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"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
请求包结构体
xxxxxxxxxx{"start":0,"count":20,}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| start | 否 | int32 | 开始导出销售订单的位置，不填默认从最新创建的订单开始拉取，获取当前页订单时，填上一页最后一个订单的order_id |
| count | 否 | int32 | 本次拉取最多返回的客户个数，不填默认值是1000.该值最小取1，最大取1000. |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"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：数字/2：YYMMDD格式日期/ 3：YYMMDDHHmm格式日期/4：单选框/5：其他/6：多选框 |
| custom_props.prop_value | 销售订单自定义属性具体值 |
11.商品管理
11.1 导出商品
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/cgi-bin/product/export?access_token=234578fe23d4
请求包结构体
xxxxxxxxxx{"start":0,"count":20,}
参数说明
| 参数 | 是否必须 | 描叙 |
|---|---|---|
| access_token | 是 | 调用接口凭证 |
| start | 否 | 开始导出商品的位置，不填默认从最新创建的商品开始拉取，获取当前页商品时，填上一页最后一个商品的 product_id |
| count | 否 | 本次拉取最多返回的商品个数，不填默认值是1000.该值最小取1，最大取1000. |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"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
请求包结构体
xxxxxxxxxx{"product_infos":[{"product_id":9,"version":1}]}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| product_infos | 是 | struct | 需要获取详情的商品信息 |
| product_infos.product_id | 是 | int64 | 商品id |
| product_infos.version | 是 | int32 | 商品 version |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"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，可以通过通讯录获取用户接口得到详细的创建人信息。 |
| ....... | 口袋助理还会返回一些没有列出的字段，不关注忽略即可 |
12.跟进记录
12.0 相关结构描述
12.0.1 会话沟通
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| tkid | 否 | Int64 | 会话沟通id 自动生成 |
| uid | 是 | Int64 | 创建人在moa中的人员id |
| gid | 是 | Int64 | 创建在moa中所属的部门 |
| cusid | 是 | Int64 | 该跟进记录对应的客户id |
| content | 是 | String | 沟通内容 不为空 |
| publish_time | 否 | Int64 | 不填自动为当前时间的格林威治时间戳 单位ms, 自己填写的需要做唯一性处理，否则可能会插入失败 |
| modify_time | 否 | Int64 | 导入时与自动与publish_time 一致 |
12.1 导入客户会话沟通
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/cgi-bin/custalk/import?access_token=234578fe23d
请求包结构体
xxxxxxxxxx{"custalks": [{"gid": 1,"uid": 11,"cusid": 30302,"content": "1234577",},{"gid": 1,"uid": 11,"cusid": 30302,"content": "12345778",}]}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| custalks | 是 | []custalk | custalk 描述 见12.0.1 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"errmsg": "ok","infos": [{"result": 0,"errmsg": "ok","tkid": 143},{"result": -2147483642,"errmsg": "cusid missing"}]}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| infos | []info | result 表示这个客户导入的情况, 不为0表示出错， errmsg 为出错信息 tkid对应这个跟进记录的唯一id, infos返回顺序与请求顺序一致 |
错误说明
| result | errmsg | 描述 |
|---|---|---|
| -214748364 | "owner(gid | uid) missing" | 跟进记录 gid uid 存在没有填写的 |
| "cusid missing" | 跟进记录客户id 没有填写 | |
| "content empty" | 跟进记录内容为空 | |
| -2147469564 | "alloc id failed" | 分配id失败 重试即可 |
| "db write failed. unique key(publish_time) dup" | 自己填写的publish_time 与数据库中的出现了冲突，需要修改时间或者不填 | |
| 0 | "ok" | 成功 |
| -2147479039 | "invalid parameter" | 参数错误 |
12.2 导出客户会话沟通
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/cgi-bin/custalk/export?access_token=234578fe23d
请求包结构体
xxxxxxxxxx{"gids": [],"pids": [],"count": 40,"skip": 0,"cusids": [30302],"stime": 1561983061000,"etime": 1561983761000}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| gids | 否 | []int64 | 过滤的部门id 不填不过滤, 不包含子部门 |
| pids | 否 | []int64 | 过滤的人员id 不填不过滤 与gids 为并集关系 |
| cusids | 否 | []int64 | 过滤的客户id |
| stime | 否 | Int64 | 过滤的起始时间 |
| etime | 否 | Int64 | 过滤的结束时间 stime <= publish_time < etime etime - stime <= 31天 etime不填为当前时间,stime不填为etime-31天 单位为ms |
| skip | 否 | Int32 | Skip >= 0, 跳过多少条 |
| count | 否 | Int32 | 0 < count <= 50 一页多少条 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"errmsg": "ok","custalks": [{"tkid": 143,"did": 519383,"uid": 11,"gid": 1,"ver": 1,"cusid": 30302,"content": "1234577","atts": [],"publish_time": 1561969614618,"modify_time": 1561969614618},{"tkid": 142,"did": 519383,"uid": 11,"gid": 1,"ver": 1,"cusid": 30302,"content": "1234577","atts": [],"publish_time": 1561969453670,"modify_time": 1561969453670}]}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | Int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 正常返回 "ok" |
| custalks | []custalk | 跟进记录信息 |
错误说明
| result | errmsg | 描叙 |
|---|---|---|
| 0 | "ok" | 成功 |
| -2147483642 | "param invalid" | 参数错误 |
| "count:[1, 50];skip:[0,+oo]" | count 和 skip 的值无效 | |
| "time range invalid" | stime 和 etime无效 | |
| -2147483640 | "read data failed. retry" | 读数据失败 请重试 |
| -2147479039 | "invalid parameter" | 参数错误 |
13 外勤轨迹
13.1 获取定位列表
应用向口袋助理系统发送请求
POST
https://api.kdzl.cn/open/api/wt/upload/list?access_token=234578fe23d
请求包结构体
xxxxxxxxxx{"position_time":1677569830945,"count":2,"id":1}
参数说明
| 参数 | 是否必须 | 类型 | 描叙 |
|---|---|---|---|
| access_token | 是 | string | 调用接口凭证 |
| position_time | 是 | int64 | 获取位置时的时间，分页时取返回值last_info.position_time，第一页按需填写 |
| id | 否 | int64 | 唯一id，分页时取返回值last_info.id,第一页0或不填均可 |
| count | 是 | int32 | 一页多少条 |
返回说明
正常情况下，口袋助理系统返回下述JSON包
xxxxxxxxxx{"result": 0,"data": {"infos": [{"point": {"longitude": 113.96343,"latitude": 22.585463,"time": 1677570116892,"pt": 0,"radius": 29,"addr": "广东省深圳市南山区丽山路65号靠近尚韩韩语教室","gen_type": 1},"position_time": 1677570082569,"pid": 16,"id": 2}, {"point": {"longitude": 113.96343,"latitude": 22.585463,"time": 1677570356669,"pt": 0,"radius": 29,"addr": "广东省深圳市南山区丽山路65号靠近尚韩韩语教室","gen_type": 1},"position_time": 1677570322405,"pid": 16,"id": 3}],"end": false,"last_info": {"point": null,"position_time": 1677570322405,"pid": 0,"id": 3}}}
参数说明
| 参数 | 类型 | 描叙 |
|---|---|---|
| result | int32 | 不等于0 表示发生了错误 |
| errmsg | string | 错误描述 |
| data | object | 数据 |
| end | bool | true表示最后一页 |
| last_info | object | 最后一条数据，分页时用 |
| infos | array | 定位信息列表 |
| position_time | int64 | 获取到位置时的时间,精确到ms |
| pid | int64 | 人员ID |
| id | int64 | 唯一ID |
| point | object | 定位相关信息 |
| longitude | float32 | 经度 |
| latitude | float32 | 纬度 |
| time | int64 | 服务端时间,精确到ms |
| pt | int32 | 1(轨迹点),2(非轨迹点),-1(无效位置点) |
| radius | float32 | 定位精度半径.单位米 |
| addr | string | 位置点信息 |
| gen_type | int32 | 1(轨迹上传点),2(签到点) |
错误说明
| result | errmsg | 描叙 |
|---|---|---|
| 0 | "" | 成功 |