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

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

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

1. ایجاد یک حساب کاربری در باسلام (opens in a new tab)

2. ایجاد یک کلاینت و یا دریافت توکن کاربری در پنل توسعه‌دهندگان (opens in a new tab)

3. برای آموزش گام‌های بعدی، به شروع توسعه یا مستندات SDK مراجعه کنید.

با استفاده از سلام API می‌توانید انواع برنامه‌ها را توسعه دهید، از جمله: - اپلیکیشن‌های موبایل برای غرفه‌داران یا مشتریان - پلاگین‌های فروشگاهی برای مدیریت محصولات و سفارش‌ها - داشبوردهای مدیریتی و تحلیلی

• بات‌های هوشمند برای پاسخگویی به مشتریان - سرویس‌های پرداخت و ابزارهای مالی - ابزارهای بازاریابی و مدیریت ارتباط با مشتری - و ...

برای ایجاد یک کلاینت، به پنل توسعه‌دهندگان (opens in a new tab) مراجعه کنید. در این صفحه می‌توانید اطلاعات برنامه خود را وارد کرده و یک کلاینت جدید ایجاد کنید. پس از ایجاد کلاینت، یک 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 شامل سرویس‌های متنوعی است، از جمله:

• کاربر، غرفه و محصول (سرویس مرکزی): API‌های اصلی برای مدیریت کاربران، غرفه، محصولات و دسته‌بندی‌ها
• سفارش: ثبت و مدیریت سفارش‌ها
• رهگیری سفارش: رهگیری سفارشات توسط مشتری و غرفه‌داران
• جستجو: جستجوی پیشرفته در محصولات و غرفه‌ها
• آپلود: آپلود فایل‌ها و تصاویر
• گفت‌وگو: مدیریت پیام‌ها و گفت‌وگوها
• کیف پول: مدیریت تراکنش‌های مالی و شارژ کیف پول
• وب‌هوک: دریافت رویدادها و تغییرات

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

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

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

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

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

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

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

بهترین و توصیه‌شده‌ترین روش برای استفاده از APIهای سلام، استفاده از SDKهای ارائه‌شده توسط تیم توسعه باسلام (opens in a new tab) است. این SDKها برای ساده‌سازی ارتباط با سرویس‌ها، مدیریت احراز هویت، کنترل خطا، و به‌روزرسانی‌های آینده طراحی شده‌اند و تجربه‌ای سریع‌تر و مطمئن‌تر برای توسعه‌دهندگان فراهم می‌کنند.

با این حال، در صورت نیاز، امکان استفاده مستقیم از APIها نیز به‌صورت مستقل وجود دارد و مستندات کامل در این سایت در دسترس است.

برای استفاده بهینه، توصیه می‌شود نکات زیر را رعایت کنید:

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

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

1. مراجعه به مستندات کامل API در این سایت
2. پیوستن به انجمن توسعه‌دهندگان باسلام (opens in a new tab)
3. ارسال سوالات خود در گروه بله توسعه‌دهندگان (opens in a new tab) و یا ارسال ایمیل به developers@basalam.com