مقدمة: لماذا تحتاج الشركات العربية إلى واجهات برمجة تطبيقات بيانات السيارات؟

يشهد سوق السيارات في العالم العربي تحولاً جذرياً. من منصات حراج في السعودية إلى dubizzle في الإمارات وأوليكس في مصر، تتسابق المنصات الرقمية لتقديم تجربة شراء أكثر شفافية. في قلب هذا التحول تقع واجهات برمجة تطبيقات بيانات السيارات (Car Data APIs) — أدوات برمجية تتيح لأي مطوّر أو شركة الوصول الفوري إلى بيانات المركبات عبر رقم الشاصي (VIN).

سواء كنت تبني تطبيق معرفة مواصفات السيارة من رقم الشاصي مجاناً، أو تطوّر نظام إدارة معارض، أو تريد دمج خدمة فحص VIN مجاني في منصتك — فهذا الدليل يشرح كل ما تحتاجه عن واجهات برمجة تطبيقات بيانات السيارات وكيفية الاستفادة منها في السوق العربي.

ما هي واجهة برمجة تطبيقات بيانات السيارات وكيف تعمل؟

واجهة برمجة التطبيقات (API) هي بروتوكول يسمح لبرنامج بالتواصل مع برنامج آخر تلقائياً. في سياق بيانات السيارات، تعمل الـ API كوسيط بين تطبيقك وقاعدة بيانات ضخمة تحتوي على معلومات ملايين المركبات حول العالم. ترسل طلباً يحتوي على رقم الشاصي (VIN) المكون من 17 خانة، فتتلقى استجابة بصيغة JSON تحتوي على كل المعلومات المتاحة — من المواصفات وسنة الصنع إلى تاريخ الحوادث والاستدعاءات.

ما الذي يميز China Vehicle History API؟

بينما تركز معظم واجهات برمجة التطبيقات مثل Vincario وCarfax وVinAudit على السيارات الأمريكية والأوروبية، تتخصص China Vehicle History API في تاريخ السيارات الصينية: سجلات الحوادث والتأمين من PICC وPing An وCPIC، وتاريخ الصيانة من الوكلاء المعتمدين — بيانات لا تتوفر في أي API آخر.

هل الـ VIN هو رقم الشاصي؟

نعم، VIN (Vehicle Identification Number) هو نفسه رقم الشاصي أو رقم الهيكل. رقم فريد مكون من 17 خانة يُعطى لكل مركبة عند التصنيع ولا يتكرر بين مركبتين. يحتوي على معلومات مشفرة عن بلد التصنيع والشركة المصنعة والطراز وسنة الإنتاج ومواصفات المحرك.

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

البداية السريعة — أول طلب خلال 5 دقائق

الـ API مبني على بروتوكول REST القياسي. جميع الطلبات والاستجابات بصيغة JSON. المصادقة عبر مفتاح API في ترويسة Authorization.

العنوان الأساسي والمصادقة

Base URL: https://api.chinavehiclehistory.com/v1
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

يُمنح مفتاح API بعد التسجيل في البرنامج الشريك. للحصول على المفتاح تواصل معنا عبر WhatsApp أو Telegram — الوصول متاح لعملاء B2B (معارض السيارات، شركات الاستيراد، مطوّرو التطبيقات).

كيف اعرف تفاصيل السيارة من رقم الشاصي؟

لمعرفة تفاصيل أي سيارة من رقم الشاصي برمجياً، استخدم نقطة نهاية فك التشفير (Decode Endpoint). إليك أول طلب باستخدام cURL:

curl -X POST https://api.chinavehiclehistory.com/v1/decode \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vin": "LGXCE6CB9P0123456"}'

نموذج الاستجابة

{
  "success": true,
  "data": {
    "vin": "LGXCE6CB9P0123456",
    "brand": "BYD",
    "model": "Song Plus DM-i",
    "year": 2023,
    "plant": "Shenzhen",
    "engine": "BYD476ZQB",
    "engine_volume": "1.5L",
    "fuel_type": "PHEV",
    "transmission": "E-CVT",
    "body_type": "SUV",
    "color": "White",
    "power_kw": 81,
    "battery_capacity_kwh": 18.3,
    "curb_weight_kg": 1780,
    "made_in": "China"
  }
}

الأمثلة ليست بيانات حقيقية

