راهنمای یکپارچهٔ API

چهار خانوادهٔ API

قرارداد هر مسیر را جدا بخوانید

الگوی احراز هویت همهٔ مسیرها یکسان نیست. مسیرهای وب ممکن است نشست مبتنی بر کوکی داشته باشند؛ یک API شبکه یا ارائه‌دهندهٔ بیرونی قرارداد دیگری دارد. کلید Wallex یا Ondo را به‌عنوان رمز ورود پلانک به API مشتری ارسال نکنید. جدول هر صفحه، روش HTTP، مسیر، دسترسی و رفتار واقعی آن مسیر را مشخص می‌کند.

پاسخ HTTP موفق به‌تنهایی نشان‌دهندهٔ کامل بودن همهٔ داده‌ها نیست؛ mode، پرچم دسترس‌پذیری داده، timestamp و خطای جزئی همان پاسخ نیز اهمیت دارند. برای مثال خالی بودن تاریخچهٔ بازار می‌تواند همراه با پاسخ موفق اطلاعات اصلی بازار باشد.

نمونهٔ خواندن کاتالوگ عمومی

این نمونه فقط دادهٔ عمومی را می‌خواند و سفارش، پرداخت یا تغییر حساب ایجاد نمی‌کند. فیلدهای دقیق مدل در مرجع API مارکت‌پلیس توضیح داده شده‌اند.

const response = await fetch("/api/catalog");
const catalog = await response.json();
if (!response.ok || catalog.mode === "unavailable") {
  throw new Error("Catalog is unavailable");
}
console.log(catalog.mode, catalog.projects);

عدد، زمان و ارز

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

مدیریت خطا و تکرار درخواست

کدهای ۴۰۰ برای ورودی نامعتبر، ۴۰۱/۴۰۳ برای دسترسی و ۵۰۳ برای سرویس ناموجود یا فعال‌نشده در مسیرهای مختلف به کار می‌روند؛ پاسخ دقیق هر مسیر مرجع نهایی است. هر خطا را به پیام روشن برای کاربر تبدیل کنید و جزئیات محرمانهٔ پاسخ ارائه‌دهنده را نمایش ندهید.

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

مراجع قراردادها