شروع توسعه
این سند راهنمای قدم اول تا اولین فراخوانی در مسیر توسعه برنامهتان را با استفاده از 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]
توجه داشته باشید که لیست 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) بزنید.
-
وبهوکها را راهاندازی کنید: اگر میخواهید هنگام وقوع رویدادها، مثل ثبت سفارش یا تغییر موجودی، بهصورت خودکار نوتیفیکیشن دریافت کنید، حتماً بخش مربوط به پیکربندی وبهوکها را بخوانید.
مستندات توسعهدهندگان همیشه در دسترس شماست تا هر زمان که نیاز داشتید، به جزئیات دقیقتری دست پیدا کنید و تجربه توسعهی سریعتری داشته باشید.