التوثيق

عنوان URL الأساسي

تتم جميع طلبات API إلى عنوان URL الأساسي التالي:

https://api.encarapi.com

على سبيل المثال، لجلب العروض:

GET https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true

المصادقة

قم بمصادقة طلباتك باستخدام مفتاح API. مرره كمعامل استعلام أو عبر رأس Authorization.

# Send your API key in the x-api-key header (recommended):
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true"

# The api_key query parameter also works:
GET https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true&api_key=YOUR_API_KEY

تجربة 5 أيام

جرّب الـ API لمدة 5 أيام مع الأسواق الثلاثة كلها (Encar و KB Chachacha و K Car)، بما في ذلك مزامنة التغييرات (آخر 7 أيام) والاستعلامات المجمّعة (1,000 معرّف يومياً) ومعاينة الأرشيف (100 إعلان مُزال يومياً). 100,000 صف من الكتالوج و2,000 استعلام تفاصيل إجمالاً (بحد أقصى 1,000 يومياً). ملفات التنزيل المرجعية (CSV) جزء من الخطط المدفوعة. يبدأ التصدير الكامل للكتالوج من خطة Business. بعد الفترة التجريبية، يستمر اشتراكك على خطة Starter بسعر 149€/شهر - يمكنك الإلغاء في أي وقت قبل اليوم الخامس.

القيم بالروسية (lang=ru)

كل نقطة نهاية تقبل lang=en تقبل أيضًا lang=ru: تأتي قيم العرض بالروسية، ويبقى كل شيء آخر كما هو (المعرّفات والرموز والأسعار والأرقام وأسماء الحقول). القيمة التي ليس لها تسمية روسية تعود إلى الإنجليزية. قد تتحسن التسميات الروسية مع الوقت، لذا اربط بياناتك بالمعرّفات والرموز وليس بالتسميات.

• تُترجم: الوقود وناقل الحركة ونظام الدفع ولون الهيكل والمقصورة وفئة الهيكل ونوع البيع وأسماء المناطق والمدن وأسماء التجهيزات والكلمات العامة في أسماء الفئات (Diesel -> дизель, 7-Seater -> 7 мест). أجيال الطرازات: Carnival 4 Gen -> Carnival 4 поколение. تبقى أسماء العلامات والطرازات والفئات بالحروف اللاتينية، كما في مواقع السيارات الروسية.
• تقبل الفلاتر القيم الروسية أيضًا: fuel=дизель, color=белый, region=Сеул, city=Сувон, drivetrain=полный, sell_type=лизинг. وتبقى القيم الإنجليزية صالحة.
• ‏/api/enums?lang=ru يضيف nameRu إلى كل قيمة ويعرض قيم drivetrain و sell_type. ‏/api/nav?lang=ru يعيد DisplayValue بالروسية، بينما يبقى Value الرمز الإنجليزي للفلترة. ملفات CSV المرجعية مع lang=ru تحصل على الاسم الروسي في عمود إضافي بعد العمود الأخير.
• ‏/api/vehicle/{id}?lang=ru ونقطة bulk تعيدان قيم spec من Encar وأسماء category وأسماء optionsDecoded بالروسية، وإعلانات KB Chachacha كما في الكتالوج.
• ‏/api/catalog/export?lang=ru هو الملف نفسه مع أعمدة التسميات بالروسية؛ ترتيب الأعمدة وجميع الأعمدة الأخرى دون تغيير.
• لا تُترجم: تقارير الفحص وسجلات التأمين وتشخيصات Encar وسجلات مركبات Encar وبيانات تفاصيل K Car وحزم تجهيزات Encar (نص حر من الإعلان) ونقاط نهاية الشاحنات والحفارات (تجيب بالإنجليزية مع lang=ru).

# Russian values, filtered with Russian values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?fuel=дизель&city=Сувон&lang=ru&count=true"

# Filter values with their Russian labels (nameRu)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/enums?lang=ru"

القيم بالألمانية (lang=de)

يعمل lang=de مثل lang=ru: تأتي قيم العرض بالألمانية، ويبقى كل شيء آخر كما هو (المعرّفات والرموز والأسعار والأرقام وأسماء الحقول). القيمة التي ليس لها تسمية ألمانية تعود إلى الإنجليزية.

• تُترجم: الوقود وناقل الحركة ونظام الدفع والألوان وفئة الهيكل ونوع البيع وأسماء التجهيزات، وأسماء الطرازات والفئات من جداولنا الألمانية (C-Class -> C-Klasse, 5-Series -> 5er, Carnival 4 Gen -> Carnival 4. Generation, 7-Seater -> 7-Sitzer, Sedan -> Limousine). المناطق بأسمائها الإنجليزية، والمدن تبقى بالإنجليزية.
• تقبل الفلاتر القيم الألمانية أيضًا: fuel=Benzin, color=Weiß, transmission=Automatik, drivetrain=Allrad, sell_type=Leasingübernahme, model_group=C-Klasse. قد تجمع أسماء الطرازات الألمانية النسخ المحدّثة: Carnival 4. Generation يشمل Carnival 4 Gen و The New Carnival 4 Gen.
• القوائم والتفاصيل و bulk والتصدير تعمل كما مع lang=ru: ‏nameDe في /api/enums و /api/taxonomy/option-packages، و DisplayValue بالألمانية في /api/nav، وأعمدة *_de في ملفات CSV المرجعية، و catalog_export_de.csv للتصدير. ما لا يُترجم هو نفسه كما في lang=ru.

