نکات کلی فنی

تعاریف

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

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

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

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

نکات کلی
  • جهت استفاده از وب سرویس‌های سپهر، نیاز است که IP شما در سایت تامین کننده Trust گردد. Trust کردن تا 3 عدد IP به صورت رایگان انجام می پذیرد. جهت این کار باید IP خود به همراه نام کاربری که قصد ارسال ریکوئست به APIهای ربات سپهر دارد را به ما ارائه دهید. اما لطفا در نظر داشته باشید فرایند اداری و فنی اینکار ممکن است تا 3 روز کاری زمان ببرد.
  • استفاده از ربات B2M سپهر، تنها برای مدیر سیستم مجاز است لذا جهت استفاده نیاز به کاربری با سطح دسترسی دفترمرکزی است.
  • هیچ کدام از اسم متدها، یا پارامترهای ارسالی به آنها، Case Sensitive نیست و بزرگ یا کوچک بودن حروف هنگام کار با آنها، تاثیری در نتیجه ندارد.
  • برای تست می توانید از سایت SepehrApiTest.ir به عنوان تامین کننده استفاده نمایید.
  • اگر آدرس سایت یک تامین کننده دارای www بود، پیشهاد می گردد درخواست های خود را به آدرس بدون www ارسال نمایید. زیرا تنظیمات سایت برخی از تامین کنندگان به گونه ای است که اگر شما به www آن سایت درخواست بزنید، خطا دریافت خواهید کرد. مثال: سایت محیط تست هم به آدرس https://www.SepehrApiTest.ir و هم آدرس https://SepehrApiTest.ir در دسترس می باشد، در این حالت درخواست های خود را به https://SepehrApiTest.ir ارسال نمایید.
  • در حالت‌هایی ممکن است DNS های سایت یک تامین کننده بدون اطلاع قبلی تغییر پیدا کند. و اگر شما در زمان توسعه نرم افزار خود از یک object به صورت singleton برای مدیریت درخواست های http خود استفاده کرده باشید، ممکن است متوجه تغییرات DNS نشده و درخواست های شما با خطا روبرو شود. بنابراین در زمان توسعه نرم افزار خود این مورد را در نظر داشته باشید. جهت اطلاعات بیشتر پیشنهاد می گردد این مقاله مطالعه گردد.
  • سوالات فنی خود را به صورت پیام صوتی یا متن روی تلگرام به شماره 3333-228-0935 ارسال نمایید. 
  • سوالات غیر فنی – مانند تراست کردن IP یا نحوه انعقاد قرارداد – را به صورت پیام صوتی یا متن روی تلگرام به شماره 3333-615-0935 ارسال نمایید. 
Header های اجباری برای تمامی درخواست ها

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

Content-Type: application/json; charset=utf-8

required

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

Accept: application/json

required

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

Accept-Encoding: gzip, deflate

required

استفاده از این 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 روی آن انجام شود. مثلا برای محیط تست این آدرس برابر SepehrApiTest.ir می باشد.
  • نام کاربری شما در سایت آن تامین کننده.
  • لیست IP هایی که تمایل دارید تراست شوند.

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

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

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

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

نمونه Response در زمان بروز خطا 
{
  "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 می بایست شامل موارد زیر باشد:

  • آدرس سایت و متدی که به آن درخواست ارسال نموده اید.
  • زمان ارسال درخواست
  • Header های ارسالی
  • محتوای Json درخواست
  • مشاهده نمونه Request

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

  • زمان دریافت جواب
  • Header های دریافتی
  • محتوای جواب. لطفا دقت نمایید که عینا جوابی که سپهر برای شما ارسال کرده است را به عنوان لاگ برای ما ارسال نمایید. و از تبدیل کردن جواب به مدل خود یا دستکاری آن خودداری نمایید.
  • مشاهده نمونه Response

     

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

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

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