كم تبلغ تكلفة إضافة صورة إلى كل سجل في المخزون؟

فك ترميز VIN مجاني. أول صورة لمركبة وزاوية ولون طلاء معيّن تكلّف رصيدًا واحدًا، وتُخزَّن مؤقتًا للجميع بعد ذلك؛ وإعادة التحقق منها باستخدام If-None-Match مجانية. يكلّف عنوان URL الموقّع رصيدًا واحدًا عند إنشائه، ومع renew: true رصيدًا إضافيًا عن كل أسبوع لاحق يُفتح فيه فعلًا. مجموعة المعارض التي لديها بضعة آلاف من الوحدات في المخزون تنفق بضعة آلاف من الأرصدة مرة واحدة، ثم لا شيء تقريبًا.

يُفك ترميز VIN لكن قيمة vehicle هي null. ماذا بعد؟

تعرّفت أداة فك الترميز على العلامة والطراز والسنة، لكن الكتالوج لا يحتوي على إدخال لهذه التركيبة: مقطورة، أو بعض هياكل المركبات التجارية، أو اسم طراز لم تسجّله المصادر بعد. اعرضوا الحقول التي فُكّ ترميزها، وابحثوا في الكتالوج باستخدام GET /api/v1/vehicles?q= تحسبًا لاختلاف التهجئة، واطلبوا المركبة عبر لوحة الطلبات؛ إذ يضيف POST /api/v1/requests تصويتًا إلى الطلب المفتوح بدلًا من تكراره.

هل يغطي فك ترميز VIN السيارات المستوردة والمركبات التي لم تُبع قط في الولايات المتحدة؟

تعتمد أداة فك الترميز على بيانات vPIC من NHTSA، لذا يُفك ترميز رقم VIN بالكامل إذا كانت الشركة المصنّعة تسجّل لدى NHTSA. أما المركبة التي لم تُعتمد قط للسوق الأمريكية فغالبًا ما يُفك ترميزها إلى شركة مصنّعة وسنة دون طراز، وبعضها لا يُفك ترميزه إطلاقًا. لهذا المخزون، حدّدوا المركبة من وثيقة التسجيل بدلًا من ذلك: فالكتالوج نفسه عالمي، يبدأ من 1990، ويضم طرازات السوق اليابانية المحلية مثل Toyota Voxy.

هل تُظهر الصورة الفئة المسجّلة في السجل؟

لا. يعتمد الكتالوج على الشركة المصنّعة والطراز والسنة، لذا تظهر سيارة كوبيه EX-V6 وسيارة سيدان LX كسيارة Accord 2003 نفسها. احتفظوا بقيمتي trim وbody_class الناتجتين عن فك ترميز VIN كنص بجانب الصورة، ولا تصفوا الصورة المولَّدة أبدًا بأنها السيارة المحددة نفسها.

هل يمكن لموقع الوكيل استخدام عناوين URL نفسها المستخدمة في CRM؟

أصدروها من مفتاح تتضمن قائمة المصادر المسموح بها فيه هذا الموقع، وعندها يُرجع أي URL يحمّله متصفح من موقع آخر الخطأ 403 origin_not_allowed. أما الطلبات التي لا تحمل ترويسة Referer، مثل برامج البريد الإلكتروني، فتمرّ. يمكن لنظام CRM والموقع مشاركة مفتاح واحد ومجموعة واحدة من عناوين URL، أو استخدام مفتاح لكل منهما بحيث يمكن إلغاء أيٍّ منهما وحده.

صور السيارات من رقم VIN لبرمجيات وكلاء السيارات

المشكلة: يحتوي السجل على رقم VIN قبل أشهر من وجود صورة

