شروع سریع توسعه

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

توصیه مهم: استفاده از SDK باسلام

قبل از شروع کار با API مستقیم، قویاً توصیه می‌کنیم از SDK رسمی باسلام استفاده کنید. این SDK‌ها زمان توسعه را تا 70% کاهش می‌دهند و بسیاری از پیچیدگی‌ها را به صورت خودکار مدیریت می‌کنند.

مستندات SDK | نصب سریع SDK پایتون: pip install basalam-sdk

پیش‌نیازها

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

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

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

سناریو	روش احراز هویت
توسعه اپلیکیشن اختصاصی برای یک غرفه یا کاربر مثلاً یک پنل مدیریتی شخصی یا اسکریپت اتوماسیون برای یک غرفه یا حساب کاربری خاص	Personal Access Token
توسعه اپلیکیشن عمومی برای کاربران باسلام (Third-Party) مثلاً یک ابزار تحلیلی یا پلاگین فروشگاهی که کاربران پس از احراز هویت، به شما اجازه‌ دسترسی به اطلاعات خود را بدهند	Authorization Code Flow
ارتباط سیستمی با سرویس‌های مالی/حقوقی باسلام که بدون دخالت مستقیم کاربر، نیاز به ارسال ریکوئست به API دارند ارسال درخواست به سرویس‌هایی مانند کیف پول، امور مالی یا تسویه‌حساب که از طرف یک کاربر حقوقی، سازمان یا سیستم احراز هویت می‌شوند، نه کاربر نهایی	Client Credentials Flow

شروع سریع با SDK

SDK باسلام ساده‌ترین و سریع‌ترین راه برای کار با API های باسلام است. با استفاده از 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 مراجعه کنید.

اگر ترجیح می‌دهید مستقیماً با API کار کنید، ادامه این مستند نحوه استفاده از 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"

برای مشاهده لیست کامل Scope‌ها، به صفحه مستندات دسترسی‌ها مراجعه کنید.

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

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

cURL


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

Python


import requests
 
def get_access_token(code):
    response = requests.post(
        'https://auth.basalam.com/oauth/token',
        json={
            'grant_type': 'authorization_code',
            'client_id': 'YOUR_CLIENT_ID',
            'client_secret': 'YOUR_CLIENT_SECRET',
            'redirect_uri': 'YOUR_REDIRECT_URI',
            'code': code
        }
    )
    return response.json()

PHP


function getAccessToken($code) {
    $response = file_get_contents('https://auth.basalam.com/oauth/token', false, stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => "Content-Type: application/json",
            'content' => json_encode([
                'grant_type' => 'authorization_code',
                'client_id' => 'YOUR_CLIENT_ID',
                'client_secret' => 'YOUR_CLIENT_SECRET',
                'redirect_uri' => 'YOUR_REDIRECT_URI',
                'code' => $code
            ])
        ]
    ]));
    
    return json_decode($response, true);
}

JavaScript


async function getAccessToken(code) {
    const response = await fetch('https://auth.basalam.com/oauth/token', {
        method: 'POST',
        headers: {'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: code
        })
    });
    
    return await response.json();
}

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


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

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

cURL


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

Python


import requests
 
def get_user_info(token):
    response = requests.get(
        'https://core.basalam.com/v3/users/me',
        headers={
            'Accept': 'application/json',
            'Authorization': f'Bearer {token}'
        }
    )
    return response.json()

PHP


function getUserInfo($token) {
    $response = file_get_contents('https://core.basalam.com/v3/users/me', false, stream_context_create([
        'http' => [
            'method' => 'GET',
            'header' => "Accept: application/json\r\nAuthorization: Bearer $token"
        ]
    ]));
    
    return json_decode($response, true);
}

JavaScript


async function getUserInfo(token) {
    const response = await fetch('https://core.basalam.com/v3/users/me', {
        headers: {
            'Accept': 'application/json',
            'Authorization': `Bearer ${token}`
        }
    });
    
    return await response.json();
}

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


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

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

برای APIهایی که نیازمند دسترسی و کاربر از نوع حقوقی است، برای نمونه، دریافت تراز غرفه یا تاریخچه کیف پول، باید از احراز هویت کلاینت استفاده کنید:

cURL


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": "*"
  }'

Python


import requests
 
def get_client_token():
    response = requests.post(
        'https://auth.basalam.com/oauth/token',
        json={
            'grant_type': 'client_credentials',
            'client_id': 'YOUR_CLIENT_ID',
            'client_secret': 'YOUR_CLIENT_SECRET',
            'scope': '*'
        }
    )
    return response.json().get('access_token')

PHP


function getClientToken() {
    $response = file_get_contents('https://auth.basalam.com/oauth/token', false, stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => 'Content-Type: application/json',
            'content' => json_encode([
                'grant_type' => 'client_credentials',
                'client_id' => 'YOUR_CLIENT_ID',
                'client_secret' => 'YOUR_CLIENT_SECRET',
                'scope' => '*'
            ])
        ]
    ]));
    
    $data = json_decode($response, true);
    return $data['access_token'];
}

JavaScript


