企业自建考勤查询接口

1.概述

更新时间：2023-05-17 15:23:08
美团企业版调用本接口，获取企业内员工的实际打卡结果。其中，一名员工仅支持返回一条记录。 例如：企业考勤规则是上午9点和下午6点各打一次卡，即使员工在这期间多次打卡，查询结果也只返回一条，即上午最早打卡结果和下午最晚打卡结果。

2.接口基本信息

名称	描述
请求方式	POST
调用地址	客户平台提供
调用方	美团企业版
响应方	客户平台
响应超时时间	1s
调用限频	30QPS
重试机制	查询失败重试、重试1次

2.1.请求体

名称	类型	是否必填	示例	说明
accessKey	String	是		美团企业版分配给客户的接入秘钥
content	String	是	UgxoCGPQIzoP	请求体内容，将请求参数JSON序列化后进行加密的结果值，加密秘钥使用secretKey参数，详见签名实例

content加密前数据结构

名称	类型	是否必填	示例	说明
ts	Long	是	1617085650321	13位时间戳，标识请求时间
entId	Long	是	46574	企业ID
traceId	String	是	56a0af18ae30a168d4006c7c	日志查询ID，用于排查问题
staffIdentifierList	List<String>	是	["staff1","staff2"]	企业配置的员工唯一标识(手机号、邮箱、工号)
workDateFrom	String	是	2022-05-12	查询员工考勤的开始时间 YYYY-MM-DD
workDateTo	String	是	2022-05-12	企查询员工考勤的结束时间 YYYY-MM-DD

2.2.响应参数

名称	类型	是否必填	示例	说明
traceId	String	是	56a0af18ae30a168d4006c7c	日志查询ID，用于排查问题
status	Integer	是	0	接口响应编码，编码枚举值和解决方案详见第四章错误码
msg	String	否		错误描述信息
data	String	是	UgxoCGPQIzoP	响应数据，将响应参数JSON序列化后进行加密的结果值，解密秘钥使用secretKey参数

data解密后数据结构

类型	是否必填	示例	说明
List<RecordResult>	是	见RecordResult	返回结果

RecordResult 字段说明

名称	类型	是否必填	示例	说明
staffIdentifier	String	是	staff1	企业配置的员工唯一标识(手机号、邮箱、工号)
workDate	String	是	2023-05-17	员工考勤时间
staffStartCheckTime	Long	否	1679306000280	员工最早打卡时间(时间戳,单位为毫秒)
staffEndCheckTime	Long	否	1679306000280	员工最晚打卡时间(时间戳,单位为毫秒)

3.示例

3.1.请求示例

3.1.1.请求示例

POST /attendance/list HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
Accept: application/json

{
  "accessKey": "AB4O3CP2R3ER-TK",
  "content": "3TkMd4UPyXL7G_rA-neo8vZC0t50VzWDToUYO9rzJUdtZsCI4cjNDw3D6rpQ9bJ4ySxPxwjB7-he8VNaf_YroXI8Ap2KwBbGLkq5Id0u39OvNza-hTrHWq3k_aLjZ6TtLS8JeNzf1oL5hlcFeLQHXAPJFAUwCqHcdJ5N2eOWyOs14mVtnKb9X-XolZSlbCSF"
}

3.1.2.请求参数content解析

{
  "entId": 617,
  "staffIdentifierList": [
    "staff001",
    "staff002"
  ],
  "traceId": "-6437118597163730466",
  "workDateFrom": "2023-05-16",
  "workDateTo": "2023-05-16"
}

3.2.响应示例

3.2.1.响应结果

{
  "traceId": "-6437118597163730466",
  "status": 0,
  "msg": "ok",
  "data": "3-DQ-9PXpAb9UVhA44GHsXiZghlYquPJ0Fj4-tR01td9wNWgKRPa8X1Bb8EN9aROlOEycumEc9Jwj1TUzRgjEDTbs9VNtxzW5XZXUQrfJk5thkQLkFWx4rBXf68rxYwNXL1lVwFa__pNrMxTLhPE0mB3rAJPUrXo6xlO1dyqrxBgVMXI8DYv7CccaaEMcjrWgdSZFs65ZWWUDtLrFjsDYB_lStI8r_YLkCsH4bxwMDSNhQrEaIB01Fm2KKDDpxdK3zHJ0hjhc4XIb8AV8u3mMHjEqMeLXxS2R7MUc2DvLcebPOvJL6bbCmQkFkafPwqGjj9vizkdUcm2ygRVq2wcQw"
}

3.2.2.响应参数data解析

[
  {
    "staffIdentifier": "staff001",
    "workDate": "2023-05-16",
    "staffStartCheckTime": 1684198800000,
    "staffEndCheckTime": 1684238400000
  },
  {
    "staffIdentifier": "staff002",
    "workDate": "2023-05-16",
    "staffStartCheckTime": 1684198800000,
    "staffEndCheckTime": 1684242000000
  }
]

4.企业响应错误码

错误码	错误描述	场景描述
411	参数错误	当出现参数类型或参数值异常情况报411错误码，如entId非Long类型
412	参数缺失	当必填参数为空的情况报412，如entId为空或payTradeNo为空
413	解密验签失败	当根据secretKey解析请求参数出现异常时，报413
500	内部服务异常	客户平台系统内部处理逻辑异常时返回500，如无法生成outRefundTradeNo字段值
501	服务繁忙	当出现接口调用频次过多或接口性能较低导致无法响应请求时返回501

5.版本记录

版本号	版本日期	更新内容
v1.0	2023-05-15	企业自建考勤查询接口初稿