Api
نمای کلی API#
API تجارت داده‌های کسب‌وکار شما را در اختیار سیستم‌های خارجی قرار می‌دهد: یک ERP، ابزار گزارش‌گیری، اسکنر انبار یا دستیار هوش مصنوعی. این API عامدانه فقط‌خواندنی است؛ هیچ عملیاتی در آن نمی‌تواند رکوردی را ایجاد، ویرایش، پرداخت یا حذف کند، بنابراین یک یکپارچه‌سازی می‌تواند داده‌ها را همگام‌سازی کند بدون آنکه بتواند دفاتر حساب شما را تغییر دهد.
دو سطح HTTP به‌اضافه سرور MCP وجود دارد، و فقط v2 برای کلاینت‌های شخص ثالث در نظر گرفته شده است:
| سطح | مسیر | مخاطب | وضعیت |
|---|---|---|---|
| Business API v2 | /api/v2 | یکپارچه‌سازی‌های خارجی با استفاده از یک اعتبارنامه | پشتیبانی‌شده |
| Model Context Protocol | /mcp/business | کلاینت‌های هوش مصنوعی با همان اعتبارنامه | پشتیبانی‌شده |
| Application API v1 | /api/v1 | خود برنامه وب لایتاناخی | داخلی |
مسیرهای v1 نقاط پایانی خودِ برنامه برای مرورگر هستند: دستیار هوش مصنوعی، چت‌بات، جریان اطلاعیه‌ها، نرخ ارزها و ابزارهای کمکی محصول. این مسیرها در بافت نشست وب اجرا می‌شوند، برای رابط کاربری شکل داده شده‌اند و بدون اطلاع‌رسانی تغییر می‌کنند. یکپارچه‌سازی خود را روی v1 نسازید؛ از v2 یا MCP استفاده کنید.
آنچه API می‌تواند بخواند#
سطح v2 دقیقاً همان منابعی را دربر می‌گیرد که سیستم‌های خارجی درخواست می‌کنند. داده دیگری وجود ندارد.
| نقطه پایانی | چه چیزی برمی‌گرداند | صلاحیت |
|---|---|---|
/api/v2/context | تجارتِ اعتبارنامه، دامنه نقش، شعبه‌ها و سهمیه | هر اعتبارنامه معتبر |
/api/v2/products | کاتالوگ محصولات، قابل جستجو با کوک، مدل یا نام | products:read |
/api/v2/stock | رشته‌های موجودی با مقدارهای دسترس‌پذیر، دریافت‌شده و رزروشده | stock:read |
/api/v2/purchases و /api/v2/purchases/{id} | فاکتورهای خرید و جزئیات کامل خرید | purchases:read |
/api/v2/orders | سفارش‌های بین‌شعبه‌ای با وضعیت و مجموع‌ها | orders:read |
/api/v2/sales و /api/v2/sales/{id} | فاکتورهای فروش و جزئیات کامل فروش | sales:read |
/api/v2/health | سلامت خدمت، بدون نیاز به اعتبارنامه | هیچ |
همه‌چیز در دامنه یک تجارت محدود است. رکوردهای یک تجارت دیگر هرگز دیدنی نیستند، حتی اگر یک شناسه حدس زده شود. هیچ نقطه پایانی برای حساب‌ها، معاشات، کارمندان، نقش‌ها یا تنظیمات وجود ندارد.
احراز هویت چگونه کار می‌کند#
یکپارچه‌سازی یک حساب جداگانه نیست. آن یک اعتبارنامه است که توسط یک کارمند صادر می‌شود، به همان کارمند بسته است، و توسط اجازه‌های زندهٔ کارمند محدود می‌شود:
- یک کارمند صلاحیت‌دار تنظیمات > یکپارچه‌سازی‌های API را باز می‌کند و یک اعتبارنامه نام‌دار می‌سازد.
- اعتبارنامه یک توکن Sanctum و مجموعه‌ای از صلاحیت‌های خواندن دریافت می‌کند.
- هر درخواست دوباره بررسی می‌کند که تجارت فعال است، کاربر هنوز عضویت کارمندی فعال دارد، و آن کارمند همچنان اختییار مدیر یا سرپرست و اجازه صفحه پشت هر صلاحیت را دارد.
- اگر کارمند ترحیل شود، تنزل پیدا کند یا اجازه مربوط را از دست بدهد، اعتبارنامه در درخواست بعدی بسته و رد می‌شود (fail closed).
به احراز هویت و کلیدهای API و دامنه‌های دسترسی مراجعه کنید.
مدیر تجارت در برابر مدیر شعبه#
اختییار از نقش‌های زندهٔ کارمند گرفته می‌شود، نه از خودِ اعتبارنامه:
| اختییار | چطور شناسایی می‌شود | پوشش شعبه |
|---|---|---|
| مدیر تجارت | نقشی در دامنه تجارت که settings.write را دربر دارد | همه شعبه‌های فعال تجارت |
| مدیر شعبه | شعبه‌هایی که او مدیریت می‌کند، یا نقش Management در دامنه شعبه | فقط شعبه‌های تحت مدیریتش |
| هیچ‌کدام | نه مدیر و نه اختییار سرپرستی | اعتبارنامه رد می‌شود |
اعتبارنامه‌ای که به کارمندی تعلق دارد که دیگر هیچ‌یک از این دو شکل اختییار را ندارد، رد می‌شود. این همان دلیلی است که دسترسی API با نقش‌هایی که شما در رابط کاربری مدیریت می‌کنید تغییر می‌کند.
دامنه شعبه#
یک تجارت می‌تواند چندین شعبه داشته باشد. یک اعتبارنامه یا در سطح کل تجارت است یا به شعبه‌های انتخاب‌شده محدود می‌شود، و یک درخواست می‌تواند یک شعبه را هدف بگیرد:
GET /api/v2/sales?from=2026-10-01&to=2026-10-31
Authorization: Bearer <token>
X-Business-Branch: 4- اعتبارنامه در سطح کل تجارت بدون هدر شعبه، در همه شعبه‌های فعال می‌خواند.
- اعتبارنامه‌ای که دامنه‌اش دقیقاً به یک شعبه می‌رسد، به‌صورت خودکار از همان شعبه استفاده می‌کند.
- اعتبارنامه‌ای که دامنه‌اش چند شعبه را دربر می‌گیرد باید شعبه هدف را نام ببرد، وگرنه API با
422پاسخ می‌دهد.
الزام‌هایی که پیش از موفقیت یک درخواست باید برقرار باشند#
| الزام | نحوه اعمال |
|---|---|
| اعتبارنامه فعال | وضعیت active و متعلق به کاربرِ توکن |
| تجارت فعال | تجارت حذف‌نشده و business_status = active |
| عضویت فعال | کاربر همچنان کارمند در تجارت باشد |
| اختییار زنده | کارمند مدیر تجارت یا مدیر شعبه باشد |
| دامنه شعبه | اعتبارنامه‌های غیرسطح‌کل‌تجارت دست‌کم یک شعبه در دامنه نگه دارند |
| صلاحیت + اجازه | صلاحیت توکن و اجازه صفحه نگاشت‌شدهٔ آن |
اگر هر یک از این‌ها شکست بخورد، درخواست به‌جای داده ناقص، یک خطای احراز هویت یا اجازه‌دهی برمی‌گرداند.
اصول طراحی#
- فقط‌خواندنی طبق قرارداد. هیچ نقطه پایانی نوشتن وجود ندارد، و به همین دلیل صلاحیت‌ها با پسوند
:readنام‌گذاری شده‌اند. - کمترین اختییار. فقط صلاحیت‌های موردنیاز یکپارچه‌سازی و فقط شعبه‌هایی که به آن‌ها خدمت می‌کند را اعطا کنید.
- اجازه‌دهی زنده. اجازه‌ها در هر درخواست ارزیابی می‌شوند، نه در زمان ایجاد توکن ثبت می‌شوند.
- سهمیه‌آگاه. هر درخواست علیه سهمیه روزانه و ماهانه هر کاربر به‌اضافه یک حد هجومی کوتاه‌مدت شمرده می‌شود؛ به محدودیت‌های نرخ و سهمیه‌ها مراجعه کنید.
- نسخه‌بندی باثبات. تغییرات شکّنده به یک نسخه جدید منتقل می‌شوند؛ فیلدهای افزوده ممکن است در v2 ظاهر شوند.
- ساختارهای قابل پیش‌بینی. فهرست‌ها قالب صفحه‌بندی استاندارد برمی‌گردانند؛ منابع جزئیات یک شیء
dataبرمی‌گردانند.
قدم بعدی کجاست#
| هدف | صفحه |
|---|---|
| ساخت یک اعتبارنامه | کلیدهای API و دامنه‌های دسترسی |
| ارسال اولین درخواست | شروع سریع |
| یافتن یک نقطه پایانی | مرجع نقاط پایانی |
| اتصال یک کلاینت هوش مصنوعی | نمای کلی MCP |
| مدیریت شکست‌ها | خطاها |