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

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

موارد عمومی

سلام API چیست؟

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

برای شروع کار با سلام API چه مراحلی لازم است؟

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

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

با استفاده از سلام 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) چه کاربردی دارند؟

دسترسی‌ها (scopes) مشخص می‌کنند که برنامه شما به چه بخش‌هایی از API و داده‌های کاربر دسترسی دارد. برای مثال، اگر می‌خواهید اطلاعات محصولات را بخوانید اما نیازی به تغییر آن‌ها ندارید، می‌توانید فقط دسترسی vendor.product.read را درخواست کنید. برای اطلاعات بیشتر درباره تمام دسترسی‌های موجود، به صفحه دسترسی‌ها مراجعه کنید.

سرویس‌ها و API‌ها

چه سرویس‌هایی در سلام API در دسترس هستند؟

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

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

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

⚠️

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

مدیریت خطاها و عیب‌یابی

خطاهای رایج در سلام API چیست و چگونه آن‌ها را رفع کنم؟

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

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

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

چگونه می‌توانم از تغییرات و به‌روزرسانی‌های API مطلع شوم؟

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

وب‌هوک‌ها و رویدادها

وب‌هوک‌ها چیست و چگونه از آن‌ها استفاده کنم؟

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

چگونه می‌توانم از امنیت وب‌هوک‌ها اطمینان حاصل کنم؟

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

بهترین روش‌ها

بهترین روش‌ها برای استفاده از سلام API چیست؟

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

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

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

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

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