Api
گزارش تغییرات#
این صفحه تغییرات Business API و سرور MCP را ثبت می‌کند. تاریخ‌ها پنجره‌های انتشار تقریبی‌اند؛ رفتار توصیف‌شده در این مستندات بازتاب انتشار فعلی است.
سیاست نسخه‌بندی#
- سطح یکپارچه‌سازی پشتیبانی‌شده
/api/v2و/mcp/businessاست. - تغییرات افزوده (فیلدهای جدید، فیلترهای اختیاری جدید) ممکن است درون v2 عرضه شوند.
- تغییرات شکّنده نیازمند یک پیشوند نسخه جدید است.
/api/v1سطح داخلی برنامه است و این سیاست شامل آن نمی‌شود.
انتشار فعلی#
Business API v2#
- نقاط فقط‌خواندنی:
context،products،stock،purchases،purchases/{id}،orders،sales،sales/{id}وhealth. - پنج صلاحیت خواندن:
products:read،stock:read،purchases:read،orders:read،sales:read. - اعتبارنامه‌های بسته به کارمند با تأیید دوباره نقش و عضویت زنده در هر درخواست.
- تعیین شعبه از طریق
X-Business-Branch، با تعیین خودکار برای یک شعبه اعطاشده واحد و
422 branch_required وقتی چند شعبه اعطا شده و هیچ‌کدام نام برده نشده.
- صفحه‌بندی با
pageوper_page(1–100، پیش‌فرض 25) و پیوندهای نگه‌دارنده فیلترها. - نام محصولات آگاه از زبان از طریق
language_codeبا بازگشت به کود محصول. - منابع جزئیات خرید و فروش با فاکتور، طرف مقابل، اقلام و پرداخت‌ها.
- فهرست سفارش‌ها با فیلترهای تاریخ و وضعیت.
سهمیه‌ها و حدها#
- محدودکننده هجومی: 60 درخواست در دقیقه به ازای هر اعتبارنامه.
- سهمیه: 200 درخواست در روز و 2,000 در ماه به ازای هر کاربر.
- طرح‌ها: Free (1×)، Growth (3×)، Scale (10×)، Enterprise (50×)،
زمان‌محدود با بازگشت هنگام انقضا.
- پاسخ‌های
429شاملRetry-Afterو، برای سهمیه، دامنه، دوره، حد،
تعداد مصرف‌شده و زمان بازنشانی‌اند.
مدیریت اعتبارنامه#
- ایجاد، نام‌گذاری دوباره، چرخش و بازپس‌گیری از تنظیمات > یکپارچه‌سازی‌های API.
- نمایش یک‌باری راز؛ تنها یک هش ذخیره می‌شود.
- دامنه سطح کل تجارت یا شعبه‌های انتخاب‌شده.
- دید مدیران در سراسر تجارت؛ مدیران محدود به اعتبارنامه‌های خودشان.
- کارت مصرف با طرح، ضریب، مصرف، زمان‌های بازنشانی و نتیجه‌های اخیر.
سرور MCP#
BusinessApiServerرویPOST /mcp/businessاز طریق Streamable HTTP.- پنج ابزار:
products،stock،purchases،orders،sales. - پارامترهای مشترک ابزارها:
id،branch_id،per_page،page،language_code. - سندباکس فقط‌محلی روی
/mcp/testو/mcp/business/testدر محیط‌های local و testing. - همان لوله اعتبارنامه، صلاحیت، شعبه و سهمیه API HTTP.
برنامه‌ریزی‌شده و در حال بررسی#
این اقلام امروز موجود نیستند و یک یکپارچه‌سازی نباید آن‌ها را فرض کند:
| قلم | وضعیت |
|---|---|
| وب‌هوک‌های خروجی با امضا | موجود نیست |
| نقاط نوشتن (فروش‌ها، خریدها، پرداخت‌ها) | موجود نیست؛ عامدانه فقط‌خواندنی |
| منابع اضافی (حساب‌ها، فعالیت‌ها، مرجوعی‌ها) | موجود نیست |
| سطل‌های سهمیه به ازای هر اعتبارنامه | سهمیه به ازای هر کاربر است |
| نسخه v3 | اعلام نشده |
منسوخ‌شدن‌ها#
هیچ نقطه پایانی v2 منسوخ نشده است. اگر فیلد یا نقطه پایانی بازنشسته شود، این صفحه آن را نام می‌برد، جایگزین را اعلام می‌کند و پیش از حذف یک پنجره مهاجرت می‌دهد.
چطور به‌روز بمانید#
- پس از ارتقا مرجع نقاط پایانی را دوباره بخوانید.
- آزمون‌های قراردادی یکپارچه‌سازی‌تان را روی یک تجارت staging اجرا کنید.
- به فیلدهای افزوده توجه کنید؛ آن‌ها تغییر نمی‌خواهند اما ممکن است مفید باشند.
- ناهمخوانی‌ها را از طریق کانال پشتیبانی خود گزارش کنید، نه اینکه دورشان بزنید.