آیا این تصویر میتواند جایگزین عکسهای خودروی بیمهشده شود؟

خیر. این یک رندر استودیویی از برند، مدل و سال ثبتشده در کاتالوگ است، نه عکس، و هیچ خودروی مشخصی را نشان نمیدهد. به مشتری یا ارزیاب خسارت کمک میکند ببیند که سابقه، نوع درست خودرو را مشخص کرده است. وضعیت، آسیب، تریم، آپشنها و تغییرات از عکسها، بازرسیها و متن رمزگشاییشده به دست میآیند، و تصویر باید اعلام کند که صرفاً نمونهای نمایشی است.

افزودن تصویر به هر استعلام قیمت چقدر هزینه دارد؟

رمزگشایی VIN رایگان است. تصویر زمانی بهعنوان یک تصویر خودروی ماه محاسبه میشود که URL امضاشدهٔ آن ساخته شود یا بایتهایش به سرور شما تحویل داده شود، و پس از آن هر چند بار که لازم باشد ارائه میشود؛ بارگذاری URL امضاشده تا زمان انقضا رایگان است. URL تمدیدشونده، تصویر را در هر ماه بعدی که باز شود یک بار محاسبه میکند و در ماههایی که کسی آن را نمیبیند، هیچ.

VIN رمزگشایی میشود اما vehicle برابر null است. حالا چه کنم؟

رمزگشا خودرو را شناخت، اما کاتالوگ موردی برای آن سازنده، مدل و سال ندارد؛ این اتفاق برای تریلرها و برخی شاسیهای تجاری رخ میدهد. فیلدهای رمزگشاییشده را بدون تصویر نمایش دهید و هرگز خودروی مشابهی را جایگزین نکنید. در صورتی که املا متفاوت باشد، کاتالوگ را جستجو کنید و اگر واقعاً موجود نیست، آن را در تابلوی درخواستهای عمومی درخواست کنید.

آیا رمزگشایی VIN برای خودروهای خارج از بازار آمریکا هم کار میکند؟

رمزگشای VIN از دادههای vPIC سازمان NHTSA استفاده میکند که فقط خودروهای ساختهشده برای بازار آمریکا را پوشش میدهد. بنابراین VIN درستِ خودرویی از بازار دیگر ممکن است پاسخ 404 بدهد یا بدون مدل رمزگشایی شود. در این صورت، آن خودرو را با برند، مدل و سال از طریق endpoint رایگان resolve پیدا کنید. خود کاتالوگ نامهای تجاری بازارهای دیگر را هم پوشش میدهد.

پروندهٔ خسارت تا چه مدت میتواند تصویر را نگه دارد؟

تا زمانی که پلن شما فعال است. در پلن پولی، مجوز رندری را پوشش میدهد که درون خروجی محصول شما قرار دارد، از جمله استعلام قیمت یا گزارش؛ ظرف ۳۰ روز پس از پایان پلن، نسخههای ذخیرهشده حذف میشوند. برای نگهداشتن همیشگی تصاویر در سوابق، آنها را بهصورت Image Pack بخرید. رندرها ممکن است بهمرور بهبود یابند، بنابراین سابقهای که باید دقیقاً همان چیزی را که مشتری دیده نگه دارد، باید خود فایل را ذخیره کند نه URL را.

تصاویر خودرو برای پرونده‌های خسارت و استعلام‌های بیمه

راهنمای پیاده‌سازی که بر پایهٔ رفتار مستندشدهٔ API نوشته شده است؛ نام هیچ مشتری‌ای در آن نیامده است. منتشرشده در ۸ مهر ۱۴۰۵.

مشکل: در پرونده نام خودرویی آمده که هیچ‌کس آن را نمی‌بیند

فرم استعلام قیمت، سابقهٔ بیمه‌نامه و اولین اعلام خسارت همگی خودرو را به یک شکل مشخص می‌کنند: با VIN آن، که مشتری تایپ کرده یا از سند خودرو خوانده شده است. هر آنچه پس از آن کسی دربارهٔ خودرو می‌بیند متن است: یک سال، یک برند، یک مدل و شاید یک تریم. پرسیدن «آیا این خودروی شماست؟» در کنار یک خط متن، راه را برای «بله» گفتن به هر چیزی باز می‌کند.