جميع أرقام VIN وعناوين URL والاستجابات في هذا الدليل أمثلة توضيحية لعرض بنية الـ API. العنوان الأساسي الفعلي والمفاتيح وصيغة الاستجابات تُقدَّم عند الانضمام للبرنامج الشريك.

دليل نقاط النهاية (Endpoints)

يوفر الـ API ست نقاط نهاية تغطي دورة فحص السيارة الصينية بالكامل: من فك تشفير VIN إلى الحصول على تاريخ الصيانة الكامل.

1. POST /v1/decode — فك تشفير VIN (Basic)

يُرجع المواصفات الأساسية للسيارة من المصنع: العلامة التجارية، الطراز، سنة الصنع، المحرك، ناقل الحركة، نوع الهيكل، الوزن، ونوع الوقود. طلب متزامن — الاستجابة فورية.

// الطلب
POST /v1/decode
{
  "vin": "LGXCE6CB9P0123456",
  "email": "partner@example.com",
  "plan": "basic"
}

// الاستجابة
{
  "success": true,
  "data": {
    "brand": "BYD",
    "model": "Song Plus DM-i",
    "series": "Song Plus",
    "year": 2023,
    "price_cny": 159800,
    "engine": "BYD476ZQB 1.5L",
    "power_kw": 81,
    "transmission": "E-CVT",
    "fuel_type": "PHEV",
    "body_type": "SUV",
    "dimensions": "4705x1890x1680mm",
    "curb_weight_kg": 1780,
    "fuel_consumption_l100km": 4.4,
    "plant": "Shenzhen"
  },
  "fromCache": false
}

2. POST /v1/history — التاريخ الكامل (Standard)

يُرجع المواصفات + تاريخ التأمين من القواعد الصينية: سجلات الحوادث، المطالبات التأمينية (PICC، Ping An، CPIC)، تاريخ المسافة المقطوعة، عدد الملاك، وحالة السرقة والرهن. طلب متزامن.

// الطلب
POST /v1/history
{
  "vin": "LGXCE6CB9P0123456",
  "email": "partner@example.com",
  "plan": "standard"
}

// الاستجابة (مقتطف)
{
  "success": true,
  "data": {
    "vehicleInfo": { ... },
    "insuranceInfo": {
      "total_claims": 2,
      "claims": [
        {
          "date": "2024-03-15",
          "type": "collision",
          "amount_cny": 8500,
          "description": "Rear bumper damage",
          "insurer": "PICC"
        },
        {
          "date": "2024-09-22",
          "type": "minor_scratch",
          "amount_cny": 1200,
          "description": "Left door scratch",
          "insurer": "Ping An"
        }
      ],
      "mileage_records": [
        {"date": "2023-06-01", "km": 5200},
        {"date": "2024-01-15", "km": 18400},
        {"date": "2024-09-22", "km": 34100}
      ],
      "owners_count": 1,
      "theft_status": "clear",
      "lien_status": "clear"
    }
  }
}

3. POST /v1/premium — التقرير الكامل مع تاريخ الصيانة (Premium، غير متزامن)

يتضمن كل ما في Standard + سجلات الصيانة من الوكلاء المعتمدين ومراكز الخدمة المستقلة، وحالة حملات الاستدعاء. طلب غير متزامن — يُرجع الـ API معرّف الطلب (order_id) للتحقق من الحالة واسترجاع النتيجة. يدعم webhook عبر (callback_url) للإشعار عند جاهزية التقرير.

// الطلب
POST /v1/premium
{
  "vin": "LGXCE6CB9P0123456",
  "email": "partner@example.com",
  "plan": "premium",
  "engine": "BYD476ZQB",
  "callback_url": "https://yoursite.com/webhook/report-ready"
}

// الاستجابة
{
  "success": true,
  "order_id": "ord_abc123def456",
  "status": "processing",
  "message": "Report is being generated. Poll /v1/premium/status/ord_abc123def456 or wait for webhook."
}

بعض العلامات تتطلب رقم المحرك

للحصول على تاريخ الصيانة لبعض العلامات (Volkswagen، Toyota، BMW — الاستيراد الموازي)، يجب إرسال معامل engine. استخدم نقطة النهاية /v1/maintenance/brands للتحقق من متطلبات كل علامة تجارية.

4. GET /v1/premium/status/{orderId} — حالة التقرير المتميز

يتحقق من حالة معالجة التقرير المتميز غير المتزامن. يُرجع الحالة (pending، processing، completed، failed) ونسبة الإنجاز.