يبدأ سجل المخزون في نظام CRM أو ERP أو نظام إدارة المعارض (DMS) برقم VIN ورقم مخزون وسعر. أما الصورة فتأتي عندما يأتي مصوّر المعرض، وبعض الوحدات لا تحصل عليها أبدًا: سيارة قيد الشحن، أو سيارة مستبدلة لا تزال قيد التجديد، أو سيارة مستوردة لا يطابق اسم طرازها أي شيء في موجز الصور لدى نظام DMS، أو سيارة من التسعينيات لم يرخّص أحد صورة صحفية لها. وكل شاشة تعرض ذلك السجل، سواء قائمة مندوب المبيعات أو تقييم المشتري أو عرض السعر للعميل، تعرض بدلًا منها عنصرًا نائبًا رماديًا.

تملأ أدوات الوكلاء والاستيراد العاملة على الـ API هذه الصورة البديلة مما يحتويه السجل بالفعل. إذا كان فيه رقم VIN، فالصورة على بُعد فك ترميز مجاني واحد. وإذا لم يكن فيه سوى سطر في قائمة المخزون، فالتحديد بالنص الحر يوصلك إليها. وفي الحالتين ينتهي الأمر بأن يحمل السجل معرّف مركبة ثابتًا، وتعرض كل شاشة السيارة نفسها بالطريقة نفسها.

كيف يبدو التكامل مع أنظمة معارض السيارات

فك الترميز عند الإدخال. يُفك ترميز رقم VIN مرة واحدة عند إنشاء السجل، ويُخزَّن معرّف المركبة في الكتالوج بجانبه. ولا شيء في المراحل اللاحقة يكتب اسم شركة مصنّعة أو طراز.
زاوية للقائمة وأخرى لصفحة التفاصيل. زاوية side جانبية مستقيمة في إطار عريض لقوائم المخزون، وfront-3-4 لصفحة التفاصيل وعرض السعر.
سنوات تمتد بعيدًا. يمتد المخزون المستورد والمستعمل إلى تسعينيات القرن الماضي، ويُعرض بالجودة نفسها التي تُعرض بها الوافدات الجديدة: يغطي الكتالوج من 1990 حتى سنة الطراز الحالية، بما في ذلك الطرازات المخصصة للسوق اليابانية المحلية.
عناوين URL موقّعة داخل التطبيق. نظام CRM يعمل في المتصفح، لذا يحمّل عناوين URL موقّعة لا تتطلب مفتاحًا يصدرها الخادم، حتى خمسين في كل استدعاء، مع تجديدها للسجلات التي تبقى أكثر من أسبوع.

الخطوة 1: فك ترميز رقم VIN مجانًا

لا يكلّف GET /api/v1/vin/{vin} شيئًا ولا يتطلب سوى مفتاح API. يُرجع السنة والشركة المصنّعة والطراز والفئة ونوع الهيكل والمحرك بعد فك الترميز، وكل سمة أخرى تعرفها بيانات vPIC من NHTSA، وعندما تكون المركبة موجودة في الكتالوج، يُرجع أيضًا كائن vehicle بمعرّفها الثابت وimage_path جاهز. وتعمل أرقام VIN الجزئية أيضًا: خمسة أحرف على الأقل، مع * لكل موضع مجهول، بالإضافة إلى تلميح year اختياري.

فك الترميز

curl -s -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/vin/1HGCM82633A004352"

200 OK (مختصر)

{
  "data": {
    "vin": "1HGCM82633A004352",
    "valid": true,
    "year": 2003,
    "make": "Honda",
    "model": "Accord",
    "trim": "EX-V6",
    "body_class": "Coupe",
    "vehicle": {
      "id": "veh_3qfyk22gfhsx3",
      "make": "Honda",
      "model": "Accord",
      "year": 2003,
      "image_path": "/api/v1/images/car?vehicle=veh_3qfyk22gfhsx3"
    }
  },
  "request_id": "req_01j9x…"
}

يعتمد الكتالوج على الشركة المصنّعة والطراز والسنة

