شروع توسعه

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

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

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

پیش‌نیازها

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

احراز هویت در API باسلام

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

توکن دسترسی شخصی

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

جریان کد مجوز

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

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

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"
  }
}

اعتبارنامه‌ کلاینت

برای 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": "*"
  }'

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

برای اعتبارسنجی توکن دریافتی نیز می‌توانید از اندپوینت /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: افزودن محصول جدید

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

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

curl -X POST https://uploadio.basalam.com/v3/files \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@test-image.jpg" \
-F "file_type=product.photo" 
</Tab>
<Tab>
```python copy
import requests
 
def upload_file(token, file_path):
response = requests.post(
'https://uploadio.basalam.com/v3/files',
headers={'Authorization': f'Bearer {token}'},
files={'file': open(file_path, 'rb')}
)
return response.json()

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

{
  "id": "238300331",
  "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/v4/vendors/{vendor_id}/products \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-d '{
"name": "محصول نمونه",
"photo": 238300331,
"photos": [238300331],
"brief": "توضیحات کوتاه محصول",
"description": "توضیحات کامل محصول نمونه",
"preparation_days": 3,
"weight": 500,
"package_weight": 600,
"primary_price": 150000,
"stock": 10,
"sku": "PRODUCT-SKU-001",
"is_wholesale": false
}'

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

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

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

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

{
    "data": [
        {
            "id": 24018670,
            "title": "تیشرت پسرانه تابستانی",
            "price": 100000,
            "photo": {
                "id": 236016433,
                "original": "...",
                "xs": "...",
                "sm": "...",
                "md": "...",
                "lg": "..."
            },
            "status": {
                "name": "در دسترس",
                "value": 2976,
            },
            "inventory": 10,
            "is_wholesale": false
        }
    ],
    ...,
    "total_count": 5319,
    "result_count": 10,
    "total_page": 532,
    "page": 1,
    "per_page": 10
}

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

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

گام‌های بعدی

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

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

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

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