تصویری از مدلی که VIN به آن رمزگشایی می‌شود، به مشتری و کارشناس خسارت امکان می‌دهد در یک نگاه بررسی کنند که پرونده نوع درستی از خودرو را ثبت کرده است. اما نمی‌تواند نشان دهد کدام خودرو: رندر یک تصویرسازی استودیویی از برند، مدل و سالی از کاتالوگ است و هیچ خودروی فیزیکی مشخصی را نشان نمی‌دهد. همین یک واقعیت، کل یکپارچه‌سازی زیر را شکل می‌دهد.

یکپارچه‌سازی چگونه است

رمزگشایی هنگام ثبت. فرایند استعلام قیمت یا سامانهٔ بیمه‌نامه VIN را یک بار و به‌صورت رایگان رمزگشایی می‌کند و شناسهٔ خودرو در کاتالوگ را همراه بیمه‌نامه ذخیره می‌کند. پرونده‌های خسارتی که برای این بیمه‌نامه باز می‌شوند همین شناسه را به ارث می‌برند.
یک نما در همه‌جا. front-3-4، یعنی زاویهٔ اصلی، در یک کادر در صفحهٔ استعلام قیمت، میز کار رسیدگی به خسارت، PDF استعلام و پورتال بیمه‌نامه، تا همهٔ صفحه‌ها مدل را به یک شکل نشان دهند.
URLهای امضاشده، هرگز خود کلید. مرورگرها و ابزارهای ساخت PDF، URLهای بدون کلیدی را بارگذاری می‌کنند که سرور شما می‌سازد.
کلمات برای آنچه تصویر نمی‌تواند بگوید. تریم، آپشن‌ها، رنگ ثبت‌شده، آسیب‌دیدگی و کارکرد به‌صورت متن و عکس باقی می‌مانند و روی تصویر ذکر می‌شود که نمونهٔ نمایشی است.

گام ۱: رمزگشایی رایگان VIN

GET /api/v1/vin/{vin} رایگان است و به کلیدی با دسترسی images:read نیاز دارد. پاسخ آن شامل فیلدهای رمزگشایی‌شده از داده‌های vPIC سازمان NHTSA است (سال، برند، مدل، تیپ، سری، کلاس بدنه، موتور و هر ویژگی دیگری که vPIC می‌شناسد) و، اگر خودرو در کاتالوگ باشد، یک شیء vehicle با شناسهٔ پایدار آن و یک image_path آماده.

VIN درج‌شده در استعلام بیمه را رمزگشایی کنید

curl --fail-with-body \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/vin/WP0AA2A96RS201834"

200 OK (خلاصه‌شده)

