شروع سریع Open API باسلام

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

اگر از Python یا PHP استفاده می‌کنید، SDK باسلام بخشی از فرایند احراز هویت، ارسال درخواست و مدیریت خطاها را برای شما ساده‌تر می‌کند. برای آشنایی با API و عیب‌یابی اتصال، پیشنهاد می‌کنیم ابتدا این راهنما را بخوانید.

در این راهنما

پیش‌نیازها
آدرس‌های پایه
انتخاب روش احراز هویت
مسیر سریع: توکن دسترسی شخصی
ارسال اولین درخواست
شروع سریع با SDK
اتصال برنامه‌های عمومی با Authorization Code
اعتبارسنجی توکن
نمونهٔ کامل: افزودن محصول
خطاهای رایج
گام‌های بعدی

پیش‌نیازها

برای شروع به موارد زیر نیاز دارید:

یک حساب کاربری باسلام
دسترسی به پنل توسعه‌دهندگان
یکی از این دو مورد، متناسب با روش احراز هویت:
- توکن دسترسی شخصی (PAT)
- Client ID و Client Secret

Client Secret و توکن‌های دسترسی اطلاعات محرمانه‌اند. آن‌ها را در مخزن کد، لاگ‌ها، کد سمت مرورگر یا اپلیکیشن موبایل قرار ندهید. تبادل کد مجوز با توکن باید در سرور انجام شود.

آدرس‌های پایه

در این راهنما از سه دامنه استفاده می‌شود:

کاربرد	آدرس
فراخوانی APIهای باسلام	`https://openapi.basalam.com`
دریافت و اعتبارسنجی توکن	`https://auth.basalam.com`
دریافت مجوز از کاربر	`https://basalam.com/accounts/sso`

انتخاب روش احراز هویت

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

سناریو	روش مناسب
اسکریپت یا ابزار اختصاصی برای حساب یا غرفهٔ خودتان	Personal Access Token
برنامهٔ عمومی که هر کاربر باسلام به آن اجازهٔ دسترسی می‌دهد	Authorization Code Flow

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

مسیر سریع: توکن دسترسی شخصی

توکن دسترسی شخصی برای توسعه، آزمایش و ابزارهایی مناسب است که فقط به حساب خودتان متصل می‌شوند. برای برنامه‌ای که قرار است کاربران مختلف از آن استفاده کنند، از Authorization Code Flow استفاده کنید.

برای دریافت توکن:

وارد بخش توکن‌های دسترسی شخصی در پنل توسعه‌دهندگان شوید.
Scopeهای موردنیاز برنامه را انتخاب کنید.
توکن را ایجاد و در یک محل امن ذخیره کنید.

فهرست Scopeها و کاربرد هرکدام در مستندات دسترسی‌ها قرار دارد.

ارسال اولین درخواست

برای اطمینان از صحت اتصال، اطلاعات کاربر فعلی را از GET /v1/users/me دریافت کنید. مقدار YOUR_ACCESS_TOKEN را با توکن خود جایگزین کنید.

cURL


curl https://openapi.basalam.com/v1/users/me \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Python


import requests
 
response = requests.get(
    'https://openapi.basalam.com/v1/users/me',
    headers={
        'Accept': 'application/json',
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
)
response.raise_for_status()
 
user = response.json()
print(user)

PHP


<?php
$ch = curl_init('https://openapi.basalam.com/v1/users/me');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer YOUR_ACCESS_TOKEN'
    ]
]);
 
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($status !== 200) {
    throw new RuntimeException("Request failed with status $status");
}
 
$user = json_decode($response, true);
print_r($user);

JavaScript


const response = await fetch('https://openapi.basalam.com/v1/users/me', {
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
});
 
if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}
 
const user = await response.json();
console.log(user);

نمونهٔ پاسخ موفق:


{
  "id": 123456,
  "hash_id": "abc123",
  "username": "sample-user",
  "name": "کاربر نمونه",
  "vendor": {
    "id": 78910,
    "identifier": "sample-vendor",
    "title": "غرفه نمونه"
  }
}

شناسهٔ vendor.id را نگه دارید؛ برای فراخوانی APIهای مرتبط با غرفه، از جمله مدیریت محصولات، به آن نیاز دارید.

اگر حساب کاربر غرفه نداشته باشد، ممکن است مقدار vendor در پاسخ تهی باشد. در این حالت، APIهای وابسته به vendor_id قابل‌استفاده نیستند.

اگر پاسخ 200 OK دریافت کردید، اتصال شما برقرار است. در صورت دریافت خطا، بخش خطاهای رایج را بررسی کنید.

شروع سریع با SDK

نصب SDK پایتون


pip install basalam-sdk

دریافت اطلاعات کاربر و محصولات


from basalam import Client
 
client = Client(token="YOUR_ACCESS_TOKEN")
 
user = client.users.get_me()
print(f"سلام {user.name}!")
 
products = client.products.list(vendor_id=user.vendor.id)
for product in products:
    print(f"- {product.name}: {product.price} تومان")

افزودن محصول


new_product = client.products.create(
    vendor_id=user.vendor.id,
    name="محصول جدید",
    price=150000,
    stock=10,
    description="توضیحات محصول"
)
 
print(f"محصول {new_product.name} با موفقیت ایجاد شد.")

برای مشاهدهٔ قابلیت‌ها و تنظیمات SDK، به مستندات SDK مراجعه کنید.

اتصال برنامه‌های عمومی با Authorization Code

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

مرحلهٔ ۱: هدایت کاربر به صفحهٔ مجوز

کاربر را به آدرس زیر هدایت کنید:


https://basalam.com/accounts/sso?client_id=YOUR_CLIENT_ID&scope=REQUESTED_SCOPES&redirect_uri=YOUR_REDIRECT_URI&state=RANDOM_STATE

پارامتر	توضیح
`client_id`	شناسهٔ کلاینت دریافت‌شده از پنل توسعه‌دهندگان
`scope`	فهرست دسترسی‌های موردنیاز برنامه
`redirect_uri`	آدرس بازگشت ثبت‌شده برای کلاینت
`state`	مقدار تصادفی و غیرقابل‌حدس برای جلوگیری از حملات CSRF

Scopeها را با فاصله از هم جدا و تمام پارامترها را URL-encode کنید. برای نمونه: vendor.product.read vendor.product.write customer.order.read

مرحلهٔ ۲: دریافت و بررسی کد مجوز

پس از تأیید دسترسی، کاربر به redirect_uri بازگردانده می‌شود و پارامترهای code و state در رشتهٔ پرس‌وجو (Query String) قرار می‌گیرند.

پیش از ادامه، مقدار state دریافتی را با مقداری که در ابتدای فرایند ایجاد و در نشست کاربر ذخیره کرده‌اید مقایسه کنید. اگر این دو مقدار برابر نیستند، فرایند را متوقف کنید.

مرحلهٔ ۳: تبادل کد با توکن

کد مجوز را از سمت سرور به endpoint زیر ارسال کنید:

cURL


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

Python


import requests
 
response = requests.post(
    'https://auth.basalam.com/oauth/token',
    headers={'Accept': 'application/json'},
    json={
        'grant_type': 'authorization_code',
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET',
        'redirect_uri': 'YOUR_REDIRECT_URI',
        'code': 'AUTHORIZATION_CODE'
    }
)
response.raise_for_status()
 
tokens = response.json()

PHP


<?php
$payload = json_encode([
    'grant_type' => 'authorization_code',
    'client_id' => 'YOUR_CLIENT_ID',
    'client_secret' => 'YOUR_CLIENT_SECRET',
    'redirect_uri' => 'YOUR_REDIRECT_URI',
    'code' => 'AUTHORIZATION_CODE'
]);
 