يعرف رقم VIN أن هذه سيارة كوبيه EX-V6؛ لكن الكتالوج لا يفصل بين الفئات وأنواع الهياكل، لذا فإن الصورة المعروضة هي Accord 2003. احتفظوا بـ trim وbody_class كنص في السجل واعرضوهما بجانب الصورة، بدلًا من الادعاء بأن الصورة تُظهرهما. ورقم VIN الذي يحتوي على خطأ في رقم التحقق يُفك ترميزه مع ذلك، مع valid: false وإدراج الخطأ، فلا يصبح خطأ الكتابة في كشف المخزون طريقًا مسدودًا.

الخطوة 1ب: عندما لا يتوفر لديكم سوى سطر في قائمة المخزون

غالبًا ما تصل بيانات المخزون المستورد في جدول بيانات: سنة، وشركة مصنّعة، واسم طراز بأي تهجئة استخدمتها دار المزاد، ورمز درجة أو فئة تجهيز. نقطة النهاية POST /api/v1/images/resolve مجانية وحتمية النتائج: فهي تستخرج كلمات السنة واللون والزاوية من العبارة، وتبحث في الكتالوج بما تبقى، ثم تُرجع معاملات دقيقة مع درجة ثقة يمكنكم الاعتماد عليها.

مطابقة سطر من كشف المخزون

curl -s -X POST https://carimage.dev/api/v1/images/resolve \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "2019 toyota voxy zs side"}'

200 OK (مختصر)

{
  "data": {
    "params": {
      "vehicle_id": "veh_9w0nvw7jphp6r",
      "make": "toyota",
      "model": "voxy",
      "year": 2019,
      "view": "side",
      "color": "silver"
    },
    "display": {
      "make_name": "TOYOTA",
      "model_name": "VOXY"
    },
    "confidence": "low",
    "image_path": "/api/v1/images/car?make=toyota&model=voxy&year=2019&view=side&color=silver"
  },
  "request_id": "req_01j9x…"
}

المركبة صحيحة (Toyota Voxy موديل 2019) لكن مستوى الثقة low، لأن "ZS" فئة لا يعرفها الكتالوج فاضطرت المطابقة إلى تجاوزها. في الاستيراد الدفعي، اعتبر high منتهيًا، واعرض medium وlow على شخص مع قائمة candidates. وعندما تحتوي القائمة بالفعل على السنة والشركة المصنّعة في عمودين مستقلين، أرسلهما في الحقلين year وmake واترك الطراز وحده في query؛ فتصبح المطابقة أدق بكثير. العبارة التي لا تتضمن أي كلمات تخص المركبات تُرجع 400، والشركة المصنّعة دون طراز مطابق تُرجع 404 يسرد سنوات تلك الشركة لتطلب الطراز.

الخطوة 2: الاحتفاظ بمعرّف المركبة في السجل

أيًا كان المسار الذي أوصلكم إلى هنا، خزّنوا vehicle.id (أو params.vehicle_id) في سجل المخزون كعمود نصي عادي. فهو حتمي ودائم: للمركبة نفسها المعرّف نفسه في كل عملية نشر وبعد كل إصدار للكتالوج، لذا يمكن استخدامه بأمان كمفتاح خارجي. ومن ذلك الحين يصبح كل طلب صورة vehicle=veh_…، وهو ما لا يمكن أن يُكتب خطأً، ولن يؤدي تغيير الشركة المصنّعة لاسم علامة تجارية أو إعادة تصنيفها من قِبل أحد المصادر إلى تعطيل أي عنوان URL مخزّن.

الخطوة 3: زاوية للقائمة وأخرى لصفحة التفاصيل

قوائم المخزون عريضة وقصيرة، لذا فإن المنظر الجانبي المستقيم في إطار بنسبة 2:1 هو الخيار المعتاد: كل مركبة تتجه في الاتجاه نفسه وتستقر على خط الأساس نفسه. يقصّ trim=1&padding=6 الصورة حول السيارة قبل ملاءمتها، فتملأ Hilux وYaris الصف بالطريقة نفسها؛ ويحافظ fit=contain على اللوحة بأبعاد 640×320 بالضبط مع هوامش شفافة. وتستخدم صفحة التفاصيل front-3-4 بعرض 1024، ويتشاركان ذاكرة تخزين مؤقت واحدة: الطلاء الذي لم تحدده يكون فضيًا في كليهما.

