# 用餐申请单同步接口

# 1.概述

调用【用餐申请单同步】接口，可以将企业自有申请单或者外部生态申请单同步到美团企业版，同步成功后，在下单环节可以选中对应用餐申请单并根据申请单内的管控条件限制下单。

# 2.接口基本信息

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

# 2.1.请求体

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

# content加密前数据结构

名称	类型	是否必填	示例	说明
ts	Long	是	1617085650321	13位时间戳。若请求发起时间与平台接受请求时间相差大于10分钟，平台将直接拒绝本次请求
entId	Long	是	46574	企业ID
externalApplyList	List<ApplyInfo>	是	见ApplyInfo	同步到美团企业版的企业自有出差申请单列表,数量最小为1，最大为10

ApplyInfo字段说明

名称	类型	是否必填	示例	说明
sceneType	Integer	是		用餐场景，1：商务宴请；4：工作餐；5：团建用餐
rulePackIdentifier	String	否		用餐规则唯一标识 (可在企业管理后台-用餐规则中配置)
externalApplyNo	String	是		外部用餐申请单号
externalApplyName	String	否		申请单主题/名称（限制：64个字符以内）
submitStaff	StaffInfo	是		申请单提交人信息
startTime	Long	是		有效期开始时间（ms时间戳）
endTime	Long	是		有效期结束时间（ms时间戳）
buyerList	List<StaffInfo>	是		下单人信息（可以使用此申请单下单的成员名单）
repastPersonList	List<StaffInfo>	否		内部用餐人列表（内部员工）
guestList	List<GuestInfo>	否		外部用餐人列表（宴请客户）
costCenterList	List<CostCenterInfo>	否		成本中心列表
cityIdList	List<Integer>	否		用餐城市列表，枚举数据详见：行政区划查询接口，且仅支持市级城市，如：北京市-110000
restaurantIdList	List<String>	否		用餐餐厅列表（目前仅支持传入1个餐厅），当需要通过申请单限制具体消费餐厅时，此字段必传，并联系客户经理开通
invoiceInfo	InvoiceInfo	否		发票信息，默认不落值，如需记录申请单的发票信息，请联系客户经理开通
limitAmount	String	否		说明文案：申请单可用企业支付额度，单位元，精确到小数点后两位，当进行传值时，金额需大于0，如需强管控企业支付额度，请联系客户经理开通
reason	String	否	SCSWWES	用餐原因（限制：100个字符以内）

StaffInfo字段说明

名称	类型	是否必填	示例	说明
staffId	Long	否	49358	美团企业版员工id，美团企业版对员工的唯一标识，staffId和staffIdentifier同时存在时，以staffId为准。
staffIdentifier	String	是	17637465786	企业内部的员工唯一标识（手机号/工号/邮箱，如不确认，请和客户经理确认）
staffName	String	否	小明	员工姓名

GuestInfo字段说明

名称	类型	是否必填	示例	说明
guestName	String	是	小明	外部用餐人姓名
externalGuestId	String	否	49358	externalGuestId字段说明：外部出行人ID（客户平台侧），externalGuestId、guestPhone必传其一，如无法传值，请提前与客户经理协商
guestPhone	String	否	17637465786	外部出行人电话，externalGuestId、guestPhone必传其一，如无法传值，请提前与客户经理协商
guestCompany	String	否	北京三快在线科技有限公司	外部用餐人公司
guestOrg	String	否	美团企业版	外部用餐人所属部门名称

CostCenterInfo字段说明

名称	类型	是否必填	示例	说明
costNo	String	是		成本中心编码
costName	String	是	张三	成本中心名称
ratio	String	否	0.4	分摊比例，数值范围在[0,1]之间，当出现多个成本中心时，ratio必传，且多个成本中心的ratio之和必须为1，精度支持小数点后四位
customField1	String	否		成本中心自定义字段1
customField2	String	否		成本中心自定义字段2
customField3	String	否		成本中心自定义字段3
customField4	String	否		成本中心自定义字段4
customField5	String	否		成本中心自定义字段5

InvoiceInfo字段说明

名称	类型	是否必填	示例	说明
externalInvoiceId	String	否	68578	企业内部发票id
invoiceTitle	String	否	北京三快在线科技有限公司	发票抬头
invoiceNum	String	否	税号	发票税号

# 2.2.响应参数

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

# data解密后数据结构

类型	是否必填	示例	说明
List<ApplySyncResult>	是	见ApplySyncResult	同步申请单结果列表

ApplySyncResult字段说明

名称	类型	是否必填	示例	说明
result	Integer	是	0	接口响应编码，返回0为同步成功，返回其他则有报错，编码枚举值和解决方案详见第四章
itemMsg	String	是	成功	同步结果信息描述
applyNo	String	否	397374	美团企业版申请单号
externalApplyNo	String	是	39WNRUYJC1Z6	外部用餐申请单号

# 3.示例

# 3.1.请求示例

# 3.1.1.请求示例

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

# 3.1.2.请求参数content解析