$ch = curl_init('https://auth.basalam.com/oauth/token');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => $payload
]);
 
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($status !== 200) {
    throw new RuntimeException("Token request failed with status $status");
}
 
$tokens = json_decode($response, true);

JavaScript


const response = await fetch('https://auth.basalam.com/oauth/token', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    redirect_uri: 'YOUR_REDIRECT_URI',
    code: 'AUTHORIZATION_CODE'
  })
});
 
if (!response.ok) {
  throw new Error(`Token request failed with status ${response.status}`);
}
 
const tokens = await response.json();

نمونهٔ پاسخ موفق:


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

توکن‌ها را به‌صورت امن و مرتبط با همان کاربر ذخیره کنید. برای درخواست‌های بعدی، مقدار access_token را در هدر Authorization قرار دهید:


Authorization: Bearer ACCESS_TOKEN

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

برای بررسی اعتبار توکن و مشاهدهٔ اطلاعات هویتی مرتبط با آن، GET /whoami را فراخوانی کنید:


curl https://auth.basalam.com/whoami \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

نمونهٔ پاسخ موفق:


{
  "id": "123456",
  "name": "کاربر نمونه",
  "mobile": "09xxxxxxxxx",
  "hash_id": "abc123",
  "client": {
    "id": "78910",
    "name": "برنامه نمونه",
    "image_url": "https://example.com/image.jpg"
  }
}

نمونهٔ کامل: افزودن محصول

افزودن محصول دو مرحله دارد:

تصویر محصول را آپلود و شناسهٔ فایل را دریافت کنید.
اطلاعات محصول و شناسهٔ تصویر را برای غرفه ارسال کنید.

پیش از شروع، مطمئن شوید توکن شما Scopeهای لازم را دارد و vendor.id را از پاسخ GET /v1/users/me دریافت کرده‌اید.

مرحلهٔ ۱: آپلود تصویر محصول

فایل را با POST /v1/files آپلود کنید. پاسخ این API شامل شناسه‌ای است که در مرحلهٔ بعد به آن نیاز دارید.

cURL


curl -X POST https://openapi.basalam.com/v1/files \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -F 'file=@test-image.jpg' \
  -F 'file_type=product.photo'

Python


import requests
 
with open('test-image.jpg', 'rb') as image:
    response = requests.post(
        'https://openapi.basalam.com/v1/files',
        headers={
            'Accept': 'application/json',
            'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
        },
        files={'file': image},
        data={'file_type': 'product.photo'}
    )
 
response.raise_for_status()
uploaded_file = response.json()

PHP


<?php
$ch = curl_init('https://openapi.basalam.com/v1/files');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer YOUR_ACCESS_TOKEN'
    ],
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('test-image.jpg'),
        'file_type' => 'product.photo'
    ]
]);
 
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Upload failed with status $status");
}
 
$uploadedFile = json_decode($response, true);

JavaScript


const formData = new FormData();
formData.append('file', file);
formData.append('file_type', 'product.photo');
 
const response = await fetch('https://openapi.basalam.com/v1/files', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: formData
});
 
if (!response.ok) {
  throw new Error(`Upload failed with status ${response.status}`);
}
 
const uploadedFile = await response.json();

نمونهٔ پاسخ موفق:


{
  "id": "238300331",
  "file_name": "test-image.jpg",
  "path": "string",
  "mime_type": "image/jpeg",
  "size": 102400,
  "created_at": "2025-05-17T14:25:39Z",
  "creator_user_id": 123456
}

مشاهدهٔ مستندات API آپلود فایل

مرحلهٔ ۲: افزودن محصول

شناسهٔ غرفه را جایگزین {vendor_id} و شناسهٔ فایل آپلودشده را جایگزین 238300331 کنید.

cURL


curl -X POST https://openapi.basalam.com/v1/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
  }'

Python


import requests
 
vendor_id = 78910
product = {
    '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
}
 
response = requests.post(
    f'https://openapi.basalam.com/v1/vendors/{vendor_id}/products',
    headers={
        'Accept': 'application/json',
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    },
    json=product
)
response.raise_for_status()
 