صورة القائمة لسجل واحد

curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_3qfyk22gfhsx3&view=side&w=640&h=320&fit=contain&trim=1&padding=6&format=webp" \
  -o stock-4471.webp

الخطوة 4: عرضها في نظام CRM عبر عناوين URL موقّعة

يعمل نظام CRM في المتصفح، ولا يجوز أبدًا أن يحتفظ المتصفح بمفتاح API. عندما تعرض شاشةٌ صفحةً من المخزون، يُصدر الخادم URL موقّعًا واحدًا لكل سجل عبر POST /api/v1/image-urls (حتى خمسين في كل استدعاء، بوحدة رصيد واحدة لكلٍّ منها)، وتحمّلها الصفحة كأي صورة. هناك إعدادان مهمّان لسجل يبقى في المخزون لأشهر:

ttl_seconds: 604800 مع renew: true: يظل الرابط يعمل بعد انتهاء مدة TTL البالغة سبعة أيام، وكل أسبوع إضافي يفتح فيه أحدٌ السجلَّ فعلًا يكلّف رصيدًا واحدًا إضافيًا. أما الأسابيع التي لا ينظر فيها أحد إلى السيارة فلا تكلّف شيئًا.
مفتاح Idempotency-Key لكل صفحة من المزامنة: الطلب المُعاد يُرجع الاستجابة الأولى نفسها ولا يُصدر أي شيء مرتين.

قيّدوا مفتاح الإنشاء بنطاق نظام CRM من لوحة التحكم، وعندها يُرجع أي URL يتسرّب إلى موقع آخر الرمز 403. يؤدي إلغاء المفتاح إلى إبطال كل عناوين URL التي أنشأها. وإذا نفد الرصيد يومًا، يُرجع التجديد 402 ويعود URL نفسه إلى العمل فور وصول الأرصدة؛ وتُزيل إعادة الشحن التلقائية هذا الاحتمال. تجدون دورة الحياة كاملة في توثيق عناوين URL الموقّعة.

الاستلام وقائمة المخزون باستخدام TypeScript SDK

import { CarImageClient } from "@meterapp/car-image-sdk";

const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });

// On intake: VIN in, vehicle id on the record. Free.
const { data: decoded } = await client.decodeVin(stock.vin);
if (decoded.vehicle) {
  stock.vehicleId = decoded.vehicle.id; // veh_…, permanent; the record never spells a car again
  stock.trim = decoded.trim;            // shown next to the image, never claimed by it
}

// When the CRM draws the stock list: one signed URL per record, up to fifty per call.
// The browser loads them; the key never leaves the server.
const { data: urls } = await client.createImageUrls(
  page.map((row) => ({
    vehicle: row.vehicleId, view: "side",
    width: 640, height: 320, fit: "contain", trim: true, padding: 6, format: "auto",
  })),
  { ttlSeconds: 604_800, renew: true, renewDays: 365, idempotencyKey: `stock-list:${syncRunId}:${pageIndex}` }
);

CLI وSDK وMCP

npx @meterapp/car-image

# decode for free; the output names the vehicle id and a ready-to-run image command
npx @meterapp/car-image vin 1HGCM82633A004352
npx @meterapp/car-image vin 1HGCM82633A004352 --json | jq -r .data.vehicle.id

# a partial VIN from a faded door sticker: at least five characters, * for each unknown position
npx @meterapp/car-image vin "1HGCM826*3A" --year 2003

# the list image for one record
npx @meterapp/car-image get --vehicle veh_3qfyk22gfhsx3 --view side --width 640 --height 320 --fit contain --trim --padding 6 --format webp --out stock-4471.webp

