出差申请单查询接口

1.概述

调用【出差申请单查询】接口，查询美团企业版系统内出差申请单数据。

2.接口基本信息

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

2.1.请求体

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

content加密前数据结构

名称	类型	是否必填	示例	说明
ts	Long	是	1617085650321	13位时间戳。若请求发起时间与平台接受请求时间相差大于10分钟，平台将直接拒绝本次请求
entId	Long	是		企业ID
applyNoList	List<String>	否		美团企业版出差申请单号列表
externalApplyNoList	List<String>	否		外部出差申请单号列表
submitStaffId	Long	否		出差申请单提交人StaffId（美团企业版内部员工Id）
passengerStaffId	Long	否		出差申请单中，内部出行人StaffId（美团企业版内部员工Id）
minCreatedTime	Long	否		最小创建申请单时间，13位时间戳
maxCreatedTime	Long	否		最大创建申请单时间，13位时间戳
minModifiedTime	Long	否		最小修改申请单时间，13位时间戳
maxModifiedTime	Long	否		最大修改申请单时间，13位时间戳
pageNum	Integer	否		分页页码，默认值为1，每页数量固定为20条

2.2.响应参数

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

data解密后数据结构

名称	类型	是否必填	示例	说明
pageNum	Integer	是	1	当前页码，最小为1
pageSize	Integer	是		当前页返回申请单条数
pageTotal	Integer	是		结果集总页数
totalCount	Long	是		结果集总数量
applyList	List<ApplyInfo>	否		申请单数据列表

ApplyInfo字段说明

名称	类型	是否必填	示例	说明
applyNo	String	是	111111	美团企业版申请单号
externalApplyNo	String	否	37fha729	企业自有申请单号
applyType	Integer	是		出差申请单类型，0： 企业内部完成审批流程，1：使用美团审批流程
applyStatus	Integer	是	1	出差申请单状态，缺省值默认为1，枚举值为0：删除；1：通过；2：驳回；3：审批中；-1：撤回
submitStaff	StaffInfo	是		出差申请单提交人
travellerList	List<TravellerInfo>	是		出行人列表，包含内部出行人和外部出行人
tripList	List<TripInfo>	是		出差行程列表
createdTime	Long	是		创建时间，13位时间戳
modifiedTime	Long	是		最新更新时间，13位时间戳
invoiceTitle	String	是	深圳美团科技有限公司	企业发票抬头
reason	String	否	会展	申请事由（手动输入）
selectedReason	String	否		申请事由（下拉选择）
costCenterList	List<CostCenterInfo>	否		成本中心列表
projectList	List<ProjectInfo>	否		项目列表
feeBelongType	String	否	COST	费用归属类型，COST：费用归属成本中心；PROJECT：费用归属项目

StaffInfo字段说明

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

TravellerInfo字段说明

名称	类型	是否必填	示例	说明
travellerType	Integer	是	1	出行人类型，1：企业员工；2：外部人员
travellerId	Long	是	49358	美团企业版出行人ID，当travellerType值为1时，字段返回的是美团企业版的员工ID-staffId，当travellerType值为2时，字段返回的是美团企业版的出行人ID-guestId
travellerIdentifier	String	是	17637465786	企业内出行人唯一标识，当travellerType值为1时，字段返回的是企业内员工唯一标识-staffIdentifier，当travellerType值为2时，字段返回的是企业内外部出行人唯一标识-externalGuestId
travellerName	String	是	张三	出行人姓名
orgId	Long	否	123	所在部门ID
orgName	String	否	部门1	所在部门名称
orgIdPath	String	否	0-1	所在部门ID链，例如字段返回 0-7373-fifi44，其中0代表企业根目录
orgNamePath	String	否	集团-部门	所在部门名称链，从根目录返回，即企业名称-一级部门- …… -员工所在部门
externalOrgId	String	否	D1000105	所在客户平台的部门ID

TripInfo字段说明

名称	类型	是否必填	示例	说明
tripId	String	是		美团企业版行程ID
externalTripId	String	是		企业自有行程ID
tripType	Integer	否	0	说明修改：行程类型，0：不限；1：单程；2：往返，默认返回0。只有按行程维度控时该字段才有效，且只对机票和火车票两个品类有效。
departureTime	Long	是	1635177600000	行程开始时间，13位时间戳
arrivalTime	Long	是	1635177600000	行程结束时间，13位时间戳
categoryList	Set<Integer>	否		品类列表，0：不限制；010：到店；020：外卖；030：酒店；040：打车；050：火车票；060：机票；-1其他。【其他】即美团企业版暂不支持的品类，如果仅传-1枚举值，申请单无法下单。
departureCityList	List<CityInfo>	否		出发城市
arrivalCityList	List<CityInfo>	否		到达城市

CityInfo字段说明

名称	类型	是否必填	示例	说明
cityId	String	是	110100	城市编号（国标），例如110100
cityName	String	是	北京市	城市名称
cityType	Integer	是		城市类型，1：境内 ；2：境外

CostCenterInfo字段说明

名称	类型	是否必填	示例	说明
costNo	String	是		成本中心编码
costName	String	是	张三	成本中心名称
ratio	String	否	0.4	分摊比例，数值范围在[0,1]之间
customField1	String	否		成本中心自定义字段1
customField2	String	否		成本中心自定义字段2
customField3	String	否		成本中心自定义字段3
customField4	String	否		成本中心自定义字段4
customField5	String	否		成本中心自定义字段5

ProjectInfo字段说明

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

3.示例

3.1.请求示例

3.1.1.请求示例

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

3.1.2.请求参数content解析

{
  "ts": 1673404978000,
  "entId": 101734,
  "externalApplyNoList": [
    "xxxx123"
  ],
  "applyNoList": [
    "32906"
  ],
  "submitStaffId": 960964,
  "passengerStaffId": 960965
}

3.2.响应示例

3.2.1.响应结果

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

3.2.2.响应参数data解析

{
  "pageNum": 1,
  "pageSize": 1,
  "pageTotal": 1,
  "totalCount": 1,
  "applyList": [
    {
      "applyNo": "32906",
      "externalApplyNo": "wwj-test-1",
      "applyType": 0,
      "applyStatus": 1,
      "submitStaff": {
        "staffId": 960965,
        "staffName": "xxx",
        "staffIdentifier": "18333033760"
      },
      "travellerList": [
        {
          "travellerType": 1,
          "travellerId": 960965,
          "travellerIdentifier": "18333033760",
          "travellerName": "xxx",
          "orgId": null,
          "orgName": null,
          "orgIdPath": null,
          "orgNamePath": null,
          "orgInfo": null
        }
      ],
      "tripList": [
        {
          "tripId": "415397",
          "externalTripId": "externalTripId1",
          "tripType": 0,
          "departureTime": 1673318578000,
          "arrivalTime": 1673404978000,
          "categoryList": [
            0
          ],
          "departureCityList": [
            {
              "cityId": "110100",
              "cityName": "北京市",
              "cityType": 1
            }
          ],
          "arrivalCityList": [
            {
              "cityId": "120100",
              "cityName": "天津市",
              "cityType": 1
            }
          ]
        }
      ],
      "createdTime": 1673328407000,
      "modifiedTime": 1673328407000,
      "invoiceTitle": "测试发票抬头",
      "reason": "测试",
      "selectedReason": null,
      "costCenterList": [
        {
          "costNo": "成本中心编码",
          "costName": "成本中心名称",
          "ratio": null,
          "customField1": null,
          "customField2": null,
          "customField3": null,
          "customField4": null,
          "customField5": null
        }
      ],
      "projectList": [
        {
          "projectNo": "项目编码",
          "projectName": "项目名称 test"
        }
      ],
      "feeBelongType": ""
    }
  ]
}

4.错误码

错误码	错误描述	解决方案
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信息，根据提示确认字段是否正确传值，如applyStatus枚举值错误等
40175000	未知错误，请联系美团侧研发	请提供响应结果中的traceId参数，联系客户经理进行排查

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

public class TripApplyQueryDemo {

    private static final String invokeUrl = "https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/trip/applyQuery";
    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 {
        // 构建请求对象
        TripApplyQueryRequest tripApplyQueryRequest = new TripApplyQueryRequest();
        tripApplyQueryRequest.setTs(System.currentTimeMillis());
        tripApplyQueryRequest.setEntId(sqtClient.getEntId());
        tripApplyQueryRequest.setPageNum(1);
        tripApplyQueryRequest.setApplyNoList(Lists.newArrayList("30144"));
        // API调用
        // 注意：超时时间默认以请求对象中注解ApiMeta上设置的为准，也可以自定义传递对应的超时时间
        BaseApiResponse<TripApplyQueryResult> response = sqtClient.invokeApi(invokeUrl, tripApplyQueryRequest, null, null);
        // 响应结果为空处理
        if (response == null) {
            // 处理响应结果为空情况
            // ...

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

    private static void handleRespFailResult(BaseApiResponse<TripApplyQueryResult> 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	新增出差申请查询接口