دليل
ما هو تكامل 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
نقطة النهاية والطريقة
عنوان العملية والفعل المستخدم عليها: POST إلى availability يعني البحث عن غرف.
- 2
المصادقة
مفتاح أو رمز أو توقيع يثبت هوية المتصل. يصدر المورّدون بيانات اعتماد منفصلة لبيئة الاختبار والإنتاج.
- 3
الحمولة
المدخلات المنظّمة: المدينة والتواريخ والنزلاء والعملة. توثيق المورّد يعرّف كل حقل.
- 4
رمز الحالة
رقم يخبر كيف جرى النداء: 200 نجاح، 4xx مشكلة في الطلب، 5xx مشكلة لدى المورّد.
- 5
معرّف الطلب
معرّف يحتفظ به الطرفان. عندما يسأل الدعم عمّا حدث لحجز ما، فهذا ما يبحثون عنه.
- 6
محتوى الاستجابة
الإجابة بصيغة المورّد، التي تحوّلها منصتك إلى غرفها وأسعارها وسياساتها الخاصة.
حجز واحد، أربعة أنظمة
ما الذي يفعله تكامل API أثناء حجز فندقي
تابع إقامة لليلتين من البحث حتى القسيمة. كل سهم هو نداء API؛ المسافر لا يرى سوى الأول والأخير.
- 01يبحث عن فنادق في دبي، ليلتان، نزيلانمن: المسافر, إلى: منصة الحجز
- 02طلب توفر بالتواريخ والنزلاء والعملةمن: منصة الحجز, إلى: API المورّد
- 03الغرف والأسعار والسياسات ومفتاح السعرمن: API المورّد, إلى: منصة الحجز
- 04عرض النتائج بعد تطبيق هامشك وعملتكمن: منصة الحجز, إلى: المسافر
- 05إعادة التحقق من سعر مفتاح السعر المختار قبل الدفعمن: منصة الحجز, إلى: API المورّد
- 06تفويض الدفع للمبلغ الإجماليمن: منصة الحجز, إلى: بوابة الدفع
- 07تم التفويض، واستُلم webhook موقّعمن: بوابة الدفع, إلى: منصة الحجز
- 08طلب حجز ببيانات النزيلمن: منصة الحجز, إلى: API المورّد
- 09رقم التأكيد وشروط الإلغاءمن: API المورّد, إلى: منصة الحجز
- 10القسيمة والفاتورة ومرجع الحجزمن: منصة الحجز, إلى: المسافر
- 01المسافرمنصة الحجزيبحث عن فنادق في دبي، ليلتان، نزيلان
- 02منصة الحجزAPI المورّدطلب توفر بالتواريخ والنزلاء والعملة
- 03API المورّدمنصة الحجزالغرف والأسعار والسياسات ومفتاح السعر
- 04منصة الحجزالمسافرعرض النتائج بعد تطبيق هامشك وعملتك
- 05منصة الحجزAPI المورّدإعادة التحقق من سعر مفتاح السعر المختار قبل الدفع
- 06منصة الحجزبوابة الدفعتفويض الدفع للمبلغ الإجمالي
- 07بوابة الدفعمنصة الحجزتم التفويض، واستُلم webhook موقّع
- 08منصة الحجزAPI المورّدطلب حجز ببيانات النزيل
- 09API المورّدمنصة الحجزرقم التأكيد وشروط الإلغاء
- 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 للأعمال B2B يمكن لأدوات وكلائك استدعاؤه. أنت تملك العقد وإصداراته.
كثير من مشاريع السفر تحتاج الاثنين: المنصة تدمج المورّدين من جهة وتنشر API خاصاً بها للوكلاء والشركاء من الجهة الأخرى.
قبل وبعد
ما الذي يتغيّر عندما تتكامل الأنظمة
خطوات الحجز الخمس نفسها، منفّذة يدوياً عبر بوابات المورّدين ومنفّذة عبر تكامل API.
البحث
يفتح الوكيل بوابة كل مورّد وينسخ الأسعار إلى عرض سعر.
بحث واحد ينتشر إلى كل المورّدين المتصلين ويعيد قائمة واحدة.
التسعير
يُضاف الهامش في جدول بيانات؛ وقد يكون السعر تغيّر قبل إرسال العرض.
الهامش والضرائب وقواعد العملة تُطبّق عند الاستجابة؛ ويُعاد التحقق من السعر قبل الدفع.
الحجز
تُعاد كتابة بيانات النزيل في بوابة المورّد؛ والأخطاء المطبعية تتحوّل إلى أخطاء حجز.
تُرسل البيانات مرة واحدة وتُتحقّق وتُخزّن مع تأكيد المورّد.
الدفع
يُحصَّل الدفع بشكل منفصل ويُطابَق مع الحجز لاحقاً.
التفويض والتحصيل والاسترداد مرتبطة بمرجع الحجز.
الخدمة
الإلغاءات والتعديلات تعني تسجيل دخول آخر وبريداً آخر.
التعديلات والإلغاءات تمر عبر الاتصال نفسه وتحدّث السجل.
أين يظهر تكامل API في منصة السفر
- برنامج حجز تذاكر الطيرانقائمة تحقق للوكالات وOTA التي تبيع تذاكر الطيران
- محرك حجز الفنادقحجوزات مباشرة على موقع فندقك الخاص
- برنامج منظمي الرحلاتحجوزات وبرامج رحلات وموزعو B2B وعمليات
- نظام تأجير السياراتأدر أسطولك وفروعك وتأميناتك عبر الإنترنت
- تكامل بوابات الدفعالدفع، 3D Secure، الاستردادات والـ webhooks
- CRM لوكالات السفرالعملاء والعروض والحجوزات والفواتير في CRM واحد
المصطلحات
مصطلحات ستقابلها في توثيق 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اتفاقية المورّد والتوثيق وبيانات اعتماد بيئة الاختبار
- 2الأسواق والعملات والمنتجات وأدوار المستخدمين
- 3نطاق البحث والحجز والتعديل والإلغاء والاسترداد
- 4متطلبات الاعتماد وإجراءات الوصول إلى الإنتاج
جاهز لربط مورّد
تدمج PHPTRAVELS المورّدين والبوابات وأدوات الأعمال في منصة مستضافة ذاتياً تُسلَّم مع كودها المصدري. راجع الأسعار للاطلاع على الباقات الثلاث بدفعة واحدة، أو اسألنا عن API محدد.
أسئلة
أسئلة عن تكامل API، مع إجاباتها
إجابات مختصرة عن الأسئلة التي يطرحها الناس قبل أول مشروع تكامل لهم.
تحدّث مع المبيعاتتكامل API هو اتصال يتيح لنظامين برمجيين تبادل البيانات وتنفيذ الإجراءات تلقائياً. يرسل نظام طلباً منظّماً، ويعيد الآخر استجابة منظّمة، ويلتزم الطرفان بقواعد متفق عليها للأمان والبيانات.
في السفر يربط منصة الحجز بمورّدي الطيران والفنادق والجولات والسيارات وبوابات الدفع وأدوات الأعمال. ويدعم البحث والتحقق من السعر والحجز والإلغاء والاسترداد والتسوية دون إعادة إدخال.
REST أسلوب معماري يتبادل عادةً JSON عبر HTTP. أما XML فصيغة بيانات ما زالت شائعة لدى مورّدي GDS وبنوك الأسرّة، وغالباً داخل غلاف SOAP. عقد المورّد وتوثيقه يحدّدان أيّهما تستخدم.
يعتمد على وصول المورّد ونقاط النهاية ضمن النطاق والاعتماد وقواعد التحويل والحالات الحدّية للحجز. التقدير الموثوق يأتي بعد مراجعة التوثيق وبيانات الاعتماد وسير العمل الذي تحتاجه.
اختبر المصادقة والطلبات الصالحة وغير الصالحة والمهل الزمنية وحدود المعدّل وتغيّرات الأسعار والإرسال المكرّر والإلغاءات والاستردادات والتسوية. وفي الإنتاج يجب أن يكون كل طلب قابلاً للتتبّع إلى مرجع حجز.
لا. التكامل يربط منتجك بـAPI موجود؛ والتطوير ينشئ واجهة يتصل بها الآخرون. غالباً ما تحتاج منصات السفر الاثنين: مورّدون مدمجون من جهة وAPI للأعمال B2B منشور للشركاء من الجهة الأخرى.
واصل الاستكشاف
المزيد عن المنصة
- تكامل API السفراربط موردي السفر عبر XML وJSON بلغة PHP
- واجهات API للسفرواجهات GDS والفنادق والجولات والسيارات والدفع
- جميع التكاملاتالقائمة الكاملة والمحدّثة
- تكامل بوابات الدفعالدفع، 3D Secure، الاستردادات والـ webhooks
- تكامل API مخصصاربط أي API لمورّد أو شريك بمنصة PHPTRAVELS
- التقنيةالبنية التقنية خلف الكواليس
