คู่มือการสร้างที่เขียนจากพฤติกรรมของ API ตามเอกสาร โดยไม่ได้ระบุชื่อลูกค้ารายใด เผยแพร่เมื่อ
ปัญหา: ข้อมูลระบุรถที่ไม่มีใครมองเห็น
แบบฟอร์มขอใบเสนอราคา บันทึกกรมธรรม์ และการแจ้งเหตุความเสียหายครั้งแรก ล้วนระบุรถในแบบเดียวกัน คือด้วย VIN ที่ลูกค้าพิมพ์เองหรืออ่านจากเอกสารจดทะเบียนรถ หลังจากนั้นทุกอย่างที่คนเห็นเกี่ยวกับรถเป็นเพียงข้อความ ได้แก่ ปี ยี่ห้อ รุ่น และอาจมีรุ่นย่อย การถามว่า "นี่ใช่รถของคุณหรือไม่" ข้างข้อความหนึ่งบรรทัดจึงชวนให้ตอบว่าใช่ไม่ว่าจะเป็นรถอะไรก็ตาม
ภาพของรุ่นรถที่ได้จากการถอดรหัส VIN ช่วยให้ลูกค้าและผู้ประเมินความเสียหายตรวจสอบได้ทันทีว่าข้อมูลในระบบระบุประเภทรถถูกต้อง แต่ภาพนี้ไม่สามารถแสดงได้ว่าเป็นรถคันใด: ภาพเรนเดอร์คือภาพประกอบสไตล์สตูดิโอของยี่ห้อ รุ่น และปีในแค็ตตาล็อก และไม่ได้แสดงถึงรถคันใดคันหนึ่งที่มีอยู่จริง ข้อเท็จจริงข้อนี้เป็นตัวกำหนดการเชื่อมต่อระบบทั้งหมดด้านล่าง
การผสานรวมมีลักษณะอย่างไร
- ถอดรหัสตอนรับข้อมูลเข้า ขั้นตอนเสนอราคาหรือระบบกรมธรรม์จะถอดรหัส VIN เพียงครั้งเดียวโดยไม่มีค่าใช้จ่าย และจัดเก็บ id ของรถจากแค็ตตาล็อกไว้กับกรมธรรม์ เคลมที่เปิดภายใต้กรมธรรม์นั้นจะได้รับ id นี้ไปด้วย
- มุมมองเดียวทุกที่
front-3-4ซึ่งเป็นมุมหลัก แสดงในกรอบเดียวกันบนหน้าจอใบเสนอราคา หน้าจอจัดการเคลม PDF ใบเสนอราคา และพอร์ทัลกรมธรรม์ เพื่อให้ทุกหน้าจอแสดงรุ่นรถในแบบเดียวกัน - ใช้ Signed URL ห้ามใช้คีย์ เบราว์เซอร์และตัวเรนเดอร์ PDF จะโหลด URL ที่ไม่มีคีย์ซึ่งเซิร์ฟเวอร์ของคุณสร้างขึ้น
- ใช้ข้อความอธิบายสิ่งที่ภาพบอกไม่ได้ รุ่นย่อย อุปกรณ์เสริม สีที่บันทึกไว้ ความเสียหาย และเลขไมล์ ยังคงระบุด้วยข้อความและภาพถ่าย และภาพจะระบุว่าเป็นภาพตัวอย่าง
ขั้นตอนที่ 1: ถอดรหัส VIN ฟรี
GET /api/v1/vin/{vin} ไม่มีค่าใช้จ่ายและต้องใช้คีย์ที่มีสิทธิ์ images:read โดยจะตอบกลับด้วยฟิลด์ที่ถอดรหัสแล้วจากข้อมูล vPIC ของ NHTSA (ปี ยี่ห้อ รุ่น รุ่นย่อย ซีรีส์ ประเภทตัวถัง เครื่องยนต์ และแอตทริบิวต์อื่นๆ ทั้งหมดที่ vPIC มี) และเมื่อแค็ตตาล็อกมีรถคันนั้น จะมีออบเจ็กต์ vehicle พร้อม id ที่คงที่และ image_path ที่พร้อมใช้งาน
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"
}
}ดูที่ trim: "Carrera, Carrera T, Carrera 4" รูปแบบของ VIN นี้ครอบคลุมสามรุ่นย่อย แม้แต่การถอดรหัสจึงไม่สามารถบอกได้ว่ากรมธรรม์คุ้มครองรุ่นย่อยใด และภาพเรนเดอร์ของ 911 ปี 2024 ก็ยิ่งบอกไม่ได้ โปรดขอให้ลูกค้ายืนยันรุ่นย่อย เก็บไว้เป็นข้อความพร้อมกับ series และ body_class และให้ภาพแสดงเพียงรุ่นรถ
- VIN ที่มีหลักตรวจสอบ (check digit) ไม่ถูกต้องยังคงถอดรหัสได้ โดยมี
valid: falseและระบุปัญหาไว้ในerrorsส่วนsuggested_vinจะทำเครื่องหมาย!ที่ตัวอักษรที่ vPIC คิดว่าผิด ซึ่งเป็นสิ่งที่ควรแสดงให้ผู้ที่กำลังพิมพ์เห็น - แบบฟอร์มที่มีเพียงอักขระส่วนแรกสามารถส่ง VIN บางส่วนได้ โดยต้องมีอย่างน้อยห้าอักขระ ใช้
*แทนแต่ละตำแหน่งที่ไม่ทราบ และระบุyearเพิ่มได้ตามต้องการ 404หมายความว่า vPIC ไม่มีข้อมูลของรูปแบบนี้ vPIC ครอบคลุมรถที่ผลิตสำหรับตลาดสหรัฐฯ ดังนั้นสำหรับตลาดอื่น ให้เริ่มจากยี่ห้อและรุ่นด้วยPOST /api/v1/images/resolveซึ่งไม่มีค่าใช้จ่ายเช่นกัน
ขั้นตอนที่ 2: เก็บ id ของรถไว้ในกรมธรรม์และการเคลม
จัดเก็บ data.vehicle.id ไว้ในกรมธรรม์เป็นสตริงธรรมดา และคัดลอกไปยังทุกเคลมที่เปิดภายใต้กรมธรรม์นั้น id นี้คงที่และถาวร: รถรายการเดียวกันในแคตตาล็อกจะมี id เดียวกันในทุกการ deploy และหลังการออกแคตตาล็อกทุกเวอร์ชัน จึงใช้เป็น foreign key ได้อย่างปลอดภัย และทุกคำขอหลังจากนั้นจะระบุ vehicle=veh_78qtwrgh37bkr แทนการระบุยี่ห้อและรุ่น
เมื่อ data.vehicle เป็น null แสดงว่ายี่ห้อและรุ่นที่ถอดรหัสได้ไม่มีอยู่ในแค็ตตาล็อก เช่น รถพ่วงและแชสซีรถเชิงพาณิชย์บางรุ่น คุณยังคงแสดงฟิลด์ที่ถอดรหัสได้ตามปกติ โปรดแสดงโดยไม่มีภาพ และอย่านำรถที่คล้ายกันมาแสดงแทน
ขั้นตอนที่ 3: ใช้มุมมองเดียวในแฟ้มเคลมและ PDF ใบเสนอราคา
หน้าเสนอราคา หน้าจัดการเคลม และพอร์ทัลกรมธรรม์ล้วนเป็นแอปบนเบราว์เซอร์ ดังนั้นเซิร์ฟเวอร์ของคุณจะสร้าง signed URL ด้วย POST /api/v1/image-urls: แต่ละ URL จะนับภาพของตนเป็นภาพรถยนต์ของเดือนเมื่อถูกสร้าง สูงสุด 50 รายการต่อการเรียกหนึ่งครั้ง และโหลดได้ฟรีจนกว่าจะหมดอายุ กำหนดการจัดเฟรมภาพเพียงครั้งเดียวแล้วใช้รูปแบบเดิมซ้ำ: front-3-4 ในกรอบขนาด 640×400 พร้อม fit: "contain" และ trim พร้อม padding เล็กน้อย เพื่อให้รถคูเป้และรถกระบะเต็มกรอบในลักษณะเดียวกัน ระยะเวลาที่แต่ละ URL ควรมีอายุขึ้นอยู่กับตำแหน่งที่แสดง:
- หน้าจอทำงานด้านเคลม สร้าง URL เมื่อหน้าจอแสดงผล อายุการใช้งานเริ่มต้น 1 ชั่วโมง ครอบคลุมการทำงานหนึ่งรอบ และเคลมที่เปิดอีกครั้งในวันพรุ่งนี้จะได้รับ URL ใหม่
- PDF ใบเสนอราคา เมื่อสร้าง PDF จาก HTML ตัวเรนเดอร์จะโหลดรูปภาพครั้งเดียวแล้วฝังไว้ในไฟล์ อายุการใช้งานเริ่มต้นจึงเพียงพอ และบริการ PDF ไม่ต้องถือคีย์ของคุณเลย
format: "jpg"จะวางรูปภาพลงบนพื้นหลังสีขาว ซึ่งเหมาะกับเอกสาร - พอร์ทัลกรมธรรม์และอีเมลแจ้งต่ออายุ สิ่งเหล่านี้อยู่นานกว่าอายุสูงสุดของ URL จึงควรสร้างด้วย
renew: trueและttl_seconds: 604800(7 วัน) URL จะยังใช้งานได้ต่อไป การต่ออายุจะนับภาพหนึ่งครั้งในเดือนที่เกิดการต่ออายุ และไม่นับเพิ่มหากภาพนั้นถูกนับไปแล้วในเดือนนั้น ส่วนrenew_days: 365ซึ่งเป็นค่าสูงสุดที่อนุญาต ครอบคลุมระยะเวลากรมธรรม์หนึ่งปี
กำหนดรายการ origin ที่อนุญาตให้กับคีย์ที่ใช้สร้าง URL บนแดชบอร์ด: URL ที่ถูกโหลดจากเว็บไซต์อื่นจะตอบกลับ 403 พร้อม origin_not_allowed ส่วนโปรแกรมอีเมลและโปรแกรมดู PDF ซึ่งไม่ส่ง Referer จะยังคงโหลดได้ การเพิกถอนคีย์จะทำให้ URL ทั้งหมดที่คีย์นั้นสร้างไว้ใช้งานไม่ได้
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` }
);
}ขั้นตอนที่ 4: ระบุว่าเป็นภาพของรุ่นรถ ห้ามระบุว่าเป็นรถคันที่เอาประกัน
วางป้ายกำกับไว้ตรงที่มีรูปภาพ ไม่ใช่แค่ในเชิงอรรถ: ทั้งในข้อความ alt และในคำบรรยายใต้ภาพ ภาพเรนเดอร์แสดงยี่ห้อ รุ่น และปีในสีที่คุณเลือก และ color สามารถตั้งตามสีที่ระบุในกรมธรรม์ได้ (ชื่อสีที่กำหนดไว้ล่วงหน้าหรือค่า hex ใดก็ได้) แต่ภาพนั้นก็ยังเป็นรุ่นรถดังกล่าวในสีนั้น ไม่ใช่รถของลูกค้า
<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>ค่าใช้จ่าย และแพ็กเกจที่เหมาะสม
- ฟรี: การถอดรหัส VIN, resolve, การค้นหาในแค็ตตาล็อก และการโหลด signed URL ทุกครั้งภายในอายุการใช้งาน
- หนึ่งภาพรถยนต์: รถแต่ละคันในแต่ละสีและมุมมอง นับครั้งเดียวต่อเดือน ไม่ว่าจะถูกส่ง สร้าง หรือต่ออายุบ่อยเพียงใด ในทุกขนาดและรูปแบบไฟล์
- ภาพรถยนต์ต่อเดือน: ช่องทางขอใบเสนอราคาจะพบรถหลากหลายคัน และแต่ละแพ็กเกจรวมจำนวนภาพต่อเดือนไว้: Free 100, Pro 2,500 และ Business 10,000 ส่วน Enterprise สามารถเจรจาได้ ภาพที่นับไปแล้วในเดือนนี้จะแสดงได้เสมอ และคำขอที่เกินโควตาจะตอบกลับ 402 ก่อนที่จะมีการนับใด ๆ ดังนั้นโปรดเลือกแพ็กเกจให้เหมาะกับจำนวนรถที่คุณเสนอราคา
สำหรับแพ็กเกจแบบชำระเงิน สัญญาอนุญาตครอบคลุมการใช้ภาพเรนเดอร์ภายในสิ่งที่ผลิตภัณฑ์ของคุณสร้างให้ผู้ใช้ รวมถึงใบเสนอราคาหรือรายงาน ตราบใดที่แพ็กเกจยังใช้งานอยู่ ดูรายละเอียดได้ในสัญญาอนุญาต
CLI, SDK และ 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? })และclient.createImageUrls(…)ตามที่กล่าวไว้ข้างต้น และclient.resolve(query)สำหรับรถที่ไม่มี VIN - MCP:
decode_vinและcreate_car_image_urlsอยู่ในชุดเครื่องมือหลัก ผู้ช่วยที่มีข้อมูลการเคลมอยู่ในบริบทจึงตอบคำขอ "แสดงรุ่นรถที่ทำประกันไว้" ได้จาก VIN ที่บันทึกไว้ ดูวิธีตั้งค่าได้ที่หน้า MCP
คำถามที่พบบ่อย
- ภาพนี้ใช้แทนภาพถ่ายของรถที่เอาประกันได้หรือไม่
- ไม่ใช่ ภาพนี้เป็นภาพเรนเดอร์แบบสตูดิโอของยี่ห้อ รุ่น และปีตามแคตตาล็อก ไม่ใช่ภาพถ่าย และไม่ได้แสดงรถคันใดคันหนึ่งโดยเฉพาะ ภาพนี้ช่วยให้ลูกค้าหรือผู้ประเมินความเสียหายเห็นว่าข้อมูลในระเบียนระบุประเภทรถได้ถูกต้อง ส่วนสภาพรถ ความเสียหาย รุ่นย่อย อุปกรณ์เสริม และการดัดแปลงต้องมาจากภาพถ่าย การตรวจสภาพ และข้อความที่ถอดรหัสได้ และควรระบุกำกับว่าภาพนี้เป็นเพียงภาพตัวอย่าง
- การใส่รูปภาพในใบเสนอราคาทุกฉบับมีค่าใช้จ่ายเท่าไร
- การถอดรหัส VIN ไม่มีค่าใช้จ่าย ภาพจะนับเป็นภาพรถหนึ่งภาพของเดือนเมื่อสร้าง signed URL ของภาพนั้นหรือเมื่อส่งไฟล์ภาพมายังเซิร์ฟเวอร์ของคุณ จากนั้นจะใช้งานได้บ่อยเท่าที่ต้องการ การโหลด signed URL ไม่มีค่าใช้จ่ายจนกว่าจะหมดอายุ URL แบบต่ออายุจะนับภาพหนึ่งครั้งในแต่ละเดือนถัดไปที่มีการเปิด และไม่นับเลยในเดือนที่ไม่มีใครเปิดดู
- ถอดรหัส VIN ได้ แต่ vehicle เป็น null แล้วควรทำอย่างไรต่อ
- ตัวถอดรหัสรู้จักรถคันนี้ แต่แค็ตตาล็อกไม่มีรายการสำหรับยี่ห้อ รุ่น และปีนั้น ซึ่งอาจเกิดขึ้นกับรถพ่วงและแชสซีรถเชิงพาณิชย์บางรุ่น ให้แสดงฟิลด์ที่ถอดรหัสได้โดยไม่มีรูปภาพ และอย่าแทนที่ด้วยรถที่คล้ายกันเด็ดขาด ลองค้นหาในแค็ตตาล็อกเผื่อการสะกดแตกต่างกัน และหากไม่มีจริง ๆ ให้ส่งคำขอบนบอร์ดคำขอสาธารณะ
- การถอดรหัส VIN ใช้ได้กับรถยนต์จากนอกตลาดสหรัฐฯ หรือไม่
- ตัวถอดรหัสใช้ข้อมูล vPIC ของ NHTSA ซึ่งครอบคลุมรถที่ผลิตสำหรับตลาดสหรัฐฯ ดังนั้น VIN ที่พิมพ์ถูกต้องจากตลาดอื่นอาจได้ผลเป็น 404 หรือถอดรหัสได้โดยไม่มีรุ่น ให้ค้นหารถคันนั้นด้วยยี่ห้อ รุ่น และปีผ่าน endpoint resolve ที่ไม่มีค่าใช้จ่ายแทน ทั้งนี้ตัวแค็ตตาล็อกเองครอบคลุมชื่อรุ่นของตลาดอื่นด้วย
- แฟ้มเคลมเก็บภาพไว้ได้นานเท่าใด
- ตราบที่แพ็กเกจของคุณยังใช้งานอยู่ สำหรับแพ็กเกจแบบชำระเงิน สิทธิ์การใช้งานครอบคลุมภาพเรนเดอร์ที่อยู่ในสิ่งที่ผลิตภัณฑ์ของคุณสร้างขึ้น รวมถึงใบเสนอราคาหรือรายงาน ภายใน 30 วันหลังแพ็กเกจสิ้นสุด สำเนาที่จัดเก็บไว้จะต้องถูกลบ หากต้องการเก็บภาพไว้ในบันทึกอย่างถาวร โปรดซื้อเป็น Image Pack นอกจากนี้ภาพเรนเดอร์อาจได้รับการปรับปรุงเมื่อเวลาผ่านไป ดังนั้นบันทึกที่ต้องคงสิ่งที่ลูกค้าเห็นไว้อย่างตรงทุกประการควรจัดเก็บไฟล์แทน URL