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

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

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

برای دسترسی‌های بیشتر، از طریق پشتیبانی/موفقیت مشتری سازیتو درخواست خود را ثبت کنید.

آدرس پایه و احراز هویت

در همهٔ درخواست‌ها، دامنهٔ فروشگاه را پیش از مسیر API قرار دهید:

https://example.com/api/v1

دامنه را بدون www. بنویسید؛ درخواست به نشانی www. با کد 301 به نشانی بدون www هدایت می‌شود و درخواست‌های POST و PUT از کار می‌افتند.

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

X-API-Key: your-api-key

کلید API را مدیر اصلی (سوپرادمین) فروشگاه در پنل مدیریت، از مسیر «تنظیمات ← توسعه‌دهندگان ← کلید Admin API» می‌سازد؛ اگر این بخش برای فروشگاه فعال نیست، از پشتیبانی سازیتو درخواست کنید. کلید به کاربر سازندهٔ آن محدود نیست و همیشه با دسترسی کامل مدیر اصلی فروشگاه عمل می‌کند؛ آن را مانند رمز عبور مدیر محرمانه نگه دارید.

کلید API فقط روی مسیرهای /api/v1/products، /api/v1/images، /api/v1/orders و /api/v1/accounting (و چند مسیر دیگر) پذیرفته می‌شود و روی سایر مسیرها نادیده گرفته می‌شود. کلید نامعتبر یا ارسال‌نشده خطای جداگانه‌ای نمی‌دهد و درخواست مانند درخواست بدون احراز هویت پردازش می‌شود: مثلاً GET /api/v1/products فیلدهای مدیریتی را برنمی‌گرداند و GET /api/v1/orders با کد 200 فهرست خالی برمی‌گرداند، و درخواست‌های نوشتنی با کد 403 و بدنهٔ {"message":"User is not allowed to do the action"} رد می‌شوند.

برای بدنه‌های JSON نیز هدر زیر را ارسال کنید:

Content-Type: application/json

خلاصهٔ endpointها

عملیات متد مسیر احراز هویت
دریافت محصولات GET /api/v1/products عمومی؛ برخی فیلدها با کلید API بازمی‌گردند
دریافت یک محصول GET /api/v1/products/{product_id} عمومی
آپلود تصویر محصول POST /api/v1/images API key
ایجاد محصول POST /api/v1/products API key
به‌روزرسانی محصول PUT /api/v1/products/{product_id} API key
به‌روزرسانی جزئی محصول (SKU، attribute، variant، تصویر) PUT /api/v1/products/partial/{product_id} API key
دریافت taxonomy محصول GET /taxonomy/public/products/{store_id}/{product_id} عمومی
دریافت زیردسته‌های taxonomy GET /taxonomy/public/categories/{category_id}/children عمومی
دریافت metafieldهای دسته GET /taxonomy/public/categories/{category_id}/attributes عمومی
دریافت valueهای مجاز metafield GET /taxonomy/public/attributes/{attribute_id} عمومی
به‌روزرسانی variant با SKU PUT /api/v1/products/update_variant/sku/{sku} API key
دریافت سفارش‌ها GET /api/v1/orders API key
به‌روزرسانی سفارش PUT /api/v1/orders/{order_id} API key
ایجاد سفارش POST /api/v1/orders/create_order Access-Key یا API key
تغییر قیمت variant PUT /api/v1/accounting/update-price/{variant_id} API key
تغییر موجودی variant PUT /api/v1/accounting/update-stock/{variant_id} API key
تغییر گروهی قیمت PUT /api/v1/accounting/bulk-update-price API key
تغییر گروهی موجودی PUT /api/v1/accounting/bulk-update-stock API key

محصولات

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

GET /api/v1/products

این endpoint عمومی است. بدون کلید API، محصولات غیرفعال برنمی‌گردند، مقدار description در product_attributes خالی برمی‌گردد و پاسخ ممکن است چند دقیقه کش شده باشد. با کلید API محصولات غیرفعال هم برمی‌گردند و پاسخ از کش خوانده نمی‌شود.

صفحه‌بندی با page_number (پیش‌فرض 1) و page_size (پیش‌فرض 20، حداکثر 100) انجام می‌شود؛ page_size بزرگ‌تر بی‌صدا به 100 کاهش می‌یابد. تعداد کل در result.total_count است.

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

GET /api/v1/products/{product_id}

این endpoint عمومی است. پیش از به‌روزرسانی کامل محصول، نسخهٔ فعلی را دریافت کنید تا شناسهٔ variantها، تصویرهای متصل و ترتیب آن‌ها را حفظ کنید. نام فیلدهای پاسخ با بدنهٔ PUT فرق دارد: product_attributes ← attributes، product_variants[].product_attributes ← product_variants[].attributes، product_categories[].id ← product_category_ids، images[].id و images[].order ← image_ids و image_orders، tags[].title ← tags.

دریافت فهرست محصولات برای سرویس‌های همکار (Third-party)

GET /api/v1/thirdparties/products

این endpoint فهرستی فشرده از کاتالوگ فروشگاه را برای سرویس‌های همکار (مقایسه قیمت، فید محصول، بازاریابی و ...) برمی‌گرداند. فقط محصولات فعال و حذف‌نشده و variantهای حذف‌نشدهٔ آن‌ها (از جمله variantهای غیرفعال) در پاسخ می‌آیند. فروشگاه از روی دامنهٔ درخواست تشخیص داده می‌شود؛ بنابراین درخواست را به دامنهٔ همان فروشگاه بفرستید.

احراز هویت

این endpoint با کلید API فروشگاه کار نمی‌کند. هر درخواست باید هدر thirdparty-source-key را داشته باشد. این کلید را تیم سازیتو به هر سرویس همکار می‌دهد. درخواست بدون این هدر یا با کلید نامعتبر با کد 400 و پیام «کلید منبع (thirdparty-source-key) ارسال نشده یا معتبر نیست.» رد می‌شود.

curl "https://example-shop.ir/api/v1/thirdparties/products?page_number=1&page_size=200" \
  --header "Accept: application/json" \
  --header "thirdparty-source-key: YOUR_SOURCE_KEY"

پارامترها

پارامتر پیش‌فرض توضیح
page_number 1 شمارهٔ صفحه، از ۱ شروع می‌شود.
page_size 20 تعداد قلم‌ها در هر صفحه؛ حداکثر 200.
variant_mode all all: هر variant یک قلم. cheapest: هر محصول یک قلم با ارزان‌ترین variant. هر مقدار دیگری با خطای 400 رد می‌شود.
filters[] — آرایهٔ JSON از فیلترها؛ در ادامه توضیح داده شده است.

در حالت all قلم‌ها به ترتیب صعودی شناسهٔ variant و در حالت cheapest به ترتیب صعودی شناسهٔ محصول مرتب می‌شوند.

حالت ارزان‌ترین variant

با variant_mode=cheapest هر محصول فقط یک بار در پاسخ می‌آید. variant انتخاب‌شده به این ترتیب تعیین می‌شود:

  1. variantهای موجود بر variantهای ناموجود مقدم‌اند؛
  2. کمترین قیمت فروش (قیمت پس از تخفیف)؛
  3. در صورت برابری قیمت، شناسهٔ کوچک‌تر.

فیلترها

فیلترها به صورت آرایهٔ JSON در پارامتر filters[] ارسال می‌شوند و هر فیلتر ساختار {"name": "...", "value": "..."} دارد:

نام مقدار عملکرد
query متن جستجو در نام محصول.
ids شناسه‌ها با کاما یا آرایه فقط محصولات با این شناسه‌ها.
product_categories شناسه‌ها با کاما یا آرایه محصولاتی که مستقیماً در این دسته‌بندی‌ها هستند (بدون زیردسته‌ها).
product_type simple، digital، service یا ترکیب آن‌ها با کاما محصولات از نوع‌های خواسته‌شده.
in_stock هر مقدار (مثلاً true) فقط variantهای موجود.
out_of_stock هر مقدار (مثلاً true) فقط variantهایی که موجودی‌شان صفر است.

