مدیریتمحصولات و سفارشات
این راهنما برای فروشگاههای سازیتویی تهیه شده است تا از 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 انتخابشده به این ترتیب تعیین میشود:
- variantهای موجود بر variantهای ناموجود مقدماند؛
- کمترین قیمت فروش (قیمت پس از تخفیف)؛
- در صورت برابری قیمت، شناسهٔ کوچکتر.
- اگر همهٔ variantهای محصول ناموجود باشند، محصول با ارزانترین variant و
availability: falseمیآید. برای حذف این محصولات فیلترin_stockرا بفرستید. - فیلترها پیش از انتخاب ارزانترین variant اعمال میشوند.
total_productsتعداد محصولات را نشان میدهد وpage_sizeتعداد محصولات هر صفحه است.- هر قلم فیلد
product_idدارد. variant انتخابشده (و در نتیجهid) ممکن است با تغییر قیمت یا موجودی عوض شود؛ برای شناسایی محصول ازproduct_idاستفاده کنید.
فیلترها
فیلترها به صورت آرایهٔ 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 فقط بخشی از محصول را تغییر میدهید و لازم نیست کل محصول را دوباره بفرستید. هر کلیدی که در بدنه نباشد، دستنخورده باقی میماند.
پرکاربردترین موارد:
- تغییر SKU، قیمت یا موجودی یک variant
- افزودن، تغییر یا حذف attribute محصول
- افزودن یا حذف variant
- تغییر گالری تصویر، برچسبها یا دستهبندیها
تفاوت با
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
taxonomy_actionsیک فهرست عملیات ترتیبی است. actionها را مرتبسازی، deduplicate یا ادغام نکنید.- حداکثر ۵۰۰ action در هر درخواست مجاز است. actionها به ترتیب و یکجا اجرا میشوند: اگر یکی رد شود، هیچکدام اعمال نمیشود.
value_idsمیتواند چند مقدار داشته باشد (حداکثر ۱۰۰ مقدار برای هر metafield).- هر محصول فقط یک taxonomy category دارد؛
assign_categoryدستهٔ قبلی را جایگزین میکند و اگر چندassign_categoryبفرستید، آخرین آنها اعمال میشود. - برای حذف دسته،
{"action": "unassign_category"}بفرستید؛ محصول به دستهٔ ویژهٔuncategorizedمنتقل میشود (همان اثرassign_categoryباcategory_id: "uncategorized"). add_metafieldوremove_metafieldبرای یک attribute در یک درخواست یکدیگر را خنثی میکنند.
هنگام
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:
page_number(پیشفرض 1) وpage_size(پیشفرض 20).filters[]: آرایهٔ JSON از{"name": ..., "value": ...}که باید URL-encode شود. فیلترهای پرکاربرد:status(یک یا چند مقدار با کاما ازstarted,shipping,shipped,complete,cancelled)،seen(trueیاfalse)،query(جستوجو در نام، ایمیل و موبایل گیرنده و شمارهٔ سفارش)،start_dateوend_date(تاریخ ثبت سفارش با فرمت RFC3339 مانند2026-10-01T00:00:00Z)،ids(شناسههای سفارش با کاما) وproduct_type(simple,digital,service).- این endpoint پارامتر
sortرا اعمال نمیکند و سفارشها همیشه از جدید به قدیم برمیگردند؛ برای مرتبسازی دلخواه از/api/v1/orders/listاستفاده کنید.
نمونه:
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 (و هر مقدار خارج از این فهرست) نام شرکت حمل در پیامک درج نمیشود.
service_nameوshipping_numberهر دو باید ارسال شوند؛ اگر یکی از آنها نباشد، کد رهگیری بدون خطا نادیده گرفته میشود.shipping_numberفقط حروف و ارقام انگلیسی و علائم را میپذیرد؛ ارقام فارسی خودکار به انگلیسی تبدیل میشوند و حروف فارسی یا فاصله خطای 400 میدهد.- ارسال دوبارهٔ همان
service_nameوshipping_numberمقدار قبلی را جایگزین میکند. در پاسخ دریافت سفارش،shipping_tracking_detailsهر مرسوله فقط آخرین کد ثبتشده را (بهصورت object) نشان میدهد.
برای ارسال کد رهگیری به شمارهٔ موبایل نشانی ارسال، send_sms را true و در غیر این صورت false قرار دهید.
دریافت سفارش از طریق webhook
برای فعالسازی webhook، آدرس مقصد (http یا https) و رویدادهای موردنیاز را در یک تیکت برای پشتیبانی سازیتو ارسال کنید:
order_create: پس از پرداخت موفق هر سفارش (شامل سفارشهایی که باcreate_orderثبت میکنید).order_update: پس از بهروزرسانی سفارش، مثل تغییر وضعیت سفارش یا مرسوله، ثبت کد رهگیری یا یادداشت (ویرایش اقلام سفارش این رویداد را ارسال نمیکند).
هر فروشگاه فقط یک webhook دارد. هنگام فعالسازی یک کلید مخفی با پیشوند szt_wbh_ صادر و به شما تحویل میشود.
ارسال با متد POST و این هدرها انجام میشود:
Content-Type: application/json
Webhook-Token: szt_wbh_...
Idempotency-Key: <delivery-id>
X-Event-Delivery-ID: <delivery-id>
- امضای HMAC وجود ندارد؛ مقدار
Webhook-Tokenرا با کلید مخفی خود مقایسه کنید. - فقط پاسخ HTTP 200 یا 201 موفق حساب میشود (202 و 204 هم خطا به شمار میآیند) و باید ظرف حدود ۵ ثانیه پاسخ دهید.
- در صورت خطا، ارسال حداکثر ۵ بار با فاصلهٔ حدود یک دقیقه انجام و سپس متوقف میشود. ارسال تکراری را با
Idempotency-Keyتشخیص دهید و برای جبران رویدادهای ازدسترفته، فهرست سفارشها را دورهای بخوانید.
بدنهٔ درخواست یک پوشش رویداد است و اطلاعات سفارش در کلید 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) است و مقدار ناشناخته «پرداخت شخص ثالث» ثبت میشود. پرداخت همیشه «پرداختشده» ثبت میشود |
نکات:
- هر سفارش باید حداقل یک آیتم داشته باشد.
- برای کالا میتوانید
idvariant یاskuرا ارسال کنید.idباید در فهرست محصولات فروشگاه وجود داشته باشد. کالایی که فقط باidارسال شود به هیچیک ازshipping_itemsوصل نمیشود؛ اگر روش ارسال دارید،skuرا بفرستید. - اگر
idیاskuهر آیتم در فروشگاه پیدا نشود (یا variant حذف شده باشد)، کل درخواست با خطای 400 «پارامترهای ورودی معتبر نیست» رد میشود و سفارشی ثبت نمیشود. - مبلغها بدون بررسی ثبت میشوند و صحت آنها بر عهدهٔ درخواستدهنده است:
final_totalبرابرpayment.amount، مبلغ تخفیف برابرdiscount.amount، هزینهٔ ارسال برابر مجموعcostمرسولهها،vatبرابرvat_totalوnet_totalبرابرfinal_total + تخفیف − هزینهٔ ارسال − vatاست؛ قیمت هر آیتمprice × countثبت میشود. - نام و قیمت روش ارسال روی مرسوله فقط وقتی پر میشود که پیشتر مرسولهای با همین
nameدر فروشگاه ثبت شده باشد؛costفقط در هزینهٔ ارسال سفارش جمع میشود. phone_numberرا همیشه بفرستید؛ خریدار با شمارهٔ موبایل شناسایی یا ساخته میشود.- نام شهر و استان باید دقیقاً با نام ثبتشده در سازیتو برابر باشد؛ در غیر این صورت این بخشها در فاکتور خالی میمانند.
- ثبت سفارش با این endpoint اطلاعرسانیهای معمول سفارش جدید (پیامک و ایمیل) و webhook
order_createرا فعال میکند.