Hướng dẫn xây dựng được viết dựa trên hành vi đã ghi trong tài liệu của API; không nêu tên khách hàng nào. Đăng ngày .
Vấn đề: hồ sơ ghi tên một chiếc xe mà không ai nhìn thấy
Biểu mẫu báo giá, hồ sơ hợp đồng bảo hiểm và thông báo tổn thất ban đầu đều xác định xe theo cùng một cách: bằng số VIN, do khách hàng nhập hoặc đọc từ giấy đăng ký xe. Mọi thông tin người dùng thấy sau đó về chiếc xe đều là văn bản: năm sản xuất, hãng, mẫu xe và có thể cả phiên bản. Hỏi "đây có phải xe của quý khách không?" bên cạnh một dòng chữ thì gần như ai cũng sẽ trả lời có.
Hình ảnh của mẫu xe mà VIN giải mã ra giúp khách hàng và chuyên viên giám định kiểm tra nhanh rằng hồ sơ ghi đúng loại xe. Nó không thể cho thấy đó là chiếc xe nào: ảnh render là hình minh họa studio của một hãng, mẫu xe và năm trong danh mục, và không mô tả bất kỳ chiếc xe vật lý cụ thể nào. Chính điều này định hình toàn bộ cách tích hợp dưới đây.
Quy trình tích hợp diễn ra như thế nào
- Giải mã khi tiếp nhận. Quy trình báo giá hoặc hệ thống quản lý hợp đồng bảo hiểm giải mã VIN một lần, miễn phí, và lưu vehicle id của danh mục cùng với hợp đồng. Các yêu cầu bồi thường mở theo hợp đồng sẽ kế thừa id này.
- Một góc nhìn ở mọi nơi.
front-3-4, góc chính, trong cùng một khung trên màn hình báo giá, bàn xử lý bồi thường, PDF báo giá và cổng thông tin hợp đồng bảo hiểm, để mọi màn hình hiển thị mẫu xe theo cùng một cách. - Dùng signed URL, không bao giờ dùng khóa. Trình duyệt và trình kết xuất PDF tải các URL không chứa khóa do máy chủ của bạn tạo.
- Dùng lời cho những gì hình ảnh không thể nói. Phiên bản, tùy chọn, màu sơn trong hồ sơ, hư hỏng và số km vẫn là văn bản và ảnh chụp, còn hình ảnh ghi rõ chỉ mang tính minh họa.
Bước 1: giải mã VIN, miễn phí
GET /api/v1/vin/{vin} hoàn toàn miễn phí và cần một khóa có quyền images:read. Endpoint này trả về các trường đã giải mã từ dữ liệu vPIC của NHTSA (năm, hãng, mẫu xe, phiên bản, dòng, kiểu thân xe, động cơ và mọi thuộc tính khác mà vPIC có) và, khi danh mục có xe đó, một đối tượng vehicle với id cố định và image_path sẵn dùng.
curl --fail-with-body \
-H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
"https://carimage.dev/api/v1/vin/WP0AA2A96RS201834"{
"data": {
"vin": "WP0AA2A96RS201834",
"valid": true,
"errors": [],
"suggested_vin": null,
"year": 2024,
"make": "Porsche",
"model": "911",
"trim": "Carrera, Carrera T, Carrera 4",
"series": "Type 992",
"body_class": "Coupe",
"vehicle": {
"id": "veh_78qtwrgh37bkr",
"make": "Porsche",
"model": "911",
"year": 2024,
"image_path": "/api/v1/images/car?vehicle=veh_78qtwrgh37bkr"
},
"source": "vpic-db"
}
}Đọc trim: "Carrera, Carrera T, Carrera 4". Mẫu của VIN này bao gồm ba phiên bản, nên ngay cả kết quả giải mã cũng không thể cho biết hợp đồng bảo hiểm cho phiên bản nào, và ảnh render của chiếc 911 đời 2024 càng không thể. Hãy yêu cầu khách hàng xác nhận phiên bản, lưu nó cùng series và body_class dưới dạng văn bản, và để hình ảnh thể hiện mẫu xe.
- Một VIN có chữ số kiểm tra sai vẫn được giải mã, với
valid: falsevà lỗi nằm trongerrors;suggested_vinđánh dấu ký tự mà vPIC cho là sai bằng!, và đó là điều nên hiển thị cho người đang nhập. - Biểu mẫu chỉ có vài ký tự đầu có thể gửi VIN một phần: ít nhất năm ký tự, dùng
*cho mỗi vị trí chưa biết và có thể kèmyear. 404nghĩa là vPIC không có bản ghi nào cho mẫu VIN này. vPIC bao gồm các xe sản xuất cho thị trường Mỹ, vì vậy với các thị trường khác, hãy bắt đầu từ hãng và mẫu xe bằngPOST /api/v1/images/resolve, cũng miễn phí.
Bước 2: lưu id xe trong hợp đồng bảo hiểm và hồ sơ bồi thường
Lưu data.vehicle.id vào hợp đồng bảo hiểm dưới dạng chuỗi thuần và sao chép sang mọi hồ sơ bồi thường mở theo hợp đồng đó. Id này mang tính xác định và vĩnh viễn: cùng một xe luôn có cùng id trên mọi lần triển khai và sau mọi bản phát hành danh mục, nên có thể dùng an toàn làm khóa ngoại, và mọi yêu cầu sau đó chỉ cần ghi vehicle=veh_78qtwrgh37bkr thay vì nêu hãng và mẫu xe.
Khi data.vehicle là null, hãng và mẫu xe được giải mã không có trong danh mục, như với rơ-moóc và một số khung gầm xe thương mại. Bạn vẫn có thể hiển thị các trường đã giải mã. Hãy hiển thị chúng mà không kèm hình, và không bao giờ đặt một xe tương tự vào chỗ đó.
Bước 3: một góc nhìn trên hồ sơ bồi thường và PDF báo giá
Màn hình báo giá, bàn làm việc xử lý bồi thường và cổng hợp đồng bảo hiểm là các ứng dụng trình duyệt, vì vậy máy chủ của bạn tạo URL có chữ ký bằng POST /api/v1/image-urls: mỗi URL tính hình ảnh của nó là một hình ảnh xe của tháng tại thời điểm được tạo, tối đa 50 URL mỗi lệnh gọi, và được tải miễn phí cho đến khi hết hạn. Hãy căn khung ảnh một lần rồi dùng lại cấu hình đó: front-3-4 trong khung 640×400 với fit: "contain", và trim kèm một chút padding để một chiếc coupe và một chiếc bán tải lấp đầy khung theo cùng một cách. Thời gian tồn tại của mỗi URL tùy thuộc vào nơi nó được hiển thị:
- Màn hình xử lý bồi thường. Tạo URL khi màn hình được hiển thị. Thời hạn mặc định 1 giờ đủ cho một phiên làm việc, và hồ sơ bồi thường được mở lại vào ngày mai sẽ nhận một URL mới.
- PDF báo giá. Khi PDF được kết xuất từ HTML, trình kết xuất tải ảnh một lần rồi nhúng vào, nên thời hạn mặc định là quá đủ, và dịch vụ PDF không bao giờ giữ khóa của bạn.
format: "jpg"đặt ảnh lên nền trắng, đúng như một tài liệu cần. - Cổng thông tin hợp đồng bảo hiểm và email gia hạn. Những nội dung này tồn tại lâu hơn mọi thời hạn, vì vậy hãy tạo URL với
renew: truevàttl_seconds: 604800(7 ngày). URL vẫn tiếp tục hoạt động, mỗi lần gia hạn tính hình ảnh một lần trong tháng diễn ra gia hạn, và không tính thêm nếu hình ảnh đã được tính trong tháng đó, cònrenew_days: 365, mức dài nhất cho phép, bao trọn một kỳ hợp đồng bảo hiểm kéo dài một năm.
Cấp cho khóa dùng để tạo URL một danh sách origin được phép trên bảng điều khiển: URL được tải từ trang khác sẽ trả về 403 với origin_not_allowed, trong khi ứng dụng email và trình xem PDF, vốn không gửi Referer, vẫn tải được. Thu hồi khóa sẽ vô hiệu hóa mọi URL mà khóa đó đã tạo.
import { CarImageClient, type ImageParams } from "@meterapp/car-image-sdk";
const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });
// Quote or policy intake: the VIN in, the vehicle id and the decoded words on the record. Free.
const { data: decoded } = await client.decodeVin(policy.vin);
policy.vehicleId = decoded.vehicle?.id ?? null; // null: show the decoded text and no picture
policy.trimText = decoded.trim; // "Carrera, Carrera T, Carrera 4": words, never the picture
if (policy.vehicleId) {
// One view, framed once, for every screen and document that shows this policy's car.
const view: ImageParams = {
vehicle: policy.vehicleId, view: "front-3-4", color: policy.paintHex ?? "silver",
width: 640, height: 400, fit: "contain", trim: true, padding: 6,
};
// The claims workbench: a URL for this session, minted when the screen draws.
const { data: [workbench] } = await client.createImageUrls({ ...view, format: "auto" });
// The quote PDF: the HTML-to-PDF renderer loads the URL once and embeds the picture.
const { data: [pdf] } = await client.createImageUrls({ ...view, format: "jpg" });
// The policy portal and the renewal email: one URL that keeps working for the term.
const { data: [portal] } = await client.createImageUrls(
{ ...view, format: "auto" },
{ ttlSeconds: 604800, renew: true, renewDays: 365, idempotencyKey: `policy:${policy.id}:image` }
);
}Bước 4: gắn nhãn là mẫu xe, không bao giờ là chiếc xe được bảo hiểm
Đặt nhãn ngay tại vị trí bức ảnh, không chỉ ở chú thích cuối trang: trong văn bản alt và trong chú thích bên dưới ảnh. Ảnh render thể hiện hãng, mẫu xe và năm sản xuất với màu sơn bạn chọn, và color có thể theo màu ghi trong hợp đồng bảo hiểm (tên màu đặt sẵn hoặc mã hex bất kỳ). Đó vẫn là mẫu xe với màu sơn đó, không phải chiếc xe của khách hàng.
<figure>
<img src="https://carimage.dev/api/v1/delivery/eyJhbGciOi…" width="640" height="400"
alt="Representative image of a 2024 Porsche 911, not a photo of the insured vehicle">
<figcaption>
2024 Porsche 911 · Coupe · Type 992 · trim on the VIN: Carrera, Carrera T or Carrera 4
<small>Representative image of the model. Not a photo of the insured vehicle.</small>
</figcaption>
</figure>Chi phí bao nhiêu và gói nào phù hợp
- Miễn phí: giải mã VIN, resolve, tra cứu danh mục và mọi lần tải URL đã ký trong thời hạn hiệu lực của nó.
- Một hình ảnh xe: mỗi xe với mỗi màu sơn và góc nhìn, chỉ tính một lần mỗi tháng dù được phân phối, tạo hay gia hạn bao nhiêu lần, ở mọi kích thước và định dạng.
- Hình ảnh xe mỗi tháng: một quy trình báo giá gặp rất nhiều xe khác nhau, và mỗi gói bao gồm một số lượng hình ảnh xe mỗi tháng: Free 100, Pro 2.500 và Business 10.000; Enterprise theo thỏa thuận. Hình ảnh đã được tính trong tháng này luôn được phục vụ, còn yêu cầu vượt hạn mức sẽ trả về 402 trước khi tính bất cứ thứ gì, vì vậy hãy chọn gói theo số xe bạn báo giá.
Với gói trả phí, giấy phép cho phép dùng ảnh render bên trong những gì sản phẩm của bạn tạo ra cho người dùng, kể cả báo giá hay báo cáo, trong suốt thời gian gói còn hiệu lực; chi tiết có trong giấy phép.
CLI, SDK và MCP
# decode for free and keep the id
npx @meterapp/car-image vin WP0AA2A96RS201834 --json | jq -r .data.vehicle.id
# one renewing URL for the policy's documents, minted once however often intake retries
npx @meterapp/car-image url --vehicle veh_78qtwrgh37bkr --view front-3-4 --width 640 --height 400 \
--fit contain --trim --padding 6 --format auto --ttl 604800 --renew --renew-days 365 \
--idempotency-key policy-88213-image- SDK:
client.decodeVin(vin, { year? })vàclient.createImageUrls(…), như trên;client.resolve(query)cho xe không có VIN. - MCP:
decode_vinvàcreate_car_image_urlsnằm trong bộ công cụ cốt lõi, nên một trợ lý có hồ sơ bồi thường trong ngữ cảnh có thể trả lời "cho tôi xem mẫu xe được bảo hiểm" dựa trên VIN đã lưu. Hướng dẫn thiết lập có trên trang MCP.
Câu hỏi thường gặp
- Hình ảnh có thể thay thế ảnh chụp chiếc xe được bảo hiểm không?
- Không. Đây là ảnh render studio theo hãng, mẫu xe và năm trong danh mục, không phải ảnh chụp, và không mô tả bất kỳ chiếc xe cụ thể nào. Ảnh giúp khách hàng hoặc chuyên viên giám định thấy rằng hồ sơ ghi đúng loại xe. Tình trạng, hư hỏng, phiên bản, tùy chọn và các sửa đổi phải dựa vào ảnh chụp, kết quả kiểm định và văn bản đã giải mã, và hình ảnh nên ghi rõ là ảnh minh họa.
- Chi phí để có ảnh trên mỗi báo giá là bao nhiêu?
- Giải mã VIN là miễn phí. Ảnh được tính là một ảnh xe của tháng khi URL có chữ ký của nó được tạo hoặc khi dữ liệu ảnh được gửi đến máy chủ của bạn, sau đó có thể phân phối bao nhiêu lần tùy ý; tải URL có chữ ký là miễn phí cho đến khi hết hạn. URL tự gia hạn tính ảnh một lần trong mỗi tháng tiếp theo có người mở, và không tính gì trong những tháng không ai xem.
- VIN giải mã được nhưng vehicle là null. Giờ phải làm sao?
- Bộ giải mã nhận diện được xe nhưng danh mục không có mục nào cho hãng, mẫu và năm đó, điều này xảy ra với rơ-moóc và một số khung gầm xe thương mại. Hãy hiển thị các trường đã giải mã mà không kèm hình ảnh và không bao giờ thay bằng một chiếc xe tương tự. Hãy tìm trong danh mục phòng khi cách viết khác nhau, và nếu thực sự không có, hãy gửi yêu cầu trên bảng yêu cầu công khai.
- Giải mã VIN có áp dụng cho xe ngoài thị trường Mỹ không?
- Bộ giải mã dùng dữ liệu vPIC của NHTSA, vốn bao gồm các xe sản xuất cho thị trường Mỹ, nên một VIN nhập đúng từ thị trường khác có thể trả về 404 hoặc được giải mã mà không có mẫu xe. Thay vào đó, hãy tìm chiếc xe đó theo hãng, mẫu xe và năm sản xuất bằng endpoint resolve miễn phí; bản thân danh mục có bao gồm các dòng xe của các thị trường khác.
- Hồ sơ bồi thường được lưu hình ảnh trong bao lâu?
- Trong suốt thời gian gói của bạn còn hiệu lực. Với gói trả phí, giấy phép bao gồm bản render nằm trong nội dung sản phẩm của bạn tạo ra, kể cả báo giá hoặc báo cáo; trong vòng 30 ngày sau khi gói kết thúc, các bản sao đã lưu sẽ bị xóa. Để giữ ảnh trong hồ sơ vĩnh viễn, hãy mua chúng dưới dạng Image Pack. Bản render cũng có thể được cải thiện theo thời gian, vì vậy hồ sơ cần giữ đúng những gì khách hàng đã thấy nên lưu tệp thay vì URL.