واجهة Rivelys البرمجية (API)

البدء

1. أنشئ حساب شريك على rivelys.com واطلب توثيق ملفك.
2. في مساحتك، تبويب API، أنشئ مفتاح اختبار (rv_test_…): تكون الحجوزات تجريبية ولا تُرسل أبدًا إلى السائقين.
3. عندما يعمل الربط لديك، أنشئ مفتاحًا فعليًا (rv_live_…): تصبح الحجوزات رحلات حقيقية.

عنوان الواجهة البرمجية: https://api.rivelys.com/v1. أرسل المفتاح في الترويسة Authorization: Bearer rv_…. تتم المراسلات بصيغة JSON (UTF-8)، والتواريخ بصيغة ISO 8601. احتفظ بالمفتاح على خادمك: لا تضعه أبدًا في صفحة يراها عملاؤك.

curl https://api.rivelys.com/v1 -H "Authorization: Bearer rv_test_••••••••"

القواعد

• سعر ثابت. تحسب Rivelys سعر كل رحلة: متوسط أسعار السائقين المتاحين والمناسبين (لكل منهم تعريفته)، دون الأعلى والأدنى؛ وعند قلة السائقين، الجدول المرجعي لنوع المركبة. اطلبه عبر POST /v1/quotes، ثم احجز بإرسال هذا السعر في expected_price: إذا تغيّر في الأثناء، يُرفض الحجز مع السعر الجديد (الرمز price_changed). بعد الحجز، تحتفظ الرحلة بسعرها.
• المهلة الدنيا. يجب أن يكون موعد الانطلاق بعد 48 ساعة على الأقل من الطلب (القيمة الحالية تُعاد في min_notice_hours).
• الدفع، باختيار الشريك: agency_card (بطاقتك المسجَّلة في مساحتك، تُخصم رحلةً برحلة)، أو monthly_invoice (فاتورة شهرية للرحلات المنتهية، تُسدَّد بالخصم المباشر SEPA أو بتحويل بنكي؛ تفعّلها Rivelys لحسابك، مع سقف)، أو client_link (يُرسل رابط إلى الراكب، فيؤكد ويدفع للسائق بالبطاقة أو نقدًا).
• التأكيد. يحصل على الرحلة أول سائق موثَّق ومناسب يأخذها. إذا كان الشريك هو من يدفع، تُؤكَّد الرحلة حينها؛ ومع client_link، يؤكدها الراكب عبر رابطه.
• لا إلغاء تلقائي أبدًا. إذا لم يأخذ أي سائق الرحلة، فلا تُلغى: يُنبَّه فريق التوزيع في Rivelys ويجد حلًا.
• الإلغاء من قِبل الشريك. مجاني ما دامت الرحلة غير مؤكدة (POST /v1/bookings/{id}/cancel). بعد ذلك، تواصل مع فريق التوزيع في Rivelys.
• الحد الأقصى. 60 طلبًا في الدقيقة لكل عنوان IP.

الحصول على سعر

POST /v1/quotes: الحقول نفسها كما في الحجز (الراكب والدفع اختياريان). لا يُحجز أي شيء.

curl https://api.rivelys.com/v1/quotes \
  -H "Authorization: Bearer rv_test_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "transfer",
    "pickup_at": "2026-12-20T14:30:00+01:00",
    "pickup_address": "Aéroport Nice Côte d'Azur, Terminal 2",
    "dropoff_address": "Hôtel de Paris, Monaco",
    "passengers": 2,
    "vehicle_type": "Business"
  }'

الرد:

{
  "price": 92,
  "currency": "EUR",
  "price_basis": "average",
  "distance_km": 28,
  "duration_min": 40,
  "vehicle_type": "Business",
  "min_notice_hours": 48
}

price_basis: average (متوسط السائقين المتاحين) أو reference_grid (الجدول المرجعي).

الحجز

POST /v1/bookings: ينشئ الحجز (الرد 201). مع external_ref سبق إرساله، يُعاد الحجز الموجود (الرد 200): يمكنك إعادة المحاولة دون خطر التكرار بعد انقطاع الشبكة.

curl https://api.rivelys.com/v1/bookings \
  -H "Authorization: Bearer rv_test_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "AG-2026-00042",
    "service": "transfer",
    "pickup_at": "2026-12-20T14:30:00+01:00",
    "pickup_address": "Aéroport Nice Côte d'Azur, Terminal 2",
    "dropoff_address": "Hôtel de Paris, Monaco",
    "flight_number": "AF7300",
    "passengers": 2,
    "luggage_hold": 2,
    "vehicle_type": "Business",
    "passenger": { "name": "John Smith", "phone": "+44 7700 900123", "language": "en" },
    "notes": "Name sign at arrivals",
    "payment": "agency_card",
    "expected_price": 92
  }'

الرد:

{
  "id": "RV-4F2A9C",
  "external_ref": "AG-2026-00042",
  "environment": "live",
  "status": "searching",
  "service": "transfer",
  "pickup_at": "2026-12-20T13:30:00.000Z",
  "pickup_address": "Aéroport Nice Côte d'Azur, Terminal 2",
  "dropoff_address": "Hôtel de Paris, Monaco",
  "passengers": 2,
  "vehicle_type": "Business",
  "price": 92,
  "currency": "EUR",
  "payment": "agency_card",
  "passenger": { "name": "John Smith", "phone": "+44 7700 900123", "language": "en" },
  "client_link": "https://rivelys.com/suivi?t=…",
  "chauffeur": null,
  "created_at": "2026-12-01T09:12:44.000Z"
}

متابعة حجز

GET /v1/bookings/{id} (مثلًا RV-4F2A9C) يعيد الحجز محدَّثًا. GET /v1/bookings يعيد آخر الحجوزات (المعاملان status وlimit، 100 كحد أقصى). استعلم عن الحجز كل بضع دقائق، وليس أكثر من مرة في الدقيقة.

بمجرد أن يأخذ سائق الرحلة، يعطي chauffeur اسمه وسيارته؛ وبعد تأكيد الرحلة، رقم هاتفه ولوحة السيارة:

"status": "confirmed",
"chauffeur": {
  "name": "Karim B.",
  "vehicle": "Mercedes-Benz Classe E",
  "color": "Noir",
  "phone": "+33 6 12 34 56 78",
  "plate": "AB-123-CD"
}

الإلغاء

POST /v1/bookings/{id}/cancel: مجاني ما دامت الحالة searching أو awaiting_client. لرحلة مؤكدة، يكون الرد 409 (cannot_cancel): تواصل مع فريق التوزيع في Rivelys.

حقول الحجز

الحالات

الأخطاء

يعيد الخطأ رمز HTTP وكائن error، مع رسالة بالإنجليزية والفرنسية:

{
  "error": {
    "code": "price_changed",
    "message": "The price is now 95 EUR. Check it and send the booking again with this expected_price.",
    "message_fr": "Le prix vient d’être recalculé : 95 €.",
    "price": 95,
    "currency": "EUR"
  }
}

مفاتيح الاختبار

بمفتاح rv_test_…، يُتحقق من كل شيء كما في الوضع الفعلي (الحقول، المهلة، السعر الحقيقي)، لكن لا يُرسل شيء إلى السائقين ولا يُفوتر شيء. تحمل الحجوزات مرجعًا TEST-… وتتغير حالتها تلقائيًا: searching لمدة دقيقة واحدة، ثم يأخذها سائق اختبار (confirmed إذا كان الشريك يدفع؛ awaiting_client ثم confirmed بعد دقيقة مع client_link).

المساعدة

سؤال عن الواجهة البرمجية: contact@rivelys.com. لرحلة جارية، تواصل مع فريق التوزيع في Rivelys من مساحتك (زر «الاتصال بمركز التوزيع»).