// الطلب
GET /v1/premium/status/ord_abc123def456?email=partner@example.com

// الاستجابة
{
  "success": true,
  "status": "completed",
  "progress": 100
}

5. GET /v1/premium/results/{orderId} — نتيجة التقرير المتميز

يسترجع التقرير المتميز الجاهز بعد اكتمال المعالجة. يُرجع vehicleInfo وinsuranceInfo ومصفوفة maintenanceRecords مع سجلات من الوكلاء المعتمدين.

// الطلب
GET /v1/premium/results/ord_abc123def456?email=partner@example.com

// الاستجابة (مقتطف)
{
  "success": true,
  "data": {
    "vehicleInfo": { ... },
    "insuranceInfo": { ... },
    "maintenanceRecords": [
      {
        "date": "2023-08-10",
        "mileage_km": 10200,
        "service_type": "Scheduled maintenance",
        "items": ["Engine oil change", "Oil filter", "Air filter"],
        "dealer": "BYD Shenzhen Authorized Service",
        "oem_parts": true
      },
      {
        "date": "2024-05-20",
        "mileage_km": 25600,
        "service_type": "Scheduled maintenance",
        "items": ["Brake fluid replacement", "Cabin air filter", "Battery health check"],
        "dealer": "BYD Guangzhou Service Center",
        "oem_parts": true
      }
    ]
  }
}

6. POST /v1/lookup/plate — البحث عن VIN برقم اللوحة الصينية

يجد رقم VIN للسيارة من رقم اللوحة الصينية. مفيد عندما يتوفر لدى العميل رقم اللوحة فقط دون رقم الشاصي.

// الطلب
POST /v1/lookup/plate
{
  "license_plate": "京A12345",
  "vehicle_type": "02"
}

// الاستجابة
{
  "success": true,
  "vin": "LGXCE6CB9P0123456"
}

كيفية التحقق من مواصفات السيارة من خلال رقم الشاسيه

التحقق من المواصفات يتجاوز فك تشفير الـ VIN. عبر الـ API، يمكنك مقارنة المواصفات المُعلن عنها من البائع مع المواصفات الفعلية من المصنع — أمر بالغ الأهمية في السوق العربي حيث قد يُعلن بائع أن السيارة فئة فل كامل بينما هي ستاندرد.

مقارنة مستوى التجهيز: تحقق هل السيارة فعلاً GLS أم GL أم فئة أساسية.
التحقق من المحرك: تأكد من سعة المحرك ونوع الوقود — خاصة مع انتشار الكهربائية والهجينة من العلامات الصينية.
بلد التصنيع: اعرف ما إذا كانت مصنوعة في الصين أو في مصنع تجميع محلي.
سنة الصنع الفعلية: تمييز بين سنة الصنع وسنة الموديل — فرق مهم يؤثر على السعر.

أمثلة الكود — Python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.chinavehiclehistory.com/v1"

def decode_vin(vin: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/decode",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "vin": vin,
            "email": "partner@example.com",
            "plan": "basic"
        }
    )
    response.raise_for_status()
    return response.json()

def get_history(vin: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/history",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "vin": vin,
            "email": "partner@example.com",
            "plan": "standard"
        }
    )
    response.raise_for_status()
    return response.json()

# مثال على الاستخدام
result = decode_vin("LGXCE6CB9P0123456")
print(f"العلامة: {result['data']['brand']}")
print(f"الطراز: {result['data']['model']}")
print(f"السنة: {result['data']['year']}")

أمثلة الكود — Node.js

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.chinavehiclehistory.com/v1";

async function decodeVin(vin) {
  const response = await fetch(`${BASE_URL}/decode`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      vin,
      email: "partner@example.com",
      plan: "basic"
    })
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

async function getHistory(vin) {
  const response = await fetch(`${BASE_URL}/history`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      vin,
      email: "partner@example.com",
      plan: "standard"
    })
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// مثال على الاستخدام
const result = await decodeVin("LGXCE6CB9P0123456");
console.log(`العلامة: ${result.data.brand}`);
console.log(`الطراز: ${result.data.model}`);

كيف يمكنني الاستعلام عن معلومات المركبة؟

يتيح لك China Vehicle History API عدة طرق للاستعلام عن معلومات المركبة:

الاستعلام بالـ VIN عبر /v1/decode: الطريقة الأدق — أدخل الـ 17 حرفاً واحصل على المواصفات الأساسية فوراً.
تقرير التاريخ الكامل عبر /v1/history: سجل الحوادث والملكية وقراءات العداد والأضرار وحالة السرقة والرهن.
التقرير المتميز عبر /v1/premium: كل ما سبق + سجلات الصيانة من الوكلاء المعتمدين وحالة الاستدعاءات.
البحث برقم اللوحة عبر /v1/lookup/plate: للعثور على VIN عندما يتوفر رقم اللوحة الصينية فقط.

معالجة الأخطاء

يُرجع الـ API أكواد حالة HTTP القياسية. يُنصح بمعالجة الأكواد التالية في تطبيقك:

200 OK — تم تنفيذ الطلب بنجاح، البيانات في جسم الاستجابة.
400 Bad Request — رقم VIN غير صالح (ليس 17 خانة)، أو حقول إلزامية مفقودة (vin، email، plan).
401 Unauthorized — مفتاح API غير صالح أو مفقود في ترويسة Authorization.
404 Not Found — السيارة غير موجودة في قاعدة البيانات برقم VIN أو اللوحة المُدخل.
429 Too Many Requests — تجاوز حد الطلبات. استخدم exponential backoff قبل إعادة المحاولة.
500 Internal Server Error — خطأ في الخادم. أعد المحاولة بعد 5-10 ثوانٍ.

كيف اطلع مواصفات السيارة من رقم الشاصي: تطبيقات عملية في السوق العربي

لنستعرض كيف يُستخدم فحص رقم شاصي السيارة عملياً في المنطقة العربية:

منصات البيع (حراج، dubizzle): بناء إضافة تملأ حقول القائمة تلقائياً عند إدخال الشاصي — يقلل أخطاء الإدخال ويزيد ثقة المشتري. في الإمارات، يمكن عرض المواصفات المؤكدة كعلامة ثقة بجانب كل إعلان.
التأمين وكشف الاحتيال: برنامج كشف حوادث السيارات المبني على الـ API يتحقق من سجل المركبة قبل إصدار الوثيقة — كشف حوادث سابقة أو أضرار غمر أو تعديلات غير مصرح بها.
أنظمة إدارة المعارض (DMS): معارض جدة والرياض ودبي والقاهرة تمسح رقم VIN بالماسح الضوئي وتملأ سجل المركبة تلقائياً — المواصفات والتاريخ والتقييم.
إدارة الأساطيل: شركات النقل والتأجير تتبع مواصفات كل مركبة في الأسطول، وتراقب الاستدعاءات، وتجدول الصيانة بناءً على بيانات المصنع — خاصة مع تزايد BYD وMG وChangan في أساطيلها.
شركات استيراد السيارات الصينية: التحقق التلقائي من مواصفات كل دفعة قبل الشحن — تاريخ الحوادث والتأمين من المصادر الصينية مباشرة.
الوسطاء الجمركيون: الحصول على المواصفات الفنية الدقيقة لحساب الرسوم الجمركية عند استيراد السيارات الصينية.

لماذا فك تشفير VIN للسيارات الصينية يحتاج API متخصصة؟

السيارات الصينية تستخدم بنية VIN مختلفة عن الأمريكية والأوروبية، ومعظم خدمات الفحص التقليدية لا تدعمها بشكل كامل. China Vehicle History API تحل هذه المشكلة بقاعدة بيانات تغطي جميع العلامات الصينية الكبرى: BYD وGeely وGreat Wall (Haval وTank) وChangan وChery (Tiggo وOmoda وJaecoo) وGAC وSAIC (MG) وZeekr وNIO وXpeng وLi Auto وDongfeng وFAW وBAIC وJetour.

مقارنة مع واجهات برمجة التطبيقات الأخرى

في السوق الدولي توجد عدة واجهات برمجة تطبيقات لفحص السيارات. لا يوفر أي منها تاريخ السيارات الصينية:

Vincario API — خدمة أوروبية، الإصدار 3.2 بتوثيق جيد. تغطي مواصفات السيارات الصينية لكن ليس التاريخ (الحوادث، المسافة، الملاك).
Carfax / AutoCheck — بيانات أمريكية ممتازة لكن بدون أي مصادر صينية. مفيدة فقط لسيارات وارد أمريكي.
17VIN — مواصفات صينية وكتالوج قطع غيار. بيانات من CATARC لكن بدون تاريخ السيارة (حوادث، تأمين، صيانة).
China Vehicle History API — الوحيد الذي يوفر تاريخ السيارة من المصادر الصينية: سجلات الحوادث والتأمين (PICC، Ping An، CPIC)، تاريخ المسافة المقطوعة، الصيانة من الوكلاء، وبيانات الملاك.

