ملاحظات عمومی

راهنمای اشکال‌یابی​

• به نوع درخواست دقت کنید، احتمال دارد درخواست از نوع HTTP POST باشد و شما از GET استفاده کرده باشید.
• آدرس API را مجددا بررسی نمایید. همچنین به وجود یا عدم وجود / در انتهای آدرس دقت کنید.

تنظیم User-Agent برای بات‌ها​

برای شناسایی بات، اعمال محدودیت فراخوانی مناسب و ساده‌تر شدن پشتیبانی، در همه درخواست‌های HTTP بات هدر User-Agent را با الگوی TraderBot/<name-and-version> ارسال کنید. بخش بعد از / باید نام و نسخه بات را به‌صورت یکتا مشخص کند؛ برای نمونه: TraderBot/MyBot-1.0.0.

این هدر هنگام ورود خودکار با captcha=api الزامی و در سایر فراخوانی‌های بات اکیداً توصیه می‌شود. پارامتر مربوط به آن نیز در بخش Header Parameters همه APIهای HTTP نمایش داده می‌شود.

پاسخ‌های موفق​

نمونه پاسخ موفق:

{
  "status": "ok",
  "otherFields": "..."
}

در بیشتر APIها، در صورت موفقیت عملیات، پاسخ به‌صورت یک شیء JSON و معمولاً با وضعیت HTTP 200 بازگردانده می‌شود. مقدار رایج کلید status برابر ok است، اما بعضی endpointها مقدار دیگری مانند success دارند یا از کد موفقیت متفاوتی استفاده می‌کنند. کد HTTP و ساختار دقیق پاسخ در صفحه همان endpoint مشخص شده است.

پاسخ‌های ناموفق​

نمونه پاسخ ناموفق:

{
  "status": "failed",
  "code": "ErrorCode",
  "message": "Human-readable error message"
}

در تمامی APIها در صورتی که به هر دلیل امکان پردازش و انجام آن درخواست وجود نداشته باشد، یک پاسخ ناموفق بازگردانده می‌شود. پاسخ‌های ناموفق به دو صورت هستند، یا با کد خطای HTTP مشخص می‌شوند که مطابق با معانی وضعیت در پروتکل HTTP قابل تفسیر هستند.

در برخی endpointهای قدیمی، ممکن است درخواست ناموفق نیز با وضعیت HTTP 200 و مقدار failed در کلید status بازگردانده شود. endpointهای دیگر برای این حالت از کدهای خطای HTTP مانند 400، 409 یا 422 استفاده می‌کنند؛ بنابراین همیشه کد HTTP و ساختار پاسخ مستندشده در صفحه همان endpoint را مبنا قرار دهید. کلید code خطای دقیق رخ‌داده را مشخص می‌کند و کدهای ممکن در بخش «حالت‌های خطا» هر API آمده‌اند. معمولاً کلید message نیز توضیح بیشتری برای اشکال‌یابی ارائه می‌کند.

برخی وضعیت‌های پرکاربرد​

صفحه‌بندی

پارامترهای زیر در API های دریافت لیست دارای صفحه‌بندی قابل استفاده است:

فیلتر زمانی

پارامترهای زیر در API های دریافت لیست قابل فیلتر زمانی قابل استفاده است:

این جدول قالب رایج فیلتر تاریخ را نشان می‌دهد. بعضی endpointها به‌جای تاریخ از Unix timestamp استفاده می‌کنند؛ نوع و واحد دقیق در صفحه همان endpoint مشخص شده است.

مقادیر پولی (monetary)​

در موارد متعددی پارامترهای ورودی درخواست‌ها از نوع مقدار پولی یا monetary مشخص شده است. برای داشتن بالاترین دقت، پیشنهاد می‌شود که این مقادیر را به صورت رشته‌ای ارسال نمایید، چرا که استفاده از انواع داده‌ای مانند float در کاربردهای دقیق مالی توصیه نمی‌شود.

اعتبارسنجی دو عاملی​

در صورتی که اعتبارسنجی دو عاملی (2 Factor Authentication) را برای حساب خود فعال کرده باشید، باید در هنگام استفاده از برخی APIها، به خصوص در هنگام دریافت توکن از API لاگین، علاوه بر سایر پارامترها، رمز یک‌بار مصرف خود را نیز در هدرهای درخواست به این صورت ارسال نمایید: X-TOTP: 123456.

محدودیت فراخوانی

نمونه پاسخ ناموفق:

{
  "status": "failed",
  "code": "TooManyRequests",
  "message": "تعداد درخواست شما بیش از حد معمول تشخیص داده شده. لطفا 12 ثانیه صبر نمایید.",
  "backOff": 12,
  "limit": 60
}

برخی از APIهای نوبیتکس دارای محدودیت تعداد فراخوانی در هر بازه‌ی زمانی هستند. با این حال اگر شما به صورت معمولی و مشابه استفاده‌ی متداول کاربران از API استفاده کنید، با این محدودیت‌ها مواجه نخواهید شد. محدودیت‌ها به ازای هر API مستقلا محاسبه و اعمال می‌شوند. محدودیت‌ها معمولا بر اساس آدرس IP درخواست دهنده و در برخی موارد هم بر اساس کاربر (توکن) درخواست دهنده می‌باشند.

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

برای ارسال مجدد درخواست به همان آدرس، لازم است به اندازه مقدار مشخص‌شده در پارامتر backOff (به واحد ثانیه) صبر کنید. پارامتر limit سقف مجاز تعداد درخواست را در بازه مشخص‌شده نشان می‌دهد.

محدودیت‌های استفاده از APIها بر اساس ظرفیت پردازشی نوبیتکس یا به منظور حفظ امنیت برای هر کاربر تعیین می‌شود تا کیفیت خدمات برای همه کاربران به‌طور یکنواخت حفظ گردد. در زمان‌های ازدحام شدید بازار، به‌منظور ایجاد فرصت برابر برای همه کاربران، ممکن است محدودیت فراخوانی یک API به ازای یک کاربر کاهش یابد.

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

محدودیت مشترک APIهای سفارش‌گذاری

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

مقدار محدودیت مشترک: ۳۰۰ درخواست در ۱۰ دقیقه

محدودیت احراز ناموفق

به منظور حفاظت از امنیت حساب‌های کاربران، در صورتی که بیش از ۱۰۰ درخواست با توکن اشتباه (یا منقضی) از یک آدرس IP در مدت زمان کمتر از ۳۰ دقیقه ارسال شود، آن IP تا پایان این بازه زمانی مسدود خواهد شد. برای پیشگیری از بروز این مسئله، توصیه می‌شود فرایند تولید و تجدید توکن خود را مطابق با توضیحات احراز هویت مدیریت نمایید.

حالت متداول و Pro​

در برخی از درخواست‌ها جهت حفاظت بهتر از کاربران، برخی محدودیت‌ها اعمال می‌شود. در چنین مواردی در بخش ملاحظات این محدودیت‌ها توضیح داده شده و در انتهای آن عبارت «غیرفعال در حالت Pro» ذکر شده است. با ارائه پارامتر pro به مقدار yes به عنوان ورودی، این محدودیت برای آن درخواست غیرفعال می‌شود. با این حال دقت کنید که محدودیت‌های حالت متداول برای جلوگیری از حالت‌های خاص و اشتباهات رایج تعبیه شده است و تنها در صورت نیاز و آگاهی از تبعات احتمالی آن، اقدام به فعال‌سازی حالت Pro نمایید.