چند فیلتر با «و» (AND) ترکیب می‌شوند. چند مقدار درون یک فیلتر با «یا» (OR) ترکیب می‌شوند. فیلترهای ناشناخته نادیده گرفته می‌شوند. مقدار filters[] باید URL-encode شود:

curl --get "https://example-shop.ir/api/v1/thirdparties/products" \
  --data-urlencode "variant_mode=cheapest" \
  --data-urlencode "page_size=200" \
  --data-urlencode 'filters[]=[{"name":"in_stock","value":true},{"name":"product_categories","value":"12,15"}]' \
  --header "thirdparty-source-key: YOUR_SOURCE_KEY"

پاسخ

پاسخ بدون پوشش result / status برگردانده می‌شود. total_products و total_pages رشته هستند. نمونهٔ پاسخ در حالت cheapest:

{
  "total_products": "42",
  "total_pages": "1",
  "products": [
    {
      "id": 131917,
      "product_id": 5120,
      "sku": "in7817hbd",
      "title": "Example product - Black XL",
      "url": "https://example-shop.ir/product/example-product",
      "price": 10798000,
      "promotion_price": 9000000,
      "availability": true,
      "category": "Entertainment",
      "images": ["https://cdn.example.com/.../product.webp"],
      "description": "<p>Product description</p>",
      "attributes": { "color": "black", "size": "xl" }
    }
  ]
}
فیلد توضیح
id شناسهٔ variant.
product_id فقط در حالت cheapest: شناسهٔ محصول.
sku کد SKU.
title عنوان variant؛ اگر عنوان نداشته باشد، نام محصول.
url آدرس کامل صفحهٔ محصول.
price قیمت اصلی (پیش از تخفیف).
promotion_price قیمت پس از تخفیف؛ اگر تخفیف نباشد null است.
availability true اگر variant موجود باشد.
category نام اولین دسته‌بندی محصول، یا رشتهٔ خالی.
images آدرس تصاویر محصول.
description توضیحات محصول (HTML)، یا رشتهٔ خالی.
attributes ویژگی‌های variant به صورت «نام ← مقدار».

total_products حداکثر ۵ دقیقه کش می‌شود. برای پیمایش کامل، صفحه‌ها را به ترتیب بخوانید تا جایی که products خالی برگردد.

خطاها

کد علت
400 thirdparty-source-key ارسال نشده یا معتبر نیست، مقدار variant_mode نامعتبر است، یا خطای دیگری در درخواست رخ داده است.
503 فروشگاه موقتاً پرترافیک است یا پرس‌وجو بیش از حد طول کشیده است؛ پس از چند ثانیه (مطابق هدر Retry-After) دوباره تلاش کنید.

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

POST /api/v1/images
Content-Type: multipart/form-data

فرایند تصویر دو مرحله دارد: ابتدا فایل را آپلود کنید و id تصویر را بگیرید؛ سپس همان id را در image_ids و image_orders بدنهٔ محصول بفرستید.

هنگام استفاده از curl با -F، هدر Content-Type را دستی تنظیم نکنید؛ ابزار، boundary صحیح را اضافه می‌کند.

فیلد نوع الزامی توضیح
images[][file] file بله دادهٔ باینری تصویر
images[][name] string خیر نام فایل؛ در صورت عدم ارسال، نام فایل آپلودشده. پسوند آن باید با پسوند فایل یکی باشد
images[][alt] string خیر متن جایگزین تصویر؛ رشتهٔ خالی مجاز است

نمونهٔ درخواست:

curl --request POST "https://{shop-domain}/api/v1/images" \
  -H "X-API-Key: ${SAZITO_API_KEY}" \
  -H "Accept: application/json" \
  -F "images[][file]=@./product.jpg" \
  -F "images[][name]=product.jpg" \
  -F "images[][alt]=نمای محصول"

هر درخواست فقط یک تصویر آپلود می‌کند و فقط اولین images[][file] خوانده می‌شود؛ برای چند تصویر، چند درخواست جداگانه بفرستید. فرمت‌های مجاز jpg، jpeg، png، gif و webp است؛ حداکثر حجم ۱۰ مگابایت و حداکثر طول و عرض ۱۵۰۰۰ پیکسل. در صورت خطا کد 400 برمی‌گردد.

نمونهٔ پاسخ:

{
  "error_code": 0,
  "status": 200,
  "result": {
    "images": [
      {
        "id": 1901,
        "name": "5f4dcc3b5aa765d61d8327deb882cf99.jpg",
        "url": "/uploads/image/rootimage/1901/5f4dcc3b5aa765d61d8327deb882cf99.jpg",
        "thumb": "/uploads/image/rootimage/1901/thumb_5f4dcc3b5aa765d61d8327deb882cf99.jpg",
        "width": 1200,
        "height": 1600
      }
    ]
  }
}

مقدار لازم برای اتصال تصویر، result.images[].id است؛ URL تصویر را به‌جای ID در بدنهٔ محصول نفرستید.

ایجاد محصول

POST /api/v1/products

آرایهٔ attributes در ایجاد محصول الزامی است؛ برای محصول بدون attribute، [] بفرستید. هر محصول می‌تواند چند variant داشته باشد. هر variant باید برای همهٔ attributeهای با attribute_type: "differentiator" مقدار داشته باشد؛ در غیر این صورت کل درخواست با کد 400 رد می‌شود.

بخش فیلد نوع الزامی توضیح
product name string بله نام محصول
product product_type string بله یکی از simple، digital یا service
product enabled boolean خیر فعال‌بودن محصول؛ اگر ارسال نشود، محصول غیرفعال ساخته می‌شود
product url string خیر لینک اختصاصی محصول؛ فقط همراه با "static_url": true اعمال می‌شود. بدون آن، لینک از نام محصول ساخته می‌شود و با تغییر نام عوض می‌شود
attributes type string بله نوع attribute؛ مانند string
attributes name string بله نام attribute؛ مانند «سایز»
attributes attribute_type string بله برای تمایز variantها از differentiator استفاده کنید
attributes value any خیر مقدار attribute. توضیحات محصول (HTML) به شکل attribute با "name": "description" و "type": "text" و فیلدهای سئو (مانند metaTitle و metaDescription) نیز در همین آرایه ذخیره می‌شوند
product_category_ids — string خیر شناسهٔ دسته‌بندی‌ها، جداشده با کاما
image_ids — array of integer خیر ID تصویرهای آپلودشده؛ در سطح ریشهٔ بدنه
image_orders — array of object خیر ترتیب نمایش، مانند [{"id":1901,"order":1}]؛ در سطح ریشهٔ بدنه
tags — array of string خیر عنوان برچسب‌ها؛ آرایهٔ خالی همهٔ برچسب‌ها را حذف می‌کند
taxonomy_actions — array خیر actionهای taxonomy در سطح ریشهٔ بدنه؛ پیش از استفاده، دسترسی آن را تأیید کنید
product_variants price number خیر قیمت فروش variant (پس از تخفیف)
product_variants sku string خیر کد کالا؛ API آن را خودکار نمی‌سازد. برای استفاده از endpoint به‌روزرسانی با SKU، مقدار یکتا بفرستید
product_variants enabled boolean خیر در این endpoint نادیده گرفته می‌شود؛ هر variant ارسال‌شده فعال ذخیره می‌شود
product_variants has_max_order boolean خیر فعال‌بودن محدودیت حداکثر سفارش
product_variants max_no_of_order number خیر حداکثر تعداد در هر سفارش (همراه با has_max_order: true)
product_variants min_order_count number خیر حداقل تعداد سفارش
product_variants is_stock_managed boolean خیر فعال‌بودن مدیریت موجودی
product_variants stock_number number خیر تعداد موجودی؛ فقط وقتی is_stock_managed برابر true باشد اعمال می‌شود
product_variants relative boolean خیر اگر true باشد، stock_number به موجودی فعلی اضافه (یا با عدد منفی از آن کم) می‌شود؛ ربطی به قیمت ندارد
product_variants weight number خیر وزن محصول
product_variants raw_price number یا null خیر قیمت پیش از تخفیف (خط‌خورده)؛ null تخفیف را حذف می‌کند. در به‌روزرسانی، اگر price را بدون raw_price بفرستید، تخفیف variant حذف می‌شود
product_variants sort_index number خیر ترتیب نمایش
product_variants attributes array بله مقدار attributeهای این variant

