فروشگاه ساز سازیتو | مستندات

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 باید متعلق به همین فروشگاه باشد و کاربر آن مجوز عملیات موردنظر را داشته باشد:

مسیرهای /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 عمومی

جریان پیشنهادی

برای ساخت دسته‌بندی و درخت آن، مراحل زیر را به‌ترتیب انجام دهید:

  1. دسته‌بندی والد را بسازید.
  2. دسته‌بندی‌های فرزند را بسازید.
  3. شناسهٔ هر دسته‌بندی را از پاسخ API دریافت کنید.
  4. درخت فعلی را دریافت کنید.
  5. ساختار کامل درخت را با شناسه‌های جدید ارسال کنید.
  6. پاسخ 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
}

ساخت یا به‌روزرسانی درخت دسته‌بندی‌ها

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 داشته باشد.

پیش از تغییر:

  1. درخت فعلی را دریافت کنید.
  2. تغییر موردنظر را روی همان ساختار اعمال کنید.
  3. کل ساختار نهایی را دوباره ارسال کنید.

گره‌های موجودی که در درخواست جدید نیستند، از درخت حذف می‌شوند؛ خود دسته‌بندی حذف نمی‌شود. سپس هر دسته‌بندی‌ای که در هیچ جای ساختار ارسالی نیامده باشد، با یک گره جدید (و شناسهٔ گرهٔ جدید) به انتهای سطح اصلی درخت اضافه می‌شود. بنابراین ارسال {"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"} است.

این موارد خطا برنمی‌گردانند:

هنگام دریافت خطا، ابتدا موارد زیر را بررسی کنید: