سوالات متداول
موارد عمومی
سلام API چیست؟
سلام API یک ابزار استاندارد برای اتصال به سرویس‌های باسلام است که امکان ساخت انواع اپلیکیشن، سرویس،
پلاگین و سایر کاربردها را فراهم می‌کند. با استفاده از این API می‌توانید به عنوان یک توسعه‌دهنده خارجی
به داده‌ها و خدمات پلتفرم باسلام دسترسی پیدا کنید.
برای شروع کار با سلام API چه مراحلی لازم است؟
برای شروع کار با سلام API، باید مراحل زیر را دنبال کنید:
-
ایجاد یک حساب کاربری در باسلام
-
دریافت توکن دسترسی شخصی (PAT) یا مشخصات کلاینت (Client ID و Client Secret) از پنل توسعه‌دهندگان
-
انتخاب روش احراز هویت مناسب:
- توکن دسترسی شخصی: برای اپلیکیشن‌های اختصاصی یک غرفه یا کاربر
- جریان کد مجوز (OAuth): برای اپلیکیشن‌های عمومی که نیاز به دسترسی کاربران دارند
- اعتبارنامه کلاینت: برای ارتباطات سیستمی بدون دخالت کاربر
-
برای آموزش گام‌های بعدی، به شروع توسعه یا مستندات SDK مراجعه کنید.
چه نوع برنامه‌هایی می‌توان با سلام API ساخت؟
با استفاده از سلام API می‌توانید انواع برنامه‌ها را توسعه دهید، از جمله:
- اپلیکیشن‌های موبایل: برای غرفه‌داران یا مشتریان
- پلاگین‌های فروشگاهی: برای مدیریت محصولات، سفارش‌ها و موجودی
- داشبوردهای مدیریتی: برای تحلیل فروش و عملکرد غرفه
- بات‌های هوشمند: برای پاسخگویی خودکار به مشتریان
- سرویس‌های پرداخت: ابزارهای مالی و مدیریت کیف پول
- ابزارهای بازاریابی: سیستم‌های CRM و مدیریت کمپین
- اسکریپت‌های اتوماسیون: برای عملیات‌های تکراری غرفه
- ابزارهای گزارش‌گیری: برای تحلیل داده‌ها و گزارش‌های مدیریتی
احراز هویت و دسترسی‌ها
چگونه می‌توانم یک کلاینت برای برنامه خود ایجاد کنم؟
برای ایجاد یک کلاینت:
- به پنل توسعه‌دهندگان مراجعه کنید
- اطلاعات برنامه خود را وارد کنید:
- نام برنامه
- نوع برنامه (وب، موبایل، دسکتاپ)
- Redirect URI برای OAuth
- دسترسی‌های مورد نیاز (Scopes)
- پس از ایجاد کلاینت دریافت خواهید کرد:
client_id: شناسه عمومی برنامهclient_secret: کلید محرمانه (آن را امن نگه دارید)
هرگز client_secret را در کد سمت کلاینت یا مخازن عمومی قرار ندهید.
توکن‌های دسترسی برای چه مدت معتبر هستند؟
توکن‌های دسترسی (
access_token) به مدت زمان مشخص شده در پارامتر expires_in پاسخ API (معمولاً حدود
31622400 ثانیه یا 1 سال) معتبر هستند. پس از انقضای این مدت، باید با استفاده از refresh_token یک توکن
جدید دریافت کنید.چگونه می‌توانم یک توکن منقضی شده را تجدید کنم؟
برای تجدید یک توکن منقضی شده، باید از
refresh_token دریافت شده در مرحله احراز هویت استفاده کنید. درخواست زیر را به سرور احراز هویت ارسال کنید:curl -X POST https://auth.basalam.com/oauth/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"grant_type": "refresh_token",
"client_id": "[client_id]",
"client_secret": "[client_secret]",
"refresh_token": "[refresh_token]"
}'دسترسی‌های مختلف (scopes) چه کاربردی دارند؟
دسترسی‌ها (scopes) مشخص می‌کنند که برنامه شما به چه بخش‌هایی از API دسترسی دارد. دسترسی‌های اصلی شامل:
دسترسی‌های غرفه:
vendor.profile.read/write: مدیریت اطلاعات غرفهvendor.product.read/write: مدیریت محصولاتvendor.parcel.read/write: مدیریت سفارش‌های غرفهorder-processing: دسترسی کامل به پردازش سفارش
دسترسی‌های مشتری:
customer.profile.read/write: مدیریت پروفایل مشتریcustomer.order.read/write: مدیریت سفارش‌های مشتریcustomer.wallet.read/write: مدیریت کیف پولcustomer.chat.read/write: مدیریت گفتگوها
همیشه حداقل دسترسی‌های مورد نیاز را درخواست کنید تا اعتماد کاربران را جلب کنید.
برای لیست کامل دسترسی‌ها به صفحه دسترسی‌ها مراجعه کنید.
سرویس‌ها و APIها
چه سرویس‌هایی در سلام API در دسترس هستند؟
سلام API شامل سرویس‌های متنوعی برای توسعه کامل هر گونه اپ/پلاگین است:
سرویس‌های اصلی:
- Core API: مدیریت کاربران، غرفه‌ها، محصولات و دسته‌بندی‌ها
- Order API: ثبت، مدیریت و پردازش سفارش‌ها
- Order Processing API: رهگیری و مدیریت فرآیند سفارش
- Search API: جستجوی پیشرفته با فیلترهای متنوع
سرویس‌های پشتیبانی:
- Upload API: آپلود و مدیریت فایل‌ها و تصاویر (حداکثر حجم مشخص)
- Chat API: سیستم پیام‌رسانی و پشتیبانی مشتریان
- Wallet API: مدیریت کیف پول، تراکنش‌ها و تسویه حساب
- Webhook API: دریافت اعلان‌های لحظه‌ای رویدادها
هر سرویس دارای Endpointهای مختلف و مستندات کاملی است که در بخش API Reference قابل دسترسی است.
محدودیت درخواست‌ها (Rate Limiting) در سلام API چگونه است؟
سلام API دارای محدودیت درخواست است تا از بارگذاری بیش از حد سرور جلوگیری شود. در حالت معمول، هر کلاینت می‌تواند تعداد مشخصی درخواست در دقیقه ارسال کند. اگر از این محدودیت فراتر روید، با خطای HTTP 429 (Too Many Requests) مواجه خواهید شد. در این صورت، باید اندکی صبر کنید و سپس درخواست خود را مجدداً ارسال کنید.
توصیه می‌شود برای جلوگیری از برخورد با محدودیت درخواست، یک مکانیزم تلاش مجدد با تأخیر فزاینده در برنامه خود پیاده‌سازی کنید.
SDK های باسلام این مکانیزم را به صورت خودکار مدیریت می‌کنند.
مدیریت خطاها و عیب‌یابی
خطاهای رایج در سلام API چیست و چگونه آن‌ها را رفع کنم؟
خطاهای احراز هویت:
401 Unauthorized: توکن نامعتبر یا منقضی- راه حل: استفاده از refresh_token برای تجدید توکن
403 Forbidden: عدم دسترسی کافی- راه حل: بررسی scopes درخواستی و اطمینان از داشتن دسترسی لازم
invalid_client: اطلاعات کلاینت نادرست- راه حل: بررسی client_id و client_secret
invalid_grant: کد تأیید منقضی- راه حل: تکرار فرآیند OAuth از ابتدا
خطاهای داده:
422 Unprocessable Entity: داده‌های نامعتبر- راه حل: بررسی فرمت و اعتبار پارامترها
400 Bad Request: ساختار درخواست نادرست- راه حل: بررسی JSON syntax و هدرها
404 Not Found: منبع یافت نشد- راه حل: بررسی URL و ID منبع
برای دیباگ بهتر، همیشه لاگ کامل درخواست و پاسخ را ذخیره کنید.
چگونه می‌توانم از تغییرات و به‌روزرسانی‌های API مطلع شوم؟
کانال‌های اطلاع‌رسانی:
- مستندات API: وبلاگ تغییرات و اطلاعیه‌های مهم سلام API
- انجمن توسعه‌دهندگان: بحث‌های فنی و اعلام تغییرات
- گروه بله: پشتیبانی آنلاین و اطلاع‌رسانی سریع
وب‌هوک‌ها و رویدادها
وب‌هوک‌ها چیست و چگونه از آن‌ها استفاده کنم؟
وب‌هوک‌ها به شما امکان می‌دهند تا به صورت لحظه‌ای از رویدادهای مختلف در پلتفرم باسلام (مانند ثبت سفارش‌های
جدید، تغییر وضعیت سفارش‌ها، یا پیام‌های جدید) مطلع شوید. برای استفاده از وب‌هوک‌ها، باید یک URL در
برنامه خود ایجاد کنید که بتواند درخواست‌های POST را دریافت کند و سپس این URL را در بخش تنظیمات وب‌هوک
در پنل توسعه‌دهندگان ثبت کنید. برای اطلاعات بیشتر به صفحه وب‌هوک مراجعه کنید.
چگونه می‌توانم از امنیت وب‌هوک‌ها اطمینان حاصل کنم؟
برای اطمینان از امنیت وب‌هوک‌ها، باید اعتبار هر درخواست دریافتی را بررسی کنید. هر درخواست وب‌هوک شامل
یک هدر
X-Signature است که با استفاده از کلید مخفی کلاینت شما ایجاد شده است. شما باید محتوای درخواست
را با همان الگوریتم رمزنگاری کرده و با مقدار هدر مقایسه کنید تا اطمینان حاصل کنید که درخواست واقعاً
از باسلام ارسال شده است.SDK و ابزارهای توسعه
چه SDK هایی برای کار با سلام API وجود دارد؟
در حال حاضر SDK رسمی باسلام برای زبان‌های زیر در دسترس است:
Python SDK:
- نصب:
pip install basalam-sdk - پشتیبانی کامل از تمام سرویس‌ها
- پشتیبانی از Async/Sync
- Type hints و اعتبارسنجی داده‌ها
- مدیریت خودکار احراز هویت
- مستندات: PyPI
در حال توسعه:
- JavaScript/TypeScript SDK
- PHP SDK
- Go SDK
برای اطلاعات بیشتر به بخش SDK مراجعه کنید.
سرور MCP باسلام چیست و چگونه کار می‌کند؟
سرور MCP (Model Context Protocol) باسلام، یک ابزار قدرتمند برای تعامل با API های باسلام از طریق ابزارهای هوش مصنوعی است. این سرور امکاناتی مانند:
- دسترسی به مستندات API به صورت بلادرنگ
- اجرای درخواست‌های API مستقیم
- تولید کد بر اساس مستندات
- کمک در دیباگ و عیب‌یابی
برای نصب و استفاده، به صفحه سرور MCP باسلام مراجعه کنید.
بهترین روش‌ها
بهترین روش‌ها برای استفاده از سلام API چیست؟
استفاده از SDK: توصیه اکید می‌شود از SDKهای باسلام استفاده کنید که شامل:
- مدیریت خودکار احراز هویت و توکن
- پشتیبانی Async/Sync
- اعتبارسنجی خودکار داده‌ها
- مدیریت خطا و Rate Limiting
- کاهش 70% زمان توسعه
بهترین شیوه‌های توسعه:
-
امنیت:
- هرگز client_secret را در کد کلاینت قرار ندهید
- از HTTPS برای همه درخواست‌ها استفاده کنید
- توکن‌ها را امن ذخیره کنید
-
کارایی:
- درخواست دسترسی‌های حداقلی (Least Privilege)
- استفاده از کش برای داده‌های استاتیک
- Batch درخواست‌ها در صورت امکان
- پیاده‌سازی Pagination برای لیست‌های بزرگ
-
قابلیت اطمینان:
- پیاده‌سازی Retry Logic با Exponential Backoff
- مدیریت Timeout برای درخواست‌ها
- لاگ‌برداری جامع برای دیباگ
- مانیتورینگ مداوم عملکرد API
-
نگهداری:
- استفاده از نسخه‌بندی در URL
- آماده‌سازی برای Deprecation
- تست‌های خودکار برای Integration
- مستندسازی کد و APIهای استفاده شده
SDK باسلام بسیاری از این بهترین شیوه‌ها را به صورت خودکار پیاده‌سازی می‌کند.
چگونه می‌توانم کمک و پشتیبانی دریافت کنم؟
اگر با مشکلی مواجه شدید یا سوالی دارید، می‌توانید از روش‌های زیر کمک بگیرید:
- مراجعه به مستندات کامل API در این سایت
- پیوستن به انجمن توسعه‌دهندگان باسلام
- ارسال سوالات خود در گروه بله توسعه‌دهندگان و یا ارسال ایمیل به developers@basalam.com
برای دریافت پاسخ سریع‌تر، قبل از درخواست کمک، همیشه سعی کنید مستندات موجود را با دقت مطالعه کنید و جزئیات کاملی از مشکل خود ارائه دهید.
Last updated on