async function getClientToken() {
    const response = await fetch('https://auth.basalam.com/oauth/token', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
            grant_type: 'client_credentials',
            client_id: 'YOUR_CLIENT_ID',
            client_secret: 'YOUR_CLIENT_SECRET',
            scope: '*'
        })
    });
    
    const data = await response.json();
    return data.access_token;
}

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

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

cURL


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

Python


import requests
 
def verify_token(token):
response = requests.get(
'https://auth.basalam.com/whoami',
headers={
'Authorization': f'Bearer {token}',
'Accept': 'application/json'
}
)
return response.json() if response.status_code == 200 else None

PHP


function verifyToken($token) {
$response = file_get_contents('https://auth.basalam.com/whoami', false, stream_context_create([
  'http' => [
'method' => 'GET',
'header' => "Authorization: Bearer $token\r\nAccept: application/json"
]
]));
 
return json_decode($response, true);
}

JavaScript


async function verifyToken(token) {
const response = await fetch('https://auth.basalam.com/whoami', {
headers: {
'Authorization': `Bearer ${token}`,
'Accept': 'application/json'
}
});
 
return await response.json();
}

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


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

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

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

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

cURL


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" 
</Tabs.Tab>
<Tabs.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()

Python


function uploadFile($token, $filePath) {
$ch = curl_init('https://uploadio.basalam.com/v3/files');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
CURLOPT_POSTFIELDS => ['file' => new CURLFile($filePath)]
]);
 
$response = curl_exec($ch);
curl_close($ch);
 
return json_decode($response, true);
}

PHP


async function uploadFile(token, fileInput) {
const formData = new FormData();
formData.append('file', fileInput.files[0]);
 
const response = await fetch('https://uploadio.basalam.com/v3/files', {
method: 'POST',
headers: {'Authorization': `Bearer ${token}`},
body: formData
});
 
return await 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
}

مستندات API سرویس آپلود

افزودن محصول

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

cURL


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

Python


import requests
 
def add_product(token, product_data):
response = requests.post(
'https://core.basalam.com/v4/vendors/{vendor_id}/products',
headers={
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json',
'Accept': 'application/json'
},
json=product_data
)
return response.json()
 
product = {
"name": "محصول نمونه",
"photo": 238300331,
"photos": [238300331],
"brief": "توضیحات کوتاه محصول",
"description": "توضیحات کامل محصول نمونه",
"status": 1,
"preparation_days": 3,
"weight": 500,
"package_weight": 600,
"primary_price": 150000,
"stock": 10,
"sku": "PRODUCT-SKU-001",
"is_wholesale": False
}

PHP


function addProduct($token, $productData) {
$response = file_get_contents('https://core.basalam.com/v4/vendors/{vendor_id}/products', false, stream_context_create([
  'http' => [
'method' => 'POST',
'header' => "Authorization: Bearer $token\r\nContent-Type: application/json\r\nAccept: application/json",
'content' => json_encode($productData)
]
]));
 
return json_decode($response, true);
}
 
$product = [
"name" => "محصول نمونه",
"photo" => 238300331,
"photos" => [238300331],
"brief" => "توضیحات کوتاه محصول",
"description" => "توضیحات کامل محصول نمونه",
"status" => 1,
"preparation_days" => 3,
"weight" => 500,
"package_weight" => 600,
"primary_price" => 150000,
"stock" => 10,
"sku" => "PRODUCT-SKU-001",
"packaging_dimensions" => [
"height" => 10,
"length" => 20,
"width" => 15
],
"is_wholesale" => false
];

JavaScript


async function addProduct(token, productData) {
const response = await fetch('https://core.basalam.com/v4/vendors/{vendor_id}/products', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify(productData)
});
 
return await response.json();
}
 
const product = {
name: "محصول نمونه",
photo: 238300331,
photos: [238300331],
brief: "توضیحات کوتاه محصول",
description: "توضیحات کامل محصول نمونه",
status: 1,
preparation_days: 3,
weight: 500,
package_weight: 600,
primary_price: 150000,
stock: 10,
sku: "PRODUCT-SKU-001",
packaging_dimensions: {
height: 10,
length: 20,
width: 15
},
is_wholesale: false
};

API افزودن محصول، دو فیلد مرتبط با تصویر به نام‌های photoو photos دارد که فیلد اول تنها یک آ‌ی‌دی و فیلد دوم لیستی از آی‌دی‌ها (که آلبوم محصول را تشکیل می‌دهند) را می‌پذیرد. توصیه می‌شود آی‌دی‌ای که به فیلد photo پاس می‌دهید را نیز اولین ‌آی‌دی فیلد photos قرار دهید.

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

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

cURL


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

Python


url = "https://core.basalam.com/v3/vendors/{vendor_id}/products"
headers = {
"Authorization": f"Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
}
 
response = requests.get(url, headers=headers)
products = response.json()

PHP


<?php
$url = "https://core.basalam.com/v3/vendors/{vendor_id}/products";
 
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer YOUR_ACCESS_TOKEN",
        "Content-Type: application/json"
    )
));
 
$response = curl_exec($curl);
curl_close($curl);
$products = json_decode($response, true);
?>

JavaScript


fetch("https://core.basalam.com/v3/vendors/{vendor_id}/products", {
headers: {
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
}
})
.then(response => response.json())
.then(products => console.log(products));

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


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

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

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

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

گام‌های بعدی

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

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

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