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

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

• به نوع درخواست دقت کنید، احتمال دارد درخواست از نوع 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 دارد. بنا به API مورد استفاده ممکن است یک یا چند کلید دیگر نیز در این پاسخ بازگردانده شود.

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

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

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

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

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

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

صفحه‌بندی

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

فیلتر زمانی

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

مقادیر پولی (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 نمایید.