{
  "ts": 1617085650321,
  "entId": 100991,
  "externalApplyList": [
    {
      "sceneType": 1,
      "rulePackIdentifier": "rulePackIdentifier",
      "externalApplyNo": "5N9D0AD96RY92",
      "externalApplyName": " test",
      "startTime": 1673318578000,
      "endTime": 1673404978000,
      "limitAmount": 5000,
      "reason": "测试用餐事由",
      "submitStaff": {
        "staffIdentifier": "18913333760",
        "staffName": "张三"
      },
      "buyerList": [
        {
          "staffIdentifier": "18913333760",
          "staffName": "张三"
        }
      ],
      "repastPersonList": [
        {
          "staffIdentifier": "18913333760",
          "staffName": "张三"
        }
      ],
      "restaurantIdList": [
       "808271599564320770"
      ],
      "cityIdList": [
        110000
      ],
      "costCenterList": [
        {
          "costNo": "costNoxxx33",
          "costName": "costName test"
        }
      ],
      "invoiceInfo": {
        "invoiceTitle": "申请单发票抬头",
        "externalInvoiceId": "2697",
        "invoiceNum": "1213123"
      }
    },
    {
      "sceneType": 1,
      "externalApplyNo": "xxxxxx21",
      "externalApplyName": " test",
      "startTime": 1673318578000,
      "endTime": 1673404978000,
      "limitAmount": 5000,
      "reason": "测试用餐事由",
      "submitStaff": {
        "staffIdentifier": "18913333760",
        "staffName": "张三"
      },
      "buyerList": [
        {
          "staffIdentifier": "18913333760",
          "staffName": "张三"
        }
      ],
      "repastPersonList": [
        {
          "staffIdentifier": "18913333760",
          "staffName": "张三"
        }
      ],
      "cityIdList": [
        110000
      ],
      "costCenterList": [
        {
          "costNo": "costNoxxx33",
          "costName": "costName test"
        }
      ],
      "invoiceInfo": {
        "invoiceTitle": "申请单发票抬头",
        "externalInvoiceId": "2697",
        "invoiceNum": "1213123"
      }
    }
  ]
}

# 3.2.响应示例

# 3.2.1.响应结果

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

# 3.2.2.响应参数data解析

[
  {
    "applyNo":"5NQZ0NBUDZPD",
    "externalApplyNo":"5N9D0AD96RY9-1",
    "result":0,
    "itemMsg":"处理成功"
  },
  {
    "applyNo":"5NQZ0OBUFB42",
    "externalApplyNo":"xxxxxx21-3",
    "result":0,
    "itemMsg":"处理成功"
  }
]

# 4.错误码

# 4.1.status错误码

错误码	错误描述	解决方案
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次，超出限额则会报错
10170001	参数校验不通过，必填参数为空	请查看响应结果中的msg信息，根据提示进行调整，必传字段不可传空值
10170002	入参数据校验不通过	请查看响应结果中的msg信息，根据提示确认字段是否正确传值，如sceneType枚举值错误等
40175000	未知错误，请联系美团侧研发	请提供响应结果中的traceId参数，联系客户经理进行排查
40175001	部分处理成功	请查看响应结果中的result和itemMsg信息，根据解决方案进行调整

# 4.2.result错误码

错误码	错误描述	解决方案
10170002	入参数据校验不通过	请查看响应结果中的itemMsg信息，根据提示进行传值调整，如sceneType枚举值错误等
40175000	系统处理异常	请提供响应结果中的traceId参数和externalApplyNo参数，联系客户经理进行排查

# 5.代码实例

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

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.apply.RepastApplySyncRequest;
import com.meituan.sqt.response.in.BaseApiResponse;
import com.meituan.sqt.response.in.apply.RepastApplySyncResultItem;

import java.util.List;

public class RepastApplySyncDemo {
    private static final String invokeUrl = "https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/repast/applySync";

    private static SqtClient sqtClient = null;

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

    public static void main(String[] args) throws MtSqtException {
        // 构建请求对象
        RepastApplySyncRequest repastApplySyncRequest = new RepastApplySyncRequest();
        repastApplySyncRequest.setTs(System.currentTimeMillis());
        repastApplySyncRequest.setEntId(sqtClient.getEntId());
        
        RepastApplySyncRequest.ApplyInfo applyInfo = new RepastApplySyncRequest.ApplyInfo();
        applyInfo.setExternalApplyNo("test-1233333");
        applyInfo.setSceneType(1);
        applyInfo.setRulePackIdentifier("");
        applyInfo.setExternalApplyName("test");
        applyInfo.setStartTime(1673318578000L);
        applyInfo.setEndTime(1673404978000L);
        applyInfo.setLimitAmount("5000");
        applyInfo.setReason("test");
        
        RepastApplySyncRequest.StaffInfo submitStaff = new RepastApplySyncRequest.StaffInfo();
        submitStaff.setStaffIdentifier("18513083760");
        submitStaff.setStaffName("张三");
        applyInfo.setSubmitStaff(submitStaff);
        applyInfo.setBuyerList(Lists.newArrayList(submitStaff));
        applyInfo.setRepastPersonList(Lists.newArrayList(submitStaff));
        applyInfo.setCityIdList(Lists.newArrayList(110000));
        applyInfo.setRestaurantIdList(Lists.newArrayList("808271599564320770"));
        repastApplySyncRequest.setExternalApplyList(Lists.newArrayList(applyInfo));
        // API调用
        // 注意：超时时间默认以请求对象中注解ApiMeta上设置的为准，也可以自定义传递对应的超时时间
        BaseApiResponse<List<RepastApplySyncResultItem>> response = sqtClient.invokeApi(invokeUrl, repastApplySyncRequest, null, null);
        // 响应结果为空处理
        if (response == null) {
            // 处理响应结果为空情况
            // ...

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

    private static void handleRespFailResult(BaseApiResponse<List<RepastApplySyncResultItem>> 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-02-02	新增用餐申请同步接口
v1.1	2023-05-19	迭代，支持指定用餐规则唯一识别
v1.2	2023-07-07	迭代，支持指定计划用餐餐厅

← 角色下员工删除用餐申请单作废 →