一、接口核心说明
1.1 为什么是异步?
维保数据需要聚合全国4S店、汽修厂档案,链路长、延迟不确定,同步请求极易超时。
固定流程:下单创建任务 → 后台查询 → 回调取结果。
下单请求(GET):提交行驶证图片,生成唯一查询订单(即刻返回,无明细数据)
获取结果:通过回调notify_url获取最终维保明细。
1.2 请求参数
- key:平台密钥(必填)
- img_base64:行驶证正面base64(必填,≤4M)
- vin:车架号(选填,辅助精准查询)
- notify_url:公网回调地址(选填,生产推荐)
二、完整极简 Java 接入代码
2.1 下单请求
import com.alibaba.fastjson2.JSON;
import okhttp3.*;
import java.util.HashMap;
import java.util.Map;
public class CarMaintenanceUtil {
`https://www.tanshuapi.com/market/detail-160`// 接口地址
private static final String SUBMIT_URL = "https://api.tanshuapi.com/api/car_care_v2/v1/index";
// 替换为自己的key
private static final String KEY = "你的KEY";
// 替换为自己公网回调地址,测试可填空
private static final String NOTIFY_URL = "https://xxx.com/api/car/maintenance/callback";
private static final OkHttpClient HTTP_CLIENT = new OkHttpClient();
private static final MediaType JSON_TYPE = MediaType.get("application/json; charset=utf-8");
// 发起维保查询下单
public static String submit(String vin, String imgBase64){
Map<String,Object> map = new HashMap<>();
map.put("key",KEY);
map.put("img_base64",imgBase64);
map.put("vin",vin);
map.put("notify_url",NOTIFY_URL);
RequestBody body = RequestBody.create(JSON.toJSONString(map),JSON_TYPE);
Request request = new Request.Builder().url(SUBMIT_URL).post(body).build();
try(Response res = HTTP_CLIENT.newCall(request).execute()){
return res.body()!=null ? res.body().string() : null;
}catch (Exception e){
e.printStackTrace();
return null;
}
}
}
2.2 回调接收接口
import lombok.Data;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
@RestController
@RequestMapping("/api/car")
public class CarMaintenanceCallbackController {
@PostMapping("/maintenance/callback")
public String callback(@RequestBody MaintenanceCallback dto){
String orderId = dto.getOrder_id();
// 幂等判断:已处理直接返回,避免重复入库
// if(已处理(orderId)) return "{\"code\":1,\"msg\":\"success\"}";
// 状态处理 1=有数据 0=无数据 -1=失败
switch (dto.getResult_status()){
case "1":
// 解析维保数据、入库、生成报告
break;
case "0":
// 无维保记录
break;
case "-1":
// 查询失败,可重试
break;
}
// 固定返回成功,必须返回!
return "{\"code\":1,\"msg\":\"success\"}";
}
@Data
public static class MaintenanceCallback{
private String order_id;
private String result_status;
private String vin;
private String plate;
private ResultItem result;
}
@Data
public static class ResultItem{
private List<ContentItem> content;
private String last_to_shop_time;
}
@Data
public static class ContentItem{
private String date;
private String resultDescription;
private String type;
private String content;
private String material;
private String mileage;
}
}
三、常见报错
- 10001 错误的请求KEY:KEY填写错误、未复制完整、密钥未开通维保权限
- 10004 未知的请求源:URL带多余符号、换行、空格,必须使用纯净接口地址
四、应用场景
二手车交易平台:排查事故维修、异常故障、调表嫌疑
汽车金融/融资租赁:贷前车况风控、残值评估
车险业务:承保、理赔前历史车况核验
车企售后:存量客户保养召回、维保跟进