شروع توسعه!

شروع توسعه

این سند راهنمای قدم اول تا اولین فراخوانی در مسیر توسعه برنامه‌تان را با استفاده از API باسلام ارائه می‌دهد.

آنچه در این سند می‌خوانید

پیش‌نیازها

احراز هویت کاربر

مرحله ۱: درخواست مجوز

برای دسترسی به منابع کاربر و شروع فرآیند احراز هویت، کاربر را به آدرس مجوز باسلام با پارامترهای مشخص شده هدایت کنید:

https://basalam.com/accounts/sso?client_id=[client_id]&scope=[scope]&redirect_uri=[client_redirect_uri]&state=[state]
⚠️

توجه داشته باشید که لیست Scope‌ها با فاصله (space) از هم جدا شده باشند.

به عنوان مثال: scope="vendor.product.read vendor.product.write customer.order.read"

مرحله ۲: دریافت توکن دسترسی

پس از اعطای دسترسی به برنامه توسط کاربر، کد تایید code ارسال شده به redirect_uri خود را برای دریافت توکن دسترسی ارسال کنید:

curl -X POST https://auth.basalam.com/oauth/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "[YOUR_CLIENT_ID]",
    "client_secret": "[YOUR_CLIENT_SECRET]",
    "redirect_uri": "[YOUR_REDIRECT_URI]",
    "code": "[CODE]"
  }'

نمونه پاسخ دریافتی:

{
  "token_type": "Bearer",
  "access_token": "eyJ0eXAiO...",
  "expires_in": 31622400,
  "refresh_token": "def502..."
}

مرحله ۳: دریافت اطلاعات کاربر

curl -X GET https://core.basalam.com/v3/users/me \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer [TOKEN]'

نمونه پاسخ دریافتی:

{
  "id": 0, // آی‌دی کاربر
  "hash_id": "string", // هش‌آی‌دی کاربر
  "username": "string",
  "name": "string",
  "vendor": {
    "id": 0, // آی‌دی غرفه کاربر
    "identifier": "string", // آی‌دی غرفه
    "title": "string"
  }
}

اعتبارسنجی اطلاعات توکن کاربر

برای اعتبارسنجی توکن دریافتی نیز می‌توانید از اندپوینت /whoami استفاده کنید:

curl -X GET https://auth.basalam.com/whoami \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer [TOKEN]'

نمونه پاسخ دریافتی:

{
  "id": "...",
  "name": "....",
  "mobile": "09xxxxxxxxx",
  "hash_id": "xxx",
  "client": {
    "id": "...",
    "name": "...",
    "image_url": "..."
  }
}

احراز هویت کلاینت (توسعه شخصی)

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

curl -X POST https://auth.basalam.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
      "grant_type": "client_credentials",
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "scope": "*"
  }'

فراخوانی اولین API: افزودن محصول جدید

قبل از افزودن محصول، باید تصاویر آن را با استفاده از اندپوینت /v3/files آپلود کرده و شناسه‌های تصاویر را در درخواست افزودن محصول قرار دهید:

آپلود تصاویر محصول

curl -X POST https://uploadio.basalam.com/v3/files \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/yourfile.jpg"

نمونه پاسخ دریافتی:

{
  "id": "unique_file_id",
  "file_name": "string",
  "path": "string",
  "mime_type": "string",
  "size": 102400,
  "created_at": "2025-05-17T14:25:39Z",
  "creator_user_id": 1
}

افزودن محصول

برای افزودن محصول جدید، اطلاعات محصول را به اندپوینت /vendors/{vendor_id}/products ارسال کنید:

curl -X POST https://core.basalam.com/v3/vendors/{vendor_id}/products \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "محصول نمونه",
    "description": "توضیحات محصول نمونه", 
    "price": 150000,
    "category_id": 123,
    "images": ["image_id_1"],
    "inventory": 10,
    "is_active": true
  }'

دریافت لیست محصولات

با استفاده از اندپوینت /vendors/{vendor_id}/products برای دریافت فهرست محصولات یک غرفه ریکوئست بزنید:

curl -X GET \
--url https://core.basalam.com/v3/vendors/{vendor_id}/products \
-H 'Accept: application/json' \
-H 'prefer: '

خطاهای رایج و رفع مشکل

در اینجا برخی از خطاهای رایج که ممکن است با آنها مواجه شوید و نحوه حل آنها آمده است:

خطاتوضیحراه حل
invalid_clientمشخصات کلاینت نادرست استشناسه و رمز کلاینت را بررسی کنید
redirect_uri_mismatchآدرس بازگشت اشتباه استباید دقیقاً با آدرس ثبت‌شده مطابقت داشته باشد
invalid_grantکد تأیید اشتباه یا منقضی استفرآیند ورود کاربر را تکرار کنید
invalid_scopeدسترسی‌ درخواستی نامعتبر استمستندات را برای دسترسی‌های معتبر بررسی کنید
401 Unauthorizedتوکن نامعتبر یا منقضی شده استیک توکن جدید دریافت کنید

گام‌های بعدی

اما این فقط شروع ماجراست! برای ادامه مسیر، پیشنهاد می‌کنیم موارد زیر را بررسی کنید:

  • سرویس‌های دیگر را مرور کنید: شامل مجموعه‌ای از سرویس‌های متنوع است. برای آشنایی با عملکرد هرکدام، سری به مستندات کامل API (opens in a new tab) بزنید.

  • وب‌هوک‌ها را راه‌اندازی کنید: اگر می‌خواهید هنگام وقوع رویدادها، مثل ثبت سفارش یا تغییر موجودی، به‌صورت خودکار نوتیفیکیشن دریافت کنید، حتماً بخش مربوط به پیکربندی وب‌هوک‌ها را بخوانید.

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