دليل

ما هو تكامل API، شرح مبسّط لشركات السفر

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

  • طلب واحد، استجابة واحدة
  • REST وXML وSOAP وwebhooks
  • حجز واحد يُتتبّع عبر أربعة أنظمة
  • كيف تُختبر التكاملات

التعريف

ما هو تكامل API، بلغة بسيطة

API اختصار لواجهة برمجة التطبيقات: مجموعة القواعد التي ينشرها نظام ما ليتمكّن برنامج آخر من التخاطب معه. وتكامل API هو عمل ربط منصتك بإحدى هذه الواجهات بحيث تنتقل البيانات وتحدث الإجراءات تلقائياً.

في قطاع السفر تكون هذه المنصة عادةً نظام حجز مثل برنامج حجوزات السفر، وتعود الواجهة إلى مورّد أو بوابة دفع أو أداة أعمال. تشرح صفحة تكامل API السفر لدينا كيف تنفّذ PHPTRAVELS هذه الاتصالات، ويعرض جميع التكاملات المورّدين المتصلين بالفعل.

  • تبادل البيانات

    تنتقل الأسعار والتوفر وبيانات العملاء وتحديثات الحالة بين الأنظمة بصيغة منظّمة.

  • أتمتة الإجراءات

    البحث والحجز والدفع والإلغاء والتسوية تتم كطلبات، لا كخطوات يكرّرها شخص يدوياً.

  • تتبّع النتائج

    كل نداء يحمل مرجعاً، لذا يمكن تتبّع أي حجز فاشل حتى الطلب الذي تسبّب فيه.

الطلب

POST /v1/hotels/availability HTTP/1.1Host: api.supplier.exampleAuthorization: Bearer sk_test_••••••••Content-Type: application/json{  "city": "DXB",  "check_in": "2026-11-12",  "check_out": "2026-11-14",  "guests": 2,  "currency": "USD"}

الاستجابة

HTTP/1.1 200 OKContent-Type: application/jsonX-Request-Id: req_7f3a91{  "hotel": "Palm Marina Hotel",  "room": "Deluxe, 2 adults",  "rate": { "amount": 438.00, "currency": "USD" },  "refundable": true,  "rate_key": "rk_19d2c7"}
نداء نموذجي إلى مورّد فنادق خيالي. تختلف أسماء الحقول ونقاط النهاية والمبالغ من مورّد إلى آخر.

تشريح نداء API واحد

  1. 1

    نقطة النهاية والطريقة

    عنوان العملية والفعل المستخدم عليها: POST إلى availability يعني البحث عن غرف.

  2. 2

    المصادقة

    مفتاح أو رمز أو توقيع يثبت هوية المتصل. يصدر المورّدون بيانات اعتماد منفصلة لبيئة الاختبار والإنتاج.

  3. 3

    الحمولة

    المدخلات المنظّمة: المدينة والتواريخ والنزلاء والعملة. توثيق المورّد يعرّف كل حقل.

  4. 4

    رمز الحالة

    رقم يخبر كيف جرى النداء: 200 نجاح، 4xx مشكلة في الطلب، 5xx مشكلة لدى المورّد.

  5. 5

    معرّف الطلب

    معرّف يحتفظ به الطرفان. عندما يسأل الدعم عمّا حدث لحجز ما، فهذا ما يبحثون عنه.

  6. 6

    محتوى الاستجابة

    الإجابة بصيغة المورّد، التي تحوّلها منصتك إلى غرفها وأسعارها وسياساتها الخاصة.

حجز واحد، أربعة أنظمة

ما الذي يفعله تكامل API أثناء حجز فندقي

تابع إقامة لليلتين من البحث حتى القسيمة. كل سهم هو نداء API؛ المسافر لا يرى سوى الأول والأخير.

  1. 01المسافرمنصة الحجزيبحث عن فنادق في دبي، ليلتان، نزيلان
  2. 02منصة الحجزAPI المورّدطلب توفر بالتواريخ والنزلاء والعملة
  3. 03API المورّدمنصة الحجزالغرف والأسعار والسياسات ومفتاح السعر
  4. 04منصة الحجزالمسافرعرض النتائج بعد تطبيق هامشك وعملتك
  5. 05منصة الحجزAPI المورّدإعادة التحقق من سعر مفتاح السعر المختار قبل الدفع
  6. 06منصة الحجزبوابة الدفعتفويض الدفع للمبلغ الإجمالي
  7. 07بوابة الدفعمنصة الحجزتم التفويض، واستُلم webhook موقّع
  8. 08منصة الحجزAPI المورّدطلب حجز ببيانات النزيل
  9. 09API المورّدمنصة الحجزرقم التأكيد وشروط الإلغاء
  10. 10منصة الحجزالمسافرالقسيمة والفاتورة ومرجع الحجز

المنصة في المنتصف هي حيث يعيش تكامل API: تترجم بين شاشة المسافر وصيغة كل مورّد، وتخزّن كل مرجع.

التسلسل نفسه يخدم برنامج حجز تذاكر الطيران مع GDS، وبرنامج منظمي الرحلات مع مورّد أنشطة، وتكامل بوابات الدفع مع أي بوابة؛ أسماء الحقول وحدها هي ما يتغيّر.

أنماط التكامل

REST وXML وSOAP وwebhooks وGraphQL

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

  • REST وJSON

    JSON
    صيغة البيانات
    مستندات JSON
    النقل
    طرق HTTP: GET وPOST وPUT وDELETE
    شائع في السفر
    واجهات API الأحدث للطيران والفنادق والأنشطة والمدفوعات
    نقطة القوة
    حمولات مضغوطة وأدوات مطوّرين واسعة
    انتبه إلى
    مواصفات فضفاضة؛ كل مورّد يفسّر REST بطريقته
  • XML وSOAP

    XML
    صيغة البيانات
    مستندات XML، غالباً بمخطط صارم
    النقل
    HTTP POST بغلاف SOAP أو XML خام
    شائع في السفر
    أنظمة GDS وبنوك الأسرّة وأنظمة الفنادق والجولات الراسخة
    نقطة القوة
    عقود رسمية وتوقيعات وتعريفات خدمة
    انتبه إلى
    رسائل مطوّلة وتحليل أثقل
  • Webhooks

    EVENT
    صيغة البيانات
    JSON أو XML يدفعه الطرف الآخر
    النقل
    HTTP POST إلى عنوان URL تسجّله
    شائع في السفر
    نتائج الدفع وتغيّرات حالة الحجز وتحديثات التذاكر
    نقطة القوة
    دون استطلاع متكرر؛ منصتك تُخطَر عند حدوث شيء
    انتبه إلى
    يجب التحقق من التوقيعات ومعالجة التكرارات
  • GraphQL

    QUERY
    صيغة البيانات
    JSON بالشكل الذي يحدّده استعلامك
    النقل
    نقطة نهاية HTTP واحدة
    شائع في السفر
    بعض منصات التوزيع الأحدث وواجهات API الداخلية
    نقطة القوة
    اطلب الحقول التي تحتاجها بالضبط
    انتبه إلى
    دعم المورّدين في السفر ما زال غير شائع

تكامل API مقابل تطوير API

تكامل API

يربط منتجك بواجهة موجودة أصلاً. المورّد يملك الـAPI؛ وأنت تبني العميل والتحويل والقواعد المحيطة به.

تطوير API

ينشئ واجهة تستخدمها أنظمة أخرى للاتصال بمنتجك، مثل API للأعمال B2B يمكن لأدوات وكلائك استدعاؤه. أنت تملك العقد وإصداراته.

كثير من مشاريع السفر تحتاج الاثنين: المنصة تدمج المورّدين من جهة وتنشر API خاصاً بها للوكلاء والشركاء من الجهة الأخرى.

قبل وبعد

ما الذي يتغيّر عندما تتكامل الأنظمة

خطوات الحجز الخمس نفسها، منفّذة يدوياً عبر بوابات المورّدين ومنفّذة عبر تكامل API.

البحث

بدون تكامليدوي

يفتح الوكيل بوابة كل مورّد وينسخ الأسعار إلى عرض سعر.

مع تكامل APIتلقائي

بحث واحد ينتشر إلى كل المورّدين المتصلين ويعيد قائمة واحدة.

التسعير

بدون تكامليدوي

يُضاف الهامش في جدول بيانات؛ وقد يكون السعر تغيّر قبل إرسال العرض.

مع تكامل APIتلقائي

الهامش والضرائب وقواعد العملة تُطبّق عند الاستجابة؛ ويُعاد التحقق من السعر قبل الدفع.

الحجز

بدون تكامليدوي

تُعاد كتابة بيانات النزيل في بوابة المورّد؛ والأخطاء المطبعية تتحوّل إلى أخطاء حجز.

مع تكامل APIتلقائي

تُرسل البيانات مرة واحدة وتُتحقّق وتُخزّن مع تأكيد المورّد.

الدفع

بدون تكامليدوي

يُحصَّل الدفع بشكل منفصل ويُطابَق مع الحجز لاحقاً.

مع تكامل APIتلقائي

التفويض والتحصيل والاسترداد مرتبطة بمرجع الحجز.

الخدمة

بدون تكامليدوي

الإلغاءات والتعديلات تعني تسجيل دخول آخر وبريداً آخر.

مع تكامل APIتلقائي

التعديلات والإلغاءات تمر عبر الاتصال نفسه وتحدّث السجل.

المصطلحات

مصطلحات ستقابلها في توثيق API

اثنتا عشرة كلمة تظهر في بوابة المطوّرين لدى كل مورّد تقريباً، معرّفة كما تُستخدم في قطاع السفر.

  • API

    واجهة برمجة التطبيقات: القواعد المنشورة للتخاطب مع نظام ما.

  • المصادقة

    إثبات هوية المتصل بمفتاح API أو رمز bearer أو توقيع أو عنوان IP معتمد.

  • الاعتماد

    مراجعة المورّد لتكاملك قبل إصدار بيانات اعتماد الإنتاج.

  • نقطة النهاية

    عنوان واحد لعملية واحدة، مثل البحث أو الحجز أو الإلغاء.

  • الثبات التكراري

    إرسال الطلب نفسه مرتين ينتج نتيجة واحدة، ما يمنع الحجوزات والرسوم المكرّرة.

  • التحويل

    ترجمة حقول المورّد ورموزه وأسمائه إلى نموذج بيانات منصتك.

  • الحمولة

    البيانات المحمولة داخل الطلب أو الاستجابة، عادةً JSON أو XML.

  • حد المعدّل

    عدد النداءات التي يسمح بها المورّد في الثانية أو اليوم قبل أن يبدأ برفضها.

  • الطلب والاستجابة

    نداء واحد: منصتك تسأل، والمورّد يجيب، والطرفان يسجّلانه.

  • بيئة الاختبار

    بيئة تجريبية بمخزون وهمي وبطاقات اختبار لا يُحجز فيها شيء ولا يُحصَّل فعلياً.

  • رمز الحالة

    رقم HTTP الذي يلخّص النتيجة: 200 نجاح، 401 غير مصرّح، 429 تجاوز حد المعدّل، 500 خطأ لدى المورّد.

  • Webhook

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

الاختبار وتحديد النطاق

كيف يُختبر تكامل API للسفر قبل إطلاقه

لا يكتمل التكامل إلا عندما تتصرّف المسارات غير السعيدة كما ينبغي. تغطي جولة اختبار على بيئة اختبار المورّد الحالات التالية قبل الاعتماد والانتقال إلى بيانات اعتماد الإنتاج.

run integration tests

بيئة اختبار المورّد، تسع حالات

  • OK: المصادقة ببيانات اعتماد صالحة ومنتهية
  • OK: رفض الطلب غير الصالح مع خطأ مقروء
  • OK: معالجة انقطاع مهلة المورّد دون حجز معلّق
  • OK: احترام حد المعدّل وإعادة المحاولة بعد الانتظار
  • OK: اكتشاف تغيّر السعر عند إعادة التحقق وعرضه قبل الدفع
  • OK: الإرسال المكرّر يعيد الحجز الأول لا حجزاً ثانياً
  • OK: تطبيق الإلغاء واحتساب الرسوم
  • OK: إصدار الاسترداد على الدفعة الأصلية
  • OK: تطابق مراجع الحجز والدفع والمورّد

اجتازت كل الحالات، جاهز للاعتماد

ما يحتاجه تحديد النطاق منك

  1. 1اتفاقية المورّد والتوثيق وبيانات اعتماد بيئة الاختبار
  2. 2الأسواق والعملات والمنتجات وأدوار المستخدمين
  3. 3نطاق البحث والحجز والتعديل والإلغاء والاسترداد
  4. 4متطلبات الاعتماد وإجراءات الوصول إلى الإنتاج

جاهز لربط مورّد

تدمج PHPTRAVELS المورّدين والبوابات وأدوات الأعمال في منصة مستضافة ذاتياً تُسلَّم مع كودها المصدري. راجع الأسعار للاطلاع على الباقات الثلاث بدفعة واحدة، أو اسألنا عن API محدد.

أسئلة

أسئلة عن تكامل API، مع إجاباتها

إجابات مختصرة عن الأسئلة التي يطرحها الناس قبل أول مشروع تكامل لهم.

تحدّث مع المبيعات

تكامل API هو اتصال يتيح لنظامين برمجيين تبادل البيانات وتنفيذ الإجراءات تلقائياً. يرسل نظام طلباً منظّماً، ويعيد الآخر استجابة منظّمة، ويلتزم الطرفان بقواعد متفق عليها للأمان والبيانات.

في السفر يربط منصة الحجز بمورّدي الطيران والفنادق والجولات والسيارات وبوابات الدفع وأدوات الأعمال. ويدعم البحث والتحقق من السعر والحجز والإلغاء والاسترداد والتسوية دون إعادة إدخال.

REST أسلوب معماري يتبادل عادةً JSON عبر HTTP. أما XML فصيغة بيانات ما زالت شائعة لدى مورّدي GDS وبنوك الأسرّة، وغالباً داخل غلاف SOAP. عقد المورّد وتوثيقه يحدّدان أيّهما تستخدم.

يعتمد على وصول المورّد ونقاط النهاية ضمن النطاق والاعتماد وقواعد التحويل والحالات الحدّية للحجز. التقدير الموثوق يأتي بعد مراجعة التوثيق وبيانات الاعتماد وسير العمل الذي تحتاجه.

اختبر المصادقة والطلبات الصالحة وغير الصالحة والمهل الزمنية وحدود المعدّل وتغيّرات الأسعار والإرسال المكرّر والإلغاءات والاستردادات والتسوية. وفي الإنتاج يجب أن يكون كل طلب قابلاً للتتبّع إلى مرجع حجز.

لا. التكامل يربط منتجك بـAPI موجود؛ والتطوير ينشئ واجهة يتصل بها الآخرون. غالباً ما تحتاج منصات السفر الاثنين: مورّدون مدمجون من جهة وAPI للأعمال B2B منشور للشركاء من الجهة الأخرى.