شروع توسعه

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

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

• پیش‌نیازها
• احراز هویت کاربر
• احراز هویت کلاینت
• فراخوانی اولین API: افزودن محصول جدید
• خطاهای رایج و رفع مشکل
• گام‌های بعدی

پیش‌نیازها

• حساب کاربری در باسلام (opens in a new tab)
• مشخصات کلاینت شامل Client ID و Client Secret (از بخش مدیریت کلاینت دریافت کنید.)

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

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

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

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

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

پس از اعطای دسترسی به برنامه توسط کاربر، کد تایید 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: '

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

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

گام‌های بعدی

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

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

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

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