واجهة API للمطورين والوكلاء الأذكياء

الترخيص والإسناد

كل بيانات الواجهة مجانية للاستخدام والاستشهاد مع ذكر المصدر: «بيسيات للسيارات — beseyat.com/cars». الأسعار والتكاليف تقديرات موثّقة بتاريخ تحديث كل سيارة (dataAsOf) — اربط دائمًا بصفحة السيارة لأحدث الأرقام.

حد الاستخدام: 60 طلبًا في الساعة لكل عنوان IP، مشترك بين النقاط الثلاث. الاستجابات مُخزّنة مؤقتًا لساعة واحدة ومتاحة عبر CORS مفتوح (Access-Control-Allow-Origin: *).

نقاط النهاية

الاستعلام عن موديل

تحوّل اسم الطراز (modelKey) إلى سيارته القياسية الحالية وتعيد المواصفات الكاملة وكل سنوات الموديل والسعر والضمان وتقييم بيسيات والكتالوج وروابط الموقع. تعيد 404 لمفتاح غير معروف.

GET https://beseyat.com/cars/api/model.php?key={modelKey}

مثال على الطلب

curl 'https://beseyat.com/cars/api/model.php?key=toyota-camry'

مثال على الاستجابة (مختصر)

{
  "source": "Beseyat Cars — beseyat.com/cars",
  "license": "free to cite with attribution",
  "asOf": "2026-07-03",
  "disclaimer": "estimates; prices verified per dataAsOf",
  "modelKey": "toyota-camry",
  "priceMinSAR": 109825, "priceMaxSAR": 153985,
  "warranty": {"years": 3, "km": 100000},
  "beseyatScore": {"total": 79, "safety": 93, "…": "…"},
  "brochureUrl": "https://…",
  "webUrl": "https://beseyat.com/cars/car/toyota-camry-2026",
  "modelUrl": "https://beseyat.com/cars/model/toyota-camry",
  "car": {"id": "toyota-camry-2026", "nameEn": "Toyota Camry", "nameAr": "تويوتا كامري", "engine": {"…": "…"}, "…": "full spec"},
  "modelYears": [{"id": "toyota-camry-2026", "year": 2026, "canonical": true, "…": "…"}]
}

مقارنة بين سيارتين

أهم المواصفات جنبًا إلى جنب مع فروقات محسوبة: سعر الوكيل، القسط الشهري التقديري، تكلفة الوقود السنوية، وتكلفة الملكية لخمس سنوات — مع رابط صفحة المقارنة الكاملة. تعيد 422 ما لم يُمرَّر معرّفا سيارتين صحيحان بالضبط.

GET https://beseyat.com/cars/api/compare.php?ids={idA},{idB}

مثال على الطلب

curl 'https://beseyat.com/cars/api/compare.php?ids=toyota-camry-2026,hyundai-sonata-2026'

مثال على الاستجابة (مختصر)

{
  "source": "Beseyat Cars — beseyat.com/cars",
  "license": "free to cite with attribution",
  "cars": [{"id": "toyota-camry-2026", "priceMinSAR": 109825, "…": "…"},
           {"id": "hyundai-sonata-2026", "priceMinSAR": 98325, "…": "…"}],
  "deltas": {
    "convention": "positive = first car costs more",
    "priceSAR": 11500,
    "monthlyInstallmentSAR": 210,
    "fuelCostPerYearSAR": -278,
    "tco5YearSAR": 655,
    "cheaperTco5YearId": "hyundai-sonata-2026"
  },
  "costs": {"assumptions": {"kmPerYear": 20000, "years": 5, "purchase": "cash"}, "cars": ["…"]},
  "webUrl": "https://beseyat.com/cars/compare/hyundai-sonata-2026-vs-toyota-camry-2026"
}

تكلفة الملكية الإجمالية

تفصيل تقديري لتكلفة الملكية من سنة إلى 10 سنوات (الافتراضي 5): الاستهلاك، الوقود/الشحن، التأمين، والرسوم الحكومية عند 15,000 كم/سنة وشراء نقدي. تعيد 404 لمعرّف غير معروف و422 لسنوات غير صالحة أو سيارة بلا سعر.

GET https://beseyat.com/cars/api/tco.php?id={carId}&years={1-10}

مثال على الطلب

curl 'https://beseyat.com/cars/api/tco.php?id=toyota-camry-2026&years=5'

مثال على الاستجابة (مختصر)

{
  "source": "Beseyat Cars — beseyat.com/cars",
  "license": "free to cite with attribution",
  "asOf": "2026-07-03",
  "car": {"id": "toyota-camry-2026", "priceMinSAR": 109825, "…": "…"},
  "assumptions": {"years": 5, "kmPerYear": 15000, "purchase": "cash", "currency": "SAR"},
  "tco": {
    "totalSAR": 68761, "perYearSAR": 13752, "perMonthSAR": 1146,
    "resaleValueSAR": 66876, "energyBasis": "fuel",
    "components": {"depreciationSAR": 42949, "energySAR": 9506,
                   "insuranceSAR": 15427, "feesSAR": 880, "financingSAR": 0}
  }
}

اكتشاف الموقع للوكلاء الأذكياء (llms.txt)

يمكن للوكلاء الأذكياء ومحركات الإجابة اكتشاف الموقع وهذه الواجهة عبر llms.txt (وصف + الواجهة + أهم الصفحات) و llms-full.txt (يضيف أهم روابط خريطة الموقع).

• https://beseyat.com/cars/llms.txt
• https://beseyat.com/cars/llms-full.txt