SDK: client.decodeVin(vin, { year? }) وclient.resolve(query) وclient.getImage({ vehicle, … }) وclient.createImageUrls(…)، كما في الأعلى.
MCP: الأدوات decode_vin وresolve_vehicle وget_car_image وcreate_car_image_urls ضمن مجموعة الأدوات الأساسية، لذا يستطيع المساعد الذي يتوفر نظام المخزون في سياقه أن يجيب عن طلب "صورة للوحدة 4471" انطلاقًا من رقم VIN المسجّل. خطوات الإعداد في صفحة MCP، وحقول أداة فك الترميز وأخطاؤها في توثيق VIN.

الأسئلة الشائعة

كم تبلغ تكلفة إضافة صورة إلى كل سجل في المخزون؟: فك ترميز VIN مجاني. أول صورة لمركبة وزاوية ولون طلاء معيّن تكلّف رصيدًا واحدًا، وتُخزَّن مؤقتًا للجميع بعد ذلك؛ وإعادة التحقق منها باستخدام If-None-Match مجانية. يكلّف عنوان URL الموقّع رصيدًا واحدًا عند إنشائه، ومع renew: true رصيدًا إضافيًا عن كل أسبوع لاحق يُفتح فيه فعلًا. مجموعة المعارض التي لديها بضعة آلاف من الوحدات في المخزون تنفق بضعة آلاف من الأرصدة مرة واحدة، ثم لا شيء تقريبًا.
يُفك ترميز VIN لكن قيمة vehicle هي null. ماذا بعد؟: تعرّفت أداة فك الترميز على العلامة والطراز والسنة، لكن الكتالوج لا يحتوي على إدخال لهذه التركيبة: مقطورة، أو بعض هياكل المركبات التجارية، أو اسم طراز لم تسجّله المصادر بعد. اعرضوا الحقول التي فُكّ ترميزها، وابحثوا في الكتالوج باستخدام GET /api/v1/vehicles?q= تحسبًا لاختلاف التهجئة، واطلبوا المركبة عبر لوحة الطلبات؛ إذ يضيف POST /api/v1/requests تصويتًا إلى الطلب المفتوح بدلًا من تكراره.
هل يغطي فك ترميز VIN السيارات المستوردة والمركبات التي لم تُبع قط في الولايات المتحدة؟: تعتمد أداة فك الترميز على بيانات vPIC من NHTSA، لذا يُفك ترميز رقم VIN بالكامل إذا كانت الشركة المصنّعة تسجّل لدى NHTSA. أما المركبة التي لم تُعتمد قط للسوق الأمريكية فغالبًا ما يُفك ترميزها إلى شركة مصنّعة وسنة دون طراز، وبعضها لا يُفك ترميزه إطلاقًا. لهذا المخزون، حدّدوا المركبة من وثيقة التسجيل بدلًا من ذلك: فالكتالوج نفسه عالمي، يبدأ من 1990، ويضم طرازات السوق اليابانية المحلية مثل Toyota Voxy.
هل تُظهر الصورة الفئة المسجّلة في السجل؟: لا. يعتمد الكتالوج على الشركة المصنّعة والطراز والسنة، لذا تظهر سيارة كوبيه EX-V6 وسيارة سيدان LX كسيارة Accord 2003 نفسها. احتفظوا بقيمتي trim وbody_class الناتجتين عن فك ترميز VIN كنص بجانب الصورة، ولا تصفوا الصورة المولَّدة أبدًا بأنها السيارة المحددة نفسها.
هل يمكن لموقع الوكيل استخدام عناوين URL نفسها المستخدمة في CRM؟: أصدروها من مفتاح تتضمن قائمة المصادر المسموح بها فيه هذا الموقع، وعندها يُرجع أي URL يحمّله متصفح من موقع آخر الخطأ 403 origin_not_allowed. أما الطلبات التي لا تحمل ترويسة Referer، مثل برامج البريد الإلكتروني، فتمرّ. يمكن لنظام CRM والموقع مشاركة مفتاح واحد ومجموعة واحدة من عناوين URL، أو استخدام مفتاح لكل منهما بحيث يمكن إلغاء أيٍّ منهما وحده.