راهنما
یکپارچهسازی API چیست، به زبان کسب‌وکارهای سفر
یکپارچهسازی API اتصالی است که به دو سیستم نرمافزاری اجازه میدهد بدون آنکه کسی چیزی را دوباره تایپ کند، داده مبادله کنند و عملیات را آغاز کنند. این راهنما با دنبال کردن یک رزرو هتل که میان مسافر، پلتفرم رزرو، API تأمینکننده و درگاه پرداخت حرکت میکند، نحوه کار آن را توضیح میدهد.
- یک درخواست، یک پاسخ
- REST، XML، SOAP و وب‌هوک
- ردیابی یک رزرو در چهار سیستم
- یکپارچه‌سازی‌ها چگونه آزمایش میشوند
تعریف
یکپارچهسازی API چیست، به زبان ساده
API مخفف application programming interface است: مجموعه قواعدی که یک سیستم منتشر میکند تا نرم‌افزارهای دیگر بتوانند با آن گفتگو کنند. یکپارچهسازی 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
احراز هویت
یک کلید، توکن یا امضا ثابت میکند چه کسی فراخوانی میکند. تأمینکنندگان برای sandbox و production اعتبارنامه‌های جداگانه صادر میکنند.
- 3
Payload
ورودی ساختاریافته: شهر، تاریخ‌ها، مهمانان و ارز. مستندات تأمینکننده هر فیلد را تعریف میکند.
- 4
کد وضعیت
عددی که می‌گوید فراخوانی چگونه پیش رفت: 200 موفقیت، 4xx مشکلی در درخواست، 5xx مشکلی در سمت تأمینکننده.
- 5
شناسه درخواست
شناسه‌ای که هر دو طرف نگه می‌دارند. وقتی پشتیبانی می‌پرسد چه بر سر یک رزرو آمده، همین را جستجو میکنند.
- 6
بدنه پاسخ
پاسخ در قالب تأمینکننده، که پلتفرم شما آن را به اتاق‌ها، نرخ‌ها و سیاست‌های خودش نگاشت میکند.
یک رزرو، چهار سیستم
یکپارچهسازی API در جریان رزرو هتل چه میکند
یک اقامت دو شبه را از جستجو تا واچر دنبال کنید. هر پیکان یک فراخوانی API است؛ مسافر فقط اولی و آخری را می‌بیند.
- 01جستجوی هتل در دبی، دو شب، دو مهماناز: مسافر, به: پلتفرم رزرو
- 02درخواست موجودی با تاریخ‌ها، مهمانان و ارزاز: پلتفرم رزرو, به: API تأمینکننده
- 03اتاق‌ها، نرخ‌ها، سیاست‌ها و یک کلید نرخاز: API تأمینکننده, به: پلتفرم رزرو
- 04نمایش نتایج با اعمال مارک‌آپ و ارز شمااز: پلتفرم رزرو, به: مسافر
- 05بازبینی قیمت روی کلید نرخ انتخاب‌شده پیش از پرداختاز: پلتفرم رزرو, به: API تأمینکننده
- 06درخواست مجوز پرداخت برای مبلغ کلاز: پلتفرم رزرو, به: درگاه پرداخت
- 07مجاز شد، وب‌هوک امضاشده دریافت شداز: درگاه پرداخت, به: پلتفرم رزرو
- 08درخواست رزرو با اطلاعات مهماناز: پلتفرم رزرو, به: API تأمینکننده
- 09شماره تأیید و شرایط لغواز: API تأمینکننده, به: پلتفرم رزرو
- 10واچر، فاکتور و شماره مرجع رزرواز: پلتفرم رزرو, به: مسافر
- 01مسافرپلتفرم رزروجستجوی هتل در دبی، دو شب، دو مهمان
- 02پلتفرم رزروAPI تأمین‌کنندهدرخواست موجودی با تاریخ‌ها، مهمانان و ارز
- 03API تأمین‌کنندهپلتفرم رزرواتاق‌ها، نرخ‌ها، سیاست‌ها و یک کلید نرخ
- 04پلتفرم رزرومسافرنمایش نتایج با اعمال مارک‌آپ و ارز شما
- 05پلتفرم رزروAPI تأمین‌کنندهبازبینی قیمت روی کلید نرخ انتخاب‌شده پیش از پرداخت
- 06پلتفرم رزرودرگاه پرداختدرخواست مجوز پرداخت برای مبلغ کل
- 07درگاه پرداختپلتفرم رزرومجاز شد، وب‌هوک امضاشده دریافت شد
- 08پلتفرم رزروAPI تأمین‌کنندهدرخواست رزرو با اطلاعات مهمان
- 09API تأمین‌کنندهپلتفرم رزروشماره تأیید و شرایط لغو
- 10پلتفرم رزرومسافرواچر، فاکتور و شماره مرجع رزرو
پلتفرم میانی جایی است که یکپارچهسازی API در آن زندگی میکند: میان صفحه مسافر و قالب هر تأمینکننده ترجمه میکند و هر شماره مرجع را ذخیره میکند.
همین توالی برای نرم‌افزار رزرو بلیط هواپیما با یک GDS، نرم‌افزار تور اپراتور با یک تأمینکننده فعالیت و یکپارچهسازی درگاه پرداخت با هر درگاهی کار میکند؛ فقط نام فیلدها تغییر میکند.
سبک‌های یکپارچهسازی
REST، XML، SOAP، وب‌هوک و GraphQL
تأمینکنندگان رابط‌های خود را در سبک‌های مختلف منتشر میکنند. سبک را مستندات تأمینکننده تعیین میکند نه سلیقه، بنابراین یک پلتفرم سفر باید همه آن‌ها را پشتیبانی کند.
REST و JSON
JSON- قالب داده
- اسناد JSON
- انتقال
- متدهای HTTP: GET، POST، PUT، DELETE
- رایج در صنعت سفر
- APIهای جدیدتر پرواز، هتل، فعالیت و پرداخت
- نقطه قوت
- payload فشرده و ابزارهای گسترده برای توسعه‌دهندگان
- مراقب باشید
- مشخصات سست؛ هر تأمینکننده REST را به شکلی متفاوت تفسیر میکند
XML و SOAP
XML- قالب داده
- اسناد XML، اغلب با یک schema سخت‌گیرانه
- انتقال
- HTTP POST با پاکت SOAP یا XML ساده
- رایج در صنعت سفر
- GDS، بدبانک‌ها و سیستم‌های جاافتاده هتل و تور
- نقطه قوت
- قراردادهای رسمی، امضاها و تعاریف سرویس
- مراقب باشید
- پیام‌های طولانی و تجزیه سنگین‌تر
وب‌هوک
EVENT- قالب داده
- JSON یا XML که طرف مقابل ارسال میکند
- انتقال
- HTTP POST به URLی که شما ثبت میکنید
- رایج در صنعت سفر
- نتایج پرداخت، تغییر وضعیت رزرو، به‌روزرسانی صدور بلیت
- نقطه قوت
- بدون polling؛ وقتی اتفاقی می‌افتد به پلتفرم شما اطلاع داده می‌شود
- مراقب باشید
- امضاها باید تأیید شوند و تکرارها مدیریت شوند
GraphQL
QUERY- قالب داده
- JSON، با شکلی که کوئری شما تعیین میکند
- انتقال
- یک نقطه پایانی HTTP واحد
- رایج در صنعت سفر
- برخی پلتفرمهای توزیع جدیدتر و APIهای داخلی
- نقطه قوت
- دقیقاً فیلدهایی را درخواست کنید که نیاز دارید
- مراقب باشید
- پشتیبانی تأمینکنندگان در صنعت سفر هنوز نادر است
یکپارچهسازی API در برابر توسعه API
محصول شما را به رابطی که از قبل وجود دارد متصل میکند. API متعلق به تأمینکننده است؛ شما کلاینت، نگاشت و قواعد پیرامون آن را می‌سازید.
رابطی میسازد که سیستم‌های دیگر برای اتصال به محصول شما از آن استفاده میکنند، مانند یک API B2B که ابزارهای نمایندگان شما می‌توانند فراخوانی کنند. قرارداد و نسخه‌هایش متعلق به شماست.
بسیاری از پروژه‌های سفر به هر دو نیاز دارند: پلتفرم از یک سو تأمینکنندگان را یکپارچه میکند و از سوی دیگر API خودش را برای نمایندگان و شرکا منتشر میکند.
قبل و بعد
وقتی سیستم‌ها یکپارچه میشوند چه تغییر میکند
همان پنج مرحله یک رزرو، یک بار با دست روی پورتال‌های تأمینکننده و یک بار از طریق یکپارچهسازی API.
جستجو
یک نماینده هر پورتال تأمینکننده را باز میکند و قیمت‌ها را در یک پیش‌فاکتور کپی میکند.
یک جستجو به همه تأمینکنندگان متصل ارسال می‌شود و یک فهرست واحد برمیگرداند.
قیمت
مارک‌آپ در یک صفحه‌گسترده اضافه می‌شود؛ تا زمان ارسال پیش‌فاکتور ممکن است نرخ تغییر کرده باشد.
مارک‌آپ، مالیات و قواعد ارزی در لحظه پاسخ اعمال میشوند؛ نرخ پیش از پرداخت بازبینی می‌شود.
رزرو
اطلاعات مهمان دوباره در پورتال تأمینکننده تایپ می‌شود؛ اشتباهات تایپی به خطای رزرو تبدیل میشوند.
اطلاعات یک بار ارسال، اعتبارسنجی و همراه با تأیید تأمینکننده ذخیره می‌شود.
پرداخت
پرداخت جداگانه دریافت می‌شود و بعداً با رزرو تطبیق داده می‌شود.
مجوز، برداشت و بازپرداخت به شماره مرجع رزرو گره خورده‌اند.
خدمات
لغو و تغییر یعنی یک ورود دیگر و یک ایمیل دیگر.
تغییرات و لغوها از همان اتصال عبور میکنند و رکورد را به‌روز میکنند.
یکپارچهسازی API در کجای یک پلتفرم سفر ظاهر می‌شود
- نرم‌افزار رزرو بلیط هواپیماچکلیست آژانسها و OTA برای فروش بلیط هواپیما
- موتور رزرو هتلرزرو مستقیم در وبسایت هتل خودتان
- نرم‌افزار تور اپراتوررزرو، برنامه سفر، فروشندگان B2B و عملیات
- سیستم اجاره خودروناوگان، شعب و ودیعههای خود را آنلاین اداره کنید
- یکپارچهسازی درگاه پرداختپرداخت، 3D Secure، بازپرداخت و webhook
- CRM آژانس مسافرتیسرنخ، پیش‌فاکتور، رزرو و فاکتور در یک CRM
واژگان
اصطلاحاتی که در مستندات API با آن‌ها روبه‌رو می‌شوید
دوازده واژه که تقریباً در پورتال توسعه‌دهندگان هر تأمین‌کننده‌ای دیده میشوند، به همان معنایی که در صنعت سفر به کار می‌روند.
API
Application programming interface: قواعد منتشرشده برای گفتگو با یک سیستم.
احراز هویت
اثبات اینکه چه کسی فراخوانی میکند، با کلید API، توکن bearer، امضا یا نشانی IP تأییدشده.
گواهیدهی
بازبینی یکپارچهسازی شما توسط تأمینکننده پیش از صدور اعتبارنامه‌های production.
نقطه پایانی
یک نشانی برای یک عملیات، مانند جستجو، رزرو یا لغو.
هم‌توانی (idempotency)
ارسال دو باره یک درخواست یکسان فقط یک نتیجه تولید میکند، که از رزرو و برداشت تکراری جلوگیری میکند.
نگاشت
ترجمه فیلدها، کدها و نام‌های تأمینکننده به مدل داده پلتفرم شما.
Payload
داده‌ای که درون یک درخواست یا پاسخ حمل می‌شود، معمولاً JSON یا XML.
محدودیت نرخ فراخوانی
تعداد فراخوانی‌هایی که یک تأمینکننده در ثانیه یا در روز مجاز می‌داند، پیش از آنکه شروع به رد کردن آن‌ها کند.
درخواست و پاسخ
یک فراخوانی: پلتفرم شما می‌پرسد، تأمینکننده پاسخ میدهد و هر دو طرف آن را ثبت میکنند.
Sandbox
محیط آزمایشی با موجودی ساختگی و کارت‌های آزمایشی که در آن هیچ چیز واقعاً رزرو یا برداشت نمی‌شود.
کد وضعیت
عدد HTTP که نتیجه را خلاصه میکند: 200 موفقیت، 401 غیرمجاز، 429 محدودیت نرخ، 500 خطای تأمینکننده.
وب‌هوک
فراخوانی در جهت مخالف: تأمینکننده یا درگاه هنگام وقوع رویداد به پلتفرم شما اطلاع میدهد.
آزمایش و تعیین دامنه
یک یکپارچهسازی API سفر پیش از راه‌اندازی چگونه آزمایش می‌شود
یک یکپارچهسازی فقط زمانی تمام است که مسیرهای خطا درست رفتار کنند. یک دور آزمایش روی sandbox تأمینکننده، پیش از گواهیدهی و تغییر به اعتبارنامه‌های production، موارد زیر را پوشش میدهد.
اجرای آزمون‌های یکپارچهسازی
sandbox تأمینکننده، نه مورد
- OK: احراز هویت با اعتبارنامه‌های معتبر و منقضی‌شده
- OK: رد درخواست نامعتبر با یک خطای خوانا
- OK: مدیریت timeout تأمینکننده بدون رزرو معلق
- OK: رعایت محدودیت نرخ و تلاش مجدد پس از انتظار
- OK: تشخیص تغییر قیمت در بازبینی و نمایش آن پیش از پرداخت
- OK: ارسال تکراری رزرو اول را برمیگرداند، نه رزرو دوم
- OK: اعمال لغو و محاسبه جریمه‌ها
- OK: صدور بازپرداخت روی پرداخت اصلی
- OK: تطبیق شماره‌های مرجع رزرو، پرداخت و تأمینکننده
همه موارد قبول شدند، آماده گواهیدهی
تعیین دامنه به چه چیزی از شما نیاز دارد
- 1قرارداد تأمینکننده، مستندات و اعتبارنامه‌های sandbox
- 2بازارها، ارزها، محصولات و نقش‌های کاربری
- 3دامنه جستجو، رزرو، تغییر، لغو و بازپرداخت
- 4الزامات گواهیدهی و فرایند دسترسی به production
آماده اتصال یک تأمینکننده
PHPTRAVELS تأمینکنندگان، درگاه‌ها و ابزارهای کسبوکار را در یک پلتفرم self-hosted که با کد منبع تحویل می‌شود یکپارچه میکند. برای سه طرح با پرداخت یک‌باره قیمت‌ها را ببینید، یا درباره یک API خاص از ما بپرسید.
پرسش‌ها
پاسخ به پرسش‌های یکپارچهسازی API
پاسخ‌های کوتاه به پرسش‌هایی که افراد پیش از نخستین پروژه یکپارچهسازی می‌پرسند.
گفتگو با فروشیکپارچهسازی API اتصالی است که به دو سیستم نرمافزاری اجازه میدهد بهطور خودکار داده مبادله کنند و عملیات را آغاز کنند. یک سیستم درخواستی ساختاریافته میفرستد، دیگری پاسخی ساختاریافته برمیگرداند و هر دو از قواعد توافقشده برای امنیت و داده پیروی میکنند.
در صنعت سفر، یک پلتفرم رزرو را به تأمینکنندگان پرواز، هتل، تور یا خودرو، درگاههای پرداخت و ابزارهای کسبوکار متصل میکند. از جستجو، اعتبارسنجی قیمت، رزرو، لغو، بازپرداخت و مغایرتگیری بدون تایپ مجدد پشتیبانی میکند.
REST یک سبک معماری است که معمولاً JSON را روی HTTP مبادله میکند. XML یک قالب داده است که هنوز میان تأمینکنندگان GDS و بدبانک رایج است و اغلب در SOAP بسته‌بندی می‌شود. قرارداد و مستندات تأمینکننده تعیین میکند کدام را استفاده کنید.
به دسترسی تأمینکننده، نقاط پایانی در دامنه، گواهیدهی، قواعد نگاشت و موارد خاص رزرو بستگی دارد. برآورد قابل اتکا پس از بررسی مستندات، اعتبارنامهها و گردشکارهای مورد نیاز شما به دست میآید.
احراز هویت، درخواستهای معتبر و نامعتبر، timeout، محدودیت نرخ، تغییر قیمت، ارسال تکراری، لغو، بازپرداخت و مغایرتگیری را آزمایش کنید. در production هر درخواست باید به یک شماره مرجع رزرو قابل ردیابی باشد.
خیر. یکپارچهسازی محصول شما را به یک API موجود متصل میکند؛ توسعه رابطی میسازد که دیگران به آن متصل میشوند. پلتفرمهای سفر اغلب به هر دو نیاز دارند: تأمینکنندگان یکپارچهشده در یک سو و یک API B2B منتشرشده برای شرکا در سوی دیگر.
بیشتر بدانید
بیشتر درباره پلتفرم
- یکپارچهسازی API سفراتصال تأمینکنندگان XML و JSON با PHP
- APIهای سفرAPIهای GDS، هتل، تور، خودرو و پرداخت
- همه یکپارچهسازیهافهرست کامل و به‌روز
- یکپارچهسازی درگاه پرداختپرداخت، 3D Secure، بازپرداخت و webhook
- یکپارچهسازی API سفارشیهر API تأمینکننده یا شریک را به PHPTRAVELS وصل کنید
- فناوریزیرساخت فنی پشت صحنه