تخفیف هوشمند و کمپین‌ها
مخاطب: برنامه‌نویس یا فروشنده‌ای که می‌خواهد تخفیف هوشمند تنوع‌ها را از نرم‌افزار خود ثبت و پایش کند، تخفیف خودکار را تنظیم کند یا کالاها را به کمپین‌های دیجی‌کالا بفرستد.
📖 مقدمه
Section titled “📖 مقدمه”تخفیف هوشمند تخفیفی است که فروشنده خودش روی یک تنوع در دیجی‌کالا ثبت می‌کند: قیمت فروش سر جای خود می‌ماند و خط می‌خورد و خریدار قیمت تخفیف را می‌پردازد. کمپین‌ها (شگفت‌انگیز، مگاکمپین، شگفت‌انگیز روز) را دیجی‌کالا برگزار می‌کند و شما با قیمت پیشنهادی به آن‌ها می‌پیوندید.
قاعده‌ی محوری این صفحه: هیچ تخفیف یا قیمت کمپینی زیر حداقل قیمت شما ثبت نمی‌شود، و برای کالای بدون حداقل قیمت هیچ تخفیفی ثبت نمی‌شود. حداقل قیمت همان حداقلی است که ربات قیمت‌گذاری رعایت می‌کند (ربات قیمت‌گذاری).
با مسیرهای این صفحه می‌توانید:
| کار | مسیر | در دسترس |
|---|---|---|
| تخفیف هوشمند همه‌ی تنوع‌ها | GET /v1/promotions |
فعال |
| تخفیف هوشمند یک تنوع | GET /v1/promotions/{variant_id} |
فعال |
| ثبت یا ویرایش تخفیف | PUT /v1/promotions/{variant_id} |
فعال |
| پایان تخفیف | DELETE /v1/promotions/{variant_id} |
فعال |
| تخفیف گروهی در صف | POST /v1/promotions/batch |
فاز ۲ |
| خواندن تنظیمات تخفیف پله‌ای و تمدید | GET /v1/promotion-settings |
فعال |
| تغییر تنظیمات تخفیف پله‌ای و تمدید | PUT /v1/promotion-settings |
فعال |
| کمپین‌های باز | GET /v1/campaigns |
فعال |
| یک کمپین و کالاهای شما در آن | GET /v1/campaigns/{campaign_id} |
فعال |
| پیوستن به کمپین | POST /v1/campaigns/{campaign_id}/join |
فاز ۳ |
| خروج از کمپین | POST /v1/campaigns/{campaign_id}/leave |
فاز ۳ |
| ارزها، نرخ روز و استراتژی‌های ارزی | GET /v1/fx |
فعال |
| قیمت‌گذاری ارزی تنوع‌ها | GET /v1/fx/variants |
فعال |
| تعیین استراتژی ارزی یک تنوع | PUT /v1/fx/variants/{variant_id} |
فعال |
| تایید قیمت ارزی منتظر تایید | POST /v1/fx/variants/{variant_id}/confirm |
فعال |
و با رویدادهای وب‌هوک promotion.ending، promotion.rejected و promotion.below_floor از پایان، رد و تخفیف‌های زیر حداقل قیمت خبردار شوید.
⚙️ پیش‌نیازها
Section titled “⚙️ پیش‌نیازها”دسترسی (Scope)
Section titled “دسترسی (Scope)”| دسترسی | برای |
|---|---|
promotions:read |
خواندن تخفیف‌ها، تنظیمات و کمپین‌ها، و رویدادهای promotion.* |
promotions:write |
ثبت، ویرایش و پایان تخفیف، تخفیف گروهی، تنظیمات، پیوستن و خروج از کمپین |
prices:read |
خواندن قیمت ارزی (/v1/fx) |
prices:write |
تعیین استراتژی ارزی و تایید قیمت ارزی |
جزئیات ساخت کلید در صفحه‌ی ورود و دسترسی‌ها آمده است.
فعال بودن ماژول
Section titled “فعال بودن ماژول”ماژول «API و وب‌هوک» باید برای پنل فعال باشد؛ در غیر این صورت همه‌ی مسیرها با کد 403 و خطای module_inactive (ماژول API) یا module_required (ماژول این بخش، با نام آن در detail) پاسخ می‌دهند. مسیرهای /v1/fx به ماژول اختیاری «قیمت ارزی» هم نیاز دارند و بدون آن همان خطا را می‌دهند. برای پنلی که اشتراک آن به پایان رسیده است، هر ثبت در دیجی‌کالا با خطای subscription_inactive رد می‌شود.
آدرس پایه
Section titled “آدرس پایه”https://api.seller360.ir🧮 مدل تخفیف هوشمند
Section titled “🧮 مدل تخفیف هوشمند”وضعیت تنوع (state)
Section titled “وضعیت تنوع (state)”| مقدار | برچسب در پنل | معنی |
|---|---|---|
ok |
— | تخفیف دستی ممکن است. |
blocked |
«حداقل قیمت اجازه‌ی تخفیف نمی‌دهد» | سقف قیمت تخفیف دیجی‌کالا کمتر از حداقل قیمت شماست؛ تخفیفی ثبت‌شدنی نیست. |
no_floor |
«حداقل قیمت ندارد» | تنوع حداقل قیمت ندارد؛ تخفیف ثبت نمی‌شود. |
bot |
— | ربات با روش «تخفیف هوشمند» قیمت این تنوع را تعیین می‌کند؛ تغییر دستی ممکن نیست. |
فیلدها
Section titled “فیلدها”| فیلد | برچسب در پنل | معنی |
|---|---|---|
eligible |
— | دیجی‌کالا تخفیف هوشمند را برای این تنوع مجاز می‌داند. |
reference_price |
«قیمت مرجع» | درصد تخفیف نسبت به آن است. |
base_price |
«قیمت فروش فعلی (خط‌خورده)» | قیمت فروش پایه. |
customer_price |
«قیمت برای مشتری» | قیمتی که خریدار می‌پردازد. |
floor، floor_source |
«حداقل قیمت شما» | حداقل قیمت و منشا آن. |
cap |
«سقف مجاز» | بیشترین قیمت تخفیفی که دیجی‌کالا می‌پذیرد؛ قیمت تخفیف باید کمتر یا برابر آن باشد. |
cap_pct |
— | کمترین درصد تخفیف قابل قبول دیجی‌کالا. |
floor_pct |
— | بیشترین درصد تخفیفی که حداقل قیمت شما اجازه می‌دهد. |
min_discount_pct |
«حداقل تخفیف دیجی‌کالا» | حداقل درصد تخفیف دسته‌ی کالا. |
order_limit_min، order_limit_max |
— | بازه‌ی مجاز سقف تعداد در هر سفارش. |
stock |
— | موجودی قابل فروش. |
discount |
— | تخفیف فعال؛ خالی یعنی تخفیفی در جریان نیست (جدول بعد). |
step_level |
— | پله‌ی فعلی تخفیف پله‌ای؛ ۰ یعنی بدون پله. |
last_error، last_error_at |
— | آخرین پیام رد دیجی‌کالا در ۲ روز گذشته. |
synced_at |
— | زمان آخرین به‌روزرسانی نسخه‌ی محلی. |
تخفیف فعال (discount)
| فیلد | معنی |
|---|---|
promotion_variant_id |
شناسه‌ی رکورد تخفیف در دیجی‌کالا. |
promotion_price |
قیمت تخفیف به ریال. |
discount_pct |
درصد تخفیف نسبت به قیمت مرجع. |
started_at، end_at |
شروع و پایان. |
limit |
تعداد کالا در تخفیف. |
order_limit |
سقف تعداد در هر سفارش. |
status |
وضعیت در دیجی‌کالا: active، approved، pending (منتظر تایید دیجی‌کالا)، draft یا partially_approved. |
source |
منشا تخفیف (جدول بعد). |
منشا تخفیف (source)
| مقدار | معنی |
|---|---|
external |
بیرون از سلر ۳۶۰ ثبت شده است؛ مثلا در پنل دیجی‌کالا. |
manual |
ثبت دستی در سلر ۳۶۰ یا از همین API. |
bot |
ربات قیمت‌گذاری با روش تخفیف هوشمند. |
auto_step |
تخفیف پله‌ای کالای کم‌فروش. |
auto_renew |
تمدید خودکار. |
بازه‌ی قیمت تخفیف
Section titled “بازه‌ی قیمت تخفیف”max(floor, 1100) ≤ price ≤ cap و price مضرب ۱۰۰ ریالمدت تخفیف ۱ تا ۳۰ روز است و سقف تعداد در هر سفارش باید داخل order_limit_min تا order_limit_max باشد.
⚙️ تخفیف پله‌ای و تمدید خودکار
Section titled “⚙️ تخفیف پله‌ای و تمدید خودکار”این دو کار خودکار هر ساعت یک بار برای هر پنل اجرا می‌شوند. هر قیمت خودکار از همان بررسی تخفیف دستی می‌گذرد: هرگز زیر حداقل قیمت و هرگز بالای سقف دیجی‌کالا. تنوعی که ربات با روش تخفیف هوشمند قیمت‌گذاری می‌کند، به ربات تعلق دارد و این دو کار به آن دست نمی‌زنند.
تخفیف پله‌ای کالای کم‌فروش: کالایی که در step_window_days روز گذشته step_max_sales واحد یا کمتر فروخته و دست‌کم step_min_stock موجودی دارد، تخفیف step_pct درصد نسبت به قیمت مرجع می‌گیرد. هر step_every_days روز یک پله (step_pct درصد دیگر) اضافه می‌شود تا step_max_pct. تخفیف هر پله دست‌کم برابر حداقل تخفیف دسته‌ی دیجی‌کالاست و هرگز از حداقل قیمت پایین‌تر نمی‌رود. وقتی کالا دوباره فروش داشته باشد، تخفیف پله‌ای برداشته می‌شود.
تمدید خودکار: تخفیف فعالی که کمتر از renew_before_hours ساعت به پایان آن مانده است، با همان قیمت برای renew_days روز دیگر تمدید می‌شود.
| فیلد | برچسب در پنل | بازه | پیش‌فرض | معنی |
|---|---|---|---|---|
step_enabled |
«تخفیف پله‌ای برای کالای کم‌فروش» | true یا false |
false |
روشن بودن تخفیف پله‌ای. |
step_window_days |
«بازه‌ی بررسی (روز)» | ۳ تا ۹۰ | ۱۴ | بازه‌ی بررسی فروش. |
step_max_sales |
«حد فروش» | ۰ تا ۱۰۰۰ | ۱ | فروش کمتر یا برابر این عدد در بازه یعنی کم‌فروش. |
step_min_stock |
«حداقل موجودی» | ۱ تا ۱۰۰٬۰۰۰ | ۱ | کالای با موجودی کمتر تخفیف پله‌ای نمی‌گیرد. |
step_pct |
«تخفیف هر پله (درصد)» | ۰٫۵ تا ۵۰ | ۳ | درصد تخفیف هر پله نسبت به قیمت مرجع. |
step_every_days |
«فاصله‌ی پله‌ها (روز)» | ۱ تا ۳۰ | ۷ | فاصله‌ی پله‌ها. |
step_max_pct |
«حداکثر تخفیف (درصد)» | ۱ تا ۸۰ | ۲۰ | حداکثر درصد تخفیف پله‌ای؛ نباید از step_pct کمتر باشد. |
renew_enabled |
«تمدید خودکار» | true یا false |
false |
روشن بودن تمدید خودکار. |
renew_before_hours |
«زمان تمدید (ساعت)» | ۱ تا ۱۶۸ | ۲۴ | چند ساعت پیش از پایان تمدید شود. |
renew_days |
«مدت تمدید (روز)» | ۱ تا ۳۰ | ۷ | مدت تمدید. |
last_run_at، last_run_note |
— | فقط خواندنی | — | زمان و خلاصه‌ی آخرین اجرا. |
یک مثال با تنظیمات پیش‌فرض: کالایی که ۱۴ روز فروشی نداشته است، ابتدا ۳ درصد، پس از ۷ روز ۶ درصد و به همین ترتیب تا ۲۰ درصد تخفیف می‌گیرد؛ مگر حداقل قیمت زودتر مانع شود.
🎪 مدل کمپین
Section titled “🎪 مدل کمپین”| فیلد | معنی |
|---|---|
id، title |
شناسه و عنوان کمپین در دیجی‌کالا. |
nature |
نوع کمپین؛ مقادیر شناخته‌شده incredible_offer (شگفت‌انگیز)، mega_promotion (مگاکمپین) و deal_of_the_day (شگفت‌انگیز روز). دیجی‌کالا ممکن است نوع تازه‌ای اضافه کند. |
status |
وضعیت کمپین در دیجی‌کالا. |
start_at، end_at |
شروع و پایان کمپین. |
join_deadline، deadline_passed |
مهلت پیوستن و گذشتن آن. |
conditions |
شرایط کمپین به متن دیجی‌کالا. |
min_discount_pct |
حداقل درصد تخفیف. |
min_qty |
حداقل تعداد کالا در کمپین. |
potential_variants |
تعداد تنوع‌های شما که می‌توانند بپیوندند. |
participants |
تعداد شرکت‌کنندگان. |
joined |
دست‌کم یکی از کالاهای شما در کمپین است. |
commission_discount |
کمپین تخفیف کمیسیون دارد. |
link، synced_at |
پیوند کمپین و زمان خواندن از دیجی‌کالا. |
کالا در کمپین (mine و candidates)
Section titled “کالا در کمپین (mine و candidates)”| فیلد | برچسب در پنل | معنی |
|---|---|---|
promotion_variant_id |
— | شناسه‌ی حضور کالا در کمپین؛ برای خروج لازم است. |
selling_price، promotion_price |
«قیمت فروش»، «قیمت کمپین» | قیمت فروش و قیمت کمپین. |
cap |
— | بیشترین قیمت مجاز در کمپین. |
floor |
«حداقل قیمت شما» | حداقل قیمت شما. |
stock |
— | موجودی. |
state |
— | ok (پیوستن ممکن است)، blocked (سقف قیمت کمپین کمتر از حداقل قیمت شماست) یا no_floor (تنوع حداقل قیمت ندارد). |
status |
— | وضعیت در کمپین (جدول بعد). |
rejection_reason |
— | دلیل رد دیجی‌کالا. |
in_other_incredible |
— | کالا در شگفت‌انگیز دیگری هم هست. |
buy_box_winner |
— | برنده‌ی بای‌باکس است. |
sales_last_week |
— | فروش هفته‌ی گذشته. |
وضعیت کالا (status) |
معنی |
|---|---|
draft |
ثبت‌شده، در انتظار بررسی دیجی‌کالا. |
pending، partially_approved |
در انتظار تایید. |
approved |
تاییدشده. |
rejected، partially_rejected |
ردشده توسط دیجی‌کالا؛ دلیل در rejection_reason. |
active |
فعال. |
ended |
پایان‌یافته. |
💱 قیمت ارزی (خلاصه)
Section titled “💱 قیمت ارزی (خلاصه)”ماژول اختیاری «قیمت ارزی» قیمت فروش را از قیمت خرید ارزی و نرخ روز می‌سازد. هر تنوع یا با ربات قیمت‌گذاری می‌شود یا با استراتژی ارزی، هرگز با هر دو: دادن استراتژی ارزی، استراتژی ربات را برمی‌دارد و ربات تنوع را خاموش می‌کند. قیمت‌های ارزی از همان صف تغییر دستی پنل (پیش از ربات) در دیجی‌کالا ثبت می‌شوند و در تاریخچه‌ی قیمت با منشا fx می‌آیند؛ تغییر دستی قیمت چنین تنوعی خطای price_managed_by_fx می‌دهد (قیمت فروش).
| مفهوم | فیلد | معنی |
|---|---|---|
| ارزهای فعال | currencies |
کد ISO 4217، برچسب، rate_mode (auto نرخ روز، manual نرخ دلخواه شما) و surcharge_pct (درصد افزوده بر نرخ). |
| نرخ امروز | rates |
ریال برای یک واحد ارز، روز، منبع (tgju، priceto، tgju_history یا manual) و زمان نرخ. |
| استراتژی ارزی | strategies |
net_profit_pct (سود خالص هدف به درصد قیمت خرید، پس از کمیسیون، هزینه‌ها و مالیات)، rounding، confirm_above_pct و in_smart_discount. |
گرد کردن (rounding)، همیشه به بالا: r1k تا ۱۰٬۰۰۰ ریال، r10k تا ۱۰۰٬۰۰۰ ریال، r100k تا ۱٬۰۰۰٬۰۰۰ ریال، و nine ختم به ۹۹٬۰۰۰ ریال.
وضعیت تنوع ارزی (status)
| مقدار | معنی |
|---|---|
ok |
قیمت ثبت شده است. |
queued |
قیمت در صف ثبت است. |
confirm |
تغییر از آستانه‌ی تایید (confirm_above_pct) بیشتر است و قیمت تازه (pending_price) منتظر تایید شماست. |
held |
نگه داشته شده است؛ دلیل در status_note، مثلا تنوعی که ربات هم دارد. |
idle |
استراتژی ارزی ندارد. |
🔢 تازگی
Section titled “🔢 تازگی”- تخفیف‌ها: نسخه‌ی محلی هر ساعت از دیجی‌کالا به‌روز می‌شود (
synced_at). ثبت، ویرایش و حذف از API پس از پاسخ دیجی‌کالا برمی‌گردند. - تخفیف پله‌ای و تمدید: هر ساعت یک بار اجرا می‌شوند (
last_run_at). - کمپین‌ها: در لحظه‌ی درخواست از دیجی‌کالا خوانده می‌شوند؛ به همین دلیل ممکن است با
502یا503پاسخ دهند. - پیام‌های رد:
last_errorفقط پیام‌های ۲ روز گذشته را نگه می‌دارد.
⚠️ هشدارها
Section titled “⚠️ هشدارها”📡 مسیرها
Section titled “📡 مسیرها”GET /v1/promotions — تخفیف هوشمند تنوع‌ها فعال
Section titled “GET /v1/promotions — تخفیف هوشمند تنوع‌ها ”هر تنوعی که واجد شرایط تخفیف هوشمند است یا تخفیف فعال دارد.
GET /v1/promotions?active=1&ending_within_hours=48 HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
state |
ok، blocked، no_floor یا bot |
خیر | فقط تنوع‌هایی با این وضعیت. |
active |
0 یا 1 |
خیر | فقط تنوع‌هایی که تخفیف فعال دارند (1) یا ندارند (0). |
source |
یکی از مقادیر منشا | خیر | فقط تخفیف‌هایی با این منشا. |
ending_within_hours |
عدد ۱ تا ۷۲۰ | خیر | فقط تخفیف‌هایی که در این تعداد ساعت آینده تمام می‌شوند. |
page، size |
عدد | خیر | صفحه‌بندی. |
پاسخ نمونه
{ "status": "ok", "data": [ { "variant_id": 84780448, "sku": "PE-5144", "eligible": true, "state": "ok", "reference_price": 24500000, "base_price": 23990000, "customer_price": 23490000, "floor": 21800000, "floor_source": "cost_plus", "cap": 24010000, "cap_pct": 2, "floor_pct": 11, "min_discount_pct": 2, "order_limit_min": 1, "order_limit_max": 1000, "stock": 38, "discount": { "promotion_variant_id": 51820044, "promotion_price": 23490000, "discount_pct": 4, "started_at": "2026-11-09T00:00:00+03:30", "end_at": "2026-11-16T00:00:00+03:30", "limit": 38, "order_limit": 2, "status": "active", "source": "manual" }, "step_level": 0, "last_error": null, "last_error_at": null, "synced_at": "2026-11-12T10:00:00+03:30" } ], "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 12 }}GET /v1/promotions/{variant_id} — تخفیف یک تنوع فعال
Section titled “GET /v1/promotions/{variant_id} — تخفیف یک تنوع ”همان ساختار، برای یک تنوع. اگر تنوع در این پنل نباشد، کد 404 و خطای variant_not_found برمی‌گردد.
PUT /v1/promotions/{variant_id} — ثبت یا ویرایش تخفیف فعال
Section titled “PUT /v1/promotions/{variant_id} — ثبت یا ویرایش تخفیف ”تخفیف را در دیجی‌کالا ثبت یا ویرایش می‌کند و پاسخ را پس از پاسخ دیجی‌کالا برمی‌گرداند. پیش از ارسال همه‌ی قواعد بررسی می‌شود:
- تنوع باید واجد شرایط باشد (
promotion_not_eligible). - ربات نباید با روش تخفیف هوشمند قیمت این تنوع را تعیین کند (
promotion_managed_by_bot). - تنوع باید حداقل قیمت داشته باشد (
promotion_no_floor) و قیمت تخفیف کمتر از آن نباشد (promotion_below_floor). - قیمت مضرب ۱۰۰، بیشتر از ۱٬۰۰۰ ریال و حداکثر برابر
cap؛ مدت ۱ تا ۳۰ روز؛ سقف تعداد در هر سفارش داخل بازه‌ی دیجی‌کالا (promotion_invalid، باdetail).
PUT /v1/promotions/84780448 HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...Idempotency-Key: promo-84780448-1405-08-22Content-Type: application/json
{ "price": 23290000, "days": 7, "order_limit": 2 }| فیلد بدنه | نوع | اجباری | توضیح |
|---|---|---|---|
price |
عدد | بله | قیمت تخفیف به ریال؛ دست‌کم ۱٬۱۰۰، مضرب ۱۰۰، حداکثر برابر cap و دست‌کم برابر حداقل قیمت شما. |
days |
عدد | خیر | مدت تخفیف به روز، ۱ تا ۳۰؛ پیش‌فرض ۷. |
order_limit |
عدد | خیر | سقف تعداد در هر سفارش، داخل order_limit_min تا order_limit_max؛ پیش‌فرض مقدار تخفیف فعلی یا کمترین مقدار مجاز. |
پاسخ نمونه (کد 200)
{ "status": "ok", "data": { "promotion": { "variant_id": 84780448, "eligible": true, "state": "ok", "customer_price": 23290000, "floor": 21800000, "cap": 24010000, "discount": { "promotion_variant_id": 51820044, "promotion_price": 23290000, "discount_pct": 5, "end_at": "2026-11-16T00:00:00+03:30", "order_limit": 2, "status": "active", "source": "manual" }, "synced_at": "2026-11-12T10:21:09+03:30" }, "replaced": false, "warning": null }}خطاهای این مسیر
| کد HTTP | خطا | معنی | تکرار بی‌خطر است؟ |
|---|---|---|---|
400 |
invalid_parameter |
بدنه نامعتبر است. | خیر؛ بدنه را اصلاح کنید. |
403 |
subscription_inactive |
اشتراک فعال نیست. | خیر. |
404 |
variant_not_found |
تنوعی با این شناسه در این پنل نیست. | خیر. |
409 |
promotion_managed_by_bot |
ربات با تخفیف هوشمند این تنوع را قیمت‌گذاری می‌کند. | خیر؛ ابتدا شیوه‌ی اعمال قیمت استراتژی را تغییر دهید. |
409 |
idempotency_mismatch |
این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است. | خیر؛ کلید تازه بسازید. |
409 |
idempotency_in_progress |
درخواستی با همین کلید در حال انجام است. | بله، چند ثانیه بعد. |
422 |
promotion_not_eligible |
دیجی‌کالا تخفیف این تنوع را مجاز نمی‌داند. | خیر. |
422 |
promotion_no_floor |
تنوع حداقل قیمت ندارد. | خیر؛ ابتدا حداقل قیمت تعیین کنید. |
422 |
promotion_below_floor |
قیمت تخفیف کمتر از حداقل قیمت شماست. | خیر؛ قیمت را اصلاح کنید. |
422 |
promotion_invalid |
با قواعد دیجی‌کالا سازگار نیست؛ جزئیات در detail. |
خیر؛ بدنه را اصلاح کنید. |
502 |
digikala_refused |
دیجی‌کالا تخفیف را نپذیرفت؛ پیام دیجی‌کالا در detail. |
پس از بررسی علت. |
503 |
digikala_rate_limited |
سقف درخواست دیجی‌کالا پر است. | بله، پس از Retry-After و با همان Idempotency-Key. |
503 |
digikala_unavailable |
دیجی‌کالا در دسترس نیست. | بله، پس از Retry-After و با همان Idempotency-Key. |
فهرست همه‌ی خطاها در صفحه‌ی خطاها است.
DELETE /v1/promotions/{variant_id} — پایان تخفیف فعال
Section titled “DELETE /v1/promotions/{variant_id} — پایان تخفیف ”تخفیف فعال تنوع را در دیجی‌کالا حذف می‌کند و وضعیت تخفیف پس از حذف را برمی‌گرداند. اگر تنوع تخفیف فعالی نداشته باشد، کد 422 و خطای promotion_not_active برمی‌گردد. خطاهای digikala_refused، digikala_rate_limited و digikala_unavailable همان معنی مسیر ثبت را دارند.
POST /v1/promotions/batch — تخفیف گروهی در صف فاز ۲
Section titled “POST /v1/promotions/batch — تخفیف گروهی در صف ”تا ۱۰۰ تنوع در هر درخواست، یکی از دو شکل:
- با قیمت جداگانه برای هر تنوع (
items)؛ - با یک درصد برای همه (
variant_idsوpct، درصد نسبت به قیمت مرجع، بیشتر از ۰ و کمتر از ۹۰).
هر قلم با همان قواعد تخفیف تکی بررسی می‌شود. با replace_live: false تنوع‌هایی که تخفیف فعال دارند دست نمی‌خورند (پیش‌فرض true). مدت با days (پیش‌فرض ۷). پاسخ 202 با کار promotion_batch؛ نتیجه با GET /v1/jobs/{job_id} و رویداد job.completed (کارهای در صف).
POST /v1/promotions/batch HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...Idempotency-Key: promo-batch-yalda-1405Content-Type: application/json
{ "variant_ids": [84780448, 84780449], "pct": 5, "days": 3, "replace_live": false }GET /v1/promotion-settings و PUT — تخفیف پله‌ای و تمدید خودکار فعال
Section titled “GET /v1/promotion-settings و PUT — تخفیف پله‌ای و تمدید خودکار ”با PUT فقط فیلدهای ارسال‌شده تغییر می‌کنند و دست‌کم یک فیلد لازم است. هر مقدار بیرون از بازه‌ی خود با خطای invalid_parameter رد می‌شود. فقط تنظیمات سلر ۳۶۰ تغییر می‌کند.
PUT /v1/promotion-settings HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...Idempotency-Key: promo-settings-2026-11-12Content-Type: application/json
{ "step_enabled": true, "step_pct": 3, "step_max_pct": 15, "renew_enabled": true }پاسخ نمونه
{ "status": "ok", "data": { "step_enabled": true, "step_window_days": 14, "step_max_sales": 1, "step_pct": 3.0, "step_every_days": 7, "step_max_pct": 15.0, "step_min_stock": 1, "renew_enabled": true, "renew_days": 7, "renew_before_hours": 24, "last_run_at": "2026-11-12T10:00:00+03:30", "last_run_note": "۳ تخفیف تمدید و ۲ پله‌ی تازه ثبت شد." }}GET /v1/campaigns — کمپین‌های باز فعال
Section titled “GET /v1/campaigns — کمپین‌های باز ”کمپین‌هایی که مهلت پیوستن به آن‌ها نگذشته است، نزدیک‌ترین مهلت اول؛ در لحظه از دیجی‌کالا خوانده می‌شود.
{ "status": "ok", "data": [ { "id": 30512, "title": "شگفت‌انگیز آخر هفته", "nature": "incredible_offer", "status": "open", "start_at": "2026-11-20T00:00:00+03:30", "end_at": "2026-11-22T00:00:00+03:30", "join_deadline": "2026-11-17T23:59:00+03:30", "deadline_passed": false, "conditions": ["حداقل ۱۰ درصد تخفیف", "حداقل ۵ عدد کالا"], "min_discount_pct": 10, "min_qty": 5, "potential_variants": 37, "participants": 1240, "joined": false, "commission_discount": true, "link": null, "synced_at": "2026-11-12T10:30:02+03:30" } ]}GET /v1/campaigns/{campaign_id} — یک کمپین فعال
Section titled “GET /v1/campaigns/{campaign_id} — یک کمپین ”شرایط کمپین (campaign)، باز بودن مهلت (open)، کالاهای شما در کمپین (mine) و کالاهایی که می‌توانند بپیوندند (candidates، فقط تا پیش از مهلت). کمپین ناموجود: 404 campaign_not_found.
POST /v1/campaigns/{campaign_id}/join — پیوستن به کمپین فاز ۳
Section titled “POST /v1/campaigns/{campaign_id}/join — پیوستن به کمپین ”تا ۵۰ تنوع در هر درخواست. حداقل قیمت شما در کمپین هم مرز قطعی است: کالای بدون حداقل قیمت نمی‌پیوندد و قیمت پیشنهادی کمتر از حداقل رد می‌شود. پاسخ 202 با کار campaign_join (هشدار ۴).
POST /v1/campaigns/30512/join HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...Idempotency-Key: campaign-30512-join-01Content-Type: application/json
{ "items": [ { "variant_id": 84780448, "price": 21990000, "qty": 10, "order_limit": 2 } ] }| فیلد هر قلم | نوع | اجباری | توضیح |
|---|---|---|---|
variant_id |
عدد | بله | شناسه‌ی تنوع. |
price |
عدد | بله | قیمت پیشنهادی در کمپین به ریال، مضرب ۱۰۰ و حداکثر برابر cap کالا. |
qty |
عدد | بله | تعداد کالا در کمپین؛ دست‌کم برابر min_qty کمپین. |
order_limit |
عدد | خیر | سقف تعداد در هر سفارش. |
| کد HTTP | خطا | معنی | تکرار بی‌خطر است؟ |
|---|---|---|---|
400 |
invalid_parameter |
بدنه نامعتبر است. | خیر؛ بدنه را اصلاح کنید. |
404 |
campaign_not_found |
کمپینی با این شناسه برای این پنل نیست. | خیر. |
422 |
campaign_closed |
مهلت پیوستن گذشته است. | خیر. |
409 |
idempotency_mismatch |
این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است. | خیر؛ کلید تازه بسازید. |
POST /v1/campaigns/{campaign_id}/leave — خروج از کمپین فاز ۳
Section titled “POST /v1/campaigns/{campaign_id}/leave — خروج از کمپین ”بدنه: { "promotion_variant_id": 51820044 }، شناسه‌ی حضور کالا در کمپین از mine در جزئیات کمپین. پاسخ 202 با کار campaign_leave.
GET /v1/fx و GET /v1/fx/variants — قیمت ارزی فعال
Section titled “GET /v1/fx و GET /v1/fx/variants — قیمت ارزی ”GET /v1/fx ارزهای فعال، نرخ امروز و استراتژی‌های ارزی را برمی‌گرداند. GET /v1/fx/variants قیمت‌گذاری ارزی تنوع‌ها را با پارامترهای status و strategy_id فهرست می‌کند.
PUT /v1/fx/variants/{variant_id} و POST .../confirm — تغییر قیمت ارزی فعال
Section titled “PUT /v1/fx/variants/{variant_id} و POST .../confirm — تغییر قیمت ارزی ”PUT با بدنه‌ی { "strategy_id": 7 } استراتژی ارزی تنوع را تعیین می‌کند و strategy_id: null آن را برمی‌دارد (استراتژی ناموجود: 404 fx_strategy_not_found). confirm قیمت منتظر تایید را در صف تغییر دستی می‌گذارد (202، کار fx_confirm)؛ اگر قیمتی منتظر تایید نباشد، 422 fx_no_pending_price.
🔔 رویدادهای وب‌هوک
Section titled “🔔 رویدادهای وب‌هوک”همه‌ی رویدادهای این بخش با دسترسی promotions:read دریافت می‌شوند.
| رویداد | چه وقت |
|---|---|
promotion.ending |
تخفیفی که دستی یا بیرون از سلر ۳۶۰ ثبت شده، کمتر از ۲۴ ساعت دیگر تمام می‌شود و تمدید خودکار خاموش است. تخفیف‌های ربات و تخفیف پله‌ای این رویداد را نمی‌فرستند؛ آن‌ها به‌موقع جایگزین می‌شوند. |
promotion.rejected |
دیجی‌کالا ثبت یا ویرایش تخفیف هوشمند (kind: smart_discount) یا حضور کالا در کمپین (kind: campaign) را رد کرد. تنوع‌هایی که ربات با تخفیف هوشمند قیمت‌گذاری می‌کند این رویداد را نمی‌فرستند؛ ربات خودکار به روش عادی برمی‌گردد. |
promotion.below_floor |
تخفیف فعال یک تنوع کمتر از حداقل قیمت شماست (هشدار ۵). |
نمونه‌ی پیام promotion.rejected
{ "id": "evt_01J0D9KP", "type": "promotion.rejected", "created_at": "2026-11-13T09:12:40+03:30", "panel_id": 1, "livemode": true, "data": { "variant_id": 84780448, "sku": "PE-5144", "kind": "campaign", "campaign_id": 30512, "reason": "قیمت تخفیف از سقف مجاز بیشتر است." }}پیام‌ها ممکن است تکراری یا جابه‌جا برسند (معرفی وب‌هوک). پیش از استفاده از هر پیام، امضای آن را بررسی کنید.
💻 نمونه‌کد: ثبت تخفیف هوشمند
Section titled “💻 نمونه‌کد: ثبت تخفیف هوشمند”curl -X PUT https://api.seller360.ir/v1/promotions/84780448 \ -H "Authorization: Bearer $S360_API_KEY" \ -H "Idempotency-Key: promo-84780448-1405-08-22" \ -H "Content-Type: application/json" \ -d '{"price": 23290000, "days": 7, "order_limit": 2}'$ch = curl_init("https://api.seller360.ir/v1/promotions/84780448");curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("S360_API_KEY"), "Idempotency-Key: promo-84780448-1405-08-22", "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode(["price" => 23290000, "days" => 7, "order_limit" => 2]), CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,]);$res = json_decode(curl_exec($ch), true);if (($res["error"]["code"] ?? null) === "promotion_below_floor") { // قیمت تخفیف کمتر از حداقل قیمت است}import os, requests
res = requests.put( "https://api.seller360.ir/v1/promotions/84780448", headers={ "Authorization": f"Bearer {os.environ['S360_API_KEY']}", "Idempotency-Key": "promo-84780448-1405-08-22", }, json={"price": 23290000, "days": 7, "order_limit": 2}, timeout=30,).json()if res["status"] == "error": print(res["error"]["code"], res["error"].get("detail"))elif res["data"]["warning"]: print(res["data"]["warning"])const res = await fetch('https://api.seller360.ir/v1/promotions/84780448', { method: 'PUT', headers: { Authorization: `Bearer ${process.env.S360_API_KEY}`, 'Idempotency-Key': 'promo-84780448-1405-08-22', 'Content-Type': 'application/json', }, body: JSON.stringify({ price: 23290000, days: 7, order_limit: 2 }),})const body = await res.json()if (body.status === 'error') console.log(body.error.code, body.error.detail)using var http = new HttpClient();var req = new HttpRequestMessage(HttpMethod.Put, "https://api.seller360.ir/v1/promotions/84780448");req.Headers.Add("Authorization", $"Bearer {Environment.GetEnvironmentVariable("S360_API_KEY")}");req.Headers.Add("Idempotency-Key", "promo-84780448-1405-08-22");req.Content = JsonContent.Create(new { price = 23290000, days = 7, order_limit = 2 });var res = await http.SendAsync(req);var body = await res.Content.ReadFromJsonAsync<JsonElement>();