{
  "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 مدل ۲۰۲۴. از مشتری بخواهید تریم را تأیید کند، آن را همراه series و body_class به‌صورت متن نگه دارید و بگذارید تصویر فقط مدل را نشان دهد.

VINی که رقم کنترلی نادرست دارد همچنان رمزگشایی می‌شود، با valid: false و شرح مشکل در errors؛ suggested_vin نویسه‌ای را که vPIC نادرست می‌داند با ! علامت می‌زند، و همین را باید به کسی که در حال تایپ است نشان داد.
فرمی که فقط نویسه‌های ابتدایی را دارد می‌تواند VIN ناقص بفرستد: دست‌کم پنج نویسه، با * برای هر جایگاه نامعلوم و یک year اختیاری.
404 یعنی vPIC هیچ سابقه‌ای از این الگو ندارد. vPIC خودروهای ساخته‌شده برای بازار آمریکا را پوشش می‌دهد، بنابراین برای بازارهای دیگر از برند و مدل با POST /api/v1/images/resolve شروع کنید که آن هم رایگان است.

گام ۲: شناسه خودرو را روی بیمه‌نامه و پرونده خسارت نگه دارید

data.vehicle.id را به‌صورت یک رشتهٔ ساده روی بیمه‌نامه ذخیره کنید و آن را در هر خسارتی که برای آن ثبت می‌شود کپی کنید. این شناسه قطعی و دائمی است: یک خودرو در هر استقرار و پس از هر نسخهٔ کاتالوگ همان شناسه را دارد، بنابراین استفاده از آن به‌عنوان کلید خارجی امن است، و هر درخواست بعدی به‌جای نوشتن برند و مدل، vehicle=veh_78qtwrgh37bkr را می‌فرستد.

وقتی data.vehicle برابر null است، سازنده و مدل رمزگشایی‌شده در کاتالوگ وجود ندارند؛ مانند تریلرها و برخی شاسی‌های تجاری. همچنان می‌توانید فیلدهای رمزگشایی‌شده را نمایش دهید. آن‌ها را بدون تصویر نمایش دهید و هرگز خودروی مشابهی را به‌جای آن قرار ندهید.

مرحله ۳: یک نما در پرونده خسارت و PDF استعلام قیمت

صفحهٔ استعلام قیمت، میز کار رسیدگی به خسارت و پورتال بیمه‌نامه برنامه‌های مرورگری هستند، بنابراین سرور شما URLهای امضاشده را با POST /api/v1/image-urls صادر می‌کند: هر URL هنگام صدور، تصویر خود را به‌عنوان یک تصویر خودروی ماه شمارش می‌کند، تا ۵۰ عدد در هر فراخوانی، و تا زمان انقضا بارگذاری آن رایگان است. کادربندی تصویر را یک‌بار تعیین کنید و همان قالب را دوباره به کار ببرید: front-3-4 در کادری ۶۴۰×۴۰۰ با fit: "contain"، و trim با کمی padding تا یک کوپه و یک پیکاپ کادر را به یک شکل پر کنند. مدت اعتبار هر URL به محل نمایش آن بستگی دارد:

میز کار خسارت. URL را هنگام نمایش صفحه صادر کنید. مدت اعتبار پیش‌فرض ۱ ساعت یک جلسهٔ کاری را پوشش می‌دهد، و خسارتی که فردا دوباره باز شود URL تازه‌ای می‌گیرد.
PDF استعلام قیمت. وقتی PDF از HTML ساخته می‌شود، رندرکننده تصویر را یک بار بارگذاری و جاسازی می‌کند، بنابراین مدت اعتبار پیش‌فرض کاملاً کافی است و سرویس PDF هرگز کلید شما را در اختیار ندارد. format: "jpg" تصویر را روی پس‌زمینه سفید تخت می‌کند، که همان چیزی است که یک سند لازم دارد.
پورتال بیمه‌نامه و ایمیل تمدید. عمر این‌ها از هر مدت اعتباری بیشتر است، پس URL را با renew: true و ttl_seconds: 604800 (۷ روز) صادر کنید. URL همچنان کار می‌کند، هر تمدید تصویر را یک بار در ماهی که در آن انجام می‌شود حساب می‌کند و اگر تصویر در آن ماه قبلاً حساب شده باشد چیزی اضافه نمی‌شود، و renew_days: 365، که بیشترین مقدار مجاز است، یک دورهٔ بیمه‌نامهٔ یک‌ساله را پوشش می‌دهد.

برای کلیدی که URLها را می‌سازد، در داشبورد فهرستی از originهای مجاز تعیین کنید: URLی که از سایت دیگری بارگذاری شود با 403 و origin_not_allowed پاسخ می‌دهد، در حالی که کلاینت‌های ایمیل و نمایشگرهای PDF که Referer ارسال نمی‌کنند، همچنان آن را بارگذاری می‌کنند. لغو کلید، همهٔ URLهایی را که ساخته است از کار می‌اندازد.

ثبت اولیه، میز کار، PDF و پورتال، با TypeScript SDK

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` }
  );
}

گام ۴: آن را به‌عنوان مدل برچسب بزنید، هرگز به‌عنوان خودروی بیمه‌شده

برچسب را همان‌جایی بگذارید که تصویر هست، نه فقط در پانویس: در متن جایگزین (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، جست‌وجو در کاتالوگ، و هر بار بارگذاری یک URL امضاشده در طول اعتبار آن.
یک تصویر خودرو: هر خودرو در هر رنگ و نما، که هر چند بار هم تحویل، صادر یا تمدید شود، در هر اندازه و قالبی، ماهی یک‌بار شمرده می‌شود.
تصاویر خودرو در ماه: یک قیف استعلام قیمت با خودروهای متنوع زیادی سروکار دارد و هر طرح تعداد مشخصی از آن‌ها را در ماه شامل می‌شود: رایگان ۱۰۰، Pro ۲٬۵۰۰ و Business ۱۰٬۰۰۰؛ Enterprise با مذاکره تعیین می‌شود. تصویری که این ماه شمرده شده همیشه ارائه می‌شود، و درخواستی که از سهمیه فراتر رود پیش از هر شمارشی با 402 پاسخ داده می‌شود؛ پس طرح را متناسب با خودروهایی که برایشان قیمت ارائه می‌دهید انتخاب کنید.

در طرح پولی، تا زمانی که طرح فعال است، مجوز شامل رندری می‌شود که درون خروجی محصول شما برای کاربرانش قرار می‌گیرد، از جمله استعلام قیمت یا گزارش؛ جزئیات در مجوز آمده است.

CLI، SDK و MCP

npx @meterapp/car-image

# 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 رایگان است. تصویر زمانی به‌عنوان یک تصویر خودروی ماه محاسبه می‌شود که URL امضاشدهٔ آن ساخته شود یا بایت‌هایش به سرور شما تحویل داده شود، و پس از آن هر چند بار که لازم باشد ارائه می‌شود؛ بارگذاری URL امضاشده تا زمان انقضا رایگان است. URL تمدیدشونده، تصویر را در هر ماه بعدی که باز شود یک بار محاسبه می‌کند و در ماه‌هایی که کسی آن را نمی‌بیند، هیچ.
VIN رمزگشایی می‌شود اما vehicle برابر null است. حالا چه کنم؟: رمزگشا خودرو را شناخت، اما کاتالوگ موردی برای آن سازنده، مدل و سال ندارد؛ این اتفاق برای تریلرها و برخی شاسی‌های تجاری رخ می‌دهد. فیلدهای رمزگشایی‌شده را بدون تصویر نمایش دهید و هرگز خودروی مشابهی را جایگزین نکنید. در صورتی که املا متفاوت باشد، کاتالوگ را جستجو کنید و اگر واقعاً موجود نیست، آن را در تابلوی درخواست‌های عمومی درخواست کنید.
آیا رمزگشایی VIN برای خودروهای خارج از بازار آمریکا هم کار می‌کند؟: رمزگشای VIN از داده‌های vPIC سازمان NHTSA استفاده می‌کند که فقط خودروهای ساخته‌شده برای بازار آمریکا را پوشش می‌دهد. بنابراین VIN درستِ خودرویی از بازار دیگر ممکن است پاسخ 404 بدهد یا بدون مدل رمزگشایی شود. در این صورت، آن خودرو را با برند، مدل و سال از طریق endpoint رایگان resolve پیدا کنید. خود کاتالوگ نام‌های تجاری بازارهای دیگر را هم پوشش می‌دهد.
پروندهٔ خسارت تا چه مدت می‌تواند تصویر را نگه دارد؟: تا زمانی که پلن شما فعال است. در پلن پولی، مجوز رندری را پوشش می‌دهد که درون خروجی محصول شما قرار دارد، از جمله استعلام قیمت یا گزارش؛ ظرف ۳۰ روز پس از پایان پلن، نسخه‌های ذخیره‌شده حذف می‌شوند. برای نگه‌داشتن همیشگی تصاویر در سوابق، آن‌ها را به‌صورت Image Pack بخرید. رندرها ممکن است به‌مرور بهبود یابند، بنابراین سابقه‌ای که باید دقیقاً همان چیزی را که مشتری دیده نگه دارد، باید خود فایل را ذخیره کند نه URL را.

ادامه مطلب

داستان مشتری · نرم‌افزار نمایندگی خودروچگونه در نرم‌افزار نمایندگی، یک VIN یا فهرست موجودی را به عکسی برای هر خودرو تبدیل کنیمیک رکورد موجودی مدت‌ها پیش از داشتن عکس، VIN و شماره موجودی دارد. ابزارهای نمایندگی VIN را رایگان رمزگشایی می‌کنند، شناسه خودرو را روی رکورد نگه می‌دارند و از طریق signed URLها یک نمای یکسان را در CRM نمایش می‌دهند.