تاريخ المركبة (VHR)

الحالات والأخطاء وwebhooks

كيف يعمل

01المصادقة

أرسل x-api-key مع كل طلب. تأتي معرّفات المصادر والصيغ من كتالوجك الخاص ومن فحص VIN، ويطبّق الـ API الوصول والأسعار.

02افحص، ثم اختر مصدرًا واحدًا

يعيد POST /checks الحقول price وavailable_formats ومعاينة لكل مصدر. ويأخذ POST /reports قيمة source_id واحدة ولغة واحدة وصيغة واحدة أو أكثر، بسعر واحد لكل تقرير. إذا كانت availability_confirmed تساوي false، فاقرأ availability_notice أولًا.

03ملفات، لا سجل مضمّن

تصل JSON وHTML وPDF كروابط على CDN الخاصة بنا، وبعض المصادر تُبقي الصور أو صفحة HTML جاهزة على عنوانها الأصلي. تعامل مع كل رابط تقرير كمفتاح وصول.

04الطلبات الطويلة

ينتظر HTTP حتى 10 ثوانٍ. ويعني HTTP 202 أن العمل مستمر: استعلم عن status_url كل 1 إلى 2 ثانية حتى تصبح الحالة نهائية. لا تكرر أبدًا عملية شراء معلّقة.

05الفشل والاستعادة

خطأ المصدر لا يعني عدم وجود بيانات. لا يُحتسب التقرير إلا عندما يجهز كل ملف مختار. إذا فشلت الملفات، يعيد POST /reports/{id}/retry استخدام البيانات المحفوظة دون احتساب ثانٍ.

06Webhooks

لأرقام VIN الحقيقية أضف webhook_url عامًا عبر HTTPS وwebhook_secret (من 16 إلى 256 حرفًا). يجيب الـ API بـ 202 ويرسل النتيجة عندما تجهز، موقّعة في X-VHR-Signature مع X-VHR-Timestamp.

الحالات

تكون الإجابة نهائية عندما تكون حالتها نهائية، وحتى ذلك الحين تابع status_url.

الفحص

running: لا يزال قيد التنفيذ. استعلم عن status_url.
completedنهائية: اكتمل. أجاب كل مصدر، أو أصبحت الملفات جاهزة.
partialنهائية: اكتمل، لكن بعض المصادر أعادت خطأ.
failedنهائية: توقف بسبب خطأ. لا يُحتسب أي شيء.

التقرير

running: لا يزال قيد التنفيذ. استعلم عن status_url.
preparing: حُفظت بيانات المصدر، ويجري إنشاء الملفات.
rendering: يجري إنشاء ملف PDF.
completedنهائية: اكتمل. أجاب كل مصدر، أو أصبحت الملفات جاهزة.
not_foundنهائية: لا يملك المصدر أي سجل لرقم VIN هذا. لا يُحتسب أي شيء.
failedنهائية: توقف بسبب خطأ. لا يُحتسب أي شيء.

كل مصدر في الفحص

available: توجد سجلات: يمكن طلب هذا المصدر (دون حقل status).
pending: لا يزال هذا المصدر يجيب.
not_found: لا يملك المصدر أي سجل لرقم VIN هذا. لا يُحتسب أي شيء.
error: تعذّر على هذا المصدر الإجابة الآن. وهذا ليس مثل عدم وجود بيانات.
not_checked: لم يُفحص في هذا الطلب. ولا يعني ذلك عدم وجود بيانات.

الأخطاء

تعود الأخطاء بصيغة JSON تحتوي على الحقلين error_code و message. لا يُحتسب أي شيء عند حدوث خطأ.

401الترويسة x-api-key مفقودة أو غير صالحة.

402رصيد التقارير غير كافٍ لهذا التقرير.

403نوع التقرير هذا غير مفعّل لمفتاحك.

409التقرير نفسه لرقم VIN هذا قيد الإعداد بالفعل.

422جسم الطلب غير صالح، مثل رقم VIN أو صيغة أو لغة، أو سعر تغيّر.

429طلبات كثيرة جدًا. انتظر قليلًا ثم أعد المحاولة.

503التقارير متوقفة مؤقتًا لبعض الوقت.

Webhooks

أضف webhook_url و webhook_secret إلى فحص أو تقرير لرقم VIN حقيقي: تجيب API فورًا بـ 202 وترسل النتيجة عندما تجهز. تحقّق من التوقيع قبل أن تثق بها.

قيمة X-VHR-Signature هي sha256= متبوعة بـ HMAC-SHA256 لقيمة X-VHR-Timestamp، ثم نقطة، ثم الجسم الخام.
ارفض الطوابع الزمنية القديمة (مثلًا الأقدم من 5 دقائق) وقيم X-VHR-Event-Id المكررة.
أرقام VIN التجريبية تجيب فورًا ولا تستدعي webhook أبدًا.

import crypto from 'node:crypto'

// raw: the request body exactly as received (a Buffer or string)

export const verify = (raw, headers, secret) => {

const stamp = headers['x-vhr-timestamp']

const sent = String(headers['x-vhr-signature'] || '').replace('sha256=', '')

const age = Math.abs(Date.now() / 1000 - Number(stamp))

if (!stamp || !Number.isFinite(age) || age > 300) return false

const mac = crypto.createHmac('sha256', secret).update(`${stamp}.${raw}`).digest('hex')

return sent.length === mac.length && crypto.timingSafeEqual(Buffer.from(sent), Buffer.from(mac))

}