این راهنما برای فروشگاههای سازیتویی تهیه شده است تا از API مدیریت فروشگاه استفاده کنند. این دسترسی در پلن پیشرفته پلاس در دسترس است و بخشهای محصولات و سفارشها را پوشش میدهد.
برای دسترسیهای بیشتر، از طریق پشتیبانی/موفقیت مشتری سازیتو درخواست خود را ثبت کنید.
در همهٔ درخواستها، دامنهٔ فروشگاه را پیش از مسیر API قرار دهید:
https://www.example.com/api/v1
برای endpointهای نیازمند مجوز، کلید API را در هدر ارسال کنید:
X-API-Key: your-api-key
برای دریافت کلید API، یک کاربر با نقش ادمین ایجاد کنید و ایمیل یا شناسهٔ او را برای پشتیبانی سازیتو ارسال کنید. کلید صادرشده به همان کاربر متصل است؛ بنابراین سطح دسترسی کاربر باید متناسب با عملیات موردنظر باشد.
برای بدنههای JSON نیز هدر زیر را ارسال کنید:
Content-Type: application/json
| عملیات | متد | مسیر | احراز هویت |
|---|---|---|---|
| دریافت محصولات | GET |
/api/v1/products |
عمومی؛ برخی فیلدها با کلید API بازمیگردند |
| دریافت یک محصول | GET |
/api/v1/products/{product_id} |
API key |
| آپلود تصویر محصول | POST |
/api/v1/images |
API key |
| ایجاد محصول | POST |
/api/v1/products |
API key |
| بهروزرسانی محصول | PUT |
/api/v1/products/{product_id} |
API key |
| بهروزرسانی جزئی گالری تصویر | PUT |
/api/v1/products/partial/{product_id} |
توکن پنل ادمین (Authorization) |
| دریافت 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 |
عمومی |
| بهروزرسانی 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 |
| تغییر قیمت 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 ممکن است توضیحات محصول و برخی فیلدهای دیگر در پاسخ قرار نگیرند.
GET /api/v1/products/{product_id}
پیش از بهروزرسانی کامل محصول، نسخهٔ فعلی را دریافت کنید تا شناسهٔ variantها، تصویرهای متصل و ترتیب آنها را حفظ کنید.
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]=نمای محصول"
برای آپلود چند تصویر، سه فیلد مربوط به هر تصویر را تکرار کنید و نتیجه را در فروشگاه مقصد بررسی کنید. محدودیت فرمت و حجم فایل در سمت سرور اعمال میشود؛ پیش از اتکا به یک محدودیت ثابت، تنظیمات فعال فروشگاه را با پشتیبانی سازیتو تأیید کنید.
نمونهٔ پاسخ:
{
"error_code": 0,
"status": 200,
"result": {
"images": [
{
"id": 1901,
"name": "product.webp",
"url": "/uploads/image/rootimage/1901/product.webp",
"thumb": "/uploads/image/rootimage/1901/thumb_product.webp",
"width": 1200,
"height": 1600
}
]
}
}
مقدار لازم برای اتصال تصویر، result.images[].id است؛ URL تصویر را بهجای ID در بدنهٔ محصول نفرستید.
POST /api/v1/products
هر محصول میتواند چند variant داشته باشد. برای تعریف variant، حداقل یک attribute تعریف کنید و برای هر variant به همهٔ attributeهای تعریفشده مقدار بدهید.
| بخش | فیلد | نوع | الزامی | توضیح |
|---|---|---|---|---|
product |
name |
string | بله | نام محصول |
product |
product_type |
string | بله | یکی از simple، digital یا service |
product |
enabled |
boolean | خیر | فعالبودن محصول؛ پیشفرض true |
product |
url |
string | خیر | لینک اختصاصی محصول |
attributes |
type |
string | بله | نوع attribute؛ مانند string |
attributes |
name |
string | بله | نام attribute؛ مانند «سایز» |
attributes |
attribute_type |
string | بله | برای تمایز variantها از differentiator استفاده کنید |
product_category_ids |
— | string | خیر | شناسهٔ دستهبندیها، جداشده با کاما |
image_ids |
— | array of integer | خیر | ID تصویرهای آپلودشده؛ در سطح ریشهٔ بدنه |
image_orders |
— | array of object | خیر | ترتیب نمایش، مانند [{"id":1901,"order":1}]؛ در سطح ریشهٔ بدنه |
taxonomy_actions |
— | array | خیر | actionهای taxonomy در سطح ریشهٔ بدنه؛ پیش از استفاده، دسترسی آن را تأیید کنید |
product_variants |
price |
number | خیر | قیمت variant |
product_variants |
sku |
string | خیر | کد کالا؛ در صورت عدم ارسال، سیستم میتواند آن را بسازد |
product_variants |
enabled |
boolean | خیر | فعالبودن variant |
product_variants |
has_max_order |
boolean | خیر | فعالبودن محدودیت حداکثر سفارش |
product_variants |
min_order_count |
number | خیر | حداقل تعداد سفارش |
product_variants |
is_stock_managed |
boolean | خیر | فعالبودن مدیریت موجودی |
product_variants |
stock_number |
number | خیر | تعداد موجودی |
product_variants |
relative |
boolean | خیر | قیمت نسبی یا مطلق |
product_variants |
weight |
number | خیر | وزن محصول |
product_variants |
raw_price |
number | خیر | قیمت خام |
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": 1 },
{ "id": 1902, "order": 2 }
]
}
image_ids تصویرها را به محصول متصل میکند و image_orders ترتیب نمایش را تعیین میکند. هر id در image_orders باید در image_ids نیز وجود داشته باشد و برای هر تصویر فقط یک ترتیب ارسال شود.
ترتیبهای یکتا و افزایشی، مانند 1، 2 و 3، ارسال کنید. مقدار order در پاسخ آپلود را مبنای ترتیب گالری محصول قرار ندهید؛ ترتیب گالری فقط با image_orders تعیین میشود.
PUT /api/v1/products/partial/{product_id}
Content-Type: application/json
برای محصولی که از قبل ایجاد شده است، وقتی فقط میخواهید گالری تصویر را تغییر دهید، از این endpoint استفاده کنید. در کاربرد مستندشده، بدنه فقط شامل image_ids و image_orders در سطح ریشه است؛ product، attributes و product_variants را نفرستید.
این مسیر در جریان پنل ادمین با توکن خام پنل در هدر Authorization (بدون پیشوند Bearer) مشاهده شده است. پشتیبانی X-API-Key برای این endpoint هنوز تأیید نشده است؛ اگر فقط کلید API دارید، پیش از استفاده، پشتیبانی آن را از سازیتو تأیید کنید.
نمونهٔ درخواست با توکن پنل ادمین:
curl --request PUT "https://{shop-domain}/api/v1/products/partial/{product_id}" \
-H "Authorization: ${SAZITO_ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Origin: https://{shop-domain}" \
-H "Referer: https://{shop-domain}/admin/products" \
--data '{
"image_ids": [1901, 1902, 1903],
"image_orders": [
{ "id": 1901, "order": 1 },
{ "id": 1902, "order": 2 },
{ "id": 1903, "order": 3 }
]
}'
image_ids فهرست تصویرهای متصل و image_orders ترتیب نمایش آنها را مشخص میکند. هر id در image_orders باید در image_ids نیز وجود داشته باشد و ترتیبها یکتا و افزایشی باشند.
رفتار سرور برای تصویرهایی که از بدنه حذف میشوند—ادغام با گالری قبلی یا جایگزینی کامل آن—هنوز مستند نشده است. برای جلوگیری از حذف ناخواسته، همیشه فهرست کاملِ گالری موردنظر را در هر دو آرایه بفرستید؛ یعنی هنگام افزودن یک تصویر جدید، شناسه و ترتیب تصویرهای قبلی که باید باقی بمانند را نیز ارسال کنید.
توکن پنل ادمین را مانند یک رمز نگه دارید و هرگز آن را در کد سمت مرورگر، مخزن عمومی یا مستندات قرار ندهید. از cookieهای مرورگر در integration استفاده نکنید؛ در صورت نیاز به دسترسی پایدار، روش مورد تأیید پشتیبانی سازیتو را دریافت کنید.
برای تغییر همزمان مشخصات محصول، attributeها یا variantها، از endpoint کامل زیر استفاده کنید.
PUT /api/v1/products/{product_id}
این endpoint برای بهروزرسانی کامل محصول است. پیش از PUT محصول فعلی را با GET /api/v1/products/{product_id} دریافت کنید. هنگام ارسال product_variants یا image_ids و image_orders، همهٔ variantهای فعلی و همهٔ تصویرهای متصل و ترتیب آنها را حفظ کنید. variant یا تصویری که از بدنهٔ بهروزرسانی حذف شود، ممکن است ایجاد، حذف یا از محصول جدا شود. برای variant موجود، id آن را نیز ارسال کنید.
نمونهٔ تغییر مقدار 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 تعریف کنید:
{
"product": { "name": "تست رنگ" },
"attributes": [
{
"type": "string",
"name": "رنگ",
"value": "",
"attribute_type": "differentiator"
}
],
"product_variants": [
{
"id": 23827,
"attributes": [
{
"name": "رنگ",
"value": { "extra": "#60ec62", "fieldType": "color", "value": "قرمز" }
}
]
}
]
}
مسیرهای خواندن taxonomy نسبت به دامنهٔ همان فروشگاه هستند، اما برخلاف API مدیریت، زیر /api/v1 قرار ندارند:
https://{shop-domain}/taxonomy/public
این endpointها عمومیاند و به Authorization، X-API-Key یا cookie نشست نیاز ندارند.
GET /taxonomy/public/products/{store_id}/{product_id}
| پارامتر | توضیح |
|---|---|
store_id |
شناسهٔ عددی داخلی فروشگاه |
product_id |
شناسهٔ عددی محصول |
پاسخ، دستهبندی 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": "نام مقدار"
}
]
}
]
}
GET /taxonomy/public/categories/{category_id}/children
{
"children": [
{
"id": "cat_<child-category-id>",
"fa_name": "نام زیردسته",
"num_children": 0
}
],
"total_count": 1
}
اگر num_children بزرگتر از صفر است، برای پیمایش سطح بعدی همین endpoint را با id آن زیردسته فراخوانی کنید.
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 ویژگیهای بهارثرسیده از دستههای والد را نشان میدهد.
این سه endpoint فهرست کامل valueهای مجاز هر metafield را برنمیگردانند. endpoint محصول فقط valueهای انتخابشدهٔ همان محصول را نشان میدهد؛ شناسهٔ value جدید را از دادهٔ 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 category | taxonomy_actions[].category_id |
معمولاً cat_... |
دستهبندی taxonomy محصول |
| taxonomy metafield | taxonomy_actions[].attribute_id |
attr_... |
ویژگی taxonomy، مانند جنس یا برند |
| مقدار metafield | taxonomy_actions[].value_ids |
val_... |
مقدارهای مجاز همان metafield |
شناسههای taxonomy opaque و مختص همان فروشگاه هستند. val_... باید متعلق به attr_... ارسالشده در همان action باشد؛ شناسههای نمونه را در فروشگاه دیگر بازاستفاده نکنید.
action |
فیلدهای لازم | کاربرد |
|---|---|---|
assign_category |
category_id |
اتصال taxonomy category به محصول |
add_metafield |
attribute_id |
فعالکردن یا افزودن metafield taxonomy |
add_values |
attribute_id و value_ids |
افزودن مقدار به metafield |
remove_values |
attribute_id و value_ids |
حذف مقدار از metafield |
remove_metafield |
attribute_id |
حذف 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>"
]
}
]
}
{
"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_actions یک فهرست عملیات ترتیبی است. actionها را مرتبسازی، deduplicate یا ادغام نکنید.value_ids آرایه است اما هر add_values فقط یک مقدار داشته و actionها تکرار شدهاند. تا زمان تأیید ارسال گروهی، برای هر مقدار یک action جداگانه بفرستید.assign_category در یک درخواست دیده شدهاند، اما مشخص نیست رفتار آنها افزایشی، جایگزینی یا آخرینمقدار است؛ نتیجه را پس از بهروزرسانی بررسی کنید.uncategorized بهعنوان category_id در درخواست پنل دیده شده است، اما اثر دقیق آن برای یکپارچهسازی عمومی تأیید نشده است.remove_metafield برای همان metafield action دیگری ارسال نکنید، مگر اینکه آن سناریو را در محیط آزمایشی تأیید کرده باشید.هنگام
PUT، قطعهٔtaxonomy_actionsبهتنهایی لزوماً بدنهٔ کامل و ایمن بهروزرسانی نیست. دادهٔ فعلی محصول را حفظ کنید و پس از درخواست، نتیجه را در پاسخ API و پنل ادمین بررسی کنید.
PUT /api/v1/accounting/update-price/{variant_id}
قیمت بدون تخفیف:
{ "price": 20 }
قیمت همراه با قیمت خام و تخفیف:
{
"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 بهعنوان مقدار مطلق اعمال میشود.
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 }
]
}
PUT /api/v1/products/update_variant/sku/{sku}
مقدار SKU را در خود URL قرار دهید:
{
"is_stock_managed": true,
"stock_number": 22,
"price": 2000,
"has_raw_price": true,
"raw_price": 1200
}
GET /api/v1/orders
این endpoint به کلید API نیاز دارد.
GET /api/v1/orders/list
این endpoint به کلید Token نیاز دارد.
نمونهٔ آیتم های پاسخ
{
"id": 6321,
"created_at": "2026-08-26T11:33:45.618001Z",
"receipt_id": 5338,
"order_status": 1,
"order_identifier": "169a346094e2734e2af0963b228f31ac",
"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"
}
}
}
GET api/v1/orders/{order_id}?order_identifier={order_identifier}
نمونهٔ پاسخ:
{
"result": {
"order": {
"id": 49,
"order_identifier": "37fbc635f8d76d7ac00738f38bd7169f",
"seen": true,
"user": {
"id": 28,
"email": "hassannazari453@gmail.com",
"mobile_phone": "+989954904291",
"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/121/6364d3f0f495b6ab9dcf8d3b5c6e0b01.png",
"payment": {
"id": 54,
"payment_status": "approved",
"payment_status_fa": "تایید شده",
"payment_amount": 4000000,
"is_active": false,
"payment_identifier": "7e2bea3d48e96bebd14790be79ca5183",
"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": "b5b1177bfd5b64a50dfdbd10f6846722",
"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": "hassannazari21248@gmail.com",
"mobile_phone": "+98457894504292",
"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": "hassannazari286568@gmail.com",
"first_name": "حسن",
"last_name": "نظری",
"address": "",
"postal_code": "",
"phone_number": "",
"mobile_phone": "+989789504192",
"shipping_address_identifier": "8d98df2da914be9871da2c6de51b6a32",
"longitude": 51.349759,
"latitude": 35.702907,
"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": null,
"discount_usages": [
{
"id": 7,
"discount_code": {
"id": 2,
"code": "babak",
"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/121/6364d3f0f495b6ab9dcf8d3b5c6e0b01.png",
"payment": {
"id": 54,
"payment_status": "approved",
"payment_status_fa": "تایید شده",
"payment_amount": 4000000,
"is_active": false,
"payment_identifier": "7e2bea3d48e96bebd14790be79ca5183",
"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": "تست کد تخفیف babak",
"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": "df774322de9ce03f28976d5317141ef3",
"add_note_to_pdf": false,
"shippingItems": [
{ "id": 3951, "status": "shipping" }
]
}
id در shippingItems شناسهٔ مرسوله است و در پاسخ دریافت/ایجاد سفارش، در بخش shipping_items قابل مشاهده است.
وضعیتهای مجاز مرسوله:
started, shipping, shipped, complete, cancelled
برای ثبت کد رهگیری و ارسال اختیاری پیامک به خریدار:
{
"order_identifier": "416d9ea96918586b3053a4d7fe093946",
"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, OTHER
برای ارسال کد رهگیری به شمارهٔ خریدار، send_sms را true و در غیر این صورت false قرار دهید.
برای فعالسازی webhook، آدرس مقصد را در یک تیکت برای پشتیبانی سازیتو ارسال کنید. پس از فعالسازی، با ثبت هر سفارش اطلاعات آن به آدرس شما ارسال میشود.
نمونهٔ فشردهای از بدنهٔ ارسالی:
{
"id": 375,
"note": "",
"seen": false,
"status": "started",
"order_number": "OR0000000375",
"order_identifier": "5842f355cc563880731369bdd967d0c0",
"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
نمونهٔ درخواست:
{
"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": "zarinpal", "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 | بله | کاهش موجودی پس از ثبت سفارش |
| ریشه | note |
string | خیر | توضیحات تکمیلی |
| ریشه | vat_total |
number | خیر | مالیات بر ارزش افزوده |
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 | بله | کالاهای ارسالشونده، نام روش و هزینهٔ ارسال |
discount |
code, type, amount |
string / string / number | بله* | جزئیات تخفیف؛ *در صورت ارسال object تخفیف |
payment |
gateway_name, amount, ref_number |
string / number / string | بله | جزئیات پرداخت |
نکات:
id variant یا sku را ارسال کنید. id باید در فهرست محصولات فروشگاه وجود داشته باشد.