API ساخت دستهبندی و درخت دستهبندیها
این راهنما نحوهٔ ساخت دستهبندی محصولات و تعریف رابطهٔ والد و فرزندی میان دستهبندیها را توضیح میدهد.
در سازیتو، دستهبندی و درخت دستهبندیها دو مفهوم جدا هستند:
- دستهبندی، اطلاعاتی مانند نام، توضیحات و وضعیت فعالبودن را نگه میدارد.
- درخت دستهبندیها، ترتیب نمایش و رابطهٔ والد و فرزندی دستهبندیها را مشخص میکند.
بنابراین ابتدا باید دستهبندیها را بسازید و شناسهٔ آنها را دریافت کنید؛ سپس این شناسهها را در ساختار درخت قرار دهید.
آدرس پایه و احراز هویت
آدرس دامنهٔ فروشگاه را پیش از مسیر API قرار دهید:
export BASE_URL="https://your-store.example.com/api/v1"
export USER_TOKEN="your-admin-jwt"
نام میزبان برای شناسایی فروشگاه استفاده میشود؛ بنابراین درخواست باید به دامنهٔ همان فروشگاه ارسال شود.
درخواستهای خواندنی این راهنما عمومی هستند. برای ساخت یا تغییر دستهبندی و درخت، JWT کاربر ادمین را در هدر زیر بفرستید:
Authorization: your-admin-jwt
Content-Type: application/json
مقدار Authorization را خود token بفرستید؛ پیشوند Bearer هم پذیرفته میشود. token باید متعلق به همین فروشگاه باشد و کاربر آن مجوز عملیات موردنظر را داشته باشد:
- ساخت دستهبندی و بهروزرسانی درخت دستهبندیها (
update_tree): مجوز «ایجاد» دستهبندی - بهروزرسانی دستهبندی: مجوز «ویرایش» دستهبندی
- حذف دستهبندی: مجوز «حذف» دستهبندی
- ساخت یا بهروزرسانی درخت عمومی (
trees/construct): مجوز ایجاد درخت از دسترسیهای بخش قالب
مسیرهای
/product_categoriesو/treesدر حال حاضر ازX-API-Keyبرای احراز هویت درخواستهای نوشتنی پشتیبانی نمیکنند. در این مسیرها هدرX-API-Keyنادیده گرفته میشود؛ درخواستهای خواندنی مثل درخواست عمومی پاسخ میگیرند و درخواستهای نوشتنی با خطای403رد میشوند.
خلاصهٔ مسیرها
| عملیات | متد | مسیر | احراز هویت |
|---|---|---|---|
| ساخت دستهبندی | POST |
/product_categories |
JWT ادمین |
| دریافت دستهبندیها و درخت فعلی | GET |
/product_categories |
عمومی |
| دریافت یک دستهبندی | GET |
/product_categories/{category_id} |
عمومی |
| بهروزرسانی دستهبندی | PUT |
/product_categories/{category_id} |
JWT ادمین |
| بهروزرسانی درخت دستهبندیها | POST |
/product_categories/update_tree |
JWT ادمین |
| ساخت یا بهروزرسانی یک درخت عمومی | POST |
/trees/construct |
JWT ادمین |
| دریافت یک درخت عمومی | GET |
/trees/fetch_single |
عمومی |
جریان پیشنهادی
برای ساخت دستهبندی و درخت آن، مراحل زیر را بهترتیب انجام دهید:
- دستهبندی والد را بسازید.
- دستهبندیهای فرزند را بسازید.
- شناسهٔ هر دستهبندی را از پاسخ API دریافت کنید.
- درخت فعلی را دریافت کنید.
- ساختار کامل درخت را با شناسههای جدید ارسال کنید.
- پاسخ API را بررسی کنید و مطمئن شوید همهٔ گرهها در جای درست قرار دارند.
ساخت دستهبندی
POST /api/v1/product_categories
بدنهٔ درخواست
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
name |
string | بله | نام دستهبندی؛ سرور ارسال آن را بررسی نمیکند، پس حتماً آن را بفرستید |
description |
string | خیر | توضیحات دستهبندی |
enabled |
boolean | خیر | وضعیت فعالبودن دستهبندی؛ اگر ارسال نشود، دستهبندی غیرفعال (false) ساخته میشود |
static_url |
boolean | خیر | مشخص میکند آدرس دستهبندی دستی باشد یا خودکار ساخته شود |
url |
string | خیر | فقط وقتی static_url برابر true باشد استفاده میشود. فقط بخش انتهایی آدرس (slug) را بفرستید، مثلاً digital-goods؛ آدرس نهایی /category/digital-goods میشود. اگر این آدرس تکراری باشد، یک پسوند ۵ کاراکتری به آن اضافه میشود |
attributes |
array | خیر | ویژگیهای تکمیلی دستهبندی |
اگر static_url برابر false باشد یا url ارسال نشود، آدرس دستهبندی بر اساس نام آن ساخته میشود. در این حالت با تغییر نام دستهبندی، آدرس آن هم تغییر میکند.
نمونهٔ درخواست
curl --request POST "$BASE_URL/product_categories" \
--header "Authorization: $USER_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"name": "کالای دیجیتال",
"description": "انواع کالاهای دیجیتال",
"enabled": true,
"static_url": false
}'
نمونهٔ پاسخ
{
"result": {
"product_category": {
"id": 101,
"name": "کالای دیجیتال",
"enabled": true,
"static_url": false,
"url": "/category/کالای-دیجیتال",
"description": "انواع کالاهای دیجیتال",
"attributes": [],
"products_count": 0
}
},
"error": "",
"error_code": 0,
"status": 200
}
مقدار result.product_category.id را نگه دارید؛ برای قراردادن دستهبندی در درخت به این شناسه نیاز دارید.
برای ساخت دستهبندیهای «موبایل» و «لوازم جانبی» نیز همین درخواست را تکرار کنید. در ادامه فرض میکنیم شناسههای زیر دریافت شدهاند:
| دستهبندی | شناسه |
|---|---|
| کالای دیجیتال | 101 |
| موبایل | 102 |
| لوازم جانبی | 103 |
بهروزرسانی دستهبندی
PUT /api/v1/product_categories/{category_id}
بدنهٔ این درخواست همان فیلدهای جدول ساخت دستهبندی را میپذیرد و فقط فیلدهای ارسالشده تغییر میکنند. پاسخ هم مانند پاسخ ساخت، در result.product_category برمیگردد.
اگر
category_idوجود نداشته باشد، خطایی برنمیگردد و یک دستهبندی جدید با شناسهٔ دیگری ساخته میشود. پیش از ارسالPUT، وجود دستهبندی را باGET /api/v1/product_categories/{category_id}بررسی کنید.
دریافت دستهبندیها و درخت فعلی
پیش از هر تغییر، ساختار فعلی درخت را دریافت کنید:
curl --get "$BASE_URL/product_categories" \
--header "Authorization: $USER_TOKEN" \
--data-urlencode "page_number=1" \
--data-urlencode "page_size=100"
پاسخ شامل دو بخش اصلی است:
{
"result": {
"product_categories": [],
"tree": {
"id": 12,
"tree_type": "product_categories",
"tree_structure": {
"nodes": []
}
}
},
"error": "",
"error_code": 0,
"status": 200
}
product_categoriesشامل فهرست دستهبندیها است.tree.tree_structure.nodesساختار فعلی درخت را نشان میدهد.- فهرست
product_categoriesصفحهبندی دارد (پیشفرض ۲۰ مورد و حداکثر ۲۰۰ مورد در هر صفحه)، اماtreeهمیشه کل درخت را برمیگرداند. - این درخواست بدون JWT هم پاسخ میدهد، ولی در آن حالت درخت پیش از پاسخ ترمیم نمیشود و ممکن است دستهبندیهای تازه ساختهشده هنوز در آن نباشند. برای ویرایش درخت، آن را با JWT ادمین بخوانید.
ساخت یا بهروزرسانی درخت دستهبندیها
POST /api/v1/product_categories/update_tree
این مسیر رابطهٔ والد و فرزندی دستهبندیهای محصولات را مشخص میکند.
ساختار هر گره
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
id |
number | فقط برای گره موجود | شناسهٔ گره درخت؛ با شناسهٔ دستهبندی تفاوت دارد |
entity_type |
string | برای گره جدید بله | برای درخت دستهبندیها باید product_category باشد؛ برای گره موجود (با id) اگر ارسال نشود، مقدار ذخیرهشده استفاده میشود |
entity_id |
number | برای گره جدید بله | شناسهٔ دستهبندی؛ برای گره موجود (با id) اگر ارسال نشود، مقدار ذخیرهشده استفاده میشود |
details |
object | خیر | اطلاعات تکمیلی گره |
children |
array | خیر | فهرست گرههای فرزند؛ اگر ارسال نشود، گره فرزندی ندارد |
idشناسهٔ خود گره درخت است، اماentity_idشناسهٔ دستهبندی است. این دو مقدار را با یکدیگر اشتباه نگیرید.
میتوانید گرهها را همانطور که در پاسخ GET آمدهاند (همراه entity، created_at و updated_at) دوباره ارسال کنید؛ فیلد entity هنگام ذخیره نادیده گرفته میشود.
نمونهٔ درخواست
در نمونهٔ زیر، «کالای دیجیتال» دستهبندی والد و «موبایل» و «لوازم جانبی» فرزندان آن هستند:
curl --request POST "$BASE_URL/product_categories/update_tree" \
--header "Authorization: $USER_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"nodes": [
{
"entity_type": "product_category",
"entity_id": 101,
"details": {},
"children": [
{
"entity_type": "product_category",
"entity_id": 102,
"details": {},
"children": []
},
{
"entity_type": "product_category",
"entity_id": 103,
"details": {},
"children": []
}
]
}
]
}'
نمونهٔ پاسخ
{
"result": {
"tree": {
"id": 12,
"tree_type": "product_categories",
"identifier": "",
"tree_structure": {
"nodes": [
{
"id": 501,
"entity_type": "product_category",
"entity_id": 101,
"entity": {
"id": 101,
"name": "کالای دیجیتال",
"enabled": true,
"static_url": false,
"url": "/category/کالای-دیجیتال"
},
"details": {},
"children": [
{
"id": 502,
"entity_type": "product_category",
"entity_id": 102,
"entity": {
"id": 102,
"name": "موبایل",
"enabled": true,
"static_url": false,
"url": "/category/موبایل"
},
"details": {},
"children": []
},
{
"id": 503,
"entity_type": "product_category",
"entity_id": 103,
"entity": {
"id": 103,
"name": "لوازم جانبی",
"enabled": true,
"static_url": false,
"url": "/category/لوازم-جانبی"
},
"details": {},
"children": []
}
]
}
]
}
}
},
"error": "",
"error_code": 0,
"status": 200
}
پاسخ، کل درخت ذخیرهشده است: دستهبندیهایی که در درخواست نبودند هم در انتهای سطح اصلی دیده میشوند. در این پاسخ entity هر گره، شیء کامل دستهبندی است و در نمونهٔ بالا فقط چند فیلد آن آمده است.
نکات مهم دربارهٔ بهروزرسانی درخت
همیشه ساختار کامل را ارسال کنید
درخواست بهروزرسانی درخت، یک تغییر جزئی روی یک شاخه نیست. بدنهٔ درخواست باید ساختار کامل موردنظر را در nodes داشته باشد.
پیش از تغییر:
- درخت فعلی را دریافت کنید.
- تغییر موردنظر را روی همان ساختار اعمال کنید.
- کل ساختار نهایی را دوباره ارسال کنید.
گرههای موجودی که در درخواست جدید نیستند، از درخت حذف میشوند؛ خود دستهبندی حذف نمیشود. سپس هر دستهبندیای که در هیچ جای ساختار ارسالی نیامده باشد، با یک گره جدید (و شناسهٔ گرهٔ جدید) به انتهای سطح اصلی درخت اضافه میشود. بنابراین ارسال {"nodes": []} همهٔ دستهبندیها را بدون والد در سطح اصلی قرار میدهد.
شناسهٔ گرههای موجود را حفظ کنید
در پاسخ API، هر گره یک id دارد. هنگام بهروزرسانی درخت بهتر است id گرههای موجود را بدون تغییر ارسال کنید. برای گره جدید، فیلد id را ارسال نکنید.
نمونهٔ افزودن یک فرزند جدید به یک گره موجود:
{
"nodes": [
{
"id": 501,
"entity_type": "product_category",
"entity_id": 101,
"details": {},
"children": [
{
"id": 502,
"entity_type": "product_category",
"entity_id": 102,
"details": {},
"children": []
},
{
"id": 503,
"entity_type": "product_category",
"entity_id": 103,
"details": {},
"children": []
},
{
"entity_type": "product_category",
"entity_id": 104,
"details": {},
"children": []
}
]
}
]
}
در این نمونه، گرههای 501، 502 و 503 از قبل وجود دارند و دستهبندی 104 بهعنوان گره جدید اضافه میشود. اگر گره 503 را از این درخواست حذف کنید، دستهبندی 103 از زیر «کالای دیجیتال» خارج و به سطح اصلی درخت منتقل میشود.
فقط از شناسهٔ دستهبندی معتبر استفاده کنید
مقدار entity_id باید شناسهٔ یک دستهبندی موجود در همان فروشگاه باشد. شناسه را از پاسخ ساخت دستهبندی یا فهرست دستهبندیها بردارید. سرور این مقدار را بررسی نمیکند و خطا برنمیگرداند؛ گرهٔ دارای شناسهٔ نامعتبر ذخیره میشود، اما همراه با همهٔ فرزندانش در پاسخها نمایش داده نمیشود.
یک دستهبندی را چند بار در درخت قرار ندهید
هر دستهبندی باید فقط در یک نقطه از درخت قرار بگیرد. تکرار یک entity_id در چند شاخه میتواند ساختار درخت را ناسازگار کند.
برای حذف دستهبندی، فقط گره آن را حذف نکنید
حذف یک گره از درخت بهمعنای حذف خود دستهبندی نیست. برای حذف کامل دستهبندی باید از مسیر حذف دستهبندی استفاده شود:
DELETE /api/v1/product_categories/{category_id}
حذف دستهبندی، گرهٔ آن را از درخت پاک نمیکند. اگر دستهبندی حذفشده زیردسته داشته باشد، گرهٔ آن همراه با کل زیرشاخهاش از پاسخ درخت پنهان میشود و زیردستهها تا ارسال دوبارهٔ درخت دیده نمیشوند. بنابراین پیش از حذف چنین دستهبندیای، ابتدا با update_tree زیردستههایش را به جای دیگری منتقل کنید.
ساخت درخت عمومی
اگر هدف، ساخت منوی سایت یا یک درخت عمومی است، از مسیر زیر استفاده کنید:
POST /api/v1/trees/construct
درخت را میتوان با identifier یا id مشخص کرد. با id فقط درخت موجود بهروزرسانی میشود و درخت جدید ساخته نمیشود. اگر هر دو پارامتر ارسال شوند، id ملاک است. این درخواست هم کل ساختار درخت را جایگزین میکند و گرههایی که ارسال نشوند حذف میشوند.
ساخت یا بهروزرسانی با identifier
POST /api/v1/trees/construct?identifier=headermenu&tree_type=navigation
اگر درختی با identifier ارسالشده وجود نداشته باشد، ساخته میشود. tree_type فقط هنگام ساخت درخت جدید اعمال میشود و برای درخت موجود نادیده گرفته میشود. مقدارهای مجاز tree_type عبارتاند از:
| مقدار | کاربرد |
|---|---|
navigation |
منو و ناوبری سایت |
general |
درخت عمومی |
برای identifier=headermenu، اگر tree_type ارسال نشود، نوع درخت بهصورت خودکار navigation در نظر گرفته میشود. سایر identifierها بهصورت پیشفرض از نوع general هستند. مقدار نامعتبر tree_type رد نمیشود و درخت بدون نوع ذخیره میشود.
برای درخت دستهبندی محصولات از
trees/constructاستفاده نکنید و فقط از/product_categories/update_treeاستفاده کنید. این مسیر دستهبندیهای جاافتاده را به درخت اضافه نمیکند و کش فهرست دستهبندیها را هم پاک نمیکند.
نوع گرههای درخت عمومی
entity_type |
کاربرد |
|---|---|
product_category |
دستهبندی محصول |
product |
محصول |
cms_page |
صفحهٔ محتوایی |
blog_page |
صفحهٔ وبلاگ |
url |
لینک دلخواه |
برای گرههای متصل به یک موجودیت، مانند محصول یا دستهبندی، entity_id را ارسال کنید. برای لینک دلخواه، عنوان و آدرس در details قرار میگیرند.
نمونهٔ ساخت منوی سایت
curl --request POST \
"$BASE_URL/trees/construct?identifier=headermenu&tree_type=navigation" \
--header "Authorization: $USER_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"nodes": [
{
"entity_type": "url",
"details": {
"title": "صفحهٔ اصلی",
"url": "/"
},
"children": []
},
{
"entity_type": "product_category",
"entity_id": 101,
"details": {
"title": "محصولات",
"includeChildren": true
},
"children": []
}
]
}'
اگر includeChildren برای یک دستهبندی برابر true باشد، زیردستههای آن هنگام دریافت درخت بهصورت پویا به منو اضافه میشوند. فرزندانی که خودتان زیر چنین گرهای ارسال کنید نمایش داده نمیشوند و با زیردستههای فعلی جایگزین میشوند.
دریافت درخت عمومی
دریافت با identifier:
curl --get "$BASE_URL/trees/fetch_single" \
--data-urlencode "identifier=headermenu"
دریافت با شناسهٔ درخت:
curl --get "$BASE_URL/trees/fetch_single" \
--data-urlencode "id=12"
حداقل یکی از پارامترهای id یا identifier باید ارسال شود. پاسخ در result.tree برمیگردد. در دریافت با identifier، فیلد entity هر گره خلاصه است (برای دستهبندی و محصول: id، name، enabled، static_url و url؛ برای صفحهها title بهجای name). در دریافت با id، شیء کامل موجودیت برمیگردد. گرههایی که موجودیتشان حذف شده، همراه با فرزندانشان در پاسخ نمیآیند.
خطاهای متداول
| کد HTTP | علت احتمالی |
|---|---|
400 |
در update_tree و trees/construct: بدنهٔ درخواست JSON معتبر نیست. در مسیرهای /trees: هیچکدام از id و identifier ارسال نشده («پارامترهای ورودی معتبر نیست») یا درخت پیدا نشد («ساختار دسته بندی یافت نشد»). در GET /product_categories/{category_id}: دستهبندی وجود ندارد («پارامترهای ورودی معتبر نیست») |
403 |
JWT ارسال نشده، نامعتبر یا منقضی است، متعلق به فروشگاه دیگری است، یا کاربر مجوز عملیات موردنظر را ندارد |
418 |
دریافت درخت با id در فروشگاهی که هنوز هیچ درختی ندارد («ساختار دسته بندی وجود ندارد») |
بدنهٔ خطاهای 400 و 418 به شکل {"errors": {"message": "..."}} است. بدنهٔ خطای 403 به شکل {"message": "User is not allowed to do the action"} است.
این موارد خطا برنمیگردانند:
- در ساخت و بهروزرسانی دستهبندی، JSON نامعتبر نادیده گرفته میشود؛ در
POSTیک دستهبندی بدون نام و غیرفعال ساخته میشود و درPUTچیزی تغییر نمیکند. entity_typeیاentity_idنامعتبر در درخت ذخیره میشود، اما گره در پاسخها نمایش داده نمیشود.
هنگام دریافت خطا، ابتدا موارد زیر را بررسی کنید:
- دامنهٔ درخواست متعلق به همان فروشگاه باشد.
- برای درخواست نوشتنی، JWT معتبر در هدر
Authorizationارسال شده باشد. - بدنهٔ درخواست JSON معتبر باشد.
- مقدار
entity_typeدرست نوشته شده باشد. - همهٔ
entity_idها به موجودیتهای معتبر در همان فروشگاه اشاره کنند. - در درخواست بهروزرسانی، ساختار کامل درخت ارسال شده باشد.