تعرفة الـ API

الـ API متاح بثلاث خطط برصيد مسبق الدفع:

Basic ($20/تقرير) — حتى 100 طلب شهرياً، وصول كامل للـ API، دعم فني قياسي.
Professional ($18/تقرير) — 100-500 طلب شهرياً، وصول كامل، دعم فني ذو أولوية.
Enterprise ($16/تقرير) — 1000+ طلب شهرياً، كامل الوظائف، مدير حساب مخصص، شروط مخصصة.

للأحجام الكبيرة والشروط المخصصة تواصل معنا. المزيد عن التعرفة — في صفحة الـ API.

كيفية معرفة مواصفات السيارة عبر VIN Decoder بالعربي

معظم أدوات فك تشفير الـ VIN متاحة بالإنجليزية فقط. China Vehicle History API تدعم VIN decoder بالعربي، حيث تُعرض النتائج بالعربية مع إمكانية التبديل بين اللغات. لبناء تطبيق معرفة مواصفات السيارة من رقم الشاصي مجاناً يخدم المستخدم العربي، استخدم واجهة برمجة التطبيقات مع تخصيص واجهة المستخدم بالعربية — تدعم الاستجابات حقول الترجمة لأسماء الحقول.

خطوات بناء تطبيق فحص VIN للسوق العربي

التسجيل: تواصل معنا عبر WhatsApp أو Telegram للحصول على مفتاح API مع طلبات اختبارية كافية للتطوير.
قراءة التوثيق: راجع نقاط النهاية وصيغ الاستجابة وأكواد الأخطاء — التوثيق يشمل أمثلة بـ Python وNode.js وPHP.
بناء طبقة التكامل: أنشئ خدمة وسيطة مع تخزين مؤقت (Caching) لتجنب استعلامات مكررة لنفس الـ VIN.
واجهة عربية RTL: صمم واجهة من اليمين لليسار مع ماسح ضوئي لباركود الـ VIN لتسهيل الإدخال.
معالجة الأخطاء: رسائل واضحة بالعربية — "رقم الشاصي غير صالح" بدلاً من كود خطأ تقني.
الاختبار: اختبر مع أرقام VIN حقيقية لسيارات صينية منتشرة في السوق العربي مثل BYD وGeely وMG وChangan.

أسئلة شائعة

ما هي العلامات الصينية المدعومة؟

جميع العلامات الصينية الرئيسية: BYD وGeely وGreat Wall (Haval وTank وPoer) وChangan وChery (Tiggo وOmoda وJaecoo) وGAC وSAIC (MG) وZeekr وNIO وXpeng وLi Auto وVoyah وDongfeng وFAW وBAIC وJetour وDeepal وAvatr. كما تُدعم سيارات العلامات الأجنبية المصنعة في الصين (الاستيراد الموازي).

هل يمكن تجربة الـ API قبل الشراء؟

نعم. ابدأ بفحص VIN مجاني على الموقع لتقييم جودة البيانات. لاختبار الوصول عبر API، تواصل معنا — نوفر طلبات اختبارية.

هل يدعم الـ API إشعارات Webhook؟

نعم. عند طلب تقرير Premium، أرسل معامل callback_url — سيُرسل الـ API طلب POST إلى عنوانك عند جاهزية التقرير. هذا أسهل من الاستعلام المتكرر عن الحالة (polling).

الخلاصة

مع التوسع السريع للسيارات الصينية في الأسواق العربية — السعودية والإمارات ومصر والأردن والجزائر والعراق — تزداد الحاجة إلى أدوات موثوقة لمعرفة مواصفات السيارة من رقم الشاصي وبناء تطبيقات فحص VIN متكاملة. China Vehicle History API هي الواجهة الوحيدة التي توفر تاريخ السيارات الصينية من المصادر الأصلية — بيانات لا تتوفر في أي خدمة أخرى.

واجهة برمجة تطبيقات بيانات السيارات (API): كيف تستعلم عن مواصفات السيارة من رقم الشاصي وتبني تطبيقات فحص VIN