سوالات متداول

سلام API یک ابزار استاندارد برای اتصال به سرویس‌های باسلام است که امکان ساخت انواع اپلیکیشن، سرویس، افزونه و سایر کاربردها را فراهم می‌کند. با استفاده از این API می‌توانید به عنوان یک توسعه‌دهنده خارجی به داده‌ها و خدمات پلتفرم باسلام دسترسی پیدا کنید.

برای شروع کار با سلام API، باید مراحل زیر را دنبال کنید:

1. ایجاد یک حساب کاربری در باسلام
2. ایجاد یک کلاینت در صفحه مدیریت کلاینت
3. برای آموزش گام‌های بعدی، به شروع توسعه مراجعه کنید.

با استفاده از سلام API می‌توانید انواع برنامه‌ها را توسعه دهید، از جمله:

• اپلیکیشن‌های موبایل برای غرفه‌داران یا مشتریان
• پلاگین‌های فروشگاهی برای مدیریت محصولات و سفارش‌ها
• داشبوردهای مدیریتی و تحلیلی
• بات‌های هوشمند برای پاسخگویی به مشتریان
• سرویس‌های پرداخت و ابزارهای مالی
• ابزارهای بازاریابی و مدیریت ارتباط با مشتری
• و ...

برای ایجاد یک کلاینت، به صفحه مدیریت کلاینت مراجعه کنید. در این صفحه می‌توانید اطلاعات برنامه خود را وارد کرده و یک کلاینت جدید ایجاد کنید. پس از ایجاد کلاینت، یک client_id و 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) مشخص می‌کنند که برنامه شما به چه بخش‌هایی از API و داده‌های کاربر دسترسی دارد. برای مثال، اگر می‌خواهید اطلاعات محصولات را بخوانید اما نیازی به تغییر آن‌ها ندارید، می‌توانید فقط دسترسی vendor.product.read را درخواست کنید. برای اطلاعات بیشتر درباره تمام دسترسی‌های موجود، به صفحه دسترسی‌ها مراجعه کنید.

سلام API شامل سرویس‌های متنوعی است، از جمله:

• هسته (Core): API‌های اصلی برای مدیریت کاربران، محصولات و دسته‌بندی‌ها
• کیف پول (Wallet): مدیریت تراکنش‌های مالی و شارژ کیف پول
• سفارش (Order): ثبت و مدیریت سفارش‌ها
• جستجو (Search): جستجوی پیشرفته در محصولات و غرفه‌ها
• آپلود (Upload): مدیریت آپلود فایل‌ها و تصاویر
• گفت‌وگو (Chat): مدیریت پیام‌ها و گفت‌وگوها
• وب‌هوک (Webhook): دریافت رویدادها و تغییرات

سلام API دارای محدودیت درخواست است تا از بارگذاری بیش از حد سرور جلوگیری شود. در حالت معمول، هر کلاینت می‌تواند تعداد مشخصی درخواست در دقیقه ارسال کند. اگر از این محدودیت فراتر روید، با خطای HTTP 429 (Too Many Requests) مواجه خواهید شد. در این صورت، باید اندکی صبر کنید و سپس درخواست خود را مجدداً ارسال کنید.

خطای 401 Unauthorized: این خطا معمولاً زمانی رخ می‌دهد که توکن احراز هویت شما نامعتبر یا منقضی شده باشد. برای رفع این مشکل، توکن خود را با استفاده از refresh_token تجدید کنید.

خطای 403 Forbidden: این خطا زمانی رخ می‌دهد که کلاینت شما دسترسی کافی به منبع درخواستی را نداشته باشد. برای رفع این مشکل، مطمئن شوید که دسترسی‌های (scopes) لازم را در هنگام احراز هویت درخواست کرده‌اید.

خطای 422 Unprocessable Entity: این خطا معمولاً به دلیل داده‌های نامعتبر ارسال شده در درخواست رخ می‌دهد. پارامترهای ارسالی خود را بررسی کرده و اطمینان حاصل کنید که همه آن‌ها معتبر و در فرمت صحیح هستند.

برای اطلاع از تغییرات و به‌روزرسانی‌های سلام API، می‌توانید به انجمن باسلام مراجعه کرده یا عضو گروه توسعه‌دهندگان در پیام‌رسان بله شوید. همچنین می‌توانید وب‌هوک‌ها را پیاده‌سازی کنید تا از رویدادهای مهم مطلع شوید.

وب‌هوک‌ها به شما امکان می‌دهند تا به صورت لحظه‌ای از رویدادهای مختلف در پلتفرم باسلام (مانند ثبت سفارش‌های جدید، تغییر وضعیت سفارش‌ها، یا پیام‌های جدید) مطلع شوید. برای استفاده از وب‌هوک‌ها، باید یک URL در برنامه خود ایجاد کنید که بتواند درخواست‌های POST را دریافت کند و سپس این URL را در بخش تنظیمات وب‌هوک در پنل مدیریت کلاینت ثبت کنید. برای اطلاعات بیشتر به صفحه وب‌هوک مراجعه کنید.

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

برای استفاده بهینه از سلام API، این موارد را رعایت کنید:

1. درخواست دسترسی‌های حداقلی: فقط دسترسی‌های مورد نیاز برنامه خود را درخواست کنید.
2. استفاده از ذخیره‌سازی محلی: اطلاعاتی که به ندرت تغییر می‌کنند را در برنامه خود ذخیره کنید تا از تعداد درخواست‌ها کاسته شود.
3. مدیریت خطاها: یک سیستم قوی مدیریت خطا با مکانیزم تلاش مجدد پیاده‌سازی کنید.
4. نظارت بر عملکرد: عملکرد API را نظارت کنید تا از مشکلات احتمالی آگاه شوید.
5. به‌روزرسانی منظم: برنامه خود را با آخرین تغییرات API به‌روز نگه دارید.

اگر با مشکلی مواجه شدید یا سوالی دارید، می‌توانید از روش‌های زیر کمک بگیرید:

1. مراجعه به مستندات کامل API در این سایت
2. پیوستن به انجمن توسعه‌دهندگان باسلام
3. ارسال سوالات خود در گروه بله توسعه‌دهندگان