created_product = response.json()

PHP


<?php
$vendorId = 78910;
$product = [
    '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
];
 
$ch = curl_init("https://openapi.basalam.com/v1/vendors/$vendorId/products");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_ACCESS_TOKEN'
    ],
    CURLOPT_POSTFIELDS => json_encode($product)
]);
 
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Create product failed with status $status");
}
 
$createdProduct = json_decode($response, true);

JavaScript


const vendorId = 78910;
const product = {
  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
};
 
const response = await fetch(
  `https://openapi.basalam.com/v1/vendors/${vendorId}/products`,
  {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
      Authorization: 'Bearer YOUR_ACCESS_TOKEN'
    },
    body: JSON.stringify(product)
  }
);
 
if (!response.ok) {
  throw new Error(`Create product failed with status ${response.status}`);
}
 
const createdProduct = await response.json();

فیلد photo شناسهٔ تصویر اصلی و فیلد photos فهرست تصاویر آلبوم محصول است. شناسهٔ تصویر اصلی را به‌عنوان اولین عضو photos نیز ارسال کنید.

بررسی محصولات غرفه

برای بررسی نتیجه، فهرست محصولات غرفه را دریافت کنید:


curl https://openapi.basalam.com/v1/vendors/{vendor_id}/products \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

نمونهٔ پاسخ موفق:


{
  "data": [
    {
      "id": 24018670,
      "title": "تیشرت پسرانه تابستانی",
      "price": 100000,
      "photo": {
        "id": 236016433,
        "original": "https://example.com/original.jpg",
        "xs": "https://example.com/xs.jpg",
        "sm": "https://example.com/sm.jpg",
        "md": "https://example.com/md.jpg",
        "lg": "https://example.com/lg.jpg"
      },
      "status": {
        "name": "در دسترس"
      }
    }
  ]
}

خطاهای رایج

خطا	علت احتمالی	راه‌حل
`invalid_client`	`Client ID` یا `Client Secret` نادرست است	مقادیر کلاینت و محیط اجرایی را بررسی کنید.
`redirect_uri_mismatch`	آدرس بازگشت با مقدار ثبت‌شده یکسان نیست	پروتکل، دامنه، مسیر، پورت و اسلش انتهایی باید دقیقاً مطابق مقدار ثبت‌شده باشند.
`invalid_grant`	کد مجوز نامعتبر، منقضی یا قبلاً استفاده شده است	فرایند دریافت مجوز را دوباره آغاز کنید و کد جدید را فقط یک‌بار مصرف کنید.
`invalid_scope`	یک یا چند Scope نامعتبر یا غیرمجاز است	Scopeها را با فهرست دسترسی‌ها تطبیق دهید.
`401 Unauthorized`	توکن ارسال نشده، نامعتبر یا منقضی است	ساختار هدر `Authorization` و اعتبار توکن را بررسی کنید.
`403 Forbidden`	توکن Scope لازم را ندارد	Scope موردنیاز endpoint را به دسترسی‌های برنامه اضافه کنید.
`422 Unprocessable Entity`	داده‌های درخواست معتبر نیستند	فیلدهای الزامی، نوع داده‌ها و جزئیات خطای پاسخ را بررسی کنید.

هنگام عیب‌یابی، status code و body کامل پاسخ را ثبت کنید؛ اما توکن، Client Secret و اطلاعات حساس کاربران را در لاگ قرار ندهید.

گام‌های بعدی

برای مشاهدهٔ endpointها، پارامترها و مدل پاسخ‌ها به مرجع API بروید.
برای انتخاب حداقل دسترسی لازم، Scopeها را بررسی کنید.
برای دریافت رویدادهایی مانند ثبت سفارش یا تغییر موجودی، وب‌هوک‌ها را راه‌اندازی کنید.
اگر از Python یا PHP استفاده می‌کنید، SDK باسلام را به پروژه اضافه کنید.