用餐合规详情查询接口

1.概述

更新时间：2023-03-14 15:23:08
客户平台通过【用餐合规详情查询】接口，拉取用餐相关的支付信息、店铺信息、签到信息以及报备信息，用于客户内部合规校验。
注：店铺信息属于机密内容，如需获取，需在开通权限时，向客户经理申请获取权限。

2.接口基本信息

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

2.1.请求体

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

content加密前数据结构

名称	类型	是否必填	示例	说明
ts	Long	是	1617085650321	13位时间戳。若请求发起时间与平台接受请求时间相差大于10分钟，平台将直接拒绝本次请求
entId	Long	是	46574	企业ID
sqtBizOrderId	Long	是	529375902136680	美团企业版业务订单ID

2.2.响应参数

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

data解密后数据结构

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

Compliance字段说明

名称	类型	是否必填	示例	说明
isGreyShop	Integer	是	0	是否是灰名单商家，1：是灰名单商家 ；0：不是灰名单商家
payInfo	List<PayInfo>	否		支付信息
shopInfo	ShopInfo	否		店铺信息
signInInfo	SignInInfo	是		签到信息
reportInfo	ReportInfo	否		报备信息

PayInfo字段说明

名称	类型	是否必填	示例	说明
cardNo	String	否	8611	卡号后四位(银行卡支付才有值)
payMethod	String	否	微信支付	支付方式

ShopInfo字段说明

名称	类型	是否必填	示例	说明
shopName	String	否	肯德基	店铺名字
shopAddress	String	否	望京东路9号	地址
shopTitle	String	否	金拱门餐饮有限公司	店铺抬头
shopAvgPrice	String	否	30.00	店铺均价，单位：元，精确到小数点后两位
shopPhone	String	否	18136000000或010-88350000或者18136000000/010-88350000	店铺电话，当返回多个号码，中间用“/”分隔，座机格式xxx-xxxxxxxx，手机号码为大陆11位标准格式

SignInfo字段说明

名称	类型	是否必填	示例	说明
signInStatus	Integer	否	1	签到状态 1签到 0没签到
signInTime	String	否	2019-01-01 12:51:29	签到时间，格式yyyy-MM-dd HH:mm:ss
signInAddress	String	否	白沙里小区(离餐厅736米)	签到地址

ReportInfo字段说明

名称	类型	是否必填	示例	说明
numOfConsumer	Integer	否	2	消费人数，大于0的正整数
consumerNames	String	否	张某某,王某某	消费人员姓名，此字段是手动输入框组件内容返回
sceneTypeDesc	String	否	会议宴请	消费科目
reason	List<Reason>	否		消费原因记录
externalApplyNo	String	否	xxx	外部申请单号
personAvgAmount	String	否	300.00	消费人均金额，单位元，精确到小数点后两位
ticketPicUrls	String	否	http:xxx	用餐小票图片地址url，如果有多张图片，会使用英文,间隔
reportType	Integer	否	1	报备类型， 1：线上报备；2：特许报备
reportStatus	Integer	否		报备状态，0：无需稍后填写；1：需要稍后报备；2：已报备
editCount	Integer	否		修改次数（仅稍后报备才会有）
changeLogList	List<ChangeLog>	否		特许消费报备修改记录（历史报备单内容）
staffList	List<StaffInfo>	否		内部参与人列表
guestList	List<GuestInfo>	否		外部参与人列表
applyExceedInfo	ApplyExceedInfo	否		申请单超额信息
customFieldList	List<CustomFieldInfoCO>	否		自定义字段

Reason字段说明

名称	类型	是否必填	示例	说明
reasonTime	String	否	2020-01-08 10:55:26	消费原因填写时间，格式yyyy-MM-dd HH:mm:ss
reasonContent	String	否	会议宴请	备注原因(特许报备时指事由)
extraReason	String	否	商家原因	其它原因(特许报备时指原因)

ChangeLog

名称	类型	是否必填	示例	说明
changeType	Integer	否	1	修改类型 0:金额修改 1:人数修改
changeTime	String	否	2020-01-08 10:55:26	修改时间，格式yyyy-MM-dd HH:mm:ss
beforeValue	String	否	188	修改前记录值
afterValue	String	否	288	修改后记录值
staffIdentifier	String	否	383847	员工唯一标识

StaffInfo字段说明

名称	类型	是否必填	示例	说明
staffId	Long	是	10001	美团企业版员工Id
staffName	String	是	张三	员工姓名
staffIdentifier	String	是	001	企业对该员工的唯一标识

GuestInfo字段说明

名称	类型	是否必填	示例	说明
guestName	String	是	张三	外部人员姓名
guestFirstName	String	否	三	外部人员名
guestLastName	String	否	张	外部人员姓
guestCompany	String	否	三快在线	外部人员公司或医院
guestOrg	String	否	人事科	外部人员所属部门或科室
guestId	String	是	552	企业外部人员唯一标识(美团企业版系统)
externalGuestId	String	否	GUEST01	企业外部人员唯一识别(第三方系统）

ApplyExceedInfo字段说明

名称	类型	是否必填	示例	说明
isExceed	Integer	否	张三	是否超标,0:未超标; 1:超标
exceedAmount	String	否	22.12	超标金额。单位:元，精确到分
exceedReason	String	否	团建	超标原因

CustomFieldInfoCO字段说明

名称	类型	是否必填	示例	说明
label	String	否	特殊用餐说明	xxx
value	String	否	xx	文本框输入示例：请客户用餐分
type	Integer	否	1	文本

3.示例

3.1.请求示例

3.1.1.请求示例

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

3.1.2.请求参数content解析

{
  "ts": 1617085650321,
  "entId": 100746,
  "sqtBizOrderId": 529375902136680
}

3.2.响应示例

3.2.1.响应结果

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

3.2.2.响应参数data解析

{
  "isGreyShop": 0,
  "payInfo": [
    {
      "cardNo": null,
      "payMethod": "微信网页wap支付"
    }
  ],
  "shopInfo": {
    "shopName": "金园火锅家宴私房菜",
    "shopAddress": "公信路与东方街交界处",
    "shopTitle": "上海小小餐饮管理有限公司广富林路店",
    "shopAvgPrice": "207",
    "shopPhone": "13800000000"
  },
  "signInInfo": {
    "signInStatus": 1,
    "signInTime": "2023-03-08 14:37:45",
    "signInAddress": "白沙里小区(离餐厅736米)"
  },
  "reportInfo": {
    "numOfConsumer": 7,
    "consumerNames": "张三",
    "sceneTypeDesc": "加班餐",
    "reason": [
      {
        "reasonTime": "2023-03-08 14:39:30",
        "reasonContent": "会议用餐",
        "extraReason": "吃饭饭"
      }
    ],
    "externalApplyNo": "CSRTMAP22000857",
    "personAvgAmount": "214.00",
    "ticketPicUrls": "http://p0.meituan.net/shangqitong/137db072.jpeg",
    "reportType": 1,
    "reportStatus": 0,
    "editCount": 0,
    "changeLogList": [
      {
        "changeType": 0,
        "changeTime": "2023-03-13 15:42:10",
        "beforeValue": "3528.00",
        "afterValue": "3524.00",
        "staffIdentifier": "JZCN"
      }
    ],
    "staffList": [
      {
        "staffId": 4063604,
        "staffName": "李八",
        "staffIdentifier": "S002374"
      }
    ],
    "guestList": [
      {
        "guestId": "166159",
        "guestName": "杨六一",
        "guestFirstName": null,
        "guestLastName": null,
        "guestCompany": "汕头大学医学院第一附属医院",
        "guestOrg": "内分泌科",
        "externalGuestId": "SRE09933"
      },
      {
        "guestId": "586980",
        "guestName": "林五一",
        "guestFirstName": null,
        "guestLastName": null,
        "guestCompany": "汕头大学医学院第一附属医院",
        "guestOrg": "内分泌科",
        "externalGuestId": "SRE099112"
      },
      {
        "guestId": "164202",
        "guestName": "林一",
        "guestFirstName": null,
        "guestLastName": null,
        "guestCompany": "汕头大学医学院第一附属医院",
        "guestOrg": "内分泌科",
        "externalGuestId": null
      }
    ],
    "applyExceedInfo": {
      "isExceed": 1,
      "exceedAmount": "12.80",
      "exceedReason": "测试"
    },
    "customFieldList": [
      {
        "label": "自定义字段标题1",
        "value": "字段内容1",
        "type": 1
      },
      {
        "label": "自定义字段标题2",
        "value": "字段内容2",
        "type": 1
      }
    ]
  }
}

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	参数异常	请求参数校验异常，请根据msg中内容排查传值情况，如sqtBizOrderId是否传值
10130001	业务异常	请提供响应结果中的traceId参数和sqtBizOrderId参数，联系客户经理进行排查
10130002	系统异常	请提供响应结果中的traceId参数和sqtBizOrderId参数，联系客户经理进行排查

5.代码实例

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

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.ComplianeDetailRequest;
import com.meituan.sqt.response.in.BaseApiResponse;
import com.meituan.sqt.response.in.compliance.ComplianceDetailResultItem;

/**
 * @Description 用餐合规详情查询接口使用实例
 * @Author hubo11
 * @Date 2023/3/14 7:54 下午
 */
public class ComplianceDetailDemo {

    private static final String invokeUrl = "https://bep-openapi.meituan.com/api/sqt/open/supply/queryComplianceDetail";
    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 {
        // 构建请求对象
        ComplianeDetailRequest complianeDetailRequest = new ComplianeDetailRequest();
        complianeDetailRequest.setTs(System.currentTimeMillis());
        complianeDetailRequest.setEntId(sqtClient.getEntId());
        complianeDetailRequest.setSqtBizOrderId(1L);

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

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

    private static void handleRespFailResult(BaseApiResponse<ComplianceDetailResultItem> 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	2022-11-05	用餐合规详情查询接口初稿
v1.1	2023-06-02	合规详情增加自定义字段