接口概述
一句话说明
usedcar.price 把二手车的估值过程收敛成一次 HTTP 请求。 相比只看「车贩子报价」,接口按品牌型号 + 车龄 + 里程 + 车况 + 地域的组合做估算, 返回的是价格区间而不是单一数字,天然反映了真实交易中的议价空间。
| 请求地址 | https://api.xujian.tech/openapi/usedcar/price |
|---|---|
| 请求方式 | POST,参数放 application/json 请求体 |
| 鉴权方式 | 请求头 X-API-Key(不做签名与加密) |
| 接口编码 | usedcar.price |
| 收费类型 | PER_CALL(按次计费,0.5000 元/次) |
| 计费特殊规则 | 查得计费:参数非法、上游不可用、未能给出价格区间时返回失败且不扣费 |
| 响应格式 | JSON,Content-Type: application/json;charset=UTF-8 |
| 是否需要授权 | 否(无需授权,API Key 有效且余额充足即可调用) |
| 字段长度 | 每个字符串字段不超过 50 个字符 |
| 典型用途 | 收车 / 置换估价、零售挂牌定价、金融质押物估值、车源定价体检 |
快速开始
curl -s -X POST "https://api.xujian.tech/openapi/usedcar/price" \
-H "Content-Type: application/json" \
-H "X-API-Key: 你的APIKey" \
-d '{
"brand": "大众",
"model": "迈腾",
"year": "2023",
"configuration": "330TSI DSG 豪华型",
"registrationDate": "2022-03",
"mileage": "8.5",
"accidentHistory": "0",
"transferCount": "0",
"maintenanceRecord": "全程4S店保养",
"fuelType": "汽油",
"transmissionType": "自动",
"displacement": "2.0",
"color": "黑色",
"location": "北京",
"description": "车辆外观完好,内饰9成新,无任何改装"
}'
影响估值的四个关键参数
mileage行驶里程 —— 权重最高registrationDate上牌时间 /year年款 —— 车龄折旧location车辆所在地 —— 地域价格差异accidentHistory事故历史 —— 车况
这四项务必尽量填准;其余参数可选,但填得越全结果越稳。
请求参数
| 参数名 | 是否必填 | 说明 |
|---|---|---|
X-API-Key | 是 | 开发者 API Key |
Content-Type | 是 | application/json |
JSON 请求体字段(全部可选,brand 与 model 至少填一个,单个字段 ≤ 50 字符)
| 字段 | 类型 | 示例 | 说明 |
|---|---|---|---|
brand | String | 大众 | 品牌 |
model | String | 迈腾 | 型号 |
year | String | 2023 | 年款 |
configuration | String | 330TSI DSG 豪华型 | 配置版本 |
registrationDate | String | 2022-03 | 上牌时间(YYYY-MM) |
mileage | String | 8.5 | 行驶里程(万公里) |
accidentHistory | String | 0 | 事故历史等级:0 无事故 / 1 轻微剐蹭 / 2 更换覆盖件 / 3 结构损伤 |
transferCount | String | 0 | 过户次数 |
maintenanceRecord | String | 全程4S店保养 | 保养记录描述 |
fuelType | String | 汽油 | 燃油类型 |
transmissionType | String | 自动 | 变速箱类型 |
displacement | String | 2.0 | 排量(L) |
color | String | 黑色 | 车身颜色 |
location | String | 北京 | 车辆所在地 |
description | String | 车辆外观完好,内饰9成新,无任何改装 | 车辆描述 |
vin | String | LSVAL41Z2N2123456 | 车架号 VIN |
engineModel | String | EA888 | 发动机型号 |
emissionStandard | String | 国六 | 排放标准 |
underWarranty | String | 是 | 是否在质保期 |
vehicleUsage | String | 家用 | 车辆用途 |
响应参数
| 字段 | 类型 | 示例 | 说明 |
|---|---|---|---|
priceStart | Double | 12.5 | 评估价格下限(万元),可作为快速成交 / 收车参考价 |
priceEnd | Double | 14.8 | 评估价格上限(万元),可作为零售挂牌参考价 |
tip | String | 估计信息来源网络内容,仅供参考 | 结果说明 |
apiCode | String | usedcar.price | 接口编码 |
apiName | String | 二手车价格评估 | 接口名称 |
chargeType | String | PER_CALL | 计费类型 |
balance | BigDecimal | 调用完成后(已扣费)的账户余额(元) | |
costMs | Long | 1200 | 本次调用耗时(毫秒) |
响应示例
成功(code = 0)
{
"code": 0,
"msg": "success",
"data": {
"priceStart": 12.5,
"priceEnd": 14.8,
"tip": "估计信息来源网络内容,仅供参考",
"apiCode": "usedcar.price",
"apiName": "二手车价格评估",
"chargeType": "PER_CALL",
"balance": 99.5000,
"costMs": 1200
}
}
失败(参数不足)—— 不收费
{
"code": 500,
"msg": "brand 与 model 至少填一个(填写越完整估值越准确)",
"data": null
}
失败(估不出价格)—— 不收费
{
"code": 500,
"msg": "未能评估出该车的价格区间,请补充品牌、型号、上牌时间与行驶里程后重试;本次调用不计费",
"data": null
}
错误码与常见失败原因
| code | msg(示例) | 处理建议 |
|---|---|---|
| 0 | success | 调用成功 |
| 500 | 缺少请求头 X-API-Key | 补充 X-API-Key |
| 500 | API Key 无效 / API Key 已停用 | 检查 Key 或重新启用 |
| 500 | 客户不存在或已停用 | 联系平台(可联系微信xujian_cq) |
| 500 | 余额不足,请先充值。可联系微信xujian_cq | 充值后重试,余额不足不扣费 |
| 500 | brand 与 model 至少填一个(填写越完整估值越准确) | 至少补一个;不计费 |
| 500 | xxx 长度不能超过 50 个字符 | 缩短该字段;不计费 |
| 500 | 二手车服务未启用 / 二手车服务未配置(上游凭证缺失) | 平台侧配置问题,联系平台处理;不计费 |
| 500 | 未能评估出该车的价格区间…… | 补充品牌、型号、上牌时间与里程后重试;不计费 |
| 500 | 数据服务暂时不可用(请求上游超时或网络异常),本次调用不计费 | 稍后重试;不计费 |
多语言代码示例
Java(Hutool)
JSONObject req = JSONUtil.createObj()
.set("brand", "大众")
.set("model", "迈腾")
.set("year", "2023")
.set("configuration", "330TSI DSG 豪华型")
.set("registrationDate", "2022-03")
.set("mileage", "8.5")
.set("accidentHistory", "0")
.set("transferCount", "0")
.set("fuelType", "汽油")
.set("transmissionType", "自动")
.set("displacement", "2.0")
.set("color", "黑色")
.set("location", "北京");
String body = HttpRequest.post("https://api.xujian.tech/openapi/usedcar/price")
.header("Content-Type", "application/json")
.header("X-API-Key", apiKey)
.timeout(20000)
.body(req.toString())
.execute()
.body();
JSONObject json = JSONUtil.parseObj(body);
if (json.getInt("code") != 0) {
System.out.println("评估失败(不收费):" + json.getStr("msg"));
return;
}
JSONObject data = json.getJSONObject("data");
System.out.printf("评估区间:%.2f 万 ~ %.2f 万%n",
data.getDouble("priceStart"), data.getDouble("priceEnd"));
Python
import requests
def estimate_price(api_key: str, car: dict):
"""评估二手车价格区间;估不出返回 None 且不扣费"""
resp = requests.post(
"https://api.xujian.tech/openapi/usedcar/price",
json=car,
headers={"Content-Type": "application/json", "X-API-Key": api_key},
timeout=30,
)
result = resp.json()
if result.get("code") != 0:
print("评估失败(不收费):", result.get("msg"))
return None
data = result["data"]
return data["priceStart"], data["priceEnd"]
if __name__ == "__main__":
car = {
"brand": "大众", "model": "迈腾", "year": "2023",
"registrationDate": "2022-03", "mileage": "8.5",
"accidentHistory": "0", "transferCount": "0",
"fuelType": "汽油", "transmissionType": "自动",
"displacement": "2.0", "color": "黑色", "location": "北京",
}
print("评估区间(万元):", estimate_price("你的APIKey", car))
JavaScript(浏览器 / Node 18+)
const resp = await fetch("https://api.xujian.tech/openapi/usedcar/price", {
method: "POST",
headers: { "Content-Type": "application/json", "X-API-Key": API_KEY },
body: JSON.stringify({
brand: "大众", model: "迈腾", year: "2023",
registrationDate: "2022-03", mileage: "8.5",
accidentHistory: "0", location: "北京",
}),
});
const { code, msg, data } = await resp.json();
if (code === 0) {
console.log(`评估区间:${data.priceStart} 万 ~ ${data.priceEnd} 万`);
} else {
console.warn("评估失败(不收费):", msg);
}
常见问题(FAQ)
usedcar.price 接口怎么收费?
usedcar.price 的收费类型为 PER_CALL(按次计费),当前单价 0.5000 元/次,调用前校验余额,余额不足返回「余额不足,请先充值。可联系微信xujian_cq」且不扣费;充值可可联系微信xujian_cq。扣费金额、交易前后余额均记录于交易流水中。
哪些参数对估值影响最大?
按特征重要性排序:mileage 行驶里程(权重最高)、
registrationDate 上牌时间与 year 年款(车龄折旧)、
location 车辆所在地(地域价格波动)、
accidentHistory 事故历史(车况)。这五项务必尽量填准。
事故等级怎么填?
accidentHistory 取值 0 ~ 3:0 无事故、1 轻微剐蹭(影响 1%~3%)、
2 更换覆盖件(影响 3%~8%)、3 结构损伤(影响 20% 以上)。
不确定时填 0,并在业务侧做二次人工核验。
返回的价格区间怎么用?
priceStart(下限)可作为快速成交 / 收车参考价,
priceEnd(上限)作为零售挂牌参考价。
实际成交价通常落在区间中部偏下,建议挂牌时比评估价低 3%~5% 留出议价空间。
为什么返回的是区间而不是一个具体数字?
二手车的实际成交价受车况、地域、成交时机影响很大,单一数字反而不符合真实交易。 区间能同时给出「快速变现价」与「挂牌价」两个锚点,更适合直接用于业务定价。
支持新能源汽车吗?
支持。fuelType 可填「纯电 / 插电混动」等,并配合
emissionStandard、engineModel 描述三电信息;
纯电车型的 displacement 可留空。
调用需要签名或加密吗?
不需要。XAPI 的接口仅校验请求头 X-API-Key,不做签名、时间戳或加密。