تعاریف

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

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

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

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


نکات کلی


لطفا دقت نموده که به همراه تمامی درخواست های خود، 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 باید موارد زیر را به سپهر اعلام نمایید:

برای تراست کردن IP، نیازی نیست که رمز عبور خود را به سپهر ارسال کنید و فقط ارسال موارد فوق کفایت می کند.

درخواست خود را می توانید از طریق تلگرام به شماره تلفن 3333-615-0935 ارسال نمایید.

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


نحوه ی برگشت خطا

هنگام بروز خطا در هر یکی از متدها، سیستم سپهر http کد 500 را به همراه json زیر بر می گرداند:

{
  "ErrorMessage": "شرح خطا....",
  "ExceptionType": "System.Exception",
  "TraceId": "2345245"
}

در صورتی که قصد دارید خطای برگشتی را Deserialize نموده و ErrorMessage را از داخل آن استخراج نمایید، حتما اینکار را داخل try/catch انجام دهید که اگر یک زمان به هر دلیل خطای برگشتی از سیستم ما فرمت نمایش داده شده در بالا را نداشت، شما متن اصلی خطا را از دست ندهید. نمونه اینکار در سورس کد نمونه انجام شده است.

در صورت تمایل به دریافت خطاهای معمول – به عنوان مثال اتمام شارژ مالی حساب – می توانید با پشتیبانی سپهر تماس حاصل نموده و درخواست خود مبنی بر کاهش اعتبار روی سایت تستی SepehrApiTest.ir اعلام نمایید. بدین صورت می توانید برگشت خطا را شبیه سازی نموده و پیاده سازی خود را بر اساس آن تکمیل نمایید.


عدم پشتیبانی از درخواست های Chunked

در حال حاضر هیچ کدام از Api های سپهر از دریافت دیتا به روش Chunked پشتیبانی نمی کنند. بنابراین لطفا از ارسال اطلاعات با هدر Transfer-Encoding: chunked خودداری نمایید.

اگر از .Net Core استفاده می نمایید لطفا به این نکته توجه فرمایید که درخواست های HttpClient در .Net Core معمولا به صورت chunked ارسال می گردند. جهت اطلاعات بیشتر به مقاله How to prevent ASP.NET Core sending requests chunked مراجعه نمایید.


پشتیبانی و پیگیری مشکلات

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

لاگ Request می بایست شامل موارد زیر باشد:

لاگ Response می بایست شامل موارد زیر باشد:

در صورتی که لاگ Request و Response شامل موارد فوق نباشد، از پیگیری مشکل معذور هستیم.

در صورتی که خطای برگشتی از سرور از خانواده خطای 400 (مثلا 404 یا 405) باشد، بدین معنی است که در Request ارسالی مشکلی وجود دارد. و بهترین روش برای پیدا کردن این گروه خطاها، مقایسه request که ارسال نموده اید با request ارسالی توسط نمونه سورس کد می باشد.

یکی از ابزارهایی که در زمینه بدست آوردن Request/Response می تواند به شما کمک کند، نرم افزار رایگان Fiddler Classic که می توانید از اینجا دانلود نمایید. این ابزار مخصوص استفاده در محیط توسعه و تست می باشد و به هیچ عنوان پیشنهاد نمی گردد روی سرور اصلی نصب شود.