Api

احراز هویت#

هر درخواست API v2 و MCP با یک توکن حامل Sanctum احراز هویت می‌شود که به یک اعتبارنامه یکپارچه‌سازی تجارت تعلق دارد. توکن، اعتبارنامه را مشخص می‌کند؛ اعتبارنامه، تجارت و کارمند را مشخص می‌کند؛ و نقش‌های زندهٔ کارمند تعیین می‌کند که درخواست چه چیزی را می‌تواند بخواند. بنابراین احراز هویت دو بررسی در یکی است: یک توکن معتبر، و یک بافت اجازه‌دهی که هنوز معتبر است.

ارسال توکن#

http

GET /api/v2/context HTTP/1.1
Host: app.example.com
Authorization: Bearer 12|secret-token-value
Accept: application/json

قاعده‌ها:

توکن را با طرح Bearer در هدر Authorization بفرستید.
همیشه Accept: application/json را بفرستید؛ بدون آن، خطاهای فریم‌ورک به‌صورت HTML نمایش داده می‌شوند.
توکن هنگام ایجاد یا چرخش اعتبارنامه یک بار نشان داده می‌شود. آن را در یک مدیر راز نگه دارید.
توکن‌ها با زمان‌سنج منقضی نمی‌شوند، اما به‌محض بازپس‌گرفتن اعتبارنامه یا از دست دادن اختییار لازم توسط کارمندِ مالک، از کار می‌افتند.

سرور چه چیزی را بررسی می‌کند#

برای هر درخواست، به این ترتیب:

گام	بررسی	کد خطا
1	توکن Sanctumی وجود دارد که شناسه یکپارچه‌سازی را حمل می‌کند	`integration_credential_required` (401)
2	اعتبارنامه `active` است و به کاربرِ توکن تعلق دارد	`integration_credential_invalid` (401)
3	تجارت وجود دارد، حذف نشده و `active` است	`integration_credential_invalid` (401)
4	کاربر هنوز عضویت کارمندی فعال در تجارت دارد	`integration_membership_inactive` (403)
5	کارمند مدیر تجارت است یا دست‌کم یک شعبه را مدیریت می‌کند	`integration_role_revoked` (403)
6	اعتبارنامه غیرسطح‌کل‌تجارت هنوز شعبه‌ای در دامنه دارد	`integration_branch_scope_empty` (403)
7	صلاحیت اعطا شده، و نقش زنده اجازه نگاشت‌شده را هم می‌دهد	`api_ability_denied` (403)
8	شعبه درخواستی داخل دامنه اعتبارنامه است	`branch_scope_denied` (403) یا `branch_required` (422)

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

اختییار زنده#

اختییار در هر درخواست از نقش‌های کارمند گرفته می‌شود:

اختییار	با چه شناسایی می‌شود
مدیر تجارت	نقشی در دامنه تجارت که `settings.write` را دربر دارد
مدیر شعبه	شعبه‌ای که کارمند مدیر آن است، یا شعبه خانگی وقتی نقش `Management` در دامنه شعبه دارد
بدون اختییار	هیچ‌یک از موارد بالا، بنابراین `integration_role_revoked` برگردانده می‌شود

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

نگاشت صلاحیت و اجازه#

یک صلاحیت روی اعتبارنامه اعطا می‌شود، اما تنها زمانی کار می‌کند که نقش زندهٔ کارمند اجازه صفحه مطابق را هم بدهد:

صلاحیت	اجازه صفحه موردنیاز
`products:read`	`inventory.products.read`
`stock:read`	`inventory.branches.read`
`purchases:read`	`purchase.purchases.read`
`orders:read`	`sale.orders.read`
`sales:read`	`sale.sales.read`

سطح‌های تشدید اختییار عامدانه مستثنا هستند: هیچ صلاحیتی به access.*، مدیریت کارمندان، تغییرات گذرواژه یا تنظیمات تأیید دومرحله‌ای نگاشت نمی‌شود.

تعیین شعبه#

شعبه هدف، به این ترتیب از:

هدر X-Business-Branch.
آرگومان branch_id یک فراخوانی ابزار MCP.
پارامتر درخواست branch_id.

آنگاه:

اگر شعبه‌ای فرستاده شود، باید متعلق به تجارت و داخل دامنه اعتبارنامه باشد؛ وگرنه branch_scope_denied.
اگر شعبه‌ای فرستاده نشود و اعتبارنامه در سطح کل تجارت باشد، درخواست در سطح تجارت می‌خواند.
اگر شعبه‌ای فرستاده نشود و دقیقاً یک شعبه در دامنه باشد، همان شعبه استفاده می‌شود.
اگر شعبه‌ای فرستاده نشود و چند شعبه در دامنه باشد، API با branch_required پاسخ می‌دهد.

جداسازی توکن#

توکن‌های یکپارچه‌سازی فقط روی /api/v2/* و /mcp/* پذیرفته می‌شوند. استفاده از آن‌ها روی یک مسیر محافظت‌شده با Sanctum، مانند پشت‌دفتر پشتیبانی، این را برمی‌گرداند:

json

{
  "error": {
    "code": "integration_token_not_allowed",
    "message": "Business integration credentials are restricted to API v2 and MCP endpoints."
  }
}

پاسخ‌های شکست#

وضعیت	کد	معنا
401	`integration_credential_required`	توکنی نیست، یا توکن یک توکن یکپارچه‌سازی نیست
401	`integration_credential_invalid`	اعتبارنامه بازپس‌گرفته، تجارت غیرفعال، یا عدم تطابق کاربر
403	`integration_membership_inactive`	عضویت کارمند حذف شده است
403	`integration_role_revoked`	کارمند دیگر اختییار سرپرستی یا مدیریت ندارد
403	`integration_branch_scope_empty`	اعتبارنامه شعبه‌محدود دیگر هیچ شعبه‌ای در دامنه ندارد
403	`api_ability_denied`	صلاحیت موجود نیست، یا نقش دیگر اجازه را نمی‌دهد
403	`branch_scope_denied`	شعبه بیرون از دامنه اعتبارنامه است
422	`branch_required`	چند شعبه در دامنه است و هیچ‌کدام نام برده نشده
403	`integration_token_not_allowed`	توکن روی یک مسیر غیریکپارچه‌سازی استفاده شده

راهنمای عملیاتی#

در یک برنامه زمانی منظم و فوراً پس از هرگونه مظنون به نشت، چرخش کنید.
برای هر یکپارچه‌سازی یک اعتبارنامه نگه دارید و آن را به نام سیستم استفاده‌کننده نام‌گذاری کنید.
کمترین مجموعه صلاحیت و کمترین مجموعه شعبه را اعطا کنید.
last_used_at و رویدادهای درخواست را در کارت مصرف پایش کنید.
توکن را در کد سمت کلاینت جاسازی نکنید؛ یکپارچه‌سازی‌ها سرور‌به‌سرور هستند.