# 三方审批结果回调

# 1.概述

基本能力：客户平台在完成三方外部审批后调用【三方审批结果回调】接口，将审批结果通知美团企业版，支持单次批量结果的回调。

适用场景：审批流模板中配置了【第三方外部审批】，配置入口入下图所示。

若审批流设置页面无“第三方外部审批”选项，请联系客户经理，在【运营后台-客户详情-功能配置-审批流外部审批节点】开启对应开关。

如需对接【三方审批结果回调】接口，需对接审批事件推送接口，接收美团企业版推送的审批事件消息。

交互示意图：

3.1 企业管理员在审批流程模板中，审批人节点选择【第三方外部审批】，同时接入审批事件推送接口。

3.2 当需要【第三方外部审批】时，审批事件推送接口会给客户平台发送审批事件消息，客户接收消息后，走内部审批流程。

3.3 客户内部完成审批后，调用美团企业版审批结果回调接口，通知美团审批结果。
```
在审批事件推送接口中只需关注eventType=1（即审批流程节点变更）的通知。

当收到审批流程节点开始通知，同时assigneeType=16000（即审批人类型是第三方外部审批）时，执行企业内部审批控制或逻辑判断；审批人类型为非第三方外部审批或当收到审批流程节点结束通知，企业侧内部无需处理。
```

# 2.接口基本信息

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

# 2.1.请求体

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

# content加密前数据结构

名称	类型	是否必填	示例	说明
ts	Long	是	1617085650321	13位时间戳。若请求发起时间与平台接受请求时间相差大于10分钟，平台将直接拒绝本次请求
entId	Long	是	12345	企业ID
auditOperateRequestList	List<AuditOperateRequest>	是		审批结果实体数据，最多10条（含10条）

AuditOperateRequest字段说明

名称	类型	是否必填	示例	说明
processInstanceId	String	是	46871	审批流程实例ID，需要与审批事件推送接口processInstanceId传值一致
auditBizType	Integer	是	2010	审批业务类型，枚举值详见6.1.审批业务类型
nodeCode	String	是	node2e8a52c62e494296b5e4daf7d443c7b	审批节点ID，需要与审批事件推送接口nodeCode传值一致
operateType	Integer	是	3	审批操作类型（3：通过，4：驳回）
externalAuditorId	String	否		外部审批人在客户企业系统中的唯一标识，如员工工号、员工邮箱等。
externalAuditorName	String	否		外部审批人姓名。
remark	String	否		审批操作理由

# 2.2.响应参数

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

# data解密后数据结构

名称	类型	是否必填	示例	说明
successResultInfoList	List<OperateResultInfo>	是		审批成功的单据
failResultInfoList	List<OperateResultInfo>	是		审批失败的单据

OperateResultInfo字段说明

名称	类型	是否必填	示例	说明
processInstanceId	String	是	46871	审批流程实例ID
result	Integer	是	0	针对每个审批结果回调的响应编码，编码枚举值和解决方案详见4.2业务错误码
itemMsg	String	否		错误描述

# 3.示例

# 3.1.请求示例

# 3.1.1.请求示例

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

# 3.1.2.请求参数content解析

{
    "ts":1695371519003,
    "entId":100302,
    "auditOperateRequestList": [
        {
            "processInstanceId": 46871,
            "auditBizType": 2010,
            "nodeCode": "node2e8a52c62e494296b5e4daf7d443c7be",
            "operateType": 3,
            "externalAuditorId": "",
            "externalAuditorName": "",
            "remark": ""
        }
    ] 
}

# 3.2.响应示例

# 3.2.1.响应结果

{
    "traceId":"56a0af18ae30a168d4006c7c",
    "status":0,
    "msg":"操作成功",
    "data":"UgJn07uNgW7S7fJK0R0xVbaLxoCGPQIzoP"
}

# 3.2.2.响应参数data解析

{
    "msg": null,
    "data": {
        "successResultInfoList": [
            {
                "processInstanceId": 46871,
                "result": 0,
                "itemMsg": ""
            }     
        ],
        "failResultInfoList": []
    },
    "status": 0
}

# 4.错误码

# 4.1.公共错误码

详见：公共错误编码

# 4.2.业务错误码

错误码	错误描述	解决方案
10180007	传入的审批流程实例ID不正确，没有找到有效的审批流程实例	请检查请求传入的processInstanceId字段值，是否与审批事件推送的审批流程实例ID一致
10180008	传入的企业ID与审批流程实例不匹配，无法完成审批结果回调	请检查请求传入的entId字段值，是否与审批事件推送的企业ID一致
10180009	传入的审批业务类型与审批流程实例不匹配，无法完成审批结果回调	请检查请求传入的auditBizType字段值，是否与审批事件推送的审批业务类型一致
10180010	传入的审批节点编码与当前待审批节点不匹配，无法完成审批结果回调	请检查请求传入的nodeCode字段值，是否与审批事件推送的审批节点编码一致
10180011	传入的审批操作类型不合法，目前仅支持审批通过、审批驳回操作	请检查请求传入的operateType字段值，目前仅支持3-审批通过、4-审批驳回。
40185000	未知错误	请提供响应结果中的traceId参数，联系客户经理进行排查。
40185001	第三方平台调用异常	请稍后重试接口调用。

# 5.代码示例

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

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

    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 {
        // 构建请求对象
        SqtAuditApiOperateRequest request = new SqtAuditApiOperateRequest();
        request.setTs(System.currentTimeMillis());
        request.setEntId(sqtClient.getEntId());

        SqtAuditApiOperateRequest.AuditOperateRequest auditOperateRequest = new SqtAuditApiOperateRequest.AuditOperateRequest();
        auditOperateRequest.setProcessInstanceId("46871");
        auditOperateRequest.setAuditBizType(2002);
        auditOperateRequest.setNodeCode("");
        auditOperateRequest.setOperateType(3);
        auditOperateRequest.setExternalAuditorId("id");
        auditOperateRequest.setExternalAuditorName("name");
        auditOperateRequest.setRemark("测试");

        request.setAuditOperateRequestList(Collections.singletonList(auditOperateRequest));

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

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

    private static void handleRespFailResult(BaseApiResponse<SqtAuditOperateListResult> 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.附录

# 6.1.审批业务类型

业务类型	业务类型说明
2002	出差申请
2004	加班用餐申请
2007	用车申请
2009	酒店事中订单审批
2010	火车票事中订单审批
2011	新版事后报备
2013	机票事中订单审批

# 7.版本记录

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

← 审批事件推送预算调整 →