# German values, filtered with German values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?manufacturer=Mercedes-Benz&model_group=C-Klasse&fuel=Benzin&lang=de&count=true"

ثلاث منصات، API واحد

يوفر الـ API إعلانات مباشرة من أكبر ثلاث منصات للسيارات المستعملة في كوريا. كل نقطة نهاية تُرجع Encar افتراضيًا، لذا تستمر التكاملات الحالية في العمل دون تغيير. المنصتان الأخريان تُفعَّلان اختياريًا عبر المعامل source.

اختيار المصادر

المعامل source مقبول في /api/catalog و /api/nav و /api/enums و /api/model-search و /api/catalog/export و /api/catalog/changes وملفات CSV الخاصة بالتصنيف.

# All three marketplaces, English values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?source=all&manufacturer=bmw&fuel=diesel&lang=en&count=true"

# K Car only
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?source=kcar&manufacturer=hyundai&lang=en"

# One KB Chachacha vehicle
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/vehicle/kbc:12345678?lang=en"

عند تحديد source يحمل كل عنصر الحقل Source. معرّفات Encar تبقى أرقامًا عادية. معرّفات KB Chachacha و K Car تحمل بادئة (kbc:..., kcar:...) - مرّرها كما هي إلى /api/vehicle/{id}. مع lang=en تُرجَع أسماء الموديلات والفئات للمنصات الثلاث بالإنجليزية.

كثيرًا ما يعرض التجار السيارة نفسها على Encar و KB Chachacha. يُطابَق إعلان KB Chachacha مع إعلان Encar نشط حسب رقم اللوحة الكوري، أو حسب شهر أول تسجيل والمسافة المقطوعة والسعر عندما لا ينشر KB Chachacha رقم اللوحة؛ وتُعاد المطابقة عدة مرات يوميًا، بعد كل مرور على كتالوج Encar وKB Chachacha. لا تُرجِع /api/catalog و /api/catalog/export وبقية نقاط نهاية الكتالوج إعلانات KB Chachacha المطابَقة، مع source أو بدونه (ولا حتى مع source=kbc وحده)، لذلك لا تظهر السيارة نفسها مرتين أبدًا - وعند تضمين Encar تُرجَع كإعلان Encar.

في /api/catalog/changes?source=kbc و /api/vehicle/kbc:{id} تحمل هذه الإعلانات IsDuplicate: true و DuplicateOf (معرّف إعلان Encar كسلسلة رقمية)؛ وكما في عناصر Encar لا يظهر الحقلان إلا عندما تكون القيمة true. عند وضع العلامة أو إزالتها تسجّل تغذية التغييرات حدث updated يحتوي changedFields فيه على duplicate. للحفاظ على نسخة محلية متسقة مع /api/catalog، احذف عناصر KB Chachacha التي تصل مع IsDuplicate: true وأعد إضافتها عندما يصل تحديث بدون هذا الحقل.

تغذية التغييرات تقبل مصدرًا واحدًا لكل طلب (encar أو kbc أو kcar) وتحتفظ بمؤشر منفصل لكل مصدر.

التغطية حسب المنصة

ليست كل منصة تنشر كل الحقول.

• تنشر KB Chachacha عدد المقاعد لجزء من إعلاناتها.
• تفاصيل KB Chachacha = عنصر الكتالوج إضافة إلى قسم السجل العام (مؤشر الحوادث، الخسارة الكلية، الغرق، الاستخدام التجاري، الرهون، تشخيص الشاسيه والألواح). يحمل كل عنصر من KB Chachacha أيضًا الحقل InsuranceClaims: عدد سجلات حوادث التأمين المعروضة في صفحة الإعلان. ويتضمن التفصيل أيضًا InspectionReportUrl وInspectionReportType: ورقة الفحص التي يعرضها KB Chachacha للسيارة (link = تقرير على موقع شركة الفحص، scan = صور ممسوحة فقط على صفحة الإعلان، null = غير معروفة بعد). وعندما يكون InspectionAvailable بقيمة true، يُرجع GET /api/inspection/kbc:{id} هذه الورقة كبيانات منظمة بالتنسيق نفسه المستخدم في تقرير فحص Encar (master، outers، inners، images) مع كتلة source - وذلك لنحو إعلانين من كل خمسة إعلانات على KB Chachacha تتضمن رابطًا لورقة فحص.
• لا توجد لدى K Car مستندات تقارير منفصلة؛ عدد الحوادث ومدفوعات التأمين وتغييرات الملكية جزء من تفاصيل المركبة.

التصفية حسب حقل لا توفره منصة ما تستبعد مركبات تلك المنصة من النتائج. مثال: frame_clean=true مع source=all يُرجع إعلانات Encar و K Car فقط.

نقاط نهاية API

جميع نقاط النهاية المتاحة للوصول إلى بيانات المركبات الكورية.

بيانات القوائم المنسدلة (CSV)

نزّل قوائم الماركات والطُرز والشارات بصيغة CSV، واحفظها في الذاكرة المؤقتة، وابنِ منها قوائمك المنسدلة - دون استدعاءات فئات مع كل نقرة ودون مطابقة يدوية دون اتصال. يتضمّن كل ملف عمود عدد، ويحمل ملف الشارات توزيع نوع الهيكل (Coupe / Sedan / Cabrio).

الأسئلة المتكررة