قبل از شروع!

• پیش نیازها و شرایط اخذ API چارتری
• داشتن مجوز بند (الف) از سازمان هواپیمایی کشوری
• داشتن سرویس با قابلیت هاب ایرپلاس
• تعاریف و اصطلاحات استفاده شده در مستندات
• نکات کلی و ابتدایی راه اندازی سرویس
• Header های اجباری برای تمامی درخواست ها
• استفاده از Https و TLS
• نحوه ی تراست کردن IP
• متدهای قابل پشتیبانی
• ورژن بندی سرویس
• مدیریت خطاها – Error handling
• مقدمه ای بر Error Handling
• نحوه نگارش خطاها
• Status Code – کدهای وضعیتی درخواست ها
• خطاهایی که در قالب Response دریافت میشود
• دریافت جزئیات خطا از طریق API
• سربرگ – Header
• مقادیر ارسالی – Request Data
• پاسخ صحیح – Response True
• پاسخ نادرست – Response False
• دریافت لیست خطا ها و راه حل ها – Get Errors
• دریافت لیست ارور ها از طریق API
• سربرگ – Header
• مقادیر ارسالی – Request Data
• پاسخ صحیح – Response True
• پاسخ نادرست – Response False

پیش نیازها و شرایط اخذ API چارتری

داشتن مجوز بند (الف) از سازمان هواپیمایی کشوری

آژانس های بند الف تحت نظارت مستقیم سازمان هواپیمایی کشوری هستند و وظیفه اصلی آنها فروش بلیط خطوط هوایی داخلی و خارجی است. آژانس های بند الف به هیچ عنوان حق برگزاری تور را ندارند. همچنین مجوز فروش تورهای سایر دفاتر برگزار کننده را نداشته و مجاز به عقد قرارداد تور با مسافر نیستند.

داشتن سرویس با قابلیت هاب ایرپلاس

یکی دیگر از پیش نیاز های اتصای به سرویس چارتری داشتن سرویس  با قابلیت هاب ایرپلاس از مجموعه می باشد. این سرویس پس از گذراندن مراحل مختلف اخذ و پس از آن میتوانید از طریق پنل درخواست ارتباط خود را ارسال فرمائید.

تعاریف و اصطلاحات استفاده شده در مستندات

لطفا در هنگام استفاده از مستندات، تعاریف زیر را مد نظر داشته باشید:

تامین کننده: منظور آژانس مسافرتی و یا سرویس  است که شما در حال استفاده از API آن می باشید.

پروازهای چارتری: به پروازهایی گفته می شود که تامین کننده مالک سهمیه و نرخ آن پرواز می باشد.

پروازهای وب سرویسی: به پروازهایی گفته می شود که تامین کننده مالک آنها نیست و خود از طریق وب سرویس از یک تامین کننده دیگر آن پروازها را دریافت کرده است.

متد: منظور webapi یا تابعی هست که شما با استفاده از یک Url و روی بستر Https آن را فراخوانی می کنید.

کلاینت: یا Client به شخصی که از متدهای وب سرویس استفاده می کند اشاره دارد. معمولا منظور شخص خواننده – شما – هستید.

موتور جستجو: به کلاینتی گفته می شود که فروش بلیط انجام نمی دهد و با نمایش پروازها، مسافر را به سایت تامین کننده هدایت می کند.

آژانس آنلاین: یا OTA به کلاینتی گفته می شود که به مسافر فروش بلیط انجام می دهد.

نکات کلی و ابتدایی راه اندازی سرویس

1. پیش نیاز کار با این سرویس داشتن دانش فنی مانند (Rest-full API, JWT Authentication) و آشناییت کامل با عملیات های چارتری و رزرو بلیت، هتل و خدمات.
2. جهت استفاده از سرویس ایرپلاس، نیاز است که IP شما در هسته مرکزی Trust گردد. Trust کردن تا 2 عدد IP به صورت رایگان انجام می پذیرد. اما لطفا در نظر داشته باشید فرایند اداری و فنی اینکار ممکن است تا 1 روز کاری زمان ببرد.
3. در سیستم ایرپلاس، تامین کننده می تواند برای هر کاربر (کلاینت) نرخ و ظرفیتی اختصاصی را تعریف نماید. بنابراین لطفا حتما دقت فرمایید که با همان کاربری که بعدا می خواهید رزرو انجام دهید درخواست های Availability خود را ارسال نمایید. در غیر این صورت و هنگام متفاوت بودن نرخ یا ظرفیت، رزرو شما به خطا برخورد خواهد کرد.
4. هیچ کدام از اسم متدها، یا پارامترهای ارسالی به آنها، Case Sensitive نیست و بزرگ یا کوچک بودن حروف هنگام کار با آنها، تاثیری در نتیجه ندارد.
5. برای تست می توانید از بخش پشتیبانی درخواست سرویس دمو فرمائید و پس از آن به عنوان تامین کننده استفاده نمایید. همچنین اطلاعات پروازها و مسیرهایی که می توان روی آنها رزرو تستی انجام داد در صفحه کار با سرویس دمو موجود می باشد.
6. در حالت هایی ممکن است DNS های سایت یک تامین کننده بدون اطلاع قبلی تغییر پیدا کند. و اگر شما در زمان توسعه نرم افزار خود از یک object به صورت singleton برای مدیریت درخواست های http خود استفاده کرده باشید، ممکن است متوجه تغییرات DNS نشده و درخواست های شما با خطا روبرو شود. بنابراین در زمان توسعه نرم افزار خود این مورد را در نظر داشته باشید.

Header های اجباری برای تمامی درخواست ها

لطفا دقت نموده که به همراه تمامی درخواست های خود، header های زیر را نیز ارسال نمای

HTTP

//(required) - 1
Content-Type: application/json; charset=utf-8
//(required) - 2
Accept: application/json
//(required) - 3
Accept-Encoding: gzip, deflate

1. استفاده از این Header مشخص می کند که فرمت درخواست شما json بوده و encoding که برای ارسال اطلاعات استفاده شده utf-8 می باشد.
2. استفاده از این Header به هسته مرکزی اعلام می کند که باید جواب را به صورت json برگشت دهد.
3. استفاده از این Header باعث می گردد جواب برگشتی از سرور به صورت فشرده شده باشد

استفاده از Https و TLS

تمام در خواست های ارسالی به هسته مرکزی الزاما باید از بستر HTTPS استفاده نمایند. و درخواست های بدون SSL و روی بستر HTTP را پشتیبانی نمی شود.

همچنین زمان ارسال درخواست حتما از Tls ورژن 1.2 استفاده کنید. اینکار در .Net به صورت زیر انجام می شود:

System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12;

در صورتی که از پلتفرمی غیر از .Net برای توسعه نرم افزار خود استفاده می کنید، جهت استفاده از Tls 1.2 به مستندات پلتفرم مربوطه مراجعه کنید.

نحوه ی تراست کردن IP

جهت استفاده از وب سرویس باید IP شما در اتوماسیون Trust شود. از آنجایی که در سیستم تراست کردن IP بر اساس کاربر و روی هر سایت تامین کننده به صورت جداگانه انجام می شود، جهت تراست کردن IP باید از طریق پنل کاربری خود نسبت به ارسال درخواست در قسمت پشتیبانی اقدام فرمائید.

متدهای قابل پشتیبانی

سرویس فعلی از متدهای زیر پشتیبانی می کند

ورژن بندی سرویس

در حال حاضر طبق جدول ذیل ورژن 1 سرویس در حال اجرا می باشد.

این ورژن از پایداری بسیار بالایی برخوردار است. همچنین کلیه موارد امنیتی در این نسخه بصورت کامل رعایت شده است.

قابل توجه است در صورت تغییر ورژن از قبل اطلاع رسانی خواهد شد و مدت زمان معینی جهت مهاجرت به ورژن جدید اختصاص داده خواهد شد و پس از آن ورژن قبلی به فعالیت خود خاتمه خواهد داد.

مدیریت خطاها – Error handling

مقدمه ای بر Error Handling

قبل از هر چیز لازم است بدانیم مدیریت خطا یا error handling به چه معناست. این اصطلاح به واکنش و مکانیسم‌های بازیابی نرم‌افزار در صورت بروز خطا اشاره می‌کند. به عبارت دیگر این کار فرآیندی است که شامل پیش‌بینی دقیق، شناسایی و رفع خطاها در برنامه‌ها است.

اجرای منظم یک برنامه از طریق مدیریت خطا آسان‌تر است. وقتی صحبت از رویکردهای خطا handling می‌شود، بسیاری از برنامه‌ها با مشکلات معماری نرم‌افزار مواجه می‌شوند.

توجه داشته باشید که API AirPlus کامل منطق بر اصول RESTful API نوشته شده است پس بنابراین پاسخ تمام درخواست ها با Status Code مورد نظر خود ارسال خواهد شد و مدیریت این Status Code ها یا هما کدهای وضعیتی در برنامه شما الزامیست.

طبق اصول کلی تمام پاسخ های صحیح با کد وضعیتی 200 ارسال خواهند شد.

اما اتوماسیون ایرپلاس در زمینه مدیریت خطاها هم مستندات جامع و کاربردی را تهیه نموده است.

نحوه نگارش خطاها

پاسخ نادرست – Response False یا همان مشکل در ارسال اطلاعات

{
    "status": false,
    "time": "Timestamp", // Timestamp
    "code": "Error Code"
}

Status Code – کدهای وضعیتی درخواست ها

 وضعیت 200 — OK

کد وضعیت 200 OK نشان می‌دهد که درخواست به‌درستی توسط سرور دریافت، درک و پردازش شده و پاسخ استاندارد حاوی داده‌های درخواست‌شده را بازگردانده است.

طبق RFC 9110 (HTTP Semantics, 2022)، این کد برای موفقیت عمومی تمام متدهای HTTP استفاده می‌شود؛ در پاسخ به GET معمولاً به معنی دریافت محتوای صحیح است، در PUT و DELETE به معنی انجام کامل عملیات است.

در صورت دریافت 200، کلاینت می‌تواند فرض کند که هیچ خطایی در فرآیند ارتباط وجود نداشته و پاسخ معتبر است.

 وضعیت 201 — Created

کد 201 Created نشان می‌دهد که درخواست با موفقیت انجام شده و منبع جدیدی ایجاد شده است.

بر اساس RFC 9110، این پاسخ اغلب برای متدهای POST و گاهی PUT استفاده می‌شود. سرور می‌تواند هدر Location را شامل URI منبع تازه ایجادشده برگرداند تا کلاینت بتواند به آن دسترسی پیدا کند.

نمونه: هنگام ثبت سفارش یا خرید بلیت، اگر ایجاد آیتم در پایگاه داده موفقیت‌آمیز باشد، سرور وضعیت 201 بازمی‌گرداند.

 وضعیت 204 — No Content

کد 204 No Content به معنی موفقیت‌آمیز بودن درخواست بدون نیاز به ارسال محتوای جدید در پاسخ است.

این کد معمولاً در پاسخ به متدهای PUT, PATCH, DELETE یا POST استفاده می‌شود، زمانی‌که عمل مورد‌نظر در سرور انجام شده ولی داده‌ای برای بازگرداندن وجود ندارد.

مثال: API حذف رزرو در صورت موفق بودن حذف، بدون بدنهٔ پاسخ، وضعیت 204 ارسال می‌کند.

 وضعیت 207 — Multi‑Status

کد 207 Multi‑Status بخشی از استاندارد WebDAV (RFC 4918) است.

این کد زمانی استفاده می‌شود که یک درخواست شامل چندین عملیات یا منبع باشد و پاسخ برای هر مورد جداگانه در قالب XML یا JSON شامل وضعیت مجزا ارائه گردد.

به‌طور مثال در یک درخواست جمعی برای بروزرسانی چند فایل، اگر بعضی پردازش شوند و بعضی خطا بدهند، پاسخ 207 حاوی نتیجهٔ جزئی هر فایل ارسال می‌شود.

 وضعیت 400 — Bad Request

کد 400 Bad Request نشان‌دهندهٔ آن است که سرور نمی‌تواند یا نمی‌خواهد درخواست را پردازش کند زیرا در نحو (syntax) یا ساختار داده‌های درخواست خطا وجود دارد.

علل رایج: بدنه غیرقابل parse شدن، مقادیر ناقص، هدرهای نادرست یا شناسهٔ توکن نامعتبر.

این خطا ناشی از اشتباه سمت کلاینت است و معمولاً با پیام‌هایی نظیر invalid JSON یا missing parameter همراه می‌شود.

 وضعیت 404 — Not Found

کد 404 Not Found زمانی برگردانده می‌شود که منبع یا مسیر مورد نظر در سرور وجود ندارد یا حذف شده است.

از دید API یعنی Endpoint یا URI درخواستی شناسایی نمی‌شود.

دلایل معمول: آدرس غلط، تغییر نسخهٔ سرویس، پایان پشتیبانی از مسیر قبلی (deprecated endpoint).

راه‌حل: بررسی مجدد URL و در صورت نیاز به‌روزرسانی URI مورد استفاده.

 وضعیت 405 — Method Not Allowed

کد 405 Method Not Allowed یعنی URI مورد درخواست معتبر است، اما متد (مثلاً POST یا DELETE) توسط سرور برای آن مسیر مجاز نیست.

در پاسخ معمولاً هدر Allow شامل لیستی از متدهای مجاز مثل GET, PUT برگردانده می‌شود.

این خطا از نوع کلاینت است و نشانهٔ استفاده از متد غیرفعال برای endpoint خاص می‌باشد.

 وضعیت 409 — Conflict

کد 409 Conflict به معنی وجود تعارض در وضعیت فعلی منبع است که مانع انجام عملیات می‌شود.

این خطا زمانی بازگردانده می‌شود که درخواست در تضاد با داده‌های موجود باشد، مثلاً تلاش برای ایجاد رکورد تکراری یا بروزرسانی نسخهٔ قدیمی شیء.

در سيستم‌های دارای نسخه‌بندی و کنترل همزمان (مثل وب‌سایت رزرو یا فرم ثبت آیتم تکراری) کاربرد دارد.

 وضعیت 422 — Unprocessable Entity

کد 422 Unprocessable Content (نام جدید در RFC 9110، ‌قبلاً Unprocessable Entity در RFC 4918 بود) زمانی ارسال می‌شود که درخواست از نظر نحوی درست است ولی داده‌های آن از نظر منطقی یا اعتبارسنجی نامعتبر است.

مثلاً فیلدهای الزامی خالی‌اند یا مقادیر بعضی پارامترها خارج از محدودهٔ مجاز هستند.

این کد معمولاً در APIهایی که قبل از پردازش داده، validation دقیقی انجام می‌دهند (مثلاً در فرم‌های ثبت اطلاعات) استفاده می‌شود.

 وضعیت 500 — Internal Server Error

کد 500 Internal Server Error بیانگر خطای عمومی در سمت سرور است، بدون اشاره به علت دقیق.

معمولاً در اثر بروز استثنا (Exception)، نقص در پیکربندی، یا قطع ارتباط سرویس وابسته رخ می‌دهد.

این خطا قابل تشخیص برای کلاینت نیست و صرفاً به معنی شکست درخواست در سطح سرور است.

توصیهٔ استاندارد: بررسی log سرور، و در صورت نیاز ارائه سرویس پشتیبان یا fallback endpoint برای حفظ پایداری ارتباط.

خطاهایی که در قالب Response دریافت میشود

این خطا ها در قالب Response False بصورت کد دریافت میشوند که میتوانید در متن خطا ها و راه حل آنها را در جدول زیر مشاهده نمائید.

در ضمن میتوانید از طریق API زیر بصورت داینامیک این خطاها را دریافت و مدیریت نمائید.

دریافت جزئیات خطا از طریق API

سربرگ – Header

در این روش شما باید درخواست خود را از طریق لینک زیر ارسال فرمائید.

{{Api Url}}/error-handling

HEADER
GET /api/reservation/{{Api version}}/error-handling HTTP/1.1
Host: {{Your Host}}
Authorization: Bearer JWTToken
Content-Type: application/json
Domain: {{Your Domain}}

API Url از طریق پنل کاربری قابل مشاهده خواهد بود

مقادیر ارسالی – Request Data

{
    "code": "Error Code"
}

پاسخ صحیح – Response True

دریافت این پاسخ با Status Code 200 دریافت خواهد شد.

{
    "status": true,
    "time": "Timestamp", // Timestamp
    "data": [
        {
            "title": "Error title in Persian",
            "solution": "How to solve errors in Persian"
        },
        ...
    ]
}

پاسخ نادرست – Response False

{
    "status": false,
    "time": "Timestamp", // Timestamp
    "code": "Error Code"
}

دریافت لیست خطا ها و راه حل ها – Get Errors

دریافت لیست ارور ها از طریق API

سربرگ – Header

در این روش شما باید درخواست خود را از طریق لینک زیر ارسال فرمائید.

{{Api Url}}/errors

HEADER
GET /api/reservation/{{Api version}}/errors HTTP/1.1
Host: {{Your Host}}
Content-Type: application/json
Domain: {{Your Domain}}

API Url از طریق پنل کاربری قابل مشاهده خواهد بود.

مقادیر ارسالی – Request Data

{
    "code": error code
}

پاسخ صحیح – Response True

هنگام ارسال کلید code جواب دریافتی به صورت زیر میباشد.

پاسخ نادرست – Response False

{
  "error": {
    "code":"Error Code"
  },
  "meta": {
    "timestamp": "Timestamp" // Timestamp
  }
}

در صورت مشاهده Status Code 404 URL درخواست خود را به اشتباه وارد نموده اید.