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

مسیرها، مدل دسترسی، واحدها، پاسخ خطا و تفاوت سرویس وب و شبکه.

وضعیت: مرجع | مخاطب: توسعه‌دهنده و یکپارچه‌ساز
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

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

| خانواده | مبدأ | کاربرد |
| --- | --- | --- |
| عمومی بازار | مبدأ مارکت‌پلیس | کاتالوگ و دادهٔ بازار |
| مشتری | مبدأ مارکت‌پلیس با نشست مشتری | حساب، هویت، بانک و اتصال کیف پول |
| مدیریت | مبدأ مستقل مدیریت با نشست و نقش مدیر | کاتالوگ، اتصال‌ها، محتوا و بررسی‌ها |
| شبکه | سرویس محلی یا دروازهٔ مجاز همان محصول | پایش و عملیات Admin Main / Station / Besu |

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

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

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

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

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

```javascript
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 طبق قرارداد همان مسیر داده را ارسال کنید.
- تومان و ریال را بدون تبدیل صریح جایگزین نکنید؛ مقدار پایهٔ کاتالوگ در ریال نگهداری می‌شود.
- برای مقدار دقیق مالی و تعداد توکن، از تبدیل بی‌ضابطه به اعشار شناور خودداری کنید.
- زمان آخرین دریافت قیمت و در دسترس بودن داده را جدا از مقدار قیمت نمایش دهید.
- برای قیمت دلاری، نرخ تبدیل و واحد نهایی را همراه عدد گزارش کنید.

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

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

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

> نسخه‌بندی: مسیرهای وب فعلی عمدتاً بدون پیشوند نسخه ارائه شده‌اند. این مستندات قرارداد ثابت یک API عمومی دارای SLA یا مجوز دسترسی تجاری ایجاد نمی‌کند.

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

- [API مارکت‌پلیس](/docs/api-marketplace)
- [API مشتری](/docs/api-customer)
- [API مدیریت](/docs/api-admin)
- [API شبکه](/docs/network-api)

## مراجع پیاده‌سازی

- planck-marketplace/app/api/catalog/route.ts
- planck-marketplace/app/api/quote/route.ts
- planck-marketplace/lib/trade.ts