出差申请单同步接口

1.概述

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

2.接口基本信息

名称	描述
请求方式	POST
调用地址	测试环境：https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/trip/applySync 正式环境：https://bep-openapi.meituan.com/api/sqt/open/trip/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	同步到美团企业版的企业自有出差申请单列表，单次调用最大数量不可超过10条

ApplyInfo字段说明

名称	类型	是否必填	示例	说明
externalApplyNo	String	是	i3832	企业自有申请单ID
submitStaff	StaffInfo	是		出差申请单提交人
applyStatus	Integer	是	1	出差申请单状态，1：通过；2：驳回；3：审批中；-1：撤回
invoiceTitle	String	是	深圳美团科技有限公司	企业发票抬头，需提前到企业管理后台维护发票信息
passengerList	List<StaffInfo>	否		内部出行人列表，passengerList和guestList不能同时为空
guestList	List<GuestInfo>	否		外部出行人列表，passengerList和guestList不能同时为空
tripList	List<TripInfo>	是		行程列表，每个申请单中的行程不可超过50条，且行程列表不可为空。
tripSubsidy	String	否	200.05	出差补助金额（单位：元，精度在小数点后两位），此补助金额仅可用于餐和车的消费，且额度共享。
costCenterList	List<CostCenterInfo>	否		成本中心列表，多个成本中心分摊比例要么都为空，要么都不为空；若都不为空，数值范围必须在 [0,1] 闭区间内，且分摊比例之和必须为1。
projectList	List<ProjectInfo>	否		项目列表，目前仅支持传0-1个项目信息，且当传入项目时，projectNo和projectName必传
reason	String	否	会展	申请原因，超出500个字符的部分会被截断

StaffInfo字段说明

名称	类型	是否必填	示例	说明
staffIdentifier	String	是	17637465786	企业内部的员工唯一标识（手机号/工号/邮箱，如不确认，请和客户经理确认）
staffName	String	否	张三	员工姓名

GuestInfo字段说明

名称	类型	是否必填	示例	说明
externalGuestId	String	否	49358	外部出行人ID（客户平台侧），externalGuestId、guestPhone、guestCertificateList必传其一，如无法传值，请提前与客户经理协商
guestName	String	是	小明	外部出行人姓名
guestPhone	String	否	17637465786	外部出行人电话，externalGuestId、guestPhone、guestCertificateList必传其一，如无法传值，请提前与客户经理协商
guestCompany	String	否	北京三快在线科技有限公司	外部出行人公司
guestPosition	String	否	产品经理	外部出行人职务
guestBirthday	String	否	2008-07-05	外部出行人生日，格式：yyyy-MM-dd
guestSex	Integer	否	1	外部出行人性别，1：男；2：女
guestCertificateList	List<CertificateInfo>	否		外部出行人证件列表，externalGuestId、guestPhone、guestCertificateList必传其一，如无法传值，请提前与客户经理协商

CertificateInfo字段说明

名称	类型	是否必填	示例	说明
certificateType	Integer	是	0	证件类型，0：身份证，1：护照，2：其它，默认值为0
certificateNum	String	是	131022198909235978	证件号码

TripInfo字段说明

名称	类型	是否必填	示例	说明
externalTripId	String	是		企业自有行程ID
tripType	Integer	否	0	行程类型，0：不限；1：单程；2：往返。只有按行程维度控时该字段才有效，且只对机票和火车票两个品类有效。
departureTime	Long	是	1635177600000	行程开始时间，13位时间戳
arrivalTime	Long	是	1635177600000	行程结束时间，13位时间戳
categoryList	List<String>	否		品类列表，0：不限制；010：到店；020：外卖；030：酒店；040：打车；050：火车票；060：机票；-1其他。【其他】即美团企业版暂不支持的品类，如果仅传-1枚举值，申请单无法下单。不传或传空按照0（不限制）处理
departureCityList	List<CityInfo>	否		出发城市列表，出发城市个数不能超过50
arrivalCityList	List<CityInfo>	否		到达城市列表，到达城市个数不能超过50
hotelTripRule	HotelTripRule	否		酒店动态差标信息，只有按照行程维度管控时，字段条件才会有效，如需开通行程维度管控，请联系客户经理进行配置
hotelControlInfo	HotelControlInfo	否		酒店管控信息，只有按照行程维度管控时，字段条件才会有效，如需开通行程维度管控，请联系客户经理进行配置
flightTripRule	FlightTripRule	否		机票动态差标信息，只有按照行程维度管控时，字段条件才会有效，如需开通行程维度管控，请联系客户经理进行配置

CityInfo字段说明

名称	类型	是否必填	示例	说明
cityId	String	是	110100	城市编号（国标），枚举数据详见：行政区划查询接口，且仅支持市级和区县级城市，如110100
cityName	String	是	北京市	城市名称

HotelTripRule字段说明

名称	类型	是否必填	示例	说明
isDynamic	Boolean	否	true	是否动态差标，不传或者传false时，使用静态差标
roomPriceExceedBookType	Integer	否	200	酒店平均间夜费超标处理方案，200：可继续预定，需填写超标原因；300：拦截预定，默认值为200。当平均间夜价格大于maxRoomPrice时，会使用此字段传值方案进行处理
roomPriceExceedPayTypeList	List<Integer>	否		酒店平均间夜费用超标后，允许使用的支付方式，1：个人支付；2：企业支付；3：组合支付。当传入多种支付方式后，默认使用企业支付，员工可以在支付环节中自行切换
maxRoomPrice	String	否		每间夜差标上限（单位：元，精度在小数点后两位）：单间夜酒店的平均价格不得高于该值，如预定3间夜时，预定总金额➗3后的价格，不能高于maxRoomPrice值

HotelControlInfo字段说明

名称	类型	是否必填	示例	说明
maxRoomNight	Integer	否		最大间夜数，一个申请单中，最多可以预定的间夜总量

FlightTripRule字段说明

名称	类型	是否必填	示例	说明
isDynamic	Boolean	否	true	是否动态差标，不传或者传false时，使用静态差标
cabinDiscountList	List<CabinDiscountInfo>	否		舱位折扣列表，不传值则不限制舱位
cabinExceedBookType	Integer	否		舱位超标处理方案，200：可继续预定，需填写超标原因；300：拦截预定，默认值为200。当机票舱位超标时，会使用此字段传值方案进行处理
cabinExceedPayTypeList	List<Integer>	否		舱位超标后，允许使用的支付方式，1：个人支付；2：企业支付。当传入多种支付方式后，默认使用企业支付，员工可以在支付环节中自行切换

CabinDiscountInfo字段说明

名称	类型	是否必填	示例	说明
airCabin	Integer	是	101	机票舱位，100：头等舱；101：公务舱；102：经济舱
discount	Integer	是	9	允许预定的机票折扣，只在airCabin为102-经济舱时生效，数值为1-10，比如九折则传入9，默认值为10

CostCenterInfo字段说明

名称	类型	是否必填	示例	说明
costNo	String	是	0493	成本中心编码，长度不能超过128
costName	String	是	自定义成本中心1	成本中心名称，长度不能超过200
ratio	String	否	0.4	分摊比例,精度支持最多小数点后四位。多个成本中心分摊比例要么都为空，要么都不为空；若都不为空，数值范围必须在 [0,1] 闭区间内，且分摊比例之和必须为1。
customField1	String	否		成本中心自定义字段1
customField2	String	否		成本中心自定义字段2
customField3	String	否		成本中心自定义字段3
customField4	String	否		成本中心自定义字段4
customField5	String	否		成本中心自定义字段5

ProjectInfo字段说明

名称	类型	是否必填	示例	说明
projectNo	String	是	68578	项目编码
projectName	String	是	自定义项目1	项目名称

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": 101734,
  "externalApplyList": [
    {
      "externalApplyNo": "xxx-test-4",
      "applyStatus": 1,
      "tripSubsidy": "100",
      "reason": "测试",
      "submitStaff": {
        "staffIdentifier": "18413433760",
        "staffName": "张三"
      },
      "passengerList": [
        {
          "staffIdentifier": "18413433760",
          "staffName": "张三"
        }
      ],
      "guestList": [
        {
          "externalGuestId": "22222",
          "guestName": "22222",
          "guestSex": 1,
          "guestCertificateList": [
            {
              "certificateType": 0,
              "certificateNum": "142631199604116030"
            }
          ]
        }
      ],
      "costCenterList": [
        {
          "costNo": "成本中心编码",
          "costName": "成本中心名称"
        }
      ],
      "projectList": [
        {
          "projectNo": "项目编码",
          "projectName": "项目名称 test"
        }
      ],
      "tripList": [
        {
          "externalTripId": "externalTripId1",
          "tripType": 0,
          "departureTime": 1673318578000,
          "arrivalTime": 1673404978000,
          "categoryList": [
            "0"
          ],
          "departureCityList": [
            {
              "cityId": "110000",
              "cityName": "北京"
            }
          ],
          "arrivalCityList": [
            {
              "cityId": "120000",
              "cityName": "天津"
            }
          ]
        }
      ]
    }
  ]
}

3.2.响应示例

3.2.1.响应结果

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

3.2.2.响应参数data解析

[
  {
    "applyNo":"33006",
    "externalApplyNo":"xxx-test-4",
    "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信息，确认参数填写是否正确
40175000	未知错误，请联系美团侧研发	请提供响应结果中的traceId参数，联系客户经理进行排查
40175001	部分处理成功	请查看响应结果中的result和itemMsg信息，根据解决方案进行调整

4.2.result错误码

错误码	错误描述	解决方案
10170003	项目编码和名称都不为空	请检查项目编码和项目名称传值是否有空值，当projectList传值时，projectNo和projectName字段都需要传值
10170004	成本中心编码和名称都不为空	请检查成本中心名称和成本中心编码传值是否有空值，当costCenterList传值时，costNo和costName字段都需要传值
10170005	成本中心编码长度超过接口文档要求长度	检查costNo传值，成本中心编码长度不能超过128
10170006	成本中心名称长度超过接口文档要求长度	检查costName传值，成本中心名称长度不能超过200
10170007	申请单关联的成本中心有的分摊比例（ratio字段）为空，有的不为空	检查ratio传值，当申请单存在多个成本中心的情况下，ratio字段要么都传，要么都不传
10170008	成本中心分摊比例数值范围不在0到1之间	检查ratio传值，ratio取值范围在[0,1]
10170009	成本中心分摊比例精度最多为小数点后四位	检查ratio传值，分摊比例精度到小数点后四位
10170010	申请单关联的所有成本中心分摊比例之和不为 1	检查ratio传值，当申请单有多个成本中心且都传了ratio的情况下，ratio之和必须为1
40173000	行政区划代码非国标	根据itemMsg中的报错，检查cityId传值是否正确，城市基础数据来源为：（行政区划查询），且仅支持市级和区县级城市，如110100
40173001	出差申请单提交人不存在	检查submitStaff参数中staffIdentifier传值是否正确。staffIdentifier必须为企业配置的唯一标识，且已经同步到美团企业版，可选项为手机号/邮箱/工号，如不确认唯一标识，请联系客户经理确认。确认是否成功同步位置：企业管理后台-员工管理-组织架构
40173002	企业未开启外部申请单配置	请联系客户经理为您开通外部申请单同步权限，开通位置：运营后台-客户详情-申请单配置
40173003	出差申请的发票抬头不存在	请到企业管理后台-新发票中心-发票设置菜单确认发票抬头是否已经维护完成
40173004	当前企业未设置有效的唯一标识	联系客户经理给企业设置唯一标识
40173005	审批状态不合法	请检查applyStatus字段传值，枚举值为：1 通过；2 驳回；3 审批中；-1 撤回
40173006	出行人数超出限制，最多50人	请检查passengerList和guestList传参，二者人数之和不可超过50人
40173007	出行人有多人,未开启多人出差	请检查passengerList和guestList传参，当超过一人时，需联系客户经理开通多人出差，开通位置：运营后台-客户详情-功能配置
40173009	出差行程日期属性无效	请检查departureTime和arrivalTime字段传值，是否为正确的13位时间戳，行程开始时间是否小于行程结束时间等
40173013	重复的外部行程ID	请检查externalTripId字段传值，同一个申请单下，不可出现相同的行程ID
40173014	无效的申请单号无法撤销	请检查externalApplyNo字段传值，是否正确且申请单已经同步到美团企业版系统，确认申请单同步成功路径：企业管理后台-单据管理-差旅申请单查询
40173015	企业配置了在线消费补助，但是用户未配置差旅规则	请检查passengerList中的员工是否全部分配过差旅规则，检查位置：企业管理后台-差旅管理-差旅标准设置
40173016	passengerList和guestList不能都为空	请检查passengerList和guestList传参，二者不可都为空
40173017	目前一个申请单仅支持关联0个或1个项目	请检查projectList传参，目前仅支持传0-1个项目
40173018	出差申请的发票抬头为空，且企业没有开启默认发票抬头配置	请检查invoiceTitle字段传值，invoiceTitle必传，如不传发票抬头请联系客户经理配置默认抬头，开通路径：运营后台-客户详情-申请单配置
40173020	不允许撤回已使用关联补助的出差申请	出差申请已使用了补助，不允许撤回
40173021	根据出差申请单提交人的唯一标识查询不到提交人的员工信息	检查submitStaff参数中staffId传值，确认员工已同步到美团企业版，且传值正确。
40173022	提交人在无需申请白名单中，不支持外部出差申请同步	检查submitStaff字段传值，确认员工是否开通了免申请单的预定权限，确认位置：企业管理后台-差旅管理-申请管控
40173023	行程出发时间不能大于到达时间	检查申请单中行程的出发时间是否小于等于到达时间
40174001	外部差旅申请入库异常	请提供响应结果中的traceId参数和externalApplyNo参数，联系客户经理进行排查
40174002	外部出行人导入异常	请提供响应结果中的traceId参数和externalApplyNo参数，联系客户经理进行排查
40174003	外部差旅申请单，关联动态差标信息异常	请提供响应结果中的traceId参数和externalApplyNo参数，联系客户经理进行排查
40174004	外部差旅申请单，关联整单补助预算异常	请提供响应结果中的traceId参数和externalApplyNo参数，联系客户经理进行排查
40174005	补助生成异常	请提供响应结果中的traceId参数和externalApplyNo参数，联系客户经理进行排查
40174000	未知错误，请联系美团侧研发	请提供响应结果中的traceId参数和externalApplyNo参数，联系客户经理进行排查

5.代码实例

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

import com.google.common.collect.Lists;
import com.google.common.collect.Sets;
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.TripApplySyncRequest;
import com.meituan.sqt.response.in.BaseApiResponse;
import com.meituan.sqt.response.in.apply.TripApplySyncResultItem;

import java.util.List;

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

    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 {
        // 构建请求对象
        TripApplySyncRequest tripApplySyncRequest = new TripApplySyncRequest();
        tripApplySyncRequest.setTs(System.currentTimeMillis());
        tripApplySyncRequest.setEntId(sqtClient.getEntId());
        TripApplySyncRequest.ApplyInfo applyInfo = new TripApplySyncRequest.ApplyInfo();
        applyInfo.setExternalApplyNo("test-12333");
        applyInfo.setApplyStatus(1);
        applyInfo.setReason("test");

        TripApplySyncRequest.StaffInfo submitStaff = new TripApplySyncRequest.StaffInfo();
        submitStaff.setStaffIdentifier("18513083760");
        submitStaff.setStaffName("test");
        applyInfo.setSubmitStaff(submitStaff);
        applyInfo.setPassengerList(Lists.newArrayList(submitStaff));

        TripApplySyncRequest.TripInfo tripInfo = new TripApplySyncRequest.TripInfo();
        tripInfo.setExternalTripId("externalTripId1");
        tripInfo.setTripType(0);
        tripInfo.setDepartureTime(1673318578001l);
        tripInfo.setArrivalTime(1673404978000l);
        tripInfo.setCategoryList(Sets.newHashSet("010"));

        TripApplySyncRequest.CityInfo departureCity = new TripApplySyncRequest.CityInfo();
        departureCity.setCityId("110000");
        departureCity.setCityName("北京");
        departureCity.setCityType(1);
        tripInfo.setDepartureCityList(Lists.newArrayList(departureCity));

        TripApplySyncRequest.CityInfo arrivalCity = new TripApplySyncRequest.CityInfo();
        arrivalCity.setCityId("120000");
        arrivalCity.setCityName("天津");
        arrivalCity.setCityType(1);
        tripInfo.setArrivalCityList(Lists.newArrayList(arrivalCity));

        applyInfo.setTripList(Lists.newArrayList(tripInfo));

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

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

    private static void handleRespFailResult(BaseApiResponse<List<TripApplySyncResultItem>> 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	新增出差申请同步接口