基于业务实体批量查询合规详情接口

1.概述

更新时间：2024-05-30 15:23:08
客户平台通过【基于业务实体批量查询合规详情】接口获取合规校验结果，如异地消费、长距消费等，且当前仅支持订单维度查询合规结果。
注：店铺信息属于机密内容，如需获取，需在开通权限时，向客户经理申请获取权限。

2.接口基本信息

名称	描述
请求方式	POST
调用地址	测试环境：https://waimai-openapi.apigw.test.sankuai.com/api/sqt/open/compliance/queryBizComplianceDetails 正式环境：https://bep-openapi.meituan.com/api/sqt/open/compliance/queryBizComplianceDetails
调用方	客户平台
响应方	美团企业版
响应超时时间	5s
调用限频	每分钟访问不超过100次，每天累计访问不超过100000次

2.1.请求体

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

content加密前数据结构

名称	类型	是否必填	示例	说明
ts	Long	是	1617085650321	13位时间戳。若请求发起时间与平台接受请求时间相差大于10分钟，平台将直接拒绝本次请求
entId	Long	是	46574	企业ID
bizType	Integer	是	0	业务类型：0-订单
bizIdList	List<String>	是	["529375902136680","529375902136680"]	业务实体id列表，如：业务类型是订单时，传美团企业版业务订单ID（即sqtBizOrderId字段）

2.2.响应参数

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

data解密后数据结构

类型	是否必填	示例	说明
BizCompliancePageResult	是	见BizCompliancePageResult	返回结果

BizCompliancePageResult字段说明

名称	类型	是否必填	示例	说明
list	List<BizComplianceDetail>	是		实体合规明细列表

BizComplianceDetail字段说明

名称	类型	是否必填	示例	说明
bizType	Integer	是	0	业务类型：0-订单
bizId	String	是	12323	业务实体 id ，如：业务类型是订单时，传美团企业版业务订单ID（即sqtBizOrderId字段）
complianceDetailList	List<ComplianceCheckDetail>	是		合规检查结果列表

ComplianceCheckDetail字段说明

名称	类型	是否必填	示例	说明
complianceType	Integer	是	7	合规检查类型： 7-考勤异常； 8-异地消费； 9-非正常用餐时间消费； 10-长距买单； 11-人均超标
result	Integer	是	0	是否命中合规检查： 0-未命中，合规； 1-命中，不合规
detail	CheckInfo	是	见下文各个类型枚举	合规检查的结果详情信息，不同的合规检查类型详情字段不同， 详见： 考勤异常 异地消费 非正常用餐时间消费 长距买单 人均超标

【考勤异常】CheckInfo 详情字段说明

名称	类型	是否必填	示例	说明
staffAttendanceDetailList	List<StaffAttendanceCheckDetail>	否		订单员工考勤合规检查详情

员工考勤检查详情字段说明

名称	类型	是否必填	示例	说明
staffIdentifier	String	否	example@abc.com	员工唯一标识，工号/邮箱/手机号三者其一，若不确认，请与客户经理沟通
staffName	String	否	李伟	员工姓名
attendanceCheckType	Integer	否	10	考勤验证方式：10-校验考勤时间点；20-校验考勤时长
staffConsumerType	Integer	否	10	员工消费类型 10-消费者 20-共享餐券消费者
startWorkTime	Long	否	1715040988000	首次打卡时间，13位时间戳
endWorkTime	Long	否	1715040988000	末次打卡时间，13位时间戳
workHour	Long	否	36000	工时（单位 秒）
attendanceCheckResult	Integer	否	1	考勤合规检查结果：0-考勤正常； 1-考勤异常

示例：

{
  "complianceType": 7,
  "result": 1,
  "detail": {
    "staffAttendanceDetailList": [
      {
        "attendanceCheckResult": 0,
        "attendanceCheckType": 10,
        "staffConsumerType": 10,
        "staffName": "李四",
        "staffIdentifier": "123123123",
        "startWorkTime": 1715040988000,
        "endWorkTime": 1715085019000,
        "workHour": 36000
      },
      {
        "attendanceCheckResult": 0,
        "attendanceCheckType": 20,
        "staffConsumerType": 20,
        "staffName": "张三",
        "staffIdentifier": "123123123",
        "startWorkTime": 1715040988000,
        "endWorkTime": 1715085019000,
        "workHour": 36000
      }
    ]
  }
}

【异地消费】CheckInfo 详情字段说明

名称	类型	是否必填	示例	说明
staffCityId	String	否	101000	员工常驻城市编码
staffCityName	String	否	北京	员工常驻城市名称
shopCityId	String	否	101000	消费门店所在城市编码
shopCityName	String	否	北京	消费门店所在城市名称

示例：

{
  "complianceType": 8,
  "result": 0,
  "detail": {
    "staffCityId": "101000",
    "staffCityName": "北京",
    "shopCityId": "101000",
    "shopCityName": "北京"
  }
}

【非正常用餐时间】 CheckInfo 详情字段说明

名称	类型	是否必填	示例	说明
consumeTime	Long	否	1716384220000	消费时间，13位时间戳

示例：

{
  "complianceType": 9,
  "result": 1,
  "detail": {
    "consumeTime": 1716384220000
  }
}

【长距买单】CheckInfo 详情字段说明

名称	类型	是否必填	示例	说明
signInAddress	String	否	白沙里小区(离餐厅736米)	签到地址

示例：

{
  "complianceType": 10,
  "result": 1,
  "detail": {
    "signInAddress": "白沙里小区(离餐厅736米)"
  }
}

【人均超标】CheckInfo 详情字段说明

名称	类型	是否必填	示例	说明
realPayAmount	String	否	9.60	实际支付总金额（单位：元，保留两位小数）
consumerCount	Integer	否	2	消费人数
personAvgAmount	String	否	4.80	人均实际消费金额（单位：元，保留两位小数）

示例：

{
  "complianceType": 11,
  "result": 1,
  "detail": {
    "realPayAmount": "9.60",
    "consumerCount": 2,
    "personAvgAmount": "4.80"
  }
}

3.示例

3.1.请求示例

3.1.1.请求示例

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

3.1.2.请求参数content解析

{
  "ts": 1617085650321,
  "entId": 100746,
  "bizType": 0,
  "bizIdList": [
    "529375902138680",
    "529325902136681"
  ]
}

3.2.响应示例

3.2.1.响应结果

{
  "traceId": "56a0af18ae30a168d4006c7c",
  "status": 0,
  "data": "UgJn07uNgW7S7fJK0R0xVbaLxoCGPQIzoP"
}

3.2.2.响应参数data解析

{
  "list": [
    {
      "bizId": "1793271286407925808",
      "bizType": 0,
      "complianceDetailList": [
        {
          "complianceType": 7,
          "result": 1,
          "detail": {
            "staffAttendanceDetailList": [
              {
                "attendanceCheckResult": 0,
                "attendanceCheckType": 10,
                "staffConsumerType": 10,
                "staffIdentifier": "13232323232",
                "staffName": "李四",
                "startWorkTime": 1715040988000,
                "endWorkTime": 1715085019000,
                "workHour": 36000
              },
              {
                "attendanceCheckResult": 0,
                "attendanceCheckType": 20,
                "staffConsumerType": 20,
                "staffIdentifier": "13232323232",
                "staffName": "张三",
                "startWorkTime": 1715040988000,
                "endWorkTime": 1715085019000,
                "workHour": 36000
              }
            ]
          }
        },
        {
          "complianceType": 8,
          "result": 1,
          "detail": {
            "staffCityId": "101000",
            "staffCityName": "北京",
            "shopCityId": "100102",
            "shopCityName": "上海"
          }
        },
        {
          "complianceType": 9,
          "result": 1,
          "detail": {
            "consumeTime": 1715085019000
          }
        },
        {
          "complianceType": 10,
          "result": 1,
          "detail": {
            "signInAddress": "白沙里小区(离餐厅736米)"
          }
        },
        {
          "complianceType": 11,
          "result": 1,
          "detail": {
            "realPayAmount": "88.58",
            "consumerCount": 4,
            "personAvgAmount": "23.34"
          }
        }
      ]
    }
  ]
}

4.错误码

4.1.公共错误码

错误码	错误描述	解决方案
10010002	企业已停止合作，请联系客户经理进行确认	将接口调用的entId参数给到客户经理，由客户经理确认企业状态是否在合作中
10010003	content不合法	详细阅读content参数加密说明（签名实例），确认content加密方式和content解密前传参是否正确
10010004	ts缺失或ts时间已过期	确认ts是否传值并为13位时间戳，如果正确传值，则确认请求发起时间与美团企业版接受请求的时间差是否超过10分钟
10010005	entId不能为空	entId参数不可为空，如果未拿到entId参数，可以咨询客户经理获取
20010001	accessKey不合法	检查accessKey是否为客户经理给到的值，如果accessKey值正确，确认调用环境是否和accessKey一致，如使用测试环境的accessKey调用线上的接口
20010002	请求path不合法	检查接口调用地址是否正确，如是否有非法字符
20010003	鉴权失败，无接口访问权限	将接口调用地址给到客户经理，由客户经理检查接口权限是否开通并保存成功
20010004	越权访问，无法访问该企业数据，请检查entId的正确性	检查accessKey和entId两个参数的对应关系是否正确
30010001	访问频率过高	请确认接口访问频率，每个接口默认调用限频为每分钟不超过100次，超出调用频率会调用此错误
30010002	访问次数超过配额	请确认接口的累计访问次数，每个接口的默认累计调用量为10w次，超出限额则会报错

4.2.业务错误码

错误码	错误描述	解决方案
10130000	业务类型和业务实体id列表都不能为空	请检查业务类型和业务实体id列表传参是否为空

5.代码实例

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

package com.meituan.sqt.demo.in.compliance;

import com.google.common.collect.Lists;
import com.meituan.sqt.client.SqtClient;
import com.meituan.sqt.constant.CommonConstants;
import com.meituan.sqt.enums.ResponseStatusEnum;
import com.meituan.sqt.exception.MtSqtException;
import com.meituan.sqt.request.in.compliance.BizComplianceDetailRequest;
import com.meituan.sqt.response.in.BaseApiResponse;
import com.meituan.sqt.response.in.compliance.BizCompliancePageResult;

/**
 * @Description 基于业务实体查询合规信息
 */
public class BizComplianceDetailsDemo {

    private static final String invokeUrl = "https://bep-openapi.meituan.com/api/sqt/open/compliance/queryBizComplianceDetails";
    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 {
        // 构建请求对象
        BizComplianceDetailRequest request = new BizComplianceDetailRequest();
        request.setTs(System.currentTimeMillis());
        request.setEntId(sqtClient.getEntId());
        request.setBizType(0);
        request.setBizIdList(Lists.newArrayList(1L));

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

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

    private static void handleRespFailResult(BaseApiResponse<BizCompliancePageResult> 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	2024-05-10	业务实体上合规详情查询接口