نمونهٔ درخواست:

{
  "product": {
    "enabled": true,
    "name": "تیشرت تستی",
    "url": "",
    "product_type": "simple",
    "form_id": -1
  },
  "attributes": [
    {
      "type": "string",
      "name": "سایز",
      "attribute_type": "differentiator"
    }
  ],
  "tags": [],
  "product_category_ids": "171,168,167",
  "product_variants": [
    {
      "price": 200000,
      "sku": "TSHIRT-SMALL",
      "min_order_count": 1,
      "is_stock_managed": true,
      "stock_number": 10,
      "weight": 200,
      "attributes": [{ "name": "سایز", "value": "S" }],
      "sort_index": 0
    },
    {
      "price": 220000,
      "sku": "TSHIRT-LARGE",
      "enabled": true,
      "min_order_count": 1,
      "is_stock_managed": true,
      "stock_number": 5,
      "weight": 220,
      "attributes": [{ "name": "سایز", "value": "L" }],
      "sort_index": 1
    }
  ],
  "image_ids": [1901, 1902],
  "image_orders": [
    { "id": 1901, "order": 2 },
    { "id": 1902, "order": 1 }
  ]
}

اتصال و ترتیب تصویرها

image_ids تصویرها را به محصول متصل می‌کند و image_orders ترتیب نمایش را تعیین می‌کند. هر id در image_orders باید در image_ids نیز وجود داشته باشد و برای هر تصویر فقط یک ترتیب ارسال شود.

برای هر تصویر یک order یکتا بفرستید. تصویرها به ترتیب نزولی order نمایش داده می‌شوند: تصویری که بزرگ‌ترین order را دارد اول گالری و تصویر شاخص محصول است؛ در نمونهٔ بالا ۱۹۰۱ اول نمایش داده می‌شود. مقدار order در پاسخ آپلود را مبنای ترتیب گالری محصول قرار ندهید؛ ترتیب گالری فقط با image_orders تعیین می‌شود.

به‌روزرسانی جزئی محصول (partial)

PUT /api/v1/products/partial/{product_id}
X-API-Key: your-api-key
Content-Type: application/json

با این endpoint فقط بخشی از محصول را تغییر می‌دهید و لازم نیست کل محصول را دوباره بفرستید. هر کلیدی که در بدنه نباشد، دست‌نخورده باقی می‌ماند.

پرکاربردترین موارد:

تفاوت با PUT /api/v1/products/{product_id}: در به‌روزرسانی کامل باید همهٔ variantها و تصویرها را بفرستید، وگرنه ممکن است حذف شوند. در partial فقط همان چیزی را می‌فرستید که می‌خواهید تغییر کند.

ساختار بدنه

همهٔ کلیدهای سطح ریشه اختیاری‌اند:

کلید رفتار
product فیلدهای اصلی محصول. فقط فیلدهای ارسال‌شده تغییر می‌کنند.
attributes.upserted افزودن یا جایگزینی attribute محصول بر اساس name
attributes.deleted حذف attribute محصول بر اساس نام
product_variants.upserted variant با id، ویرایش می‌شود و variant بدون id، ساخته می‌شود
product_variants.deleted حذف variant بر اساس id
image_ids / image_orders جایگزینی کامل گالری تصویر
tags جایگزینی کامل برچسب‌ها
product_category_ids جایگزینی کامل دسته‌بندی‌ها

اگر بدنه یا یکی از variantها نامعتبر باشد، درخواست رد می‌شود و تغییری ذخیره نمی‌شود. اگر پاسخ خطا گرفتید، پیش از تکرار درخواست، محصول را دوباره بخوانید.

فیلدهای product
فیلد نوع توضیح
name string نام محصول
enabled boolean فعال یا غیرفعال کردن محصول
product_type string یکی از simple، digital یا service
static_url boolean استفاده از لینک اختصاصی
url string لینک اختصاصی؛ فقط وقتی static_url برابر true باشد اعمال می‌شود
form_id number شناسهٔ فرم پویا
فیلدهای هر آیتم در attributes.upserted
فیلد نوع توضیح
name string نام attribute؛ اگر attributeای با همین نام وجود داشته باشد، کامل جایگزین می‌شود
type string نوع فیلد؛ مانند string
attribute_type string differentiator برای attributeی که variantها را از هم جدا می‌کند (مثل سایز و رنگ)؛ هر مقدار دیگر یعنی attribute معمولی
value any مقدار attribute معمولی، مانند "پنبه"

چون attribute هم‌نام کامل جایگزین می‌شود، هنگام ویرایش همهٔ فیلدهای آن را بفرستید، نه فقط فیلدی را که تغییر کرده است.

فیلدهای هر آیتم در product_variants.upserted
فیلد نوع توضیح
id number شناسهٔ variant موجود؛ برای ساخت variant جدید نفرستید
sku string کد کالا
price number قیمت
raw_price number یا null قیمت قبل از تخفیف؛ با null حذف می‌شود
stock_number number موجودی
relative boolean اگر true باشد، stock_number به موجودی فعلی اضافه یا از آن کم می‌شود (مثلاً -2)
is_stock_managed boolean فعال‌بودن مدیریت موجودی
enabled boolean فعال‌بودن variant
attributes array مقدار attributeهای تمایزدهنده، مانند [{"name":"سایز","value":"L"}]
weight number وزن به گرم
min_order_count number حداقل تعداد سفارش
has_max_order / max_no_of_order boolean / number محدودیت حداکثر سفارش
sort_index number ترتیب نمایش
image_id number تصویر اختصاصی variant

عنوان variant از نام محصول به‌علاوهٔ مقدار attributeهای آن ساخته می‌شود. اگر attributes یک variant را نفرستید (مثلاً فقط sku یا قیمت را تغییر دهید)، attributeها و عنوان فعلی آن حفظ می‌شوند. اگر attributes را بفرستید، کل attributeهای آن variant با فهرست ارسالی جایگزین می‌شود.

اگر محصول attribute از نوع differentiator داشته باشد، هر variant محصول باید برای آن مقدار داشته باشد. در غیر این صورت کل درخواست با خطای error_message_differentiator_attribute_must_have_value رد می‌شود.

نمونه‌ها

برای گرفتن id variantها و مقدار فعلی attributeها، ابتدا محصول را با GET /api/v1/products/{product_id} بخوانید.

۱. تغییر SKU یک variant
curl --request PUT "https://{shop-domain}/api/v1/products/partial/{product_id}" \
  -H "X-API-Key: ${SAZITO_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "product_variants": {
      "upserted": [
        {
          "id": 5501,
          "sku": "TSHIRT-L-BLUE"
        }
      ]
    }
  }'

برای تغییر هم‌زمان قیمت و موجودی، در همین آیتم price و stock_number را هم بفرستید. برای چند variant، چند آیتم در upserted قرار دهید.

۲. کم یا زیاد کردن موجودی (نسبی)
{
  "product_variants": {
    "upserted": [
      {
        "id": 5501,
        "relative": true,
        "stock_number": -2
      }
    ]
  }
}
۳. افزودن یا تغییر attribute معمولی محصول
{
  "attributes": {
    "upserted": [
      { "name": "جنس", "type": "string", "attribute_type": "", "value": "پنبه" }
    ]
  }
}
۴. حذف attribute محصول
{
  "attributes": {
    "deleted": ["جنس"]
  }
}

برای حذف یک attribute از نوع differentiator (مثلاً «سایز»)، مقدار آن را هم از attributes همهٔ variantها حذف کنید. در غیر این صورت، آن مقدار هنوز در عنوان variantها باقی می‌ماند.

۵. افزودن variant جدید

variant بدون id ساخته می‌شود. برای همهٔ attributeهای differentiator محصول مقدار بدهید:

{
  "product_variants": {
    "upserted": [
      {
        "sku": "TSHIRT-XL",
        "price": 240000,
        "is_stock_managed": true,
        "stock_number": 3,
        "weight": 230,
        "enabled": true,
        "attributes": [{ "name": "سایز", "value": "XL" }]
      }
    ]
  }
}

برای variant جدید با یک مقدار تمایزدهندهٔ جدید (مثلاً رنگی که قبلاً وجود نداشته)، در همان درخواست attribute محصول را هم در attributes.upserted بفرستید.

۶. حذف variant
{
  "product_variants": {
    "deleted": [5502, 5503]
  }
}

حذف variant برگشت‌پذیر نیست. اگر یکی از شناسه‌ها متعلق به این محصول نباشد یا وجود نداشته باشد، کل درخواست با خطای «تنوع محصول یافت نشد یا متعلق به این محصول نمی‌باشد» رد می‌شود و هیچ variantی حذف نمی‌شود. تکرار درخواست حذف برای variantی که قبلاً حذف شده، خطا نمی‌دهد.

۷. تغییر گالری تصویر

image_ids گالری را کامل جایگزین می‌کند؛ تصویری که در فهرست نباشد از محصول جدا می‌شود. هر id در image_orders باید در image_ids هم باشد. تصویرها به ترتیب نزولی order نمایش داده می‌شوند: تصویری که بزرگ‌ترین order را دارد اول گالری و تصویر شاخص محصول است. در نمونهٔ زیر ترتیب نمایش ۱۹۰۱، ۱۹۰۲، ۱۹۰۳ است.

{
  "image_ids": [1901, 1902, 1903],
  "image_orders": [
    { "id": 1901, "order": 3 },
    { "id": 1902, "order": 2 },
    { "id": 1903, "order": 1 }
  ]
}

برای افزودن یک تصویر، تصویرهای قبلی را هم در هر دو آرایه بفرستید. برای آپلود تصویر جدید، بخش «آپلود تصویر محصول» را ببینید.

۸. فعال یا غیرفعال کردن محصول
{
  "product": { "enabled": false }
}

پاسخ

در صورت موفقیت، 200 و محصول کامل به‌روزشده، همان ساختار GET /api/v1/products/{product_id}، برمی‌گردد:

{
  "status": 200,
  "result": {
    "product": {
      "id": 1234,
      "name": "تیشرت تستی",
      "product_variants": [
        { "id": 5501, "sku": "TSHIRT-L-BLUE", "title": "تیشرت تستی L", "price": 220000, "stock_number": 5, "enabled": true }
      ]
    }
  }
}

خطاها

خطاها با کد 400 و به شکل {"errors":{"message":"..."}} برمی‌گردند. نبودن یا اشتباه بودن کلید API خطای 403 می‌دهد.

پیام خطا علت
محصول درخواستی یافت نشد product_id اشتباه است
تنوع محصول یافت نشد یا متعلق به این محصول نمی‌باشد شناسه‌ای در product_variants.upserted یا product_variants.deleted وجود ندارد یا متعلق به این محصول نیست
ویژگی‌های متمایز کننده باید مقدار داشته باشند یکی از variantها برای attribute تمایزدهنده مقدار ندارد
پارامتر نامعتبر ساختار بدنه اشتباه است؛ مثلاً upserted آرایه نیست یا product شیء نیست

به‌روزرسانی کامل محصول

PUT /api/v1/products/{product_id}

این endpoint برای به‌روزرسانی کامل محصول است. پیش از PUT محصول فعلی را با GET /api/v1/products/{product_id} دریافت کنید. هنگام ارسال product_variants یا image_ids و image_orders، همهٔ variantهای فعلی و همهٔ تصویرهای متصل و ترتیب آن‌ها را حفظ کنید. کلیدهای سطح ریشه‌ای که ارسال نشوند دست‌نخورده می‌مانند. اگر product_variants ارسال شود، variantهایی که در فهرست نیستند حذف می‌شوند و آیتم بدون id variant جدید می‌سازد؛ اگر image_ids ارسال شود، تصویرهایی که در آن نیستند از محصول جدا می‌شوند. برای variant موجود، id آن را نیز ارسال کنید؛ id باید متعلق به همین محصول باشد، وگرنه کل درخواست رد می‌شود. اگر attributes یک variant را بفرستید، کل attributeهای آن variant با فهرست ارسالی جایگزین می‌شود و اگر نفرستید، attributeهای فعلی آن حفظ می‌شوند. عنوان variant از نام محصول به‌علاوهٔ مقدار attributeهای آن ساخته می‌شود.

نمونهٔ تغییر مقدار attribute برای variantهای موجود:

{
  "product": { "name": "تست رنگ" },
  "product_variants": [
    {
      "id": 23827,
      "attributes": [
        {
          "name": "رنگ",
          "value": { "extra": "#60ec62", "fieldType": "color", "value": "قرمز" }
        }
      ]
    },
    {
      "id": 23834,
      "attributes": [
        {
          "name": "رنگ",
          "value": { "extra": "#eeec16", "fieldType": "color", "value": "آبی" }
        }
      ]
    }
  ]
}

اگر attribute موردنظر از قبل وجود ندارد، آن را به attributes اضافه کنید. attributes در سطح ریشه همهٔ attributeهای فعلی محصول، از جمله توضیحات (description) و فیلدهای سئو، را جایگزین می‌کند؛ بنابراین product_attributes فعلی را از GET بخوانید، attribute جدید را به آن اضافه کنید و کل آرایه را بفرستید (در نمونهٔ زیر فقط attribute جدید نشان داده شده است). برای افزودن یک attribute بدون ارسال بقیه، از به‌روزرسانی جزئی (attributes.upserted) استفاده کنید:

{
  "product": { "name": "تست رنگ" },
  "attributes": [
    {
      "type": "string",
      "name": "رنگ",
      "value": "",
      "attribute_type": "differentiator"
    }
  ],
  "product_variants": [
    {
      "id": 23827,
      "attributes": [
        {
          "name": "رنگ",
          "value": { "extra": "#60ec62", "fieldType": "color", "value": "قرمز" }
        }
      ]
    }
  ]
}

taxonomy محصول: دسته‌بندی، metafield و مقدارها

خواندن taxonomy با endpointهای عمومی

مسیرهای خواندن taxonomy نسبت به دامنهٔ همان فروشگاه هستند، اما برخلاف API مدیریت، زیر /api/v1 قرار ندارند:

https://{shop-domain}/taxonomy/public

این endpointها عمومی‌اند و به Authorization، X-API-Key یا cookie نشست نیاز ندارند.

دریافت taxonomy فعلی محصول
GET /taxonomy/public/products/{store_id}/{product_id}
پارامتر توضیح
store_id شناسهٔ عددی داخلی فروشگاه؛ آن را از پشتیبانی سازیتو دریافت کنید
product_id شناسهٔ عددی محصول

اگر برای محصول هنوز taxonomy ثبت نشده باشد، پاسخ 404 است. در غیر این صورت پاسخ، دسته‌بندی taxonomy و metafieldها و valueهای انتخاب‌شدهٔ محصول را برمی‌گرداند:

{
  "id": "{product_id}",
  "store_id": "{store_id}",
  "is_active": true,
  "category": {
    "id": "cat_<category-id>",
    "fa_name": "نام دسته‌بندی"
  },
  "metafields": [
    {
      "attribute": {
        "id": "attr_<metafield-id>",
        "fa_name": "نام ویژگی"
      },
      "values": [
        {
          "id": "val_<value-id>",
          "fa_name": "نام مقدار"
        }
      ]
    }
  ]
}
دریافت زیردسته‌های یک taxonomy category
GET /taxonomy/public/categories/{category_id}/children
{
  "children": [
    {
      "id": "cat_<child-category-id>",
      "fa_name": "نام زیردسته",
      "num_children": 0
    }
  ],
  "total_count": 1
}

برای دریافت دسته‌های سطح اول، category_id را 0 بگذارید. اگر num_children بزرگ‌تر از صفر است، برای پیمایش سطح بعدی همین endpoint را با id آن زیردسته فراخوانی کنید.

دریافت metafieldهای یک taxonomy category
GET /taxonomy/public/categories/{category_id}/attributes
{
  "category_id": "cat_<category-id>",
  "direct_attributes": [],
  "inherited_attributes": [
    {
      "id": "attr_<metafield-id>",
      "en_name": "Attribute name",
      "fa_name": "نام ویژگی",
      "is_active": true
    }
  ],
  "all_attributes": [
    {
      "id": "attr_<metafield-id>",
      "en_name": "Attribute name",
      "fa_name": "نام ویژگی",
      "is_active": true
    }
  ]
}

برای نمایش همهٔ metafieldهای قابل استفاده، آرایهٔ all_attributes را بخوانید. direct_attributes ویژگی‌های مستقیم دسته و inherited_attributes ویژگی‌های به‌ارث‌رسیده از دسته‌های والد را نشان می‌دهد.

دریافت valueهای مجاز یک metafield
GET /taxonomy/public/attributes/{attribute_id}
{
  "id": "attr_<metafield-id>",
  "en_name": "Attribute name",
  "fa_name": "نام ویژگی",
  "is_active": true,
  "values": [
    {
      "id": "val_<value-id>",
      "en_name": "Value name",
      "fa_name": "نام مقدار",
      "is_active": true
    }
  ]
}

شناسهٔ valueها (val_...) را از آرایهٔ values بخوانید. برای جستجو با متن از GET /taxonomy/public/categories/search?q=... و GET /taxonomy/public/values/search?q=... استفاده کنید.

نوشتن taxonomy هنگام ایجاد یا به‌روزرسانی محصول

برای تنظیم taxonomy، آرایهٔ taxonomy_actions را در سطح ریشهٔ بدنهٔ ایجاد یا به‌روزرسانی کامل محصول ارسال کنید. این فیلد را داخل product یا attributes قرار ندهید:

POST /api/v1/products
PUT /api/v1/products/{product_id}

taxonomy با دسته‌بندی عادی محصول متفاوت است. taxonomy_actions[].category_id جایگزین product_category_ids نمی‌شود. خواندن taxonomy عمومی است، اما ایجاد یا تغییر آن به اعتبارنامه‌ای با دسترسی نوشتن محصول نیاز دارد. اگر قابلیت taxonomy برای فروشگاه فعال نباشد یا actionها رد شوند، محصول با موفقیت ذخیره می‌شود (کد 200) اما result.success_taxonomy برابر false است؛ همیشه این فیلد را بررسی کنید.

مفهوم فیلد شکل شناسه توضیح
taxonomy category taxonomy_actions[].category_id معمولاً cat_... دسته‌بندی taxonomy محصول
taxonomy metafield taxonomy_actions[].attribute_id attr_... ویژگی taxonomy، مانند جنس یا برند
مقدار metafield taxonomy_actions[].value_ids val_... مقدارهای مجاز همان metafield

شناسه‌های taxonomy (cat_...، attr_... و val_...) سراسری‌اند و در همهٔ فروشگاه‌ها یکسان‌اند. val_... باید متعلق به attr_... ارسال‌شده در همان action باشد (آرایهٔ values در GET /taxonomy/public/attributes/{attribute_id})؛ در غیر این صورت کل درخواست taxonomy رد می‌شود.

actionهای تأییدشده

action فیلدهای لازم کاربرد
assign_category category_id اتصال taxonomy category به محصول
add_metafield attribute_id و value_ids (یا یک add_values بعدی برای همان attribute_id در همان درخواست) افزودن metafield taxonomy به محصول
add_values attribute_id و value_ids افزودن مقدار به metafield
remove_values attribute_id و value_ids حذف مقدار از metafield
remove_metafield attribute_id حذف metafield از محصول
unassign_category — حذف taxonomy category؛ محصول به دستهٔ ویژهٔ uncategorized منتقل می‌شود

افزودن دسته‌بندی، metafield و مقدار

هنگامی که برای یک metafield جدید مقدار می‌فرستید، ابتدا add_metafield و سپس add_values را برای همان attribute_id قرار دهید:

{
  "taxonomy_actions": [
    {
      "action": "assign_category",
      "category_id": "cat_<taxonomy-category-id>"
    },
    {
      "action": "add_metafield",
      "attribute_id": "attr_<metafield-id>"
    },
    {
      "action": "add_values",
      "attribute_id": "attr_<metafield-id>",
      "value_ids": [
        "val_<value-id>"
      ]
    }
  ]
}

حذف مقدار یا metafield

{
  "taxonomy_actions": [
    {
      "action": "remove_values",
      "attribute_id": "attr_<metafield-id>",
      "value_ids": [
        "val_<value-id>"
      ]
    },
    {
      "action": "remove_metafield",
      "attribute_id": "attr_<metafield-id-to-remove>"
    }
  ]
}

نکات مهم taxonomy

هنگام PUT، قطعهٔ taxonomy_actions به‌تنهایی لزوماً بدنهٔ کامل و ایمن به‌روزرسانی نیست. دادهٔ فعلی محصول را حفظ کنید و پس از درخواست، نتیجه را در پاسخ API و پنل ادمین بررسی کنید.

تغییر قیمت و موجودی variant

endpointهای این بخش و به‌روزرسانی با SKU، variant غیرفعال را فعال می‌کنند.

تغییر قیمت

PUT /api/v1/accounting/update-price/{variant_id}

قیمت بدون تخفیف (price قیمت فروش است و تخفیف قبلی حذف می‌شود):

{ "price": 20 }

قیمت همراه با تخفیف (price قیمت پیش از تخفیف و discount_price قیمت فروش است؛ اگر discount_price ارسال نشود، قیمت فروش صفر می‌شود):

{
  "price": 20,
  "has_raw_price": true,
  "discount_price": 10
}

تغییر موجودی

PUT /api/v1/accounting/update-stock/{variant_id}

تعیین مقدار مطلق موجودی:

{
  "is_stock_manager": true,
  "stock_number": 20
}

برای موجودی نامحدود، is_stock_manager را false قرار دهید. برای افزایش یا کاهش نسبی موجودی از is_relative استفاده کنید؛ عدد مثبت موجودی را افزایش و عدد منفی آن را کاهش می‌دهد:

{
  "is_stock_manager": true,
  "stock_number": -2,
  "is_relative": true
}

اگر is_relative ارسال نشود یا false باشد، stock_number به‌عنوان مقدار مطلق اعمال می‌شود. is_stock_manager را همیشه صریح بفرستید؛ اگر ارسال نشود false در نظر گرفته می‌شود و موجودی نامحدود (و stock_number صفر) می‌شود.

تغییر گروهی قیمت یا موجودی

PUT /api/v1/accounting/bulk-update-price
{
  "variants": [
    { "id": 5800, "price": 10 },
    { "id": 5820, "price": 10 }
  ]
}
PUT /api/v1/accounting/bulk-update-stock
{
  "variants": [
    { "id": 5800, "is_stock_manager": true, "stock_number": 10 },
    { "id": 5820, "is_stock_manager": true, "stock_number": 10 }
  ]
}

در تغییر گروهی قیمت، has_raw_price و discount_price و در تغییر گروهی موجودی، is_relative نیز مانند endpointهای تکی پشتیبانی می‌شوند. پاسخ با کد 200 و به شکل {"success_count": 2, "failed_count": 0, "failed_variant_ids": null} است؛ شناسه‌های ناموجود در failed_variant_ids می‌آیند. تعداد variantهای هر درخواست و تعداد درخواست‌های گروهی در دقیقه محدود است؛ در صورت عبور از حد، کد 413 یا 429 (همراه با هدر Retry-After) برمی‌گردد.

به‌روزرسانی variant با SKU

PUT /api/v1/products/update_variant/sku/{sku}

مقدار SKU را URL-encode کنید و در خود URL قرار دهید. فقط فیلدهای stock_number، is_stock_managed، price، has_raw_price و raw_price خوانده می‌شوند. price قیمت فروش و raw_price قیمت پیش از تخفیف است؛ اگر price را بدون raw_price بفرستید، تخفیف variant حذف می‌شود:

{
  "is_stock_managed": true,
  "stock_number": 22,
  "price": 1200,
  "has_raw_price": true,
  "raw_price": 2000
}

اگر SKU پیدا نشود، کد 400 برمی‌گردد. اگر چند variant یک SKU داشته باشند، فقط یکی از آن‌ها تغییر می‌کند.

سفارش‌ها

دریافت فهرست سفارش‌ها

GET /api/v1/orders

این endpoint به کلید API نیاز دارد و هر آیتم آن ساختار کامل «جزئیات سفارش» (بخش بعد) را دارد.

پارامترهای query:

نمونه:

GET /api/v1/orders?page_size=50&filters[]=[{"name":"status","value":"shipping,shipped"}]

ساختار پاسخ:

{
  "result": {
    "orders": [],
    "page_number": 1,
    "page_size": 20,
    "total_count": 0,
    "total_count_raw": 0,
    "seen_count": 0,
    "not_seen_count": 0
  },
  "error": "",
  "error_code": 0,
  "status": 200
}

total_count تعداد سفارش‌های منطبق با فیلترهاست. اگر کلید API نامعتبر باشد، این endpoint خطا نمی‌دهد و فهرست خالی با کد 200 برمی‌گرداند.

دریافت فهرست جدید سفارش‌ها

GET /api/v1/orders/list

این endpoint نیز با همان کلید API (X-API-Key) کار می‌کند و بدون احراز هویت خطای 401 می‌دهد. خروجی آن نسخهٔ سبک فهرست است و همان پارامترهای page_number، page_size و filters[] را می‌پذیرد؛ علاوه بر آن sort (یکی از created_at، order_status یا final_total؛ پیش‌فرض شناسهٔ سفارش) و sort_order (asc یا desc؛ پیش‌فرض desc) را هم پشتیبانی می‌کند. آیتم‌ها در result.orders و کنار همان فیلدهای صفحه‌بندیِ GET /api/v1/orders برمی‌گردند.

نمونهٔ یک آیتم پاسخ:

{
  "id": 6321,
  "created_at": "2026-08-26T11:33:45.618001Z",
  "receipt_id": 5338,
  "order_status": 1,
  "order_identifier": "11111111111111111111111111111111",
  "final_total": 2961000,
  "first_name": "نام مشتری",
  "last_name": "نام خانوادگی مشتری",
  "seen": true,
  "status": "shipping",
  "status_title": "در حال آماده سازی",
  "order_number": "OR0000006321",
  "metadata": {
    "takhfifan": {
      "token": "",
      "transaction_id": "",
      "revenue": "",
      "shipping": "",
      "tax": "",
      "discount": "",
      "new_customer": false,
      "affiliation": "",
      "coupon_code": "",
      "items": []
    },
    "tracking_data": {
      "list": [
        {
          "capturedAt": "2026-06-29T14:00:09+03:30",
          "follow_up_index": 0,
          "journey_identifier": "SimpleCashback",
          "journey_title": "بازگشت وجه خودکار",
          "referrer": "marketing.sazito.com",
          "sent_time": "2026-06-29T14:00:09+03:30"
        },
        {
          "utm_source": "restricted"
        },
        {
          "utm_source": "restricted"
        },
        {
          "capturedAt": "2026-08-23T20:42:12+03:30",
          "deliver_time": "2026-08-23T20:42:12+03:30",
          "follow_up_index": 0,
          "journey_identifier": "AbandonedCart",
          "journey_title": "سبد خرید رها شده",
          "last_touch_point_time": "2026-08-23T20:42:12+03:30",
          "referrer": "marketing.sazito.com",
          "sent_time": "2026-08-23T20:41:05+03:30"
        }
      ],
      "referrer": "marketing.sazito.com"
    }
  }
}

معنای order_status: ‏0=started، 1=shipping، 2=shipped، 3=complete، 4=cancelled، 5=failed. وضعیت failed («پرداخت نشده») فقط وقتی در این دو فهرست دیده می‌شود که نمایش سفارش‌های پرداخت‌نشده برای فروشگاه فعال باشد؛ این سفارش‌ها پرداخت نشده‌اند و نباید ارسال شوند.

دریافت جزئیات یک سفارش

GET /api/v1/orders/{order_id}?order_identifier={order_identifier}

پارامتر order_identifier الزامی است؛ بدون آن پاسخ 400 با پیام «پارامترهای ورودی معتبر نیست» و با مقدار نادرست پاسخ 400 با پیام «سفارش یافت نشد» برمی‌گردد. این endpoint با داشتن order_identifier بدون کلید API هم پاسخ می‌دهد؛ پس order_identifier سفارش‌ها را مانند رمز نگه دارید.

نمونهٔ پاسخ:

{
    "result": {
        "order": {
            "id": 49,
            "order_identifier": "22222222222222222222222222222222",
            "seen": true,
            "user": {
                "id": 28,
                "email": "user@example.com",
                "mobile_phone": "+98912xxxxxxx",
                "mobile_phone_verified_at": null,
                "first_name": "نام مشتری",
                "last_name": "نام خانوادگی مشتری",
                "birth_date": null,
                "shipping_addresses": null,
                "roles": null,
                "sold": null,
                "is_guest": false,
                "is_god": false,
                "sold_amount": null,
                "balance": null,
                "created_at": "2024-10-10T08:24:58.988087Z",
                "updated_at": "2026-08-25T11:37:38.435105Z"
            },
            "receipt": {
                "id": 32,
                "receipt_ref": "234234",
                "image_url": "/uploads/image/rootimage/0/receipt-example.png",
                "payment": {
                    "id": 54,
                    "payment_status": "approved",
                    "payment_status_fa": "تایید شده",
                    "payment_amount": 4000000,
                    "is_active": false,
                    "payment_identifier": "33333333333333333333333333333333",
                    "payment_type": {
                        "id": 4,
                        "title": "card to card payment",
                        "title_fa": "پرداخت کارت به کارت",
                        "description": null,
                        "reference_code": "cardtocardpayment",
                        "order": 0,
                        "is_default": false
                    },
                    "payment_sub_type": "advancedcardtocard",
                    "invoice_id": 77,
                    "invoice_identifier": "",
                    "created_at": "2025-01-07T06:37:19.4634Z",
                    "updated_at": "2026-08-25T11:37:38.438692Z"
                },
                "receipt_amount": 4000000,
                "created_at": "2025-01-07T06:37:27.027186Z",
                "updated_at": "2026-08-25T11:37:38.440625Z"
            },
            "invoice": {
                "id": 77,
                "invoice_identifier": "44444444444444444444444444444444",
                "net_total": 4500000,
                "final_total": 4000000,
                "discount_total": 500000,
                "shipping_total": 0,
                "credit_total": 0,
                "coupon_total": 0,
                "vat": 0,
                "vat_percent": 0,
                "user": {
                    "id": 28,
                    "email": "user@example.com",
                    "mobile_phone": "+98912xxxxxxx",
                    "mobile_phone_verified_at": null,
                    "first_name": "نام مشتری",
                    "last_name": "نام خانوادگی مشتری",
                    "birth_date": null,
                    "shipping_addresses": null,
                    "roles": null,
                    "sold": null,
                    "is_guest": false,
                    "is_god": false,
                    "sold_amount": null,
                    "balance": null,
                    "created_at": "2024-10-10T08:24:58.988087Z",
                    "updated_at": "2026-08-25T11:37:38.435105Z"
                },
                "shipping_address": {
                    "id": 144,
                    "email": "user@example.com",
                    "first_name": "نام مشتری",
                    "last_name": "نام خانوادگی مشتری",
                    "address": "",
                    "postal_code": "",
                    "phone_number": "",
                    "mobile_phone": "+98912xxxxxxx",
                    "shipping_address_identifier": "55555555555555555555555555555555",
                    "longitude": 51.389,
                    "latitude": 35.689,
                    "region": {
                    },
                    "city": {
                    },
                    "user": {
                    },
                    "user_id": 0,
                    "show_map": false,
                    "created_at": "2025-01-07T06:37:16.202323Z",
                    "updated_at": "2025-01-07T06:37:16.202323Z"
                },
                "shipping_method": "",
                "shipping_items": [
                    {
                        "id": 51,
                        "invoice_item_ids": [343],
                        "rate": { "id": 1, "name": "پست پیشتاز", "price": 0 },
                        "shipping_number": "SH0000000051",
                        "status": "cancelled",
                        "status_title": "لغو شده",
                        "shipping_tracking_detail": "",
                        "shipping_tracking_details": {},
                        "complete_custom_message": "",
                        "third_party_details": {}
                    }
                ],
                "discount_usages": [
                    {
                        "id": 7,
                        "discount_code": {
                            "id": 2,
                            "code": "SAMPLE10",
                            "discount_condition": {
                            },
                            "discount_usages": null,
                            "usage_count": 0,
                            "total_discount": 0,
                            "total_purchase": 0,
                            "shareable_link": "",
                            "parent_id": 0,
                            "type": 0,
                            "discount_settings": null,
                            "metadata": null,
                            "created_at": "2025-01-02T18:28:00.122279Z",
                            "updated_at": "2026-03-15T07:14:11.611698Z"
                        },
                        "invoice": {
                        },
                        "used": true,
                        "created_at": "2025-01-07T06:37:14.688186Z",
                        "updated_at": "2025-01-07T06:37:27.025452Z"
                    }
                ],
                "credit_usage": {
                },
                "invoice_items": [
                    {
                        "id": 343,
                        "product_variant": {
                        },
                        "booking_attributes": null,
                        "booking_result": null,
                        "no_of_items": 1,
                        "single_item_price": 4500000,
                        "total_items_price": 4500000,
                        "single_item_raw_price": 9000000,
                        "total_items_raw_price": 9000000,
                        "has_raw_price": false,
                        "variant_attributes": [],
                        "name": "دوره آموزشی + تیمسازی، بکند و گولنگ 🚀",
                        "image": {
                            "id": 117,
                            "name": "c20ad4d76fe97759aa27a0c99bff6710.jpg",
                            "alt": "",
                            "width": 1250,
                            "height": 1122,
                            "width_ratio": 0,
                            "height_ratio": 0,
                            "url": "https://oss.sazito.com/apiuploads/baar/uploads/image/rootimage/117/c20ad4d76fe97759aa27a0c99bff6710.jpg",
                            "thumb": "/uploads/image/rootimage/117/thumb_c20ad4d76fe97759aa27a0c99bff6710.jpg",
                            "order": 1,
                            "created_at": "2024-12-19T06:18:10.942081Z",
                            "updated_at": "2026-08-09T04:23:16.167748Z"
                        },
                        "form_attributes": {},
                        "customer_profit": 4500000,
                        "customer_profit_percentage": 50,
                        "created_by": "",
                        "created_at": "2025-01-07T06:37:10.022089Z",
                        "updated_at": "2025-01-07T06:37:16.409375Z"
                    }
                ],
                "receipts": [
                    {
                        "id": 32,
                        "receipt_ref": "234234",
                        "image_url": "/uploads/image/rootimage/0/receipt-example.png",
                        "payment": {
                            "id": 54,
                            "payment_status": "approved",
                            "payment_status_fa": "تایید شده",
                            "payment_amount": 4000000,
                            "is_active": false,
                            "payment_identifier": "33333333333333333333333333333333",
                            "payment_type": {
                                "id": 4,
                                "title": "card to card payment",
                                "title_fa": "پرداخت کارت به کارت",
                                "description": null,
                                "reference_code": "cardtocardpayment",
                                "order": 0,
                                "is_default": false
                            },
                            "payment_sub_type": "advancedcardtocard",
                            "invoice_id": 77,
                            "invoice_identifier": "",
                            "created_at": "2025-01-07T06:37:19.4634Z",
                            "updated_at": "2026-08-25T11:37:38.438692Z"
                        },
                        "receipt_amount": 4000000,
                        "created_at": "2025-01-07T06:37:27.027186Z",
                        "updated_at": "2026-08-25T11:37:38.440625Z"
                    }
                ],
                "coupon": {
                },
                
                "form_attributes": {},
                "shipping_method_needed": false,
                "shipping_details_customer": null,
                "user_comment": "",
                "created_at": "2025-01-03T06:26:15.632615Z",
                "updated_at": "2025-01-07T06:38:48.967909Z",
                "has_credit": false,
                "wallet_balance": 0,
                "customer_profit": 5000000,
                "customer_profit_percentage": 56,
                "items_total_raw_price": 9000000,
                "items_discount": 4500000,
                "wallet_min_amount": 0
            },
            "order_comments": null,
            "shipping_tracking_detail": "",
            "complete_custom_message": "",
            "shipping_details": {},
            "order_number": "OR0000000049",
            "note": "یادداشت نمونه",
            "add_note_to_pdf": false,
            "status": "cancelled",
            "status_title": "لغو شده",
            "metadata": {
                "takhfifan": {
                },
                "tracking_data": {
                    "list": []
                }
            },
            "created_at": "2025-01-07T06:37:27.029363Z",
            "updated_at": "2026-08-25T11:37:38.4457Z",
            "has_editions": false,
            "editions": [],
            "third_party_type": 0,
            "third_party_name": ""
        }
    },
    "error": "",
    "error_code": 0,
    "status": 200
}

به‌روزرسانی سفارش و وضعیت ارسال

PUT /api/v1/orders/{order_id}

نمونهٔ تغییر وضعیت یک مرسوله:

{
  "order_identifier": "66666666666666666666666666666666",
  "add_note_to_pdf": false,
  "shippingItems": [
    { "id": 3951, "status": "shipping" }
  ]
}

id در shippingItems شناسهٔ مرسوله است و در پاسخ دریافت/ایجاد سفارش، در invoice.shipping_items[].id قابل مشاهده است (به‌جای id می‌توانید shipping_item_id هم بفرستید).

order_identifier در بدنه الزامی است و اگر ارسال نشود یا با سفارش نخواند، پاسخ 400 برمی‌گردد. پاسخ موفق، خلاصهٔ سفارش را با همان ساختار آیتم‌های /api/v1/orders/list برمی‌گرداند (نه جزئیات کامل).

وضعیت کلی سفارش از کمترین وضعیتِ مرسوله‌هایی محاسبه می‌شود که در همین درخواست فرستاده‌اید (ترتیب: started < shipping < shipped < complete < cancelled). اگر سفارش چند مرسوله دارد، در هر درخواست همهٔ مرسوله‌ها را با وضعیت فعلی‌شان بفرستید؛ وگرنه وضعیت سفارش فقط بر اساس مرسوله‌های ارسال‌شده تعیین می‌شود.

لغو یک مرسوله موجودی کالاهای آن را برمی‌گرداند و خارج کردن آن از حالت لغو دوباره موجودی کم می‌کند. تغییر وضعیت، بسته به تنظیمات اطلاع‌رسانی فروشگاه، ممکن است برای خریدار پیامک وضعیت ارسال کند.

وضعیت‌های مجاز مرسوله:

started, shipping, shipped, complete, cancelled

مقدار نامعتبر برای status مرسوله خطای 400 می‌دهد.

برای ثبت کد رهگیری و ارسال اختیاری پیامک به خریدار:

{
  "order_identifier": "77777777777777777777777777777777",
  "add_note_to_pdf": false,
  "shippingItems": [
    {
      "id": 1995,
      "status": "started",
      "shipping_tracking_details": {
        "service_name": "IRANPOST",
        "shipping_number": "123456",
        "send_sms": true
      }
    }
  ]
}

مقدارهای service_name (همان گزینه‌های پنل مدیریت):

IRANPOST, TIPAX, MAHEX, TNEXT, CHAPAR, BOXIT, LINKEXPRESS, DEKAPOST, DIGIEXPRESS, OTHER

برای OTHER (و هر مقدار خارج از این فهرست) نام شرکت حمل در پیامک درج نمی‌شود.

برای ارسال کد رهگیری به شمارهٔ موبایل نشانی ارسال، send_sms را true و در غیر این صورت false قرار دهید.

دریافت سفارش از طریق webhook

برای فعال‌سازی webhook، آدرس مقصد (http یا https) و رویدادهای موردنیاز را در یک تیکت برای پشتیبانی سازیتو ارسال کنید:

هر فروشگاه فقط یک webhook دارد. هنگام فعال‌سازی یک کلید مخفی با پیشوند szt_wbh_ صادر و به شما تحویل می‌شود.

ارسال با متد POST و این هدرها انجام می‌شود:

Content-Type: application/json
Webhook-Token: szt_wbh_...
Idempotency-Key: <delivery-id>
X-Event-Delivery-ID: <delivery-id>

بدنهٔ درخواست یک پوشش رویداد است و اطلاعات سفارش در کلید entity قرار دارد:

{
  "id": "رشتهٔ شناسهٔ رویداد",
  "event_name": "<subdomain>:sazito_shop:order:create",
  "entity_type": 1,
  "action_type": 1,
  "store_id": 123,
  "date": "2026-11-01T10:00:00Z",
  "delivery_id": "<delivery-id>",
  "entity": { "id": 375, "order_identifier": "...", "status": "started", "invoice": {} }
}

event_name به order:create یا order:update ختم می‌شود (action_type به‌ترتیب 1 و 2). همراه رویدادهای order:update معمولاً یک رویداد دوم با همین event_name هم می‌رسد که entity آن به‌جای سفارش، رکورد ممیزی با فیلدهایی مانند activity_type و model_id است؛ رویدادهایی را که entity.order_identifier ندارند نادیده بگیرید.

نمونهٔ فشردهٔ entity (اطلاعات سفارش):

{
  "id": 375,
  "note": "",
  "seen": false,
  "status": "started",
  "order_number": "OR0000000375",
  "order_identifier": "88888888888888888888888888888888",
  "invoice": {
    "id": 420,
    "net_total": 1000,
    "final_total": 1073,
    "vat": 70,
    "vat_percent": 7,
    "user": { "id": 3, "first_name": "نام", "last_name": "نام‌خانوادگی", "email": "customer@example.com" },
    "invoice_items": [
      {
        "id": 1277,
        "name": "نام محصول",
        "no_of_items": 1,
        "single_item_price": 1000,
        "total_items_price": 1000,
        "product_variant": { "id": 67, "sku": "EXAMPLE-SKU", "price": 1000 }
      }
    ],
    "shipping_items": [
      {
        "id": 1065,
        "status": "started",
        "shipping_number": "SH0000001065",
        "invoice_item_ids": [1277]
      }
    ],
    "shipping_address": {
      "first_name": "نام",
      "last_name": "نام‌خانوادگی",
      "email": "customer@example.com",
      "mobile_phone": "+989000000000",
      "postal_code": "1234567890",
      "address": "نشانی نمونه"
    }
  }
}

ایجاد سفارش

POST /api/v1/orders/create_order

این endpoint از هدر اختصاصی زیر استفاده می‌کند:

Access-Key: your-access-key

به‌جای Access-Key می‌توانید هدر X-API-Key (کلید API فروشگاه) را هم بفرستید. اگر هیچ‌کدام معتبر نباشد، پاسخ 400 با پیام «پارامترهای ورودی معتبر نیست» برمی‌گردد.

پاسخ موفق، سفارش ثبت‌شده را با همان ساختار «جزئیات سفارش» در result.order برمی‌گرداند (شناسهٔ مرسوله‌ها در invoice.shipping_items[].id).

نمونهٔ درخواست:

{
  "items": [
    { "sku": "PROD-001", "count": 2, "price": 29.99, "rawPrice": 35.99 },
    { "sku": "PROD-002", "count": 1, "price": 15.5, "rawPrice": 18.99 }
  ],
  "shipping_address": {
    "phone_number": "09121234567",
    "email": "customer@example.com",
    "address": "نشانی نمونه",
    "location": "توضیح تکمیلی",
    "postal_code": "1000000000",
    "city": "تهران",
    "region": "تهران",
    "first_name": "نام",
    "last_name": "نام‌خانوادگی",
    "longitude": 51.389,
    "latitude": 35.689
  },
  "third_party_name": "integration-name",
  "shipping_items": [
    { "skus": ["PROD-001", "PROD-002"], "name": "Post", "cost": 5.99 }
  ],
  "discount": { "code": "SUMMER2026", "type": "percentage", "amount": 15 },
  "payment": { "gateway_name": "zarinpalpersonal", "amount": 75.47, "ref_number": "7C8S9T2U1V13W" },
  "update_inventories": true,
  "note": "تحویل پیش از ساعت ۱۷",
  "vat_total": 6.78
}
بخش فیلد نوع الزامی توضیح
ریشه items array بله فهرست کالاهای سفارش
ریشه shipping_address object بله اطلاعات گیرنده
ریشه third_party_name string خیر نام ثابت اپراتور یا سیستم واسط؛ برای گزارش‌گیری از یک مقدار واحد استفاده کنید
ریشه shipping_items array بله روش‌های ارسال انتخاب‌شده
ریشه discount object خیر اطلاعات تخفیف
ریشه payment object بله اطلاعات پرداخت
ریشه update_inventories boolean خیر (پیش‌فرض false) اگر true باشد موجودی کالاها پس از ثبت سفارش کم می‌شود. در هر حالت، اگر موجودی کالایی که مدیریت موجودی دارد کافی نباشد، درخواست با خطای 400 رد می‌شود
ریشه note string خیر توضیحات تکمیلی
ریشه vat_total number خیر مالیات بر ارزش افزوده
ریشه receipt_image_url string خیر آدرس تصویر رسید پرداخت
items[] sku یا id string / number بله SKU یا شناسهٔ variant
items[] count integer بله تعداد کالا
items[] price number بله قیمت نهایی کالا
items[] rawPrice number خیر قیمت پیش از تخفیف؛ در حال حاضر ذخیره نمی‌شود
shipping_address phone_number, email, address, postal_code, city, region, first_name, last_name string بله اطلاعات اصلی گیرنده
shipping_address location string خیر توضیح تکمیلی موقعیت؛ در حال حاضر ذخیره نمی‌شود
shipping_address longitude, latitude number خیر مختصات جغرافیایی
shipping_items[] skus, name, cost array / string / number بله کالاهای ارسال‌شونده (فقط با sku آیتم‌ها تطبیق داده می‌شوند)، نام روش و هزینهٔ ارسال
discount code, type, amount string / string / number خیر فقط amount به‌عنوان مبلغ تخفیف (discount_total) ثبت می‌شود؛ code و type ذخیره نمی‌شوند
payment gateway_name, amount, ref_number string / number / string بله جزئیات پرداخت؛ amount مبلغ نهایی سفارش و ref_number شمارهٔ رسید می‌شود. gateway_name یکی از کدهای درگاه سازیتو (مثل zarinpalpersonal) است و مقدار ناشناخته «پرداخت شخص ثالث» ثبت می‌شود. پرداخت همیشه «پرداخت‌شده» ثبت می‌شود

نکات: