审批列表查询

1.概述

1. 基本能力：企业侧调用此接口，获取员工的审批任务清单，支持单次查询多个员工。

2. 适用场景：

   2.1 主要适用于“员工主动打开企业系统中的审批列表”等场景。美团企业版为客户提供了事前申请（下单预订前提交申请，通过后可下单）、事中审批（预订下单后需提交审批，审批通过后可支付）、事后报备（订单支付消费后需进行报备审批）等功能，如果企业客户希望在美团企业版系统完成审批流程控制和审批详情的查阅，同时支持员工在企业侧系统的待办中心等统一查看审批列表，则可以通过本文档进行接口对接。

   2.2 如果企业侧希望给员工发送实时审批通知，或者希望将员工的审批数据存储在本地，请使用审批事件推送接口。

3. 应用示意图：

2.接口基本信息

名称	描述
请求方式	POST
调用地址	测试环境：https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/audit/query/taskList 正式环境：https://bep-openapi.meituan.com/api/sqt/open/audit/query/taskList
调用方	客户平台
响应方	美团企业版
响应超时时间	5秒
调用限频	100次/分钟，10w次/天

2.1.请求体

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

content加密前数据结构

名称	类型	是否必填	示例	说明
ts	Long	是	1617085650321	13位时间戳。若请求发起时间与平台接受请求时间相差大于10分钟，平台将直接拒绝本次请求
entId	Long	是	12345	企业ID
staffIdList	List	否	[1,2,3]	查询员工的列表，staffId含义为美团侧存储的员工唯一标识，staffIdList和staffIdentifierList必传其一，都不为空时，只处理staffIdList
staffIdentifierList	List	否	["code1", "code2"]	查询员工的列表，staffIdentifier含义为企业的唯一标识（手机号或者工号或者邮箱，可和客户经理确认），staffIdList和staffIdentifierList必传其一，都不为空时，只处理staffIdList
searchType	Integer	是	1	审批任务搜索类型(1-待审批、2-已审批、3-抄送、4-已发起)
auditBizTypeList	List	是	2002	审批业务类型(2002-出差申请、2007-用车申请、2009-酒店预订申请、2010-火车票预订申请、2011-新版事后报备、2013-机票预定申请)
startTime	Long	是	1617085650321	提交审批开始时间，13位时间戳
endTime	Long	是	1617085650321	提交审批结束时间，13位时间戳
pageNum	Integer	是	1	页码
pageSize	Integer	是	20	每页记录数，1~100之间的正整数

2.2.响应参数

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

data解密后数据结构

名称	类型	是否必填	示例	说明
pageNum	Integer	是	1	当前页码，最小为1
pageSize	Integer	是	20	当前页返回申请单条数
totalCount	Long	是	468	总数量
result	List<AuditTaskInfo>	否		查询结果列表

AuditTaskInfo字段说明

名称	类型	是否必填	示例	说明
entId	Long	是	1001	企业ID
processInstanceId	Long	是	460242	审批流程实例ID
processName	String	是	审批流程	审批流程模板名称
processCode	String	是	sqtAudit151135213551218597986	审批流程模板编码
auditBizType	Integer	是	2009	审批业务类型
auditBizNo	String	是	1683647437501132849	审批业务编号
submitStaff	UserInfo	是		发起人
assigneeStaffList	List<UserInfo>	是		已审批人列表
candidateStaffList	List<UserInfo>	是		待审批人列表
carbonCopyStaffList	List<UserInfo>	是		抄送人列表

UserInfo字段说明

名称	类型	是否必填	示例	说明
staffIdentifier	String	是	zhangsan@meituan.com	审批人在美团系统中的员工唯一标识(根据企业配置唯一标识，获取邮箱、电话、工号)
staffEntIdentifier	String	否		审批人在客户企业系统中的唯一标识

3.示例

3.1.请求示例

3.1.1.请求示例

{
  "accessKey":"B3KSWLDSKSKDMJ",
  "content":"UgxoCGPQIzoP"
}

3.1.2.请求参数content解析

{
    "ts":1695371519003,
    "entId":1001,
    "searchType": 4,
    "staffIdentifierList":["zhangsan@meituan.com"],
    "auditBizTypeList":[2009],
    "startTime":"1690371519003",
    "endTime":"1695371519003",
    "pageNum": 1,
    "pageSize": 10
}

3.2.响应示例

3.2.1.响应结果

{
    "traceId":"56a0af18ae30a168d4006c7c",
    "status":0,
    "msg":"同步成功",
    "data":"UgJn07uNgW7S7fJK0R0xVbaLxoCGPQIzoP"
}

3.2.2.响应参数data解析

{
    "msg": null,
    "data": {
        "pageNum": 1,
        "pageSize": 10,
        "totalCount": 2,
        "result": [
            {
                "entId": 1001,
                "processInstanceId": 460242,
                "processName": "审批流程",
                "processCode": "sqtAudit151135213551218597986",
                "auditBizType": 2009,
                "auditBizNo": "1683647437501132849",
                "submitStaff": {
                    "staffIdentifier": "zhangsan@meituan.com",
                    "staffEntIdentifier": null
                },
                "assigneeStaffList": [
                    {
                        "staffIdentifier": "zhangsan@meituan.com",
                        "staffEntIdentifier": null
                    }
                ],
                "candidateStaffList": [],
                "carbonCopyStaffList": []
            },
            {
                "entId": 1001,
                "processInstanceId": 460359,
                "processName": "审批流程",
                "processCode": "sqtAudit153533213551218597986",
                "auditBizType": 2009,
                "auditBizNo": "1684009746438320171",
                "submitStaff": {
                    "staffIdentifier": "zhangsan@meituan.com",
                    "staffEntIdentifier": null
                },
                "assigneeStaffList": [
                    {
                        "staffIdentifier": "zhangsan@meituan.com",
                        "staffEntIdentifier": null
                    }
                ],
                "candidateStaffList": [],
                "carbonCopyStaffList": []
            }
        ]
    },
    "status": 0
}

4.错误码

4.1.公共错误码

详见：公共错误编码

4.2.业务错误码

错误码	错误描述	解决方案
10180000	参数校验不通过，参数格式不是合法的json	请检查参数JSON格式或字段类型。
10180001	参数校验不通过，必填参数为空	请查看响应结果中的msg信息，确认必填字段是否填写完整。
10180002	入参数据校验不通过	请根据错误信息自查错误原因，可重点检查入参的字段类型、准确性等情况。
10180003	搜索类型无效	请根据接口文档，传入有效的searchType。
10180004	传入的员工唯一标识列表，没有找到有效的员工信息	请检查 staffIdentifierList 的传值情况，当前传入的staffIdentifierList 查不到员工信息。
10180005	未传入有效的员工列表	请检查 staffIdList 或 staffIdentifierList 的传值情况，staffIdList和staffIdentifierList必传其一。
40185000	未知错误	请提供响应结果中的traceId参数，联系客户经理进行排查。
40185001	第三方平台调用异常	请稍后重试接口调用。

5.代码示例

依赖SDK包地址：SDK下载地址

{
    private static final String invokeUrl = "https://waimai-openapi.apigw.test.sankuai.com/api/sqt/open/audit/query/taskList";

    private static SqtClient sqtClient = null;

    static {
        // 初始化SqtClient，只需要初始化一次即可
        // entId，accessKey，secretKey需要根据不同环境动态的设置获取
        sqtClient = new SqtClient.Builder()
                .setEntId(CommonConstants.entId)
                .setAccessKey(CommonConstants.accessKey)
                .setSecretKey(CommonConstants.secretKey)
                .build();
    }

    public static void main(String[] args) throws MtSqtException {
        // 构建请求对象
        SqtAuditApiTaskPageQueryRequest request = new SqtAuditApiTaskPageQueryRequest();
        request.setTs(System.currentTimeMillis());
        request.setEntId(sqtClient.getEntId());
        request.setSearchType(SearchTypeEnum.INITIATE_TASK.getCode());
        request.setStartTime(1690007719297L);
        request.setEndTime(1695183227684L);
        request.setStaffIdList(Collections.singletonList(481220L));
        request.setAuditBizTypeList(Collections.singletonList(2002));
        request.setPageNum(1);
        request.setPageSize(10);

        // API调用
        // 注意：超时时间默认以请求对象中注解ApiMeta上设置的为准，也可以自定义传递对应的超时时间
        BaseApiResponse<List<SqtAuditApiTaskInfo>> response = sqtClient.invokeApi(invokeUrl, request, null, null);
        // 响应结果为空处理
        if (response == null) {
            // 处理响应结果为空情况
            // ...

        }
        // 获取结果
        if (ResponseStatusEnum.SUCCESS.getCode().intValue() == response.getStatus()) {
            // 成功
            List<SqtAuditApiTaskInfo> resultItemList = response.getRealData();
            // 处理业务逻辑
            // ...
        } else {
            // 处理失败场景
            handleRespFailResult(response);
        }
    }

    private static void handleRespFailResult(BaseApiResponse<List<SqtAuditApiTaskInfo>> response) {
        // 访问频率过高
        if (ResponseStatusEnum.HIGH_FREQUENCY_ACCESS.getCode().intValue() == response.getStatus()) {
            // 解决方案参照：https://h5.dianping.com/app/bep-docs/open-platform-doc/guide/rate_limiting.html
        }
        // 访问次数超过配额
        if (ResponseStatusEnum.EXCEED_ACCESS_NUMBER.getCode().intValue() == response.getStatus()) {
            // 解决方案参照：https://h5.dianping.com/app/bep-docs/open-platform-doc/guide/rate_limiting.html
        }
        // 其它失败场景

    }
}

6.版本记录

版本号	版本日期	更新内容
v1.0	2023-09-26	新增接口