[toc] # 车辆维保对接API 则一提供了不同规范的API，调用服务端API前，需了解开发前须知及调用流程。本文提供了调用则一服务端API示例，供开发者参考。 ## 白名单 则一服务端API接口访问有IP白名单限制，需要接口调用方提供调用API的服务器IP地址。 ## 数据加签 采用md5(32位小写)算法生成签名 appKey(则一提供) + appSecret(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(请求数据) ## 数据加密 数据加密采用AES算法 加密模式： CBC 填充方式：PKCS5Padding 偏移量：iv(则一提供) 加密内容：appKey(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(加密数据) 密钥： appSecret(则一提供) 输出：base64 字符集：utf-8 注：无敏感数据则无需加密 ## 获取访问凭证 ### 概述 调用则一服务API时，都需要先获取对应权限类型的访问凭证accessToken。访问凭证（accessToken）是由则一权限系统颁发的，用来校验调用者的身份信息，确保调用者具有要执行的操作的权限。 **说明**： 在使用accessToken时，请注意： * accessToken的有效期默认为30天，有效期内重复获取会返回相同结果，过期后获取会返回新的accessToken。 * 开发者需要缓存accessToken，用于后续接口的调用。不能频繁调用获取accessToken接口，否则会受到频率拦截。 * 当调用业务API时，如果返回状态码为401，则说明accessToken不正确或已过期，这时需要重新获取accessToken后再调用对应的API。 ### 接口信息 #### 请求方式： post #### 请求地址： * 生产：https://gw.shjiuze.cn/auth-service-api/login/password * 测试：https://test.shjiuze.cn/auth-service-api/login/password #### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | -------- | ------ | ---- | ----------- | ---------------- | | username | String | 是 | zhangsan | 用户名，则一提供 | | password | String | 是 | password123 | 密码，则一提供 | #### 返回参数 | 名称 | 类型 | 示例值 | 描述 | | ------------------------------ | ---------- | -------------------------------- | -------------------------------------------------- | | success | boolean | true | 成功标识: true 成功，false 失败 | | businessException | boolean | false | 业务异常标识: true 业务异常，false 正常 | | errorCode | String | 200 | 错误码: 200 业务异常，500 系统异常， 空表示无错误 | | message | String | 订单号不能为空 | 错误信息，无错误则返回空 | | result | ZYTokenDto | | accessToken结果数据 | |     accessToken | String | 000626f15b4b41bba6fe56216a5d2f73 | accessToken | |     expiresIn | Integer | 2060 | 有效期限单位秒，accessToken在2060秒后过期 | |     tokenType | String | bearer | token类型 | #### 请求示例 ##### Http方式 ```http POST /auth-service-api/login/password HTTP/1.1 Host:test.shjiuze.cn Content-Type:application/json { "username" : "zeyi", "password" : "test1111" } ``` ##### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; ZYClient zyClient = new ZYClient(appKey, appSecret); ZYTokenRequestDto zyTokenRequest = new ZYTokenRequestDto(); zyTokenRequest.setUsername("zeyi"); zyTokenRequest.setPassword("test1111"); String body = gson.toJson(zyTokenRequest); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + Constants.TOKEN_PATH, body); if(httpResponseData == null) { throw new TokenException("则一Token请求失败,返回为空!"); } ZYResponse zyResponse = gson.fromJson(httpResponseData.getBody(), new TypeToken>(){}.getType()); if(!Boolean.TRUE.equals(zyResponse.isSuccess())) { throw new TokenException("则一Token请求返回失败!" + zyResponse.getMessage()); } if(zyResponse.getResult() == null) { throw new TokenException("则一Token请求返回失败,返回结果为空!" + zyResponse.getMessage()); } if(StringUtils.isBlank(zyResponse.getResult().getAccessToken())) { throw new TokenException("则一Token请求返回数据异常,AccessToken为空!" + zyResponse.getMessage()); } // 结果 zyResponse.getResult(); } } ``` #### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "accessToken": "64d7f367-609b-4f7d-a84d-a3d2a0b5ad85", "expiresIn": 602105, "tokenType": "bearer" } } ``` ## 车辆报修 ### 简要描述 · 车辆报修 ### 请求URL · 车畅行提供 /vehicleRepair/repair ### 请求方式 · POST ### 请求示例 ```json { "code":"WBJL21071000044", "licenseNumber":"鄂ARY348", "trailerNumber":"辽BHC28挂", "owner":"上海则一", "brand":"东风", "specification":"9.6", "vanType":"厢车", "driverName":"张三", "driverMobile":"18888888888", "vin":"21654564894984LK", "engineNumber":"2156156", "engineModel":"大众EA111", "manufactureTime":"1642993757000", "registrationTime":"1642993757000", "mileage":100000, "trafficCompulsoryInsuranceStartTime":"1642993757000", "trafficCompulsoryInsuranceEndTime":"1642993757000", "commercialInsuranceStartTime":"1642993757000", "commercialInsuranceEndTime":"1642993757000", "medallionInvalidTime":"1642993757000", "monthMileage":100000, "recentRepairTime":"1642993757000", "vehicleObject":"车头", "vehicleAddress":"湖北省随州市曾都区淅河镇002县道", "vehicleAddressLng":"113.465168", "vehicleAddressLat":"31.664137", "orgName":"上海区", "repairProjectList":[ { "name":"机油滤芯", "number":1 } ] ``` ### 参数 | 参数名 | 必传 | 类型 | | 说明 | | :---------------------------------- | ---- | ------- | ---- | ------------------------------- | | code | 是 | string | | 维保单号 | | licenseNumber | 是 | string | | 车牌号 | | trailerNumber | 否 | string | | 挂车号 | | owner | 是 | string | | 车辆所有人 | | brand | 否 | string | | 品牌 | | specification | 否 | string | | 车型 | | vanType | 否 | string | | 车厢类型 | | driverName | 是 | string | | 司机联系姓名 | | driverMobile | 是 | string | | 司机联系电话 | | vin | 是 | string | | 车架号 | | engineNumber | 是 | string | | 发动机号码 | | engineModel | 否 | string | | 发动机型号 | | manufactureTime | 否 | string | | 出厂日期时间戳(毫秒) | | registrationTime | 否 | string | | 注册日期时间戳(毫秒) | | mileage | 否 | Integer | | 车辆里程数 | | trafficCompulsoryInsuranceStartTime | 否 | string | | 交强险开始时间戳(毫秒) | | trafficCompulsoryInsuranceEndTime | 否 | string | | 交强险结束时间戳(毫秒) | | commercialInsuranceStartTime | 否 | string | | 商业险开始时间戳(毫秒) | | commercialInsuranceEndTime | 否 | string | | 商业险结束时间戳(毫秒) | | medallionInvalidTime | 否 | string | | 营运证失效日期时间戳(毫秒) | | monthMileage | 否 | Integer | | 月行驶里程数 | | recentRepairTime | 否 | string | | 最近维修日期时间戳(毫秒) | | vehicleObject | 是 | string | | 维修对象(车头、车挂、车头+车挂) | | vehicleAddress | 是 | string | | 车辆位置 | | vehicleAddressLng | 是 | string | | 车辆位置经度 | | vehicleAddressLat | 是 | string | | 车辆位置纬度 | | orgName | 是 | string | | 车辆所属区域 | | remark | 否 | string | | 备注 | | repairProjectList | 是 | list | | 维修项目列表 | | name | 是 | string | | 维修项目名称 | | number | 是 | Integer | | 维修项目数量 | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "XXX不存在!"} ## 车辆维修确认 ### 简要描述 · 车辆维修确认 ### 请求URL · 测试环境：https://test.shjiuze.cn/vehicle-service-api/maintenance/repairConfirm · 生产环境：https://gw.shjiuze.cn/vehicle-service-api/maintenance/repairConfirm ### 请求示例 #### Http方式 ```http POST /vehicle-service-api/maintenance/repairConfirm HTTP/1.1 Host:test.shjiuze.cn Content-Type:application/json { "code":"WBJL21071000044", "repairFlag":true, "expectRepairTime":"1642759341000", "reason":"无可用站点", "stationUser":"张大三", "stationMobile":"13277788817", "stationAddress":"湖北省武汉市东西湖区新城十六路88号2056物流园B33-34", "stationLng":"113.461238", "stationLat":"32.614137" } ``` #### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "报修确认Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/maintenance/repairConfirm", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/maintenance/repairConfirm", "accessToken", jsonData); } } } ``` ### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ### Body参数 | 参数名 | 必传 | 类型 | 说明 | | ---------------- | ---- | ------- | -------------------- | | code | 是 | string | 维保单号 | | repairFlag | 是 | boolean | 是否可维修 | | expectRepairTime | 否 | string | 预计维修时间戳(毫秒) | | reason | 否 | string | 不可维修原因 | | stationUser | 否 | string | 站点联系人 | | stationMobile | 否 | string | 站点联系电话 | | stationAddress | 否 | string | 站点地址 | | stationLng | 否 | string | 站点地址经度 | | stationLat | 否 | string | 站点地址纬度 | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "XXX不存在!"} ## 车辆维修清单 ### 简要描述 · 车辆维修清单 ### 请求URL · 测试环境：https://test.shjiuze.cn/vehicle-service-api/maintenance/repairList · 生产环境：https://gw.shjiuze.cn/vehicle-service-api/maintenance/repairList ### 请求示例 #### Http方式 ```http POST /vehicle-service-api/maintenance/repairList HTTP/1.1 Host:test.shjiuze.cn Content-Type:application/json { "code":"WBJL21071000044", "orderCode":"xxxx", "discountedAmount":100, "totalAmount":1000, "paidAmount":900, "mileage":121900, "type":"大修", "startTime":"1642993757000", "completeTime":"1642993757000", "fieldMaintainPictureUrl":"http://zeyi-tms-test.oss-cn-hangzhou.aliyuncs.com/image/app/9c019526-63fd-4a39-808a-744a452cca18.jpg", "certificatePictureUrl":"http://zeyi-tms-test.oss-cn-hangzhou.aliyuncs.com/image/app/9c019526-63fd-4a39-808a-744a452cca18.jpg", "mileagePictureUrl":"http://zeyi-tms-test.oss-cn-hangzhou.aliyuncs.com/image/app/9c019526-63fd-4a39-808a-744a452cca18.jpg", "feeList":[ { "name":"工时费", "amount":100, "discountedAmount":0, "remark":"" }, { "name":"材料费", "amount":950, "discountedAmount":50, "remark":"" } ], "repairProjectList":[ { "name":"空调滤芯", "number":2, "unitPrice":275, "discountedAmount":50, "laborAmount":0, "totalAmount":500, "remark":"" }, { "name":"机油滤芯", "number":1, "unitPrice":400, "discountedAmount":0, "laborAmount":100, "totalAmount":500, "remark":"" }, ​ { ​ "name":"工时费用", ​ "timeQuota":"1", ​ "unitAmount":100, ​ "totalAmount":100, ​ "remark":"" ​ } ​ ] } ``` #### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "推送维修清单Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/maintenance/repairList", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/maintenance/repairList", "accessToken", jsonData); } } } ``` ### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ### Body参数 | 参数名 | 必传 | 类型 | 说明 | | ---------------------------------------- | ---- | ---------- | ------------------------------------------ | | code | 是 | string | 维保编码 | | orderCode | 是 | string | 维保订单号 | | discountedAmount | 否 | Bigdecimal | 折扣金额 | | totalAmount | 是 | Bigdecimal | 总金额 | | paidAmount | 是 | Bigdecimal | 应付金额 | | mileage | 是 | Integer | 车辆里程数 | | type | 是 | string | 维修类型 | | startTime | 是 | string | 开始时间戳(毫秒) | | completeTime | 是 | string | 完工时间戳(毫秒) | | fieldMaintainPictureUrl | 是 | string | 清单照片url,多个图片用逗号分割 | | certificatePictureUrl | 是 | string | 现场照片url,多个图片用逗号分割 | | mileagePictureUrl | 是 | string | 里程照片url,多个图片用逗号分割 | | feeList | 否 | list | 费用明细集合 | |     name | 是 | string | 名称(工时费、拖车费等等) | |     unit | 否 | string | 单位 | |     unitPrice | 否 | Bigdecimal | 单价 | |     number | 否 | Integer | 数量 | |     amount | 是 | Bigdecimal | 金额 | |     discountedAmount | 是 | Bigdecimal | 折扣金额 | |     remark | 否 | string | 备注 | | repairProjectList | 否 | list | 维修项目集合（包含配件信息） | |     name | 是 | string | 项目名称 | |     unit | 否 | string | 单位 | |     number | 否 | Integer | 数量 | |     unitPrice | 是 | Bigdecimal | 单价 | |     discountedAmount | 否 | Bigdecimal | 折扣金额 | |     totalAmount | 是 | Bigdecimal | 合计金额 | |     timeQuota | 否 | Bigdecimal | 工时定额 | |     projectType | 是 | string | 维修项目类型(配件:materials\|项目:project) | |     remark | 否 | string | 备注 | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "xxx不存在!"} ## 车辆保养 ### 简要描述 · 车辆保养信息推送 ### 请求URL · 车畅行提供/vehicleMaintain/maintain ### 请求方式 · POST ### 请求示例 ```json { "code":"WBJL21071000044", "licenseNumber":"鄂ARY348", "trailerNumber":"辽BHC28挂", "owner":"上海则一", "brand":"东风", "specification":"9.6", "vanType":"厢车", "driverName":"张三", "driverMobile":"18888888888", "vin":"21654564894984LK", "engineNumber":"2156156", "engineModel":"大众EA111", "manufactureTime":"1642993757000", "registrationTime":"1642993757000", "mileage":100000, "trafficCompulsoryInsuranceStartTime":"1642993757000", "trafficCompulsoryInsuranceEndTime":"1642993757000", "commercialInsuranceStartTime":"1642993757000", "commercialInsuranceEndTime":"1642993757000", "medallionInvalidTime":"1642993757000", "monthMileage":100000, "recentMaintainTime":"1642993757000", "vehicleObject":"车头", "vehicleAddress":"湖北省随州市曾都区淅河镇002县道", "vehicleAddressLng":"113.465168", "vehicleAddressLat":"31.664137", "orgName":"上海区", "maintainProjectList":[ {"name": "机油滤芯"} ] } ``` ### 参数 | 参数名 | 必传 | 类型 | | 说明 | | :---------------------------------- | ---- | ------- | ---- | ------------------------------- | | code | 是 | string | | 维保单号 | | licenseNumber | 是 | string | | 车牌号 | | trailerNumber | 否 | string | | 挂车号 | | owner | 是 | string | | 车辆所有人 | | brand | 否 | string | | 品牌 | | specification | 否 | string | | 车型 | | vanType | 否 | string | | 车厢类型 | | driverName | 是 | string | | 司机联系姓名 | | driverMobile | 是 | string | | 司机联系电话 | | vin | 是 | string | | 车架号 | | engineNumber | 是 | string | | 发动机号码 | | engineModel | 否 | string | | 发动机型号 | | manufactureTime | 否 | string | | 出厂日期时间戳(毫秒) | | registrationTime | 否 | string | | 注册日期时间戳(毫秒) | | mileage | 否 | Integer | | 车辆里程数 | | trafficCompulsoryInsuranceStartTime | 否 | string | | 交强险开始时间戳(毫秒) | | trafficCompulsoryInsuranceEndTime | 否 | string | | 交强险结束时间戳(毫秒) | | commercialInsuranceStartTime | 否 | string | | 商业险开始时间戳(毫秒) | | commercialInsuranceEndTime | 否 | string | | 商业险结束时间戳(毫秒) | | medallionInvalidTime | 否 | string | | 营运证失效日期时间戳(毫秒) | | monthMileage | 否 | Integer | | 月行驶里程数 | | recentMaintainTime | 否 | string | | 最近保养日期时间戳(毫秒) | | vehicleObject | 是 | string | | 保养对象(车头、车挂、车头+车挂) | | vehicleAddress | 是 | string | | 车辆位置 | | vehicleAddressLng | 是 | string | | 车辆位置经度 | | vehicleAddressLat | 是 | string | | 车辆位置纬度 | | orgName | 是 | string | | 车辆所属区域 | | remark | 否 | string | | 备注 | | maintainProjectList | 是 | list | | 保养项目列表 | | name | 是 | string | | 保养项目名称 | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "xxx不存在!"} ### 备注 | 保养类型：保养项目 | | ------------------ | | 发动机： | | 检查皮带 | | 机油滤芯 | | 干燥罐 | | 柴油滤芯(细滤) | | 空气滤芯 | | 其他 | | 机油 | | 油水分离器(粗滤) | | 空调滤芯 | | 底盘润滑： | | 变速箱齿轮油 | | 后桥齿轮油 | | 车轮保养： | | 轮毂保养 | | 挂车保养： | | 轴承保养 | | 轮毂保养 | | 底盘润滑： | | 打黄油 | ## 车辆保养确认 ### 简要描述 · 车辆保养确认 ### 请求URL · 测试环境：https://test.shjiuze.cn/vehicle-service-api/maintenance/maintainConfirm · 生产环境：https://gw.shjiuze.cn/vehicle-service-api/maintenance/maintainConfirm ### 请求示例 #### Http方式 ```http POST /vehicle-service-api/maintenance/maintainConfirm HTTP/1.1 Host:test.shjiuze.cn Content-Type:application/json { "code":"WBJL21071000044", "maintainFlag":true, "expectMaintainTime":"1642759341000", "reason":"无可用站点", "stationUser":"张大三", "stationMobile":"13277788817", "stationAddress":"湖北省武汉市东西湖区新城十六路88号2056物流园B33-34", "stationLng":"113.461238", "stationLat":"32.614137" } ``` #### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "保养确认Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/maintenance/maintainConfirm", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/maintenance/maintainConfirm", "accessToken", jsonData); } } } ``` ### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ### Body参数 | 参数名 | 必传 | 类型 | 说明 | | ------------------ | ---- | ------- | -------------------- | | code | 是 | string | 维保单号 | | maintainFlag | 是 | boolean | 是否可保养 | | expectMaintainTime | 否 | string | 预计保养时间戳(毫秒) | | reason | 否 | string | 不可保养原因 | | stationUser | 否 | string | 站点联系人 | | stationMobile | 否 | string | 站点联系电话 | | stationAddress | 否 | string | 站点地址 | | stationLng | 否 | string | 站点地址经度 | | stationLat | 否 | string | 站点地址纬度 | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "xxx不存在!"} ## 车辆保养清单 ### 简要描述 · 车辆保养清单 ### 请求URL · 测试环境：https://test.shjiuze.cn/vehicle-service-api/maintenance/maintainList · 生产环境：https://gw.shjiuze.cn/vehicle-service-api/maintenance/maintainList ### 请求示例 #### Http方式 ```http POST /vehicle-service-api/maintenance/maintainList HTTP/1.1 Host:test.shjiuze.cn Content-Type:application/json { "code":"WBJL21071000044", "orderCode":"xxxx", "discountedAmount":100, "totalAmount":1000, "paidAmount":900, "mileage":121900, "type":"首保", "startTime":"1642993757000", "completeTime":"1642993757000", "fieldMaintainPictureUrl":"http://zeyi-tms-test.oss-cn-hangzhou.aliyuncs.com/image/app/9c019526-63fd-4a39-808a-744a452cca18.jpg", "certificatePictureUrl":"http://zeyi-tms-test.oss-cn-hangzhou.aliyuncs.com/image/app/9c019526-63fd-4a39-808a-744a452cca18.jpg", "mileagePictureUrl":"http://zeyi-tms-test.oss-cn-hangzhou.aliyuncs.com/image/app/9c019526-63fd-4a39-808a-744a452cca18.jpg", "feeList":[ { "name":"工时费", "amount":100, "discountedAmount":0, "remark":"" }, { "name":"材料费", "amount":950, "discountedAmount":50, "remark":"" } ], "maintainProjectList":[ { "name":"空调滤芯", "number":2, "unitPrice":275, "discountedAmount":50, "laborAmount":0, "totalAmount":500, ​ "type":"MAINTAIN" ​ "remark":"" ​ }, ​ { ​ "name":"机油滤芯", ​ "number":1, ​ "unitPrice":400, ​ "discountedAmount":0, ​ "laborAmount":100, ​ "totalAmount":500, ​ "type":"MAINTAIN" ​ "remark":"" ​ }, ​ { ​ "name":"工时费用", ​ "timeQuota":"1", ​ "unitAmount":100, ​ "amount":100, ​ "remark":"" ​ } ​ ] } ``` #### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "保养清单Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/maintenance/maintainList", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/maintenance/maintainList", "accessToken", jsonData); } } } ``` ### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ### Body参数 | 参数名 | 必传 | 类型 | 说明 | | ----------------------------------------------- | ---- | ---------- | -------------------------------------------- | | code | 是 | string | 维保编码 | | orderCode | 是 | string | 维保订单号 | | discountedAmount | 否 | Bigdecimal | 折扣金额 | | totalAmount | 是 | Bigdecimal | 总金额 | | paidAmount | 是 | Bigdecimal | 应付金额 | | mileage | 是 | Integer | 车辆里程数 | | type | 是 | string | 保养类型 | | startTime | 是 | string | 开始时间戳(毫秒) | | completeTime | 是 | string | 完工时间戳(毫秒) | | fieldMaintainPictureUrl | 是 | string | 清单照片url,多个图片用逗号分割 | | certificatePictureUrl | 是 | string | 现场照片url,多个图片用逗号分割 | | mileagePictureUrl | 是 | string | 里程照片url,多个图片用逗号分割 | | feeList | 否 | list | 费用明细集合 | |     name | 是 | string | 名称(工时费、材料费、拖车费等等) | |     unit | 否 | string | 单位 | |     unitPrice | 否 | Bigdecimal | 单价 | |     number | 否 | Integer | 数量 | |     amount | 是 | Bigdecimal | 金额 | |     discountedAmount | 是 | Bigdecimal | 折扣金额 | |     remark | 否 | string | 备注 | | maintainProjectList | 否 | list | 保养项目集合（包含配件信息） | |     name | 是 | string | 项目名称 | |      unit | 否 | string | 单位 | |     number | 是 | Integer | 数量 | |     unitPrice | 是 | Bigdecimal | 单价 | |     discountedAmount | 否 | Bigdecimal | 折扣金额 | |     totalAmount | 是 | Bigdecimal | 合计金额 | |     type | 是 | string | MAINTAIN：保养 或 REPAIR：维修 | |     remark | 否 | string | 备注 | |     timeQuota | 否 | Bigdecimal | 工时定额 | |     projectType | 是 | string | 维保项目类型（配件:materials\|项目:project） | |     nextMaintainanceMileage | 否 | Integer | 下次保养里程数 | |     nextMaintainanceTime | 是 | string | 下次保养时间戳（毫秒） | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "xxx不存在!"} ## 车辆维保审核 ### 简要描述 · 车辆维保审核 ### 请求URL · 车畅行提供 /vehicleMaintainRepair/audit ### 请求方式 · POST ### 请求示例 { "code":"WBJL21071000044", "auditStatus":"PASS", "auditRemark":"审核备注", "auditeTime":"1642755099000", "contactUser":"张大三", "contactMobile":"13277676171" } ### 参数 | 参数名 | 必传 | 类型 | 说明 | | ------------- | ---- | ------ | ------------------------------------------- | | code | 是 | string | 维保编码 | | auditStatus | 是 | string | 审核状态(PASS:审核通过，NO_PASS:审核不通过) | | auditRemark | 否 | string | 审核备注 | | auditeTime | 是 | string | 审核时间戳(毫秒) | | contactUser | 否 | string | 审核联系人 | | contactMobile | 否 | string | 审核联系人电话 | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "xxx不存在!"} ## 车辆维保作废 ### 简要描述 · 车辆维保作废 ### 请求URL · 车畅行提供 /vehicleMaintainRepair/delete ### 请求方式 · POST ### 请求示例 { "code":"WBJL21071000044", "reason":"上报信息错误", "operationTime":"1642755099000", "operationUser":"张大三", "operationMobile":"13277676171" } ### 参数 | 参数名 | 必传 | 类型 | 说明 | | --------------- | ---- | ------ | ---------------- | | code | 是 | string | 维保编码 | | reason | 否 | string | 作废原因 | | operationTime | 是 | string | 操作时间戳(毫秒) | | operationUser | 否 | string | 操作人 | | operationMobile | 否 | string | 操作人电话 | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "xxx异常!"} ## 车辆维保合同推送 ### 简要描述 · 车辆维修合同推送 ### 请求URL · 测试环境：https://test.shjiuze.cn/vehicle-service-api/vehicleMaintainRepairContract/push · 生产环境：https://gw.shjiuze.cn/vehicle-service-api/vehicleMaintainRepairContract/push ### 请求示例 #### Http方式 ```http POST /vehicle-service-api/vehicleMaintainRepairContract/push HTTP/1.1 Host:test.shjiuze.cn Content-Type:application/json { "code":"HT123123123123", "originContractCode":"", "maintainRepairCode":"WBJL123123123123", "companyName":"上海东风公司", "branchName":"上海东风青浦门店", "billStatus":"", "maintainType":"首保", "devoteRate":0.56, "memberType":"", "memberNo":"", "comeDate":"1642993757000", "sendWay":"", "collectionWay":"自提", "collectionDate":"1642993757000", "licenseNumber":"沪A123456", "specification":"9.6", "mileage":100000, "expectCompleteTime":"1642993757000", "deliveryTime":"1642993757000", "remark":"备注", "month":"2021-02-02", "productTotalAmount":1000, "serviceTotalAmount":1000, "productDiscountedAmount":100, "serviceDiscountedAmount":100, "totalAmount":1800, "contractDetail":[ { "serviceName": "换机油", "serviceNeedHour": 2, "serviceHourUnitAmount": 100, "serviceCustomerUnitAmount": 120, "serviceBranchUnitAmount": 150, "confirmFlag": true, "completeTime": "1642993757000", "selfCheckUser": "张三", "selfCheckTime": "1642993757000", "checkUser": "张三", "checkTime": "1642993757000", "remark": "备注", } ] } ``` #### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "维保合同推送Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/vehicleMaintainRepairContract/push", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/vehicleMaintainRepairContract/push", "accessToken", jsonData); } } } ``` ### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ### Body参数 | 参数名 | 必传 | 类型 | 说明 | | ------------------------- | ---- | ---------- | -------------------- | | code | 是 | string | 合同编号 | | originContractCode | 否 | string | 源合同编号 | | maintainRepairCode | 是 | string | 维保编号 | | companyName | 是 | string | 甲方公司名称 | | branchName | 是 | string | 维修门店名称 | | billStatus | 是 | string | 单据状态 | | maintainType | 是 | string | 维保类型 | | devoteRate | 否 | Bigdecimal | 维修类贡献比例 | | memberType | 否 | string | 会员类型 | | memberNo | 否 | string | 会员编号 | | comeDate | 是 | string | 进场时间戳(毫秒) | | sendWay | 否 | string | 送修方式 | | collectionWay | 否 | string | 提车方式 | | collectionDate | 否 | string | 提车时间戳(毫秒) | | licenseNumber | 是 | string | 车牌号 | | specification | 是 | string | 车型 | | mileage | 否 | Integer | 公里数 | | expectCompleteTime | 是 | string | 预计完成时间戳(毫秒) | | deliveryTime | 否 | string | 出厂时间戳(毫秒) | | remark | 否 | string | 备注 | | month | 否 | string | 会计时间 | | productTotalAmount | 否 | Bigdecimal | 货品项目总费用 | | serviceTotalAmount | 否 | Bigdecimal | 服务项目总费用 | | productDiscountedAmount | 否 | Bigdecimal | 货品项目优惠折扣费用 | | serviceDiscountedAmount | 否 | Bigdecimal | 服务项目优惠折扣费用 | | totalAmount | 否 | Bigdecimal | 总费用 | | contractDetail | 是 | list | 合同明细 | | serviceName | 是 | string | 服务名称 | | serviceNeedHour | 是 | Integer | 服务项目所需工时 | | serviceHourUnitAmount | 是 | Bigdecimal | 服务项目工时单价 | | serviceCustomerUnitAmount | 是 | Bigdecimal | 服务项目客户单价 | | serviceBranchUnitAmount | 是 | Bigdecimal | 服务项目门店单价 | | confirmFlag | 是 | boolean | 是否确认维修 | | completeTime | 否 | string | 完工时间戳(毫秒) | | selfCheckUser | 否 | string | 自检人 | | selfCheckTime | 否 | string | 自检时间戳(毫秒) | | checkUser | 否 | string | 过程检验人 | | checkTime | 否 | string | 过程检验时间戳(毫秒) | | remark | 否 | string | 备注 | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "xxx异常!"} ## 车辆维保合同作废 ### 简要描述 · 车辆维保合同作废 ### 请求URL · 测试环境：https://test.shjiuze.cn/vehicle-service-api/vehicleMaintainRepairContract/invalid · 生产环境：https://gw.shjiuze.cn/vehicle-service-api/vehicleMaintainRepairContract/invalid ### 请求示例 #### Http方式 ```http POST /vehicle-service-api/vehicleMaintainRepairContract/delete HTTP/1.1 Host:test.shjiuze.cn Content-Type:application/json { "code":"HT21071000044", "reason":"上报信息错误", "operationTime":"1642755099000", "operationUser":"张大三", "operationMobile":"13277676171" } ``` #### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "维保合同作废Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/vehicleMaintainRepairContract/delete", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/vehicleMaintainRepairContract/delete", "accessToken", jsonData); } } } ``` ### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ### Body参数 | 参数名 | 必传 | 类型 | 说明 | | --------------- | ---- | ------ | ---------------- | | code | 是 | string | 合同编码 | | reason | 否 | string | 作废原因 | | operationTime | 是 | string | 操作时间戳(毫秒) | | operationUser | 否 | string | 操作人 | | operationMobile | 否 | string | 操作人电话 | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "xxx异常!"} ## 维保单作废 ### 简要描述 · 维保单作废 ​ 如果此维保单已生成结算单或者已付款，则维保单不可作废，系统会抛出业务异常例如：已生成结算单不可作废 或 已付款不可作废 ### 请求URL · 测试环境：https://test.shjiuze.cn/vehicle-service-api/maintenance/invalid · 生产环境：https://gw.shjiuze.cn/vehicle-service-api/maintenance/invalid ### 请求示例 #### Http方式 ```http POST /vehicle-service-api/maintenance/delete HTTP/1.1 Host:test.shjiuze.cn Content-Type:application/json { "code":"WBJL22090200012", "reason":"原因：重复数据等等xxxxxxxx", "operationTime":"1642755099000", "operationUser":"张大三", "operationMobile":"13277676171" } ``` #### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "维保单作废Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/maintenance/invalid", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/vehicle-service-api/maintenance/delete", "accessToken", jsonData); } } } ``` ### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ### Body参数 | 参数名 | 必传 | 类型 | 说明 | | --------------- | ---- | ------ | ---------------- | | code | 是 | string | 维保编码 | | reason | 是 | string | 作废原因 | | operationTime | 是 | string | 操作时间戳(毫秒) | | operationUser | 否 | string | 操作人 | | operationMobile | 否 | string | 操作人电话 | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "xxx已付款，无法作废!"} ## 维保单价格推送 ### 简要描述 维保单价格推送 ### 请求方式 · POST ### 请求URL · 车畅行提供 /vehicleMaintainRepair/confirmPirce

请求示例

{ "code":"WBJL21071000044", "confirmAmount":1000, "feeList":[ { "name":"工时费", "confirmNumber":0, "confirmAmount":0 }, { "name":"材料费", "confirmNumber":0, "confirmAmount":0 } ], "maintainProjectList":[ { "name":"空调滤芯", "confirmNumber":2, "confirmAmount":0, "type":"MAINTAIN", "projectType":"materials" }, { "name":"机油滤芯", "confirmNumber":1, "confirmAmount":500, "type":"MAINTAIN", "projectType":"materials" } ] } ### Body参数 | 参数名 | 必传 | 类型 | 说明 | | ------------------------------------- | ---- | ---------- | -------------------------------------------- | | code | 是 | string | 维保编码 | | confirmAmount | 是 | Bigdecimal | 则一确认总金额 | | feeList | 是 | list | 费用明细集合 | |     name | 是 | string | 名称(工时费、材料费、拖车费等等) | |     confirmNumber | 是 | Integer | 则一确认数量 | |     confirmAmount | 是 | Bigdecimal | 则一确认金额 | | maintainProjectList | 是 | list | 保养项目集合（包含配件信息） | |     name | 是 | string | 项目名称 | |     confirmNumber | 是 | Integer | 则一确认数量 | |     confirmAmount | 是 | Bigdecimal | 则一确认金额 | |     type | 是 | string | MAINTAIN：保养 或 REPAIR：维修 | |     projectType | 是 | string | 维保项目类型（配件:materials\|项目:project） | ### 返回正常示例 { "success": true, "businessException": false} ### 返回异常示例 { "success": false, "businessException": true, "errorCode": "200", "message": "xxx不能为空!"} ------------------------------------------------------------------------------------------ ### 2022-03-05更新日志 1. [车辆报修](#车辆报修) 、[车辆保养](#车辆保养)接口参数增加remark字段非必填 2. [车辆保养清单](#车辆保养清单)：接口参数maintainProjectList中增加类型type字段需必填 ### 2022-03-11更新日志 1. 回调则一接口请求路径变更 2. [车辆保养清单](#车辆保养清单)、[车辆维修清单](#车辆维修清单)：接口参数taskFeeList移除、合并到维修保养项目集合字段中。 3. [车辆保养清单](#车辆保养清单)：保养项目集合中增加下次保养时间、下次保养里程数字段 ### 2022-03-16更新日志 ​ 1.优化接口请求示例 ### 2022-03-23更新日志 ​ 1.维修、保养清单推送增加应付金额字段（必填）：【应付价格】计算逻辑：应付价格=总金额-折扣金额 ### 2022-03-31更新日志 ​ 1.车辆维修清单、车辆保养清单中的项目集合兼容配件信息 ### 2022-09-02更新日志 1. 增加维保单作废接口 （车畅行操作作废后成功后 回调此接口） 2. 增加维保单价格推送接口 (我司对维保清单的项目价格确认后推送给车畅行) ### 2022-10-13更新日志 ```json 1. 维修及保养清单推送增加orderCode（必填） 开始时间戳：startTime（必填） 完工时间戳：completeTime （必填） ``` ### 2022-11-03更新日志 ```json 1. 车辆报修、车辆保养接口增加车辆所属区域字段：orgName 2. 车辆维修清单、车辆保养清单中的项目集合、费用明细集合设置为非必填 ```