# 用车申请单同步接口

# 1.概述

美团企业版为客户提供了用车申请、审批等功能，如果企业客户希望在内部系统完成用车申请，申请单内部审批通过后，在美团企业版进行用车消费，则可以通过本文档进行接口对接。流程如下

# 2.接口基本信息

名称	描述
请求方式	POST
调用地址	测试环境：https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/car/applySync 正式环境：https://bep-openapi.meituan.com/api/sqt/open/car/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字段说明

名称	类型	是否必填	示例	说明
sceneType	Integer	是	2	用车场景：2-企业用车
rulePackIdentifier	String	是	1636106378034	规则包编码(需提前在企业后台进行用车规则配置，值为用车规则详情页的规则ID)
externalApplyNo	String	是	REQ001	外部用车申请单号
applyType	Integer	是	201	申请单类型：201-按次数申请；202-按日期申请
submitStaff	StaffInfo	是		申请单提交人信息
applyReason	String	是	拜访客户	申请事由说明（限制：200个字符以内）
applyCount	Integer	否	7	申请用车次数（限制：[1,100]）
applyAmount	String	否	123.45	申请金额（单位：元，精度在小数点后两位）
scheduleList	List<ScheduleInfo>	是		用车日程列表(当前仅支持单个日程)
costCenterList	List<CostCenterInfo>	否		成本中心列表(当前仅支持单个成本中心)

StaffInfo字段说明

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

ScheduleInfo字段说明

名称	类型	是否必填	示例	说明
startTime	Long	是	1600000000000	开始时间（ms时间戳）
endTime	Long	是	1700000000000	结束时间（ms时间戳）
scheduleType	Integer	否	0	日程类型（默认0）：0-不限；1-单程；2-往返
cityList	List<CityInfo>	否		城市信息列表

CityInfo字段说明

名称	类型	是否必填	示例	说明
cityType	Integer	是	10	城市类型：10-不区分出发或到达的城市；11-出发地城市；12-目的地城市
citySource	Integer	否	10	城市数据来源 10-境内location
cityId	Integer	是	110000	城市编码(国标行政区划编码)
address	String	否	顺义首都机场	用车具体地址
longitude	String	否	116.488634	出发地经度
latitude	String	否	40.007064	出发地纬度

CostCenterInfo字段说明

名称	类型	是否必填	示例	说明
costNo	String	是		成本中心编码
costName	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	是	REQ001	外部用车申请单号

# 3.示例

# 3.1.请求示例

# 3.1.1.请求示例

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

# 3.1.2.请求参数content解析

{
    "ts": 1617085650321,
    "entId": 100991,
    "externalApplyList": [
        {
            "sceneType": 2,
            "externalApplyNo": "外部用车申请单号",
            "rulePackIdentifier": "用车规则详情页-规则ID",
            "applyType": 201,
            "submitStaff": {
                "staffIdentifier": "员工唯一标识"
            },
            "applyReason": "拜访客户",
            "applyCount": 99,
            "applyAmount": null,
            "scheduleList": [
                {
                    "startTime": 1675995929843,
                    "endTime": 1676082329843,
                    "scheduleType": 1,
                    "cityList": [
                        {
                            "cityId": 110105,
                            "cityName": "城市名称-110000",
                            "cityType": 10,
                            "address": "具体地址-110000",
                            "longitude": "116.488634",
                            "latitude": "40.007064"
                        }
                    ]
                }
            ],
            "costCenterList": [
                {
                    "costNo": "costNo1",
                    "costName": "costName1"
                }
            ]
        }
    ]
}

# 3.2.响应示例

# 3.2.1.响应结果

{
    "traceId":"56a0af18ae30a168d4006c7c",
    "status":0,
    "msg":"success",
    "data":"Ju-ZvG_h8mfXHu74cWHxDpqyfpD-I_flSVDPo5qGeruKDNJTt84wm3dSlFHIxxz6dziNtQltt8NAxPKUJ1R1ipLCaPaLshmVWF2p_nvZIZdMdd1SxJW23XTSfWdlkMjcEd_0zrlbNqHRSofkFvNTL0G7C2e8JZTX7yqTrXlBUgU"
}

# 3.2.2.响应参数data解析

[
    {
        "applyNo": "CA1747097793694048299",
        "externalApplyNo": "外部用车申请单号",
        "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错误码

错误码	错误描述	解决方案
10170000	参数校验不通过，参数格式不是合法的json	请检查请求传入的请求数据模型，是否符合接口文档描述。
10170001	参数校验不通过，必填参数为空或取值范围不正确	请检查提示信息中的属性，是否符合接口文档描述。
10170002	未开启外部用车申请功能，如需开启，请联系美团企业版项目经理	请联系美团企业版项目经理，在您的企业开启外部用车申请单功能。
10170003	传入申请类型无效，请检查	请检查请求传入的applyType字段值，是否为字段说明中包含的201、202。
10170004	传入的规则包编码无效，请检查	请检查请求传入的rulePackIdentifier字段值，是否为用车规则详情页的规则ID。
10170005	传入提交人无对应规则包配置，请检查	请检查请求传入的submitStaff员工信息，是否有指定用车规则的权限。
10170006	传入申请类型与规则包配置不符，请检查	请检查请求传入的applyType字段值，是否与指定用车规则配置匹配。
10170007	传入申请金额与规则包配置不符，请检查	请检查请求传入的applyAmount字段值，是否与指定用车规则配置匹配。
10170008	传入城市信息与规则包配置不符，请检查	请检查请求传入的cityList字段值，是否与指定用车规则配置匹配。
10170009	传入用车次数与规则包配置不符，请检查	请检查请求传入的applyCount字段值，是否与指定用车规则配置匹配。
10170010	传入用车时间与规则包配置不符，请检查	请检查请求传入的startTime、endTime字段值，是否与指定用车规则配置匹配。
10170011	传入用车原因与规则包配置不符，请检查	请检查请求传入的applyReason字段值，是否与指定用车规则配置匹配。
10170012	传入时间范围有误，请检查	请检查请求传入的startTime、endTime字段值，是否符合时间段格式要求。
10170013	传入经纬度非法，请检查	请检查请求传入的startTime、endTime字段值，是否符合经纬度格式要求。
10170014	传入城市Id有误，请使用国标行政区划编码	请检查请求传入的cityId字段值，是否为国标行政区划编码。
10170015	传入提交人不存在，请检查	请检查请求传入的staffIdentifier字段值，是否为真实员工的唯一标识信息。
10170017	传入单据已存在，但为不可用状态，不支持更新	请检查请求传入的externalApplyNo字段值，由于对应单据已通过【用车申请单作废】接口作废，无法更新。请提交新的用车申请单。

# 5.代码实例

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

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

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

import java.util.List;

public class CarApplySyncDemo {
    private static final String invokeUrl = "https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/car/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 {
        // 构建请求对象
        CarApplySyncRequest carApplySyncRequest = new CarApplySyncRequest();
        carApplySyncRequest.setTs(System.currentTimeMillis());
        carApplySyncRequest.setEntId(sqtClient.getEntId());

        CarApplySyncRequest.ApplyInfo applyInfo = new CarApplySyncRequest.ApplyInfo();
        applyInfo.setExternalApplyNo("外部用车申请单号");
        applyInfo.setSceneType(2);
        applyInfo.setRulePackIdentifier("用车规则详情页-规则ID");
        applyInfo.setApplyType(201);
        applyInfo.setApplyCount(99);
        applyInfo.setApplyReason("拜访客户");

        CarApplySyncRequest.StaffInfo submitStaff = new CarApplySyncRequest.StaffInfo();
        submitStaff.setStaffIdentifier("员工唯一标识");
        submitStaff.setStaffName("张三");
        applyInfo.setSubmitStaff(submitStaff);

        CarApplySyncRequest.ScheduleInfo scheduleInfo = new CarApplySyncRequest.ScheduleInfo();
        scheduleInfo.setStartTime(1600000000000L);
        scheduleInfo.setEndTime(1700000000000L);
        scheduleInfo.setScheduleType(0);
        scheduleInfo.setCityList(Lists.newArrayList());
        applyInfo.setScheduleList(Lists.newArrayList(scheduleInfo));
        
        CarApplySyncRequest.CostCenterInfo costCenterInfo = new CarApplySyncRequest.CostCenterInfo();
        costCenterInfo.setCostNo("costNo");
        costCenterInfo.setCostName("costName");
        applyInfo.setCostCenterList(Lists.newArrayList(costCenterInfo));
        
        carApplySyncRequest.setExternalApplyList(Lists.newArrayList(applyInfo));
        // API调用
        // 注意：超时时间默认以请求对象中注解ApiMeta上设置的为准，也可以自定义传递对应的超时时间
        BaseApiResponse<List<CarApplySyncResultItem>> response = sqtClient.invokeApi(invokeUrl, carApplySyncRequest, null, null);
        // 响应结果为空处理
        if (response == null) {
            // 处理响应结果为空情况
            // ...

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

    private static void handleRespFailResult(BaseApiResponse<List<CarApplySyncResultItem>> 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-01-16	新增用车申请同步接口

← 出差申请单查询用车申请单作废 →