车辆物流数据开放 API
产品概述
车辆从入库到出库的全流程数据均可通过接口查询,方便接入贵司自有系统(ERP / TMS / 库存看板等)。各环节提供的数据如下:
| 环节 | 提供的数据 |
|---|---|
| 入库 | 入库核验时间、入库编号、入库验收照片与视频、合格证等单证 |
| 在场 | 在场数量、所在仓库、存放库位、车型 |
| 装柜 | SO 单号、柜号、封条号(锁号)、柜型、装柜完成与放行时间、装柜照片及视频 |
| 出库 | 出库类型、出库时间、出库柜号、出库影像 |
数据范围规则:
1. 仅返回贵司在系统内有权查看的车辆数据,与「客户门户」可见范围一致,不涉及其他公司车辆。
2. 贵司在多个堆场有业务时,同一密钥可聚合查询全部已授权堆场。
3. 本接口为只读接口,不提供任何写入能力。
接入信息
| 项目 | 值 |
|---|---|
| 正式环境 Base URL | https://a.wkaitool.cn/api/open/v1 |
| 传输协议 | HTTPS(TLS 1.2+) |
| 数据格式 | JSON(UTF-8) |
| 时间格式 | YYYY-MM-DD HH:MM:SS,北京时间(UTC+8) |
开通后服务方将下发 API Key 与已授权堆场编码(tenantCode)清单。
鉴权方式
所有请求在 Header 中携带 Bearer Token:
Authorization: Bearer <API Key>
鉴权失败返回对应错误码(见错误码),不返回任何业务数据。
通用约定
所有接口返回统一响应结构:
| 字段 | 类型 | 说明 |
|---|---|---|
| statusCode | integer | 业务状态码,20000 表示成功 |
| message | string | 提示信息 |
| alertMessage | string | null | 异常提示信息,正常时为 null |
| requestId | string | 服务端请求流水号,联调排障时请提供 |
| data | object | null | 业务数据 |
响应 Header 同时携带 X-Request-Id。
调用额度
| 限制 | 默认值 | 超限响应 |
|---|---|---|
| 每分钟 | 60 次 | HTTP 429,statusCode 42901 |
| 每自然日 | 10000 次 | HTTP 429,statusCode 42902 |
收到 429 后请退避至下一分钟再重试。额度可按套餐调整。
错误码
| HTTP | statusCode | errorCode | 说明 |
|---|---|---|---|
| 401 | 40100 | missing_api_key | 未携带接口访问令牌 |
| 401 | 40101 | invalid_api_key | 令牌无效 |
| 403 | 40300 | client_disabled | 接口账户已停用 |
| 403 | 40301 | client_expired | 接口服务已到期 |
| 403 | 40302 | media_not_allowed | 当前套餐未开通媒体文件访问 |
| 404 | 40400 | resource_not_found | 资源不存在或无权访问 |
| 422 | 42200 | validation_error | 请求参数不正确 |
| 429 | 42901 | minute_quota_exceeded | 超过每分钟调用额度 |
| 429 | 42902 | daily_quota_exceeded | 超过当日调用额度 |
| 500 | 50000 | internal_error | 服务内部错误 |
{
"statusCode": 40101,
"errorCode": "invalid_api_key",
"message": "接口访问令牌无效",
"alertMessage": null,
"requestId": "req_1f2e3d4c5b6a7980",
"data": null
}账户信息
返回当前密钥的授权堆场与套餐配置,可用来确认密钥有效、授权范围是否符合预期。
请求示例
curl -s "https://a.wkaitool.cn/api/open/v1/account" \ -H "Authorization: Bearer <API Key>"
// HttpClient 全局复用一个实例即可,不要每次请求都 new
static readonly HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "<API Key>");
var json = await client.GetStringAsync("https://a.wkaitool.cn/api/open/v1/account");
Console.WriteLine(json);HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://a.wkaitool.cn/api/open/v1/account"))
.header("Authorization", "Bearer <API Key>")
.build();
HttpResponse<String> resp = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());req, _ := http.NewRequest("GET", "https://a.wkaitool.cn/api/open/v1/account", nil)
req.Header.Set("Authorization", "Bearer <API Key>")
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))import requests
resp = requests.get(
"https://a.wkaitool.cn/api/open/v1/account",
headers={"Authorization": "Bearer <API Key>"},
timeout=15,
)
print(resp.json())const resp = await fetch("https://a.wkaitool.cn/api/open/v1/account", {
headers: { Authorization: "Bearer <API Key>" },
});
console.log(await resp.json());$ch = curl_init("https://a.wkaitool.cn/api/open/v1/account");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer <API Key>"],
CURLOPT_TIMEOUT => 15,
]);
$resp = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($resp['data']);响应字段(data)
| 字段 | 类型 | 说明 |
|---|---|---|
| client | object | 客户端信息 |
| name | string | 客户端名称 |
| createdAt | string | 开通时间 |
| expiresAt | string | null | 服务到期时间 |
| quota | object | 套餐配置 |
| minuteQuota | integer | 每分钟调用额度 |
| dailyQuota | integer | 每日调用额度 |
| allowMedia | boolean | 是否允许媒体文件访问 |
| scopes | array<object> | 授权堆场列表 |
| tenantCode | string | 堆场编码,可作为查询参数 |
| tenantName | string | 堆场名称 |
| authorizedAccountCount | integer | 该堆场下授权的客户账号数 |
响应示例
{
"statusCode": 20000,
"message": "查询成功",
"alertMessage": null,
"requestId": "req_9a8b7c6d5e4f3a21",
"data": {
"client": {
"name": "示例供应链有限公司",
"createdAt": "2026-07-03 15:00:00",
"expiresAt": "2027-07-31 00:00:00"
},
"quota": { "minuteQuota": 60, "dailyQuota": 10000, "allowMedia": true },
"scopes": [
{ "tenantCode": "t2588xxxx", "tenantName": "示例装箱场", "authorizedAccountCount": 5 },
{ "tenantCode": "t0612xxxx", "tenantName": "示例堆场", "authorizedAccountCount": 9 }
]
}
}车辆列表
分页查询授权范围内的车辆,支持状态筛选与增量同步,返回全量统计(在场数量等)。
请求参数(Query)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
tenantCode | string | 否 | 限定某个堆场;只能缩小范围,不在授权范围内时返回空结果 |
status | string | 否 | all(默认)/ in_stock 在场 / packed 装柜流程中(已排入装柜单、尚未放行,返回项 stockStatus 为 packing 或 packed)/ pickup_outbound 提车出库中 / outbound 已出库 |
vin | string | 否 | 精确 VIN 查询 |
updatedSince | string | 否 | 增量同步:仅返回该时间之后有数据变更的车辆(含状态变化、装柜/放行、新增照片视频及单证),格式 YYYY-MM-DD HH:MM:SS |
page | int | 否 | 页码,默认 1 |
size | int | 否 | 每页条数,默认 50,最大 100 |
includeMedia | bool | 否 | 是否随列表返回媒体清单,默认 false。列表建议不带媒体,详情使用批量 VIN 查询接口 |
请求示例
curl -s "https://a.wkaitool.cn/api/open/v1/vehicles?status=in_stock&page=1&size=50" \ -H "Authorization: Bearer <API Key>"
// HttpClient 全局复用一个实例即可,不要每次请求都 new
static readonly HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "<API Key>");
var json = await client.GetStringAsync(
"https://a.wkaitool.cn/api/open/v1/vehicles?status=in_stock&page=1&size=50");
Console.WriteLine(json);HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://a.wkaitool.cn/api/open/v1/vehicles?status=in_stock&page=1&size=50"))
.header("Authorization", "Bearer <API Key>")
.build();
HttpResponse<String> resp = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());url := "https://a.wkaitool.cn/api/open/v1/vehicles?status=in_stock&page=1&size=50"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("Authorization", "Bearer <API Key>")
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
var result map[string]any
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])import requests
resp = requests.get(
"https://a.wkaitool.cn/api/open/v1/vehicles",
params={"status": "in_stock", "page": 1, "size": 50},
headers={"Authorization": "Bearer <API Key>"},
timeout=15,
)
data = resp.json()["data"]
print(data["summary"], len(data["items"]))const qs = new URLSearchParams({ status: "in_stock", page: 1, size: 50 });
const resp = await fetch(`https://a.wkaitool.cn/api/open/v1/vehicles?${qs}`, {
headers: { Authorization: "Bearer <API Key>" },
});
const { data } = await resp.json();
console.log(data.summary, data.items.length);$qs = http_build_query(['status' => 'in_stock', 'page' => 1, 'size' => 50]);
$ch = curl_init("https://a.wkaitool.cn/api/open/v1/vehicles?$qs");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer <API Key>"],
]);
$data = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);
echo $data['summary']['inYard'], " 台在场\n";响应字段(data)
| 字段 | 类型 | 说明 |
|---|---|---|
| query.param | object | 请求参数回显 |
| summary | object | 授权范围全量统计(受 tenantCode 缩小影响,不受 vin / updatedSince / 分页影响) |
| total | integer | 全部车辆(含已出库历史) |
| inYard | integer | 在场数量(含装柜流程中、未放行车辆) |
| inPacking | integer | 已进入装柜流程、尚未放行 |
| pickupOutbound | integer | 已被提车 / 直接出库任务锁定 |
| outbound | integer | 已出库(含装柜放行) |
| pagination | object | 分页信息:page / size / total / hasMore |
| items | array<object> | 车辆列表,字段结构见下 |
| vin | string | 车架号 |
| stockStatus | string | 车辆状态,取值见数据字典 |
| stockStatusText | string | 状态中文文案 |
| tenant | object | 所在堆场:code / name |
| customer | object | 客户归属:id / name |
| vehicleModel | string | null | 车型 |
| materialCode | string | null | 物料号 |
| inbound | object | 入库信息 |
| orderCode | string | 入库订单码 |
| inboundNo | string | null | 入库编号(交接编号) |
| verifiedAt | string | null | 入库核验完成时间 |
| warehouseName | string | null | 所在仓库 |
| storageLocation | string | null | 存放库位 |
| packing | object | null | 装柜信息(未进装柜流程时为 null) |
| soNo / cabinetNo / sealNo | string | null | SO 单号 / 柜号 / 封条号(即锁号) |
| cabinetType | string | null | 柜型,如 40HQ |
| status / statusText | string | 装柜单状态,见数据字典 |
| completedAt / releasedAt | string | null | 装柜完成时间 / 放行时间 |
| media | array | 装柜媒体清单(includeMedia=true 时返回) |
| outbound | object | null | 出库记录:type / containerNo / outboundAt(装柜放行出库以 packing.releasedAt 为准) |
| media | object | 媒体清单(includeMedia=true 时返回):inbound 入库验收 / documents 单证 |
| fileId | string | 文件标识,用于文件下载接口 |
| kind | string | 媒体类型,见数据字典 |
| downloadUrl | string | 下载路径(需携带鉴权调用) |
| createdAt | string | null | 拍摄 / 上传时间 |
| updatedAt | string | 数据水位:该车数据最后变更时间,增量同步基准 |
响应示例
{
"statusCode": 20000,
"message": "查询成功",
"alertMessage": null,
"requestId": "req_5566778899aabbcc",
"data": {
"query": {
"param": { "tenantCode": null, "status": "in_stock", "vin": null,
"updatedSince": null, "page": 1, "size": 50, "includeMedia": false }
},
"summary": {
"total": 1385,
"inYard": 1201,
"inPacking": 96,
"pickupOutbound": 12,
"outbound": 184
},
"pagination": { "page": 1, "size": 50, "total": 1201, "hasMore": true },
"items": [
{
"vin": "LFMAAA0C1R0608038",
"stockStatus": "in_stock",
"stockStatusText": "在库",
"tenant": { "code": "t0612xxxx", "name": "示例堆场" },
"customer": { "id": 1177, "name": "示例供应链有限公司" },
"vehicleModel": "GS3 影速 劲享版",
"materialCode": "1004003",
"inbound": {
"orderCode": "8321",
"inboundNo": "HY-20260612-018",
"verifiedAt": "2026-06-12 15:40:21",
"warehouseName": "1号仓",
"storageLocation": "A4-4"
},
"packing": null,
"outbound": null,
"updatedAt": "2026-06-12 15:40:21"
}
]
}
}summary.inYard 即在场数量,可直接用于库存看板。批量 VIN 查询
按 VIN 批量查询完整档案,含入库、装柜、出库全量信息与媒体文件清单。
请求体(application/json)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
vins | string[] | 是 | VIN 列表,1 ~ 100 个,服务端自动去重并转大写 |
请求示例
curl -s -X POST "https://a.wkaitool.cn/api/open/v1/vehicles/query" \
-H "Authorization: Bearer <API Key>" \
-H "Content-Type: application/json" \
-d '{"vins": ["LFMAAA0C1R0608038", "LGXCE4CB1R0000001"]}'// HttpClient 全局复用一个实例即可,不要每次请求都 new
static readonly HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "<API Key>");
var body = new StringContent(
"{\"vins\": [\"LFMAAA0C1R0608038\", \"LGXCE4CB1R0000001\"]}",
Encoding.UTF8, "application/json");
var resp = await client.PostAsync("https://a.wkaitool.cn/api/open/v1/vehicles/query", body);
Console.WriteLine(await resp.Content.ReadAsStringAsync());String payload = "{\"vins\": [\"LFMAAA0C1R0608038\", \"LGXCE4CB1R0000001\"]}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://a.wkaitool.cn/api/open/v1/vehicles/query"))
.header("Authorization", "Bearer <API Key>")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> resp = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());payload := strings.NewReader(`{"vins": ["LFMAAA0C1R0608038", "LGXCE4CB1R0000001"]}`)
req, _ := http.NewRequest("POST", "https://a.wkaitool.cn/api/open/v1/vehicles/query", payload)
req.Header.Set("Authorization", "Bearer <API Key>")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))import requests
resp = requests.post(
"https://a.wkaitool.cn/api/open/v1/vehicles/query",
json={"vins": ["LFMAAA0C1R0608038", "LGXCE4CB1R0000001"]},
headers={"Authorization": "Bearer <API Key>"},
timeout=30,
)
for item in resp.json()["data"]["items"]:
print(item["vin"], item["status"])const resp = await fetch("https://a.wkaitool.cn/api/open/v1/vehicles/query", {
method: "POST",
headers: {
Authorization: "Bearer <API Key>",
"Content-Type": "application/json",
},
body: JSON.stringify({ vins: ["LFMAAA0C1R0608038", "LGXCE4CB1R0000001"] }),
});
const { data } = await resp.json();
data.items.forEach(it => console.log(it.vin, it.status));$ch = curl_init("https://a.wkaitool.cn/api/open/v1/vehicles/query");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <API Key>",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode(['vins' => ['LFMAAA0C1R0608038', 'LGXCE4CB1R0000001']]),
]);
$items = json_decode(curl_exec($ch), true)['data']['items'];
curl_close($ch);
foreach ($items as $item) {
echo $item['vin'], ' ', $item['status'], "\n";
}响应字段(data)
| 字段 | 类型 | 说明 |
|---|---|---|
| query.param.vins | array<string> | 请求 VIN 回显(去重转大写后) |
| summary | object | total / foundCount / notFoundCount |
| items | array<object> | 查询结果 |
| status | string | found 已找到 / not_found 未找到(不在系统内、未完成入库核验或不在授权范围) |
| (其余字段) | — | 与车辆列表 items 结构一致,且始终携带 media 媒体清单 |
补充说明:
1. 未查到的 VIN 返回 status: "not_found",不报错。
2. 同一 VIN 在多个授权堆场均有记录时各返回一条;同一堆场多次入库仅返回最新一次生命周期。
3. 装柜放行出库的车辆,出库时间与柜号以 packing.releasedAt / packing.cabinetNo 为准。
响应示例(节选:一台已装柜放行车辆)
{
"statusCode": 20000,
"message": "查询成功",
"alertMessage": null,
"requestId": "req_a1b2c3d4e5f60718",
"data": {
"query": { "param": { "vins": ["LFMAAA0C1R0608038", "LGXCE4CB1R0000001"] } },
"summary": { "total": 2, "foundCount": 1, "notFoundCount": 1 },
"items": [
{
"vin": "LFMAAA0C1R0608038",
"status": "found",
"stockStatus": "outbound",
"stockStatusText": "已出库",
"tenant": { "code": "t0612xxxx", "name": "示例堆场" },
"customer": { "id": 1177, "name": "示例供应链有限公司" },
"vehicleModel": "GS3 影速 劲享版",
"materialCode": "1004003",
"inbound": {
"orderCode": "8321",
"inboundNo": "HY-20260612-018",
"verifiedAt": "2026-06-12 15:40:21",
"warehouseName": "1号仓",
"storageLocation": "A4-4"
},
"packing": {
"soNo": "SO2606180032",
"cabinetNo": "MSKU1234567",
"sealNo": "CN88231206",
"cabinetType": "40HQ",
"status": "completed",
"statusText": "已完成",
"completedAt": "2026-06-18 17:22:40",
"releasedAt": "2026-06-20 09:15:02",
"media": [
{
"fileId": "packing_media:90211",
"kind": "cabinet_photo",
"downloadUrl": "/api/open/v1/files/packing_media:90211/download",
"createdAt": "2026-06-18 17:20:11"
},
{
"fileId": "packing_media:90215",
"kind": "evidence_video",
"downloadUrl": "/api/open/v1/files/packing_media:90215/download",
"createdAt": "2026-06-18 17:21:35"
}
]
},
"outbound": null,
"media": {
"inbound": [
{
"fileId": "order_media:441203",
"kind": "front",
"downloadUrl": "/api/open/v1/files/order_media:441203/download",
"createdAt": "2026-06-12 15:39:40"
}
],
"documents": [
{
"fileId": "order_document:5521",
"kind": "certificate",
"downloadUrl": "/api/open/v1/files/order_document:5521/download",
"createdAt": "2026-06-12 15:41:03"
}
]
},
"updatedAt": "2026-06-20 09:15:02"
},
{ "vin": "LGXCE4CB1R0000001", "status": "not_found" }
]
}
}文件下载
fileId 来自车辆接口响应中的媒体清单。请求需携带 Bearer Token,服务端校验授权后返回 302 跳转至文件地址,HTTP 客户端需开启跟随跳转(cURL 加 -L)。
请求示例
curl -sL "https://a.wkaitool.cn/api/open/v1/files/order_media:441203/download" \ -H "Authorization: Bearer <API Key>" -o vin_front.jpg
// HttpClient 全局复用一个实例即可;默认会跟随 302 跳转
static readonly HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "<API Key>");
var bytes = await client.GetByteArrayAsync(
"https://a.wkaitool.cn/api/open/v1/files/order_media:441203/download");
await File.WriteAllBytesAsync("vin_front.jpg", bytes);HttpClient client = HttpClient.newBuilder()
.followRedirects(HttpClient.Redirect.NORMAL) // 需开启跟随 302 跳转
.build();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://a.wkaitool.cn/api/open/v1/files/order_media:441203/download"))
.header("Authorization", "Bearer <API Key>")
.build();
client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("vin_front.jpg")));req, _ := http.NewRequest("GET",
"https://a.wkaitool.cn/api/open/v1/files/order_media:441203/download", nil)
req.Header.Set("Authorization", "Bearer <API Key>")
resp, err := http.DefaultClient.Do(req) // 默认跟随 302 跳转
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
out, _ := os.Create("vin_front.jpg")
defer out.Close()
io.Copy(out, resp.Body)import requests
resp = requests.get(
"https://a.wkaitool.cn/api/open/v1/files/order_media:441203/download",
headers={"Authorization": "Bearer <API Key>"},
timeout=60, # 默认跟随 302 跳转
)
open("vin_front.jpg", "wb").write(resp.content)const resp = await fetch(
"https://a.wkaitool.cn/api/open/v1/files/order_media:441203/download",
{ headers: { Authorization: "Bearer <API Key>" } }, // fetch 默认跟随跳转
);
require("fs").writeFileSync("vin_front.jpg", Buffer.from(await resp.arrayBuffer()));$ch = curl_init("https://a.wkaitool.cn/api/open/v1/files/order_media:441203/download");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true, // curl 默认不跟随 302,必须开启
CURLOPT_HTTPHEADER => ["Authorization: Bearer <API Key>"],
]);
file_put_contents('vin_front.jpg', curl_exec($ch));
curl_close($ch);1. 跳转地址请即取即用,不建议持久化存储或长期依赖;如需再次获取文件,请重新调用本接口(每次都会校验授权)。
2. 文件不存在或不在授权范围内时统一返回 404 / resource_not_found。
3. 文件下载计入调用额度。
数据字典
车辆状态 stockStatus
| 值 | 文案 | 含义 |
|---|---|---|
in_stock | 在库 | 已完成入库核验,在场 |
packing | 装柜中 | 已排入装柜单,装柜作业未完成 |
packed | 已装柜 | 装柜完成,待放行 |
pickup_outbound | 提车出库中 | 被提车 / 直接出库任务锁定 |
outbound | 已出库 | 已出库或装柜放行 |
exception | 异常 | 入库核验异常 |
装柜单状态 packing.status
| 值 | 文案 |
|---|---|
unclaimed | 待装柜 |
in_progress | 装柜中 |
ready_submit | 待提交 |
paused / pause_pending | 已挂起 / 挂起处理中 |
completed | 已完成 |
媒体类型 kind
| 分组 | kind | 说明 |
|---|---|---|
| 入库验收 media.inbound | front / left_front 等视角标签、photo、video | 入库核验照片与视频 |
| 单证 media.documents | certificate / conformity_cert / eco_cert | 合格证 / 一致性证书 / 环保信息单 |
| 装柜 packing.media | cabinet_photo | 装柜过程柜照 |
seal_photo / loader_signature | 封条照 / 装柜员签名 | |
evidence_photo / evidence_video | 本车验车照片 / 装车视频 | |
| 出库 outbound.media | outbound_photo / outbound_video | 出库影像 |
增量同步方案
items[].updatedAt 是该车的数据水位:车辆状态、装柜单、装柜媒体、入库照片、单证中最后一次变更的时间。装柜完成、放行、补传照片等都会推进水位,请以它作为同步基准。
推荐流程:
1. 首次全量:GET /vehicles?page=1&size=100 逐页拉取,记录本地最大 updatedAt。
2. 定时增量:每 5 ~ 10 分钟 GET /vehicles?updatedSince=<上次最大updatedAt>,返回按 updatedAt 升序,处理完更新本地水位。
3. 增量结果中的车辆如需最新照片、视频清单,用批量 VIN 查询接口按 VIN 获取完整详情。
4. 请控制在额度内;summary.inYard 可直接用于在场数量看板。
如对时效要求更高,Webhook 事件推送(装柜完成、放行等状态变更实时回调)已列入 V2 规划,见变更记录。
变更记录
| 版本 | 日期 | 说明 |
|---|---|---|
| V2.0 | 规划中 | Webhook 事件推送:入库核验、装柜完成、放行、出库、核验异常等状态变更实时回调至贵司接收地址,免轮询;异常事件通知。开放时间与订阅方式另行通知,现有 V1 接口保持不变 |
| V1.0 | 2026-07-03 | 首次发布:账户信息、车辆列表、批量 VIN 查询、文件下载 |
接口字段一经发布保持向后兼容;如有重大升级将发布 /open/v2 并提前通知。联调过程中如遇问题,请联系服务方对接人并附上响应中的 requestId。对 Webhook 推送有需求或希望优先接入的客户,可向对接人登记。