上一小节我们完成了项目开发环境的搭建,本小结我们具体介绍一下项目中使用到的接口文档。
本次我们以钉钉开放接口作为项目接口测试的示例,方便大家都能统一学习和调用,具体接口如下:
1、获取企业内部应用的access_token
在获取access_token前,需要在开发者后台查看应用的AppKey和AppSecret:
- 登录钉钉开发者后台。
- 在应用开发页面,单击目标应用进入应用详情页面。
- 在基础信息页面,复制应用的AppKey和AppSecret。
重要
请妥善保管应用的AppKey和AppSecret。
基本信息
请求方式:GET
请求地址:https://oapi.dingtalk.com/gettoken
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
appkey | String | 是 | dingeqqpkv3xxxx | 应用的唯一标识key。 |
appsecret | String | 是 | GT-lsu-taDAsTsxxxx | 应用的密钥。AppKey和AppSecret可在钉钉开发者后台的应用详情页面获取。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
access_token | String | fw8ef8we8f76e6f7s8dxxxx | 生成的access_token。 |
expires_in | Number | 7200 | access_token的过期时间,单位秒。 |
errmsg | String | ok | 返回码描述。 |
errcode | Number | 0 | 返回码。 |
接口详见
获取企业内部应用的access_token - 钉钉开放平台
2、创建公告
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/blackboard/create
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
create_request | OapiCreateBlackboardVo | 是 | 请求对象。 | |
operation_userid | String | 是 | manager01 | 操作人的userId,必须是公告管理员。 |
author | String | 否 | 杨xx | 公告作者。 |
private_level | Number | 否 | 0 | 保密等级:
|
ding | Boolean | 否 | false | 是否发送应用内钉提醒:
|
blackboard_receiver | BlackboardReceiverOpenVo | 是 | 公告接收人。 | |
deptid_list | Number[] | 否 | [1] | 接收部门ID列表,最大的列表长度为20。 |
userid_list | String[] | 否 | ["manager02"] | 接收人userId列表,最大的列表长度为1000。 |
title | String | 是 | 入职须知 | 公告标题。 |
push_top | Boolean | 否 | true | 公告是否置顶。
|
content | String | 是 | 欢迎加入我们的大家庭 | 公告内容。 |
category_id | String | 否 | 987uy66t5rt54er | 公告分类ID。 |
coverpic_mediaid | String | 否 | @lADPDeC2ufXOeRzMqM0BLA | 封面图,格式为@mediaId。 可以通过上传媒体文件接口上传图片,获取media_id参数值。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | Boolean | true | 是否创建成功。
|
success | Boolean | true | 本次调用是否成功。
|
errcode | Number | 0 | 返回码。 |
request_id | String | roz884n3k7rf | 请求ID。 |
接口详见
3、更新公告
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/blackboard/update
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
update_request | OapiUpdateBlackboardVo | 是 | 请求对象。 | |
author | String | 否 | 杨xx | 公告作者。 |
ding | Boolean | 否 | true | 是否发送应用内钉提醒:
|
blackboard_id | String | 是 | 908uhyg76tfr543e | 公告ID。 |
title | String | 是 | 入职须知 | 公告标题。 |
content | String | 是 | 欢迎加入我们的大家庭 | 公告内容。 |
category_id | String | 否 | 89uuy7ytg6bnnjh7 | 公告分类ID,可以通过获取公告分类列表接口获取id参数值。 |
notify | Boolean | 否 | true | 修改后是否再次通知接收人。
|
operation_userid | String | 是 | manager01 | 操作人userid,必须是公告管理员。 |
coverpic_mediaid | String | 否 | @lADPDeC2ufXOeRzMqM0BLA | 封面图,格式为@mediaId。 可以通过上传媒体文件接口上传图片,获取media_id参数值。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | Boolean | true | 是否成功。
|
success | Boolean | true | 本次调用是否成功。
|
errcode | Number | 0 | 返回码。 |
request_id | String | roz884n3k7rf | 请求ID。 |
接口详见
4、删除公告
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/blackboard/delete
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
blackboard_id | String | 是 | 098uyg65ffytr43 | 公告ID,可以通过获取公告ID列表接口获取result参数值。 |
operation_userid | String | 是 | manager01 | 操作人userId,必须是公告管理员。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | Boolean | true | 是否删除成功。
|
success | Boolean | true | 本次调用是否成功。
|
errcode | Number | 0 | 请求失败返回错误信息。 |
errmsg | String | ok | 返回码描述 |
request_id | String | roz884n3k7rf | 请求ID。 |
接口详见
5、获取公告详情
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/blackboard/get
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
blackboard_id | String | 是 | 9uiuihhgui989huh | 公告id,可以通过获取公告ID列表接口获取id参数值。 |
operation_userid | String | 是 | manager01 | 操作人userId。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | Object | OapiBlackboardVo | 公告详情。 |
id | String | 9uiuihhgui989huh | 公告id。 |
author | String | 小明 | 公告作者。 |
title | String | 入职须知 | 公告标题。 |
content | String | 欢迎加入我们的大家庭 | 公告内容。 |
category_id | String | 09ui87hgyytg463634 | 公告分类ID。 |
private_level | Number | 0 | 保密等级。
|
depname_list | String[] | 人事部 | 接收部门列表。 |
username_list | String[] | 小明 | 接收人列表。 |
gmt_create | String | 2019-10-22 14:43:07 | 公告创建时间。 |
gmt_modified | String | 2019-11-22 10:43:07 | 公告最后修改时间。 |
read_count | Number | 10 | 已读人数。 |
unread_count | Number | 1 | 未读人数。 |
coverpic_url | String | https://gw.alicdn.com/tfs/TB1ayl9mpYqK1RjSZLeXXbXppXa-170-62.png | 封面图的url链接。 |
user_list | Object[] | ["user_list":{"staff_id":"001","name":"小明"}] | 接收人列表。 |
staff_id | String | 001 | 员工userId。 |
name | String | 小明 | 员工名字。 |
deptList | Object[] | ["user_list":{"dept_id":"001","name":"人事部"}] | 接收部门列表。 |
dept_id | String | hbjev8364 | 部门ID,该参数已加密。 |
name | String | 人事部 | 部门名称。 |
success | Boolean | true | 本次调用是否成功。
|
errcode | Number | 0 | 返回码。 |
request_id | String | q5ddepxxxx | 请求ID。 |
接口详见
6、获取公告ID列表
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/blackboard/listids
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
query_request | OapiBlackboardQueryVo | 是 | 请求对象。 | |
operation_userid | String | 是 | manager4220 | 操作人userId,必须是公告管理员。 |
page_size | Number | 是 | 10 | 分页大小,从1开始不超过30,且必须为正整数。 |
start_time | Date | 否 | 2019-10-07 10:10:10 | 开始时间。
|
end_time | Date | 否 | 2019-11-07 10:10:10 | 结束时间。
|
page | Number | 是 | 1 | 页码,从1开始且必须为正整数。 |
category_id | String | 否 | 9i9u7y7g6t65 | 分类ID,可以通过获取公告分类列表接口获取id参数值。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | String[] | ["72b4f87d27e815f6fecxxxx"] | 公告ID列表。 |
success | Boolean | true | 本次调用是否成功。
|
errcode | Number | 0 | 返回码。 |
request_id | String | pxxm7ylvmppr | 请求ID。 |
接口详见
7、获取公告分类列表
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/blackboard/category/list
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
operation_userid | String | 是 | manager01 | 操作人userId,必须是公告管理员。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | BlackboardCategoryVo[] | 返回结果。 | |
id | String | 89uuhygybj | 分类ID。 |
name | String | 日签 | 分类名。 |
success | Boolean | true | 本次调用是否成功。
|
errcode | Number | 0 | 返回码。 |
request_id | String | ie9aarwu1m1t | 请求ID。 |
接口详见
8、获取用户可查看的公告
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/blackboard/listtopten
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
userid | String | 是 | manager01 | 员工的userId。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
errcode | Number | 0 | 返回码。 |
request_id | String | 3y4bln1b7e7q | 请求ID。 |
blackboard_list | OapiBlackboardVo[] | 返回结果。 | |
gmt_create | Date | 2020-09-08 14:42:12 | 创建时间。 |
title | String | 放假通知。 | 公告标题。 |
url | String | https://app.dingtalk.com/xxxx | 跳转URL。 |
categoryId | String | 576920db | 公告分类ID。 |
id | Sting | a3071449 | 公告ID。 |
接口详见
9、创建日志
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/report/create
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | bE3xxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
create_report_param | OapiCreateReportParam | 是 | 创建日志的参数对象。 | |
contents | OapiReportContentVo[] | 是 | 日志内容数组,根据该日志模板中每一项信息传参。 | |
template_id | String | 是 | 12345abcde | 模板ID。 |
to_userids | String[] | 否 | ["123","456"] | 日志发送到的员工userId。 |
to_chat | Boolean | 是 | true | 发送日志到员工时是否发送单聊消息。
|
to_cids | String[] | 否 | 123 | 日志要发送到的群ID。 重要
进入钉钉工作台,然后选择日志 > 模板管理 > 权限设置 > 默认发送范围,设置该日志模板的默认接收群。 |
dd_from | String | 是 | report | 日志来源,每个组织可以自己起一个唯一的来源标识,自定义的值。 |
userid | String | 是 | 12345 | 创建日志的员工userId。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
errmsg | String | ok | 返回码描述。 |
errcode | Number | 0 | 返回码。 |
result | String | 175abec4de6bd | 调用结果。 |
接口详见
10、获取模板详情
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/report/template/getbyname
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | bE3xxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
userid | String | 是 | 12345 | 操作该接口的员工userId。 |
template_name | String | 是 | 日报 | 模板名称。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | ReportTemplateResponseVo | 返回结果。 | |
default_receivers | DefaultReceivers[] | 模板默认接收人。 | |
user_name | String | 用户1 | 默认接收人名称。 |
userid | String | 111 | 默认接收人员工的userId。 |
name | String | 周报 | 模板名称。 |
id | String | 12345abcde | 模板ID。 |
fields | Fields[] | 日志模板内各字段的信息。 | |
field_name | String | 字段1 | 模板字段名称。 |
type | Number | 1 | 字段类型。 |
sort | Number | 0 | 模板字段在当前模板内排序。 |
user_name | String | 小明 | 操作该接口的员工姓名。 |
userid | String | 12345 | 操作该接口的员工userId。 |
default_received_convs | BaseConversationVo[] | 默认接收群。 说明 模板中如果没有设置默认接收群,该字段不会返回。 | |
conversation_id | String | 1223445 | 该日志模板的默认接收群ID。 说明 进入钉钉工作台,然后选择日志 > 模板管理 > 权限设置 > 默认发送范围,设置该日志模板的默认接收群。 |
title | String | 群名称 | 群名称。 |
errcode | Number | 0 | 返回码。 |
errmsg | String | ok | 返回码描述。 |
接口详见
11、获取用户发出的日志列表
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/report/list
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
start_time | Number | 是 | 1507564800000 | 查询的日志创建的开始时间,Unix时间戳,单位毫秒。 说明 start_time参数和end_time参数最多相隔180天。 |
end_time | Number | 是 | 1507564800000 | 查询的日志创建的结束时间,Unix时间戳,单位毫秒。 说明 start_time参数和end_time参数最多相隔180天。 |
template_name | String | 否 | 周报 | 要查询的模板名称。 |
userid | String | 否 | user123 | 员工的userId。 |
cursor | Number | 是 | 0 | 查询游标,初始传入0,后续从上一次的返回值中获取。 |
size | Number | 是 | 10 | 每页数据量,最大值为20。 |
modified_start_time | Number | 否 | 1507564800000 | 查询的日志修改的开始时间,Unix时间戳,单位毫秒。 |
modified_end_time | Number | 否 | 1507564800000 | 查询的日志修改的结束时间,Unix时间戳,单位毫秒。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | PageVo | 返回结果。 | |
data_list | ReportOapiVo[] | 日志列表。 | |
contents | JsonObject[] | 日志内容。 | |
sort | String | 1 | 排序。 |
type | String | 0 | 日志类型。 |
value | String | 开发工作 | 用户填写的内容。 |
key | String | 今日工作 | 模板内容。 |
remark | String | 这是备注 | 备注。 |
template_name | String | 日报 | 日志模板名称。 |
dept_name | String | 部门1 | 部门。 |
creator_name | String | 张三 | 日志创建人。 |
creator_id | String | user123 | 日志创建人的userId。 |
create_time | Number | 1507564800000 | 日志创建时间。 |
report_id | String | xxxxxxx | 日志ID。 |
modified_time | Number | 1507564800000 | 日志修改时间。 |
size | Number | 10 | 分页大小。 |
next_cursor | Number | 10000 | 下一游标。 |
has_more | Boolean | false | 是否还有下一页数据。
|
errcode | Number | 0 | 返回码。 |
errmsg | String | ok | 返回码描述。 |
接口详见
12、获取用户发送日志的概要信息
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/report/simplelist
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
start_time | Number | 是 | 1507564800000 | 查询起始时间,Unix时间戳,单位毫秒。 说明 start_time参数和end_time参数最多相隔180天。 |
end_time | Number | 是 | 1507564800000 | 查询截止时间,Unix时间戳,单位毫秒。 说明 start_time参数和end_time参数最多相隔180天。 |
template_name | String | 否 | 周报 | 要查询的模板名称。 |
userid | String | 否 | user123 | 员工的userId。 |
cursor | Number | 是 | 0 | 查询游标,初始传入0,后续从上一次的返回值中获取。 |
size | Number | 是 | 10 | 每页数据量,最大为20。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | PageVo | 返回结果。 | |
data_list | ReportOapiVo[] | 日志列表。 | |
remark | String | 日报 | 备注。 |
template_name | String | 日报 | 日志模板名。 |
dept_name | String | 市场部 | 部门。 |
creator_name | String | 杨xx | 日志创建人。 |
creator_id | String | manager4220 | 日志创建人userId。 |
create_time | Number | 1507564800000 | 日志创建时间。 |
report_id | String | 1746xxxx | 日志ID。 |
size | Number | 10 | 分页大小。 |
next_cursor | Number | 10000 | 下一页的游标,当返回结果里没有next_cursor时,表示分页结束。 |
has_more | Boolean | false | 是否还有下一页数据。
|
errcode | Number | 0 | 返回码。 |
request_id | String | 3qwbhu6edlcz | 请求ID。 |
接口详见
13、获取日志相关人员列表
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/report/statistics/listbytype
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
report_id | String | 是 | 17469xxx | 日志ID。
|
type | Number | 是 | 0 | 查询类型:
|
offset | Number | 否 | 0 | 分页查询的游标,最开始传0,后续传返回参数中的next_cursor值,默认值为0。 |
size | Number | 否 | 100 | 分页参数,每页大小,最多传100,默认值为100。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
success | Boolean | true | 是否成功。
|
request_id | String | p0gvgqih0nfv | 请求ID。 |
errcode | Number | 0 | 返回码。 |
result | ReportPageVo | 返回结果。 | |
next_cursor | Number | 100 | 下一次分页调用的offset值,当返回结果里没有next_cursor时,表示分页结束。 |
has_more | Boolean | true | 是否还有下一页数据。
|
userid_list | String[] | ["user123","user456"] | userId列表。 |
接口详见
14、获取日志接收人员列表
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/report/receiver/list
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
report_id | String | 是 | 174xxxx | 日志ID。
|
offset | Number | 否 | 0 | 分页查询的游标,最开始传0,后续传返回参数中next_cursor的值,默认值为0。 |
size | Number | 否 | 100 | 分页参数,每页大小,最多传100,默认值为100。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | ReportPageVo | 返回结果。 | |
has_more | Boolean | true | 是否还有下一页数据。
|
next_cursor | Number | 100 | 下一次分页调用的offset值,当返回结果里没有next_cursor时,表示分页结束。 |
userid_list | String[] | ["user123","user456"] | 日志接收人userId列表。 |
errcode | Number | 0 | 返回码。 |
errmsg | String | p0gvgqih0nfv | 请求ID。 |
success | Boolean | true | 是否成功。
|
接口详见
15、获取日志评论详情
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/report/comment/list
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
report_id | String | 是 | 174xxxx | 日志ID。
|
offset | Number | 否 | 0 | 分页查询的游标,最开始传0,后续传返回参数中的next_cursor值,默认值为0。 |
size | Number | 否 | 20 | 分页参数,每页大小,最多传20,默认值为20。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | ReportPageVo | 返回结果。 | |
comments | ReportCommentVo[] | 日志评论详情。 | |
create_time | Date | 2020-09-08 00:26:37 | 评论时间。 |
content | String | 不错 | 评论内容。 |
userid | String | user456 | 评论人ID。 |
has_more | Boolean | true | 是否还有下一页。
|
next_cursor | Number | 20 | 下一次分页调用的offset值,当返回结果里没有next_cursor时,表示分页结束。 |
errcode | Number | 0 | 返回码。 |
request_id | String | 5kngbdmfdrle | 请求ID。 |
success | Boolean | true | 调用结果。
|
接口详见
16、获取用户日志未读数
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/report/getunreadcount
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
userid | String | 是 | user123 | 要获取的员工userId。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
count | Number | 2 | 员工日志未读数。 |
request_id | String | wp9ie6b3d8pg | 请求ID。 |
errcode | Number | 0 | 返回码。 |
errmsg | String | ok | 返回的错误信息。 |
接口详见
17、获取用户可见的日志模板
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/report/template/listbyuserid
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
userid | String | 否 | manager7078 | 员工的userId。 说明 不传递表示获取所有日志模板。 |
offset | Number | 否 | 0 | 分页游标,从0开始。根据返回结果里的next_cursor是否为空来判断是否还有下一页,且再次调用时offset设置成next_cursor的值。 |
size | Number | 否 | 100 | 分页大小,最大可设置成100。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
request_id | String | kszb71rpxu7u | 请求ID。 |
errcode | Number | 0 | 返回码。 |
errmsg | String | ok | 错误信息 |
result | HomePageReportTemplateVo | 返回结果。 | |
template_list | ReportTemplateTopVo[] | 模板列表。 | |
name | String | 日报 | 日志模板名称。 |
icon_url | String | https://landray.dingtalkapps.com/alid/app/report/images/ico-png/0.png | 模板图标URL。 |
report_code | String | 14e882e7fd7e774e40ce9d144ddaa84d | 模板Code。 |
url | String | https://landray.dingtalkapps.com/alid/app/report/createReport_new.html?skip=0&corpid=${corpid}&id=${report_code} | 模板URL。 |
next_cursor | Number | 100 | 下一次分页调用的offset值,当返回结果里没nextCursor时,表示分页结束。 |
接口详见
18、获取待入职员工列表
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/querypreentry
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
offset | Number | 是 | 0 | 分页游标,从0开始。根据返回结果里的next_cursor是否为空来判断是否还有下一页,且再次调用时offset设置成next_cursor的值。 |
size | Number | 是 | 50 | 分页大小,最大50。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | PageResult | 返回结果。 | |
next_cursor | Number | 10 | 下一次分页调用的offset值,当返回结果里没有nextCursor时,表示分页结束。 |
data_list | String[] | ["11","22"] | 查询到的待入职员工userid。 |
errcode | Number | 0 | 返回码。 |
errmsg | String | ok | 返回码描述。 |
success | Boolean | false | 是否调用成功。
|
request_id | String | 64jz549xdj6q | 请求ID。 |
接口详见
19、获取在职员工列表
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/queryonjob
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
status_list | String | 是 | 2,3,5,-1 | 在职员工状态筛选,可以查询多个状态。不同状态之间使用英文逗号分隔。
|
offset | Number | 是 | 0 | 分页游标,从0开始。根据返回结果里的next_cursor是否为空来判断是否还有下一页,且再次调用时offset设置成next_cursor的值。 |
size | Number | 是 | 50 | 分页大小,最大50。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | PageResult | 返回结果。 | |
data_list | String | ["user123"] | 查询到的员工userid。 |
next_cursor | Number | 0 | 下一次分页调用的offset值,当返回结果里没有next_cursor时,表示分页结束。 |
errcode | Number | 0 | 返回码。 |
errmsg | String | ok | 返回码描述。 |
success | Boolean | false | 是否调用成功。
|
request_id | String | u2nu5vpoq6p | 请求ID。 |
接口详见
20、获取离职员工列表
调用本接口,查询企业离职员工userId列表。
例如,在企业智能人事应用中查看已离职员工列表,如下图所示。
调用本接口,可获取企业下已离职员工的userId列表。
权限
要调用此API,需要以下权限之一。
应用类型 | 是否支持 | 权限 | API Explorer调试 |
企业内部应用 | 支持 | 智能人事个人信息读权限 | |
第三方企业应用 | 支持 | 智能人事个人信息读权限 |
请求方法
GET /v1.0/hrm/employees/dismissions?nextToken=Long&maxResults=Integer HTTP/1.1
Host:api.dingtalk.com
x-acs-dingtalk-access-token:String
Content-Type:application/json
Header参数
名称 | 类型 | 是否必填 | 描述 |
x-acs-dingtalk-access-token | String | 是 | 调用该接口的访问凭证。
|
Query参数
名称 | 类型 | 是否必填 | 描述 |
nextToken | Long | 否 | 分页查询的游标。
|
maxResults | Integer | 否 | 每页条目数,默认值30,最大值50。 |
返回参数
名称 | 类型 | 描述 |
nextToken | Long | 分页游标。 |
hasMore | Boolean | 是否还有更多数据, 以此为依据判断是否继续查询下一页。
|
userIdList | Array of String | 返回的离职人员userId列表。 |
接口详见
21、获取用户签到记录
基本信息
请求方式:POST
请求地址:https://oapi.dingtalk.com/topapi/checkin/record/get
Query参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
access_token | String | 是 | 6d1bxxxx | 调用该接口的应用凭证。
|
Body参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
userid_list | String | 是 | manager4220 | 需要查询的用户列表,最大列表长度为10。 |
start_time | Number | 是 | 1605437194000 | 开始时间,Unix时间戳,单位毫秒。 |
end_time | Number | 是 | 1605786394000 | 截止时间,单位毫秒。
|
cursor | Number | 是 | 0 | 分页查询的游标,最开始可以传0。 |
size | Number | 是 | 100 | 分页查询的每页大小,最大100。 |
返回参数
名称 | 类型 | 示例值 | 描述 |
result | PageResult | 返回结果。 | |
next_cursor | Number | 100 | 下次查询的游标,为null代表没有更多的数据。 |
page_list | CheckinRecordVo[] | 签到信息。 | |
checkin_time | Number | 1494852872446 | 签到时间,单位毫秒。 |
image_list | String[] | ["https://static.dingtalk.com/media/xxxx"] | 签到照片URL列表。 说明 如果签到没有上传图片,不返回该字段。 |
detail_place | String | 杭州市余杭区五常街道 | 签到详细地址。 |
remark | String | 备注 | 签到备注。 |
userid | String | 080517 | 签到用户userId。 |
place | String | 绿城未来park | 签到地址。 |
longitude | String | 120.017394 | 签到位置经度(暂未开放)。 |
latitude | String | 30.286046 | 签到位置维度(暂未开放)。 |
visit_user | String | 刘先生 | 签到的拜访对象,可以为外部联系人的userId或者用户自己输入的名字。 |
errcode | Number | 0 | 返回码。 |
request_id | String | pod643x3uywf | 请求ID。 |
接口详见
最后感谢每一个认真阅读我文章的人,礼尚往来总是要有的,虽然不是什么很值钱的东西,如果你用得到的话可以直接拿走,希望可以帮助到大家!