接口自动化测试框架实战-2-项目接口文档

上一小节我们完成了项目开发环境的搭建，本小结我们具体介绍一下项目中使用到的接口文档。

本次我们以钉钉开放接口作为项目接口测试的示例，方便大家都能统一学习和调用，具体接口如下：

1、获取企业内部应用的access_token

在获取access_token前，需要在开发者后台查看应用的AppKey和AppSecret：

1. 登录钉钉开发者后台。
2. 在应用开发页面，单击目标应用进入应用详情页面。
3. 在基础信息页面，复制应用的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	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
create_request	OapiCreateBlackboardVo	是		请求对象。
operation_userid	String	是	manager01	操作人的userId，必须是公告管理员。
author	String	否	杨xx	公告作者。
private_level	Number	否	0	保密等级： 0：普通公告 20：保密公告
ding	Boolean	否	false	是否发送应用内钉提醒： true：发送 false：不发送
blackboard_receiver	BlackboardReceiverOpenVo	是		公告接收人。
deptid_list	Number[]	否	[1]	接收部门ID列表，最大的列表长度为20。
userid_list	String[]	否	["manager02"]	接收人userId列表，最大的列表长度为1000。
title	String	是	入职须知	公告标题。
push_top	Boolean	否	true	公告是否置顶。 true：置顶 false：不置顶
content	String	是	欢迎加入我们的大家庭	公告内容。
category_id	String	否	987uy66t5rt54er	公告分类ID。
coverpic_mediaid	String	否	@lADPDeC2ufXOeRzMqM0BLA	封面图，格式为@mediaId。 可以通过上传媒体文件接口上传图片，获取media_id参数值。

返回参数

名称	类型	示例值	描述
result	Boolean	true	是否创建成功。 true：成功 false：失败
success	Boolean	true	本次调用是否成功。 true：成功 false：失败
errcode	Number	0	返回码。
request_id	String	roz884n3k7rf	请求ID。

接口详见

创建公告 - 钉钉开放平台

3、更新公告

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/blackboard/update

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
update_request	OapiUpdateBlackboardVo	是		请求对象。
author	String	否	杨xx	公告作者。
ding	Boolean	否	true	是否发送应用内钉提醒： true：发送 false：不发送
blackboard_id	String	是	908uhyg76tfr543e	公告ID。
title	String	是	入职须知	公告标题。
content	String	是	欢迎加入我们的大家庭	公告内容。
category_id	String	否	89uuy7ytg6bnnjh7	公告分类ID，可以通过获取公告分类列表接口获取id参数值。
notify	Boolean	否	true	修改后是否再次通知接收人。 true：通知 false：不通知
operation_userid	String	是	manager01	操作人userid，必须是公告管理员。
coverpic_mediaid	String	否	@lADPDeC2ufXOeRzMqM0BLA	封面图，格式为@mediaId。 可以通过上传媒体文件接口上传图片，获取media_id参数值。

返回参数

名称	类型	示例值	描述
result	Boolean	true	是否成功。 true：成功 false：失败
success	Boolean	true	本次调用是否成功。 true：成功 false：失败
errcode	Number	0	返回码。
request_id	String	roz884n3k7rf	请求ID。

接口详见

更新公告 - 钉钉开放平台

4、删除公告

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/blackboard/delete

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
blackboard_id	String	是	098uyg65ffytr43	公告ID，可以通过获取公告ID列表接口获取result参数值。
operation_userid	String	是	manager01	操作人userId，必须是公告管理员。

返回参数

名称	类型	示例值	描述
result	Boolean	true	是否删除成功。 true：成功 false：失败
success	Boolean	true	本次调用是否成功。 true：成功 false：失败
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	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

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	保密等级。 0：普通公告 20：保密公告
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	本次调用是否成功。 true：成功 false：失败
errcode	Number	0	返回码。
request_id	String	q5ddepxxxx	请求ID。

接口详见

获取公告详情 - 钉钉开放平台

6、获取公告ID列表

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/blackboard/listids

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
query_request	OapiBlackboardQueryVo	是		请求对象。
operation_userid	String	是	manager4220	操作人userId，必须是公告管理员。
page_size	Number	是	10	分页大小，从1开始不超过30，且必须为正整数。
start_time	Date	否	2019-10-07 10:10:10	开始时间。 如果只传start_time，start_time距当前时间不能超过180天。 如果传start_time和end_time，时间间隔不能超过180天。 如果不传start_time和end_time，默认获取近一个月内的公告信息。
end_time	Date	否	2019-11-07 10:10:10	结束时间。 如果只传start_time，start_time距当前时间不能超过180天。 如果传start_time和end_time，时间间隔不能超过180天。 如果不传start_time和end_time，默认获取近一个月内的公告信息。
page	Number	是	1	页码，从1开始且必须为正整数。
category_id	String	否	9i9u7y7g6t65	分类ID，可以通过获取公告分类列表接口获取id参数值。

返回参数

名称	类型	示例值	描述
result	String[]	["72b4f87d27e815f6fecxxxx"]	公告ID列表。
success	Boolean	true	本次调用是否成功。 true：成功 false：失败
errcode	Number	0	返回码。
request_id	String	pxxm7ylvmppr	请求ID。

接口详见

获取公告ID列表 - 钉钉开放平台

7、获取公告分类列表

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/blackboard/category/list

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
operation_userid	String	是	manager01	操作人userId，必须是公告管理员。

返回参数

名称	类型	示例值	描述
result	BlackboardCategoryVo[]		返回结果。
id	String	89uuhygybj	分类ID。
name	String	日签	分类名。
success	Boolean	true	本次调用是否成功。 true：成功 false：失败
errcode	Number	0	返回码。
request_id	String	ie9aarwu1m1t	请求ID。

接口详见

获取公告分类列表 - 钉钉开放平台

8、获取用户可查看的公告

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/blackboard/listtopten

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

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	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。 第三方企业应用，通过获取第三方企业应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
create_report_param	OapiCreateReportParam	是		创建日志的参数对象。
contents	OapiReportContentVo[]	是		日志内容数组，根据该日志模板中每一项信息传参。
template_id	String	是	12345abcde	模板ID。 企业内部应用，调用获取模板详情接口获取id参数值。 第三方企业应用，调用获取模板详情接口获取id参数值。
to_userids	String[]	否	["123","456"]	日志发送到的员工userId。
to_chat	Boolean	是	true	发送日志到员工时是否发送单聊消息。 true：发送日志消息给指定用户 false：不单独发送消息
to_cids	String[]	否	123	日志要发送到的群ID。 重要 该群是在日志模板中预先已经配置好的接收群。如果没有配置，则无法发送到指定的群。 进入钉钉工作台，然后选择日志 > 模板管理 > 权限设置 > 默认发送范围，设置该日志模板的默认接收群。 企业内部应用，配置接收群后，可调用获取模板详情接口获取conversation_id参数值，即为发送到的群ID。 第三方企业应用，配置接收群后，可调用获取模板详情接口获取conversation_id参数值，即为发送到的群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	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。 第三方企业应用，通过获取第三方企业应用的access_token接口获取。

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	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。 第三方企业应用，通过获取第三方企业应用的access_token接口获取。

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	是否还有下一页数据。 true：有 false：没有
errcode	Number	0	返回码。
errmsg	String	ok	返回码描述。

接口详见

获取用户发出的日志列表 - 钉钉开放平台

12、获取用户发送日志的概要信息

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/report/simplelist

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

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	是否还有下一页数据。 true：有 false：没有
errcode	Number	0	返回码。
request_id	String	3qwbhu6edlcz	请求ID。

接口详见

获取用户发送日志的概要信息 - 钉钉开放平台

13、获取日志相关人员列表

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/report/statistics/listbytype

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
report_id	String	是	17469xxx	日志ID。 调用获取用户发送日志的概要信息接口获取report_id参数值。 调用获取用户发出的日志列表接口获取report_id参数值。
type	Number	是	0	查询类型： 0：已读人员列表 1：评论人员列表 2：点赞人员列表
offset	Number	否	0	分页查询的游标，最开始传0，后续传返回参数中的next_cursor值，默认值为0。
size	Number	否	100	分页参数，每页大小，最多传100，默认值为100。

返回参数

名称	类型	示例值	描述
success	Boolean	true	是否成功。 true：成功 false：失败
request_id	String	p0gvgqih0nfv	请求ID。
errcode	Number	0	返回码。
result	ReportPageVo		返回结果。
next_cursor	Number	100	下一次分页调用的offset值，当返回结果里没有next_cursor时，表示分页结束。
has_more	Boolean	true	是否还有下一页数据。 true：有 false：没有
userid_list	String[]	["user123","user456"]	userId列表。

接口详见

获取日志相关人员列表 - 钉钉开放平台

14、获取日志接收人员列表

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/report/receiver/list

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
report_id	String	是	174xxxx	日志ID。 调用获取用户发送日志的概要信息接口获取report_id参数值。 调用获取用户发出的日志列表接口获取report_id参数值。
offset	Number	否	0	分页查询的游标，最开始传0，后续传返回参数中next_cursor的值，默认值为0。
size	Number	否	100	分页参数，每页大小，最多传100，默认值为100。

返回参数

名称	类型	示例值	描述
result	ReportPageVo		返回结果。
has_more	Boolean	true	是否还有下一页数据。 true：有 false：没有
next_cursor	Number	100	下一次分页调用的offset值，当返回结果里没有next_cursor时，表示分页结束。
userid_list	String[]	["user123","user456"]	日志接收人userId列表。
errcode	Number	0	返回码。
errmsg	String	p0gvgqih0nfv	请求ID。
success	Boolean	true	是否成功。 true：成功 false：失败

接口详见

获取日志接收人员列表 - 钉钉开放平台

15、获取日志评论详情

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/report/comment/list

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
report_id	String	是	174xxxx	日志ID。 调用获取用户发送日志的概要信息接口获取report_id参数值。 调用获取用户发出的日志列表接口获取report_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	是否还有下一页。 true：有 false：没有
next_cursor	Number	20	下一次分页调用的offset值，当返回结果里没有next_cursor时，表示分页结束。
errcode	Number	0	返回码。
request_id	String	5kngbdmfdrle	请求ID。
success	Boolean	true	调用结果。 true：成功 false：失败

接口详见

获取日志评论详情 - 钉钉开放平台

16、获取用户日志未读数

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/report/getunreadcount

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

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	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。

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	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。 第三方企业应用，通过获取第三方企业应用的access_token接口获取。

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	是否调用成功。 true：成功 false：失败
request_id	String	64jz549xdj6q	请求ID。

接口详见

获取待入职员工列表 - 钉钉开放平台

19、获取在职员工列表

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/queryonjob

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。 第三方企业应用，通过获取第三方企业应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
status_list	String	是	2,3,5,-1	在职员工状态筛选，可以查询多个状态。不同状态之间使用英文逗号分隔。 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	是否调用成功。 true：成功 false：失败
request_id	String	u2nu5vpoq6p	请求ID。

接口详见

获取在职员工列表 - 钉钉开放平台

20、获取离职员工列表

调用本接口，查询企业离职员工userId列表。

例如，在企业智能人事应用中查看已离职员工列表，如下图所示。

调用本接口，可获取企业下已离职员工的userId列表。

权限

要调用此API，需要以下权限之一。

应用类型	是否支持	权限	API Explorer调试
企业内部应用	支持	智能人事个人信息读权限	API Explorer
第三方企业应用	支持	智能人事个人信息读权限	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	是	调用该接口的访问凭证。 企业内部应用，调用获取企业内部应用的accessToken接口获取。 第三方企业应用，调用获取第三方应用授权企业的accessToken接口获取。

Query参数

名称	类型	是否必填	描述
nextToken	Long	否	分页查询的游标。 如果是首次查询，该参数传0或者不传。 如果是非首次查询，该参数传上次调用时返回的nextToken。
maxResults	Integer	否	每页条目数，默认值30，最大值50。

返回参数

名称	类型	描述
nextToken	Long	分页游标。
hasMore	Boolean	是否还有更多数据， 以此为依据判断是否继续查询下一页。 true：有 false：没有
userIdList	Array of String	返回的离职人员userId列表。

接口详见

获取离职员工列表 - 钉钉开放平台

21、获取用户签到记录

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/checkin/record/get

Query参数

名称	类型	是否必填	示例值	描述
access_token	String	是	6d1bxxxx	调用该接口的应用凭证。 企业内部应用，通过获取企业内部应用的access_token接口获取。 第三方企业应用，通过获取第三方企业应用的access_token接口获取。

Body参数

名称	类型	是否必填	示例值	描述
userid_list	String	是	manager4220	需要查询的用户列表，最大列表长度为10。
start_time	Number	是	1605437194000	开始时间，Unix时间戳，单位毫秒。
end_time	Number	是	1605786394000	截止时间，单位毫秒。 如果是取1个人的数据，时间范围最大10天。 如果是取多个人的数据，时间范围最大1天。
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。

接口详见

获取用户签到记录 - 钉钉开放平台

最后感谢每一个认真阅读我文章的人，礼尚往来总是要有的，虽然不是什么很值钱的东西，如果你用得到的话可以直接拿走，希望可以帮助到大家！