رفتن به محتوا
مستندات API سلر ۳۶۰

ربات قیمت‌گذاری و استراتژی‌ها

مخاطب: برنامه‌نویس یا فروشنده‌ای که می‌خواهد ربات قیمت‌گذاری سلر ۳۶۰ را از نرم‌افزار خود کنترل کند، استراتژی بسازد یا تغییر دهد، تنوع‌ها را به استراتژی متصل کند و سلامت ربات را پایش کند.

📖 مقدمه

Section titled “📖 مقدمه”

ربات قیمت‌گذاری سلر ۳۶۰ قیمت فروش تنوع‌های شما را در دیجی‌کالا بر اساس رقبا و بای‌باکس تنظیم می‌کند. رفتار ربات را استراتژی تعیین می‌کند: مجموعه‌ای از پاسخ‌ها به پرسش‌هایی مانند «با چه کسانی رقابت شود؟»، «وقتی بای‌باکس در اختیار شماست چه شود؟» و «اگر بردن بای‌باکس زیر حداقل قیمت شما باشد چه شود؟». همان فرم «استراتژی‌ها» در پنل، در این API به‌صورت فیلدهای یک شیء JSON در دسترس است.

ربات روی یک تنوع فقط وقتی کار می‌کند که هر سه شرط برقرار باشد:

  1. کلید اصلی ربات پنل روشن باشد (GET /v1/bot و enabled).
  2. ربات همان تنوع روشن باشد (enabled در GET /v1/bot/variants/{variant_id}).
  3. یک استراتژی به تنوع متصل باشد (strategy_id).

با مسیرهای این صفحه می‌توانید:

کار مسیر در دسترس
وضعیت و سلامت ربات GET /v1/bot فعال
روشن یا خاموش کردن کلید اصلی PUT /v1/bot فعال
ربات همه‌ی تنوع‌ها GET /v1/bot/variants فعال
ربات یک تنوع GET /v1/bot/variants/{variant_id} فعال
تغییر ربات یک تنوع PATCH /v1/bot/variants/{variant_id} فعال
فهرست استراتژی‌ها GET /v1/bot/strategies فعال
ساخت استراتژی POST /v1/bot/strategies فعال
خواندن یک استراتژی GET /v1/bot/strategies/{strategy_id} فعال
ویرایش استراتژی PUT /v1/bot/strategies/{strategy_id} فعال
حذف استراتژی DELETE /v1/bot/strategies/{strategy_id} فعال
کپی استراتژی POST /v1/bot/strategies/{strategy_id}/copy فعال
پنهان کردن استراتژی آماده POST /v1/bot/strategies/{strategy_id}/hide فعال
بازگرداندن استراتژی پنهان POST /v1/bot/strategies/{strategy_id}/unhide فعال
اتصال و جدا کردن گروهی تنوع‌ها POST /v1/bot/strategies/{strategy_id}/variants فعال
تغییر گروهی حداقل قیمت POST /v1/bot/floors فعال
سقف‌های اشتراک GET /v1/bot/limits فعال

و با رویدادهای وب‌هوک bot.stalled، bot.writes_failing، bot.rate_limited، bot.variant_stopped و bot.plan_quota_over از هر مشکل ربات خبردار شوید.

⚙️ پیش‌نیازها

Section titled “⚙️ پیش‌نیازها”

دسترسی (Scope)

Section titled “دسترسی (Scope)”
دسترسی برای
bot:read خواندن وضعیت ربات، ربات تنوع‌ها، استراتژی‌ها و سقف‌ها، و دریافت رویدادهای bot.*
bot:write کلید اصلی، ربات تنوع‌ها، ساخت و تغییر استراتژی، اتصال تنوع‌ها و تغییر حداقل قیمت
prices:read پیشنهاد می‌شود: برای خواندن تاریخچه‌ی تصمیم‌های ربات (GET /v1/price-changes?source=bot)

جزئیات ساخت کلید در صفحه‌ی ورود و دسترسی‌ها آمده است.

فعال بودن ماژول

Section titled “فعال بودن ماژول”

ماژول «API و وب‌هوک» باید برای پنل فعال باشد؛ در غیر این صورت همه‌ی مسیرها با کد 403 و خطای module_inactive (ماژول API) یا module_required (ماژول این بخش، با نام آن در detail) پاسخ می‌دهند. برای پنلی که به دیجی‌کالا وصل نیست (panel_unavailable) یا اشتراک فعال ندارد (subscription_inactive)، روشن کردن کلید اصلی ممکن نیست و ربات هیچ قیمتی ثبت نمی‌کند.

آدرس پایه

Section titled “آدرس پایه”
https://api.seller360.ir

🧮 ربات چگونه کار می‌کند

Section titled “🧮 ربات چگونه کار می‌کند”

یک دور ربات

Section titled “یک دور ربات”

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

  1. صف تغییر دستی اول: قیمت‌هایی که از پنل یا از POST /v1/prices/batch در صف هستند، پیش از ربات به دیجی‌کالا فرستاده می‌شوند.
  2. انتخاب تنوع‌ها: تنوع‌هایی که ربات آن‌ها روشن است، استراتژی دارند، داخل سقف اشتراک هستند و نوبت بازبینی آن‌ها رسیده است.
  3. خواندن بازار: فهرست فروشندگان، قیمت و رتبه‌ی هر پیشنهاد و صاحب بای‌باکس از دیجی‌کالا خوانده می‌شود.
  4. کنار گذاشتن رقبا: فهرست سیاه و سفید، سپس دامنه‌ی رقبا، بازه‌ی قیمتی، بازه‌ی زمان ارسال و قیمت‌های نامتعارف (اگر روشن باشد).
  5. محاسبه‌ی قیمت هدف: بر اساس «میزان رقابت بر پایه» و «شیوه‌ی رقابت».
  6. اعمال سناریوها: برنده بودن، تنها فروشنده بودن، کمتر بودن از حداقل قیمت، نبود قیمت مرجع و غیره.
  7. محدود کردن به بازه: قیمت هرگز بیرون از حداقل و حداکثر استراتژی و بیرون از بازه‌ی مجاز دیجی‌کالا (۰٫۵ تا ۱٫۱۴ برابر قیمت مرجع) قرار نمی‌گیرد.
  8. ثبت: اگر قیمت تازه با قیمت فعلی فرق داشته باشد، در دیجی‌کالا نوشته می‌شود و در تاریخچه با منشا bot و دلیل فارسی ثبت می‌شود.

وضعیت ربات هر تنوع (state)

Section titled “وضعیت ربات هر تنوع (state)”
مقدار برچسب در پنل معنی
running «کالاهای روی ربات» ربات روشن است و تنوع را قیمت‌گذاری می‌کند.
stopped «متوقف‌شده» ربات روشن است اما استراتژی آن را متوقف کرده است (دلیل در stop_code)؛ با تغییر شرایط خودکار ادامه می‌دهد.
disabled «خاموش‌شده» استراتژی ربات این تنوع را خاموش کرده است (مثلا در فهرست فروشندگان نیستید).
parked «موقتا کنار گذاشته» دیجی‌کالا ۵ بار پیاپی ثبت قیمت را رد کرد؛ تا write_blocked_until تلاشی نمی‌شود.
over_quota «تنوع‌های خارج از سقف اشتراک» ربات روشن است اما تنوع بیرون از سقف اشتراک است و قیمت‌گذاری نمی‌شود.
no_strategy — استراتژی متصل نیست؛ ربات کاری نمی‌کند.
off «ربات خاموش» ربات این تنوع خاموش است.

دلیل توقف (stop_code)

Section titled “دلیل توقف (stop_code)”
مقدار برچسب در پنل معنی
no_reference_price «دیجی‌کالا برای این محصول قیمت مرجع اعلام نکرده است» بدون قیمت مرجع، بازه‌ی مجاز روشن نیست.
not_in_sellers «فروشگاه شما در فهرست فروشندگان این محصول نیست» پیشنهاد شما در صفحه‌ی کالا دیده نمی‌شود.
floor_above_cap «حداقل قیمت شما از سقف مجاز دیجی‌کالا بالاتر است» و استراتژی گفته است متوقف شود.
floor_unreachable همان و استراتژی گفته است تنوع در دیجی‌کالا غیرفعال شود.
needed_price_below_floor «برای بردن بای‌باکس باید زیر حداقل قیمت شما می‌رفت» و استراتژی گفته است تنوع غیرفعال شود.
alone_in_market «تنها فروشنده‌ی این محصول هستید» و استراتژی گفته است متوقف شود.
no_rivals_after_filters «همه‌ی رقبا با استثناهای استراتژی کنار گذاشته شدند» رقیب وجود دارد اما با استثناهای استراتژی هیچ رقیبی نماند.
we_own_the_box «بای‌باکس در اختیار شماست» و استراتژی گفته است متوقف شود.

توضیح فارسی هر توقف در stop_reason می‌آید.

فیلدهای وضعیت ربات (GET /v1/bot)

Section titled “فیلدهای وضعیت ربات (GET /v1/bot)”
فیلد برچسب در پنل معنی
enabled «کلید ربات» کلید اصلی ربات روشن است.
live — ربات قیمت‌ها را واقعا در دیجی‌کالا ثبت می‌کند؛ false فقط در پنل نمایشی (شبیه‌سازی).
tick_seconds — فاصله‌ی بیدار شدن ربات این پنل به ثانیه (فقط خواندنی).
last_run_at «آخرین اجرا» آخرین اجرای کامل ربات.
last_tick_at — آخرین بررسی ربات.
last_summary — خلاصه‌ی آخرین اجرا: evaluated (بررسی‌شده)، changed (تصمیم تغییر)، applied (ثبت‌شده در دیجی‌کالا)، skipped (بدون استراتژی)، not_due (نوبت نرسیده)، over_quota (بیرون از سقف) و rate_limited.
rate_limited_until — اگر دیجی‌کالا درخواست‌ها را محدود کرده باشد، ربات تا این زمان منتظر می‌ماند.
health.writes_failing «دیجی‌کالا ثبت قیمت را رد می‌کند» در ۳ ساعت گذشته تغییر قیمت تعیین شده اما هیچ‌یک ثبت نشده است.
health.pending_changes — تغییرهای ثبت‌نشده‌ی ۳ ساعت گذشته.
health.last_applied_at — آخرین ثبت موفق قیمت ربات.
counts «کالاهای روی ربات» تنوع‌های موجودی‌دار با ربات روشن: managed، winning (برنده‌ی بای‌باکس)، losing و inactive (غیرفعال در دیجی‌کالا).

فیلدهای ربات هر تنوع

Section titled “فیلدهای ربات هر تنوع”
فیلد برچسب در پنل معنی
enabled «وضعیت ربات» ربات این تنوع روشن است (بدون استراتژی اثری ندارد).
strategy_id، strategy_title «استراتژی‌ها» استراتژی متصل.
state، stop_code، stop_reason «وضعیت ربات»، «علت» جدول‌های بالا.
floor_mode «روش تعیین حداقل قیمت» manual یا cost_plus (بخش حداقل قیمت).
min_price «حداقل قیمت دستی» به ریال.
max_price «حداکثر قیمت» به ریال.
target_profit_pct، target_profit «سود هدف» سود هدف حالت cost_plus، به درصد بهای خرید یا به ریال؛ اگر درصد تعیین شده باشد، درصد ملاک است.
floor «حداقل قیمت شما» حداقلی که ربات اکنون رعایت می‌کند.
floor_source — منشا همان حداقل: manual، cost_plus یا strategy.
base_floor، floor_restore_at — حداقل قیمت پایه و زمان بازگشت خودکار به آن (بخش تغییر گروهی حداقل قیمت).
effective_interval_minutes «سرعت به‌روزرسانی» فاصله‌ی فعلی بازبینی این تنوع به دقیقه، با سرعت تطبیقی و کف سرعت اشتراک.
last_repriced_at — آخرین قیمت‌گذاری.
last_decision «تصمیم تغییر قیمت» آخرین تصمیم: زمان، قیمت تازه، تغییر کرد یا نه، وضعیت ثبت و دلیل.
write_fail_streak، write_blocked_until، write_fail_reason «رد شده» ردهای پیاپی ثبت قیمت توسط دیجی‌کالا و زمان پایان کنار گذاشتن.

🔻 حداقل قیمت

Section titled “🔻 حداقل قیمت”

حداقل قیمت مهم‌ترین محافظ سود شماست. ربات بیشترین مقدار از این سه را رعایت می‌کند و منشا آن را در floor_source اعلام می‌کند:

منشا برچسب در پنل از کجا می‌آید
manual «حداقل قیمت دستی» min_price که خودتان برای تنوع تعیین کرده‌اید.
cost_plus «بهای خرید به‌علاوه‌ی سود» بهای خرید ثبت‌شده به‌علاوه‌ی سود هدف (target_profit_pct یا target_profit)؛ خودکار با تغییر بهای خرید به‌روز می‌شود.
strategy — حداقلی که خود استراتژی می‌سازد؛ مثلا با pricing_basis برابر profit_selling یا rrp_discount.

در حالت cost_plus هم اگر min_price بیشتر باشد، رعایت می‌شود. فرستادن min_price در PATCH /v1/bot/variants/{variant_id} حالت را manual می‌کند، مگر floor_mode را هم بفرستید.

حداقل قیمت فقط برای ربات نیست: تخفیف هوشمند و کمپین‌ها هرگز زیر آن ثبت نمی‌شوند و کالای بدون حداقل قیمت تخفیف نمی‌گیرد.

🧠 استراتژی‌ها

Section titled “🧠 استراتژی‌ها”

شش استراتژی آماده

Section titled “شش استراتژی آماده”

هر پنل شش استراتژی آماده دارد (is_preset: true). استراتژی آماده فقط خواندنی است: می‌توانید آن را ببینید، کپی کنید، پنهان کنید و بازگردانید؛ ولی ویرایش یا حذف نمی‌شود (strategy_locked). برای تغییر آن ابتدا کپی بگیرید. سلر ۳۶۰ تعریف استراتژی‌های آماده را با هر نسخه‌ی تازه به‌روز می‌کند؛ کپی شما دست نمی‌خورد.

کلید (preset_key) عنوان در پنل مناسب برای
seller360 «استراتژی سلر ۳۶۰» (پیشنهادی) رقابت هوشمند برای بای‌باکس؛ قیمت پایه در سقف مجاز و قیمت رقابتی به‌صورت تخفیف هوشمند.
win_box «بردن بای‌باکس (تهاجمی)» دسته‌های پررقابت؛ حاشیه‌ی نیم درصد و سرعت تطبیقی ۵ دقیقه تا یک ساعت.
max_profit «حداکثر سود» محافظت از حاشیه‌ی سود؛ بدون رقابت با فروشندگان زیر حداقل قیمت شما.
defensive «محافظه‌کار (ضد جنگ قیمت)» بازاری که رقبا هم ربات دارند؛ توقف هنگام در اختیار داشتن بای‌باکس.
lowest_price «کمترین قیمت لیست» کالایی که خریدار فقط قیمت را مقایسه می‌کند.
rrp_based «مرجع‌محور (کالای کم‌رقیب)» کالای انحصاری یا کم‌رقیب؛ حداقل و حداکثر از قیمت مرجع.

مقایسه‌ی پاسخ‌های اصلی

گزینه seller360 win_box max_profit defensive lowest_price rrp_based
pricing_basis manual manual manual manual manual rrp_discount (۱۰ درصد)
compete_goal buybox buybox buybox buybox lowest buybox
winner_action continue continue continue stop continue continue
alone_action raise raise raise stop raise raise
raise_rule cap_max cap_rrp cap_max cap_rrp cap_rrp cap_rrp
below_min_action raise set_min set_min set_min set_min set_min
apply_method smart_discount direct direct direct direct direct
rivals_scope all_product all_product all_product same_variant same_variant all_product
price_range all all above_min above_min all all
lead_time_scope all all all mine all all
no_rival_action default_rules default_rules default_rules stop default_rules default_rules
سرعت به‌روزرسانی ۵ دقیقه ۱۵ دقیقه (تطبیقی ۵ دقیقه تا ۱ ساعت) ۳۰ دقیقه ۱ ساعت ۱۵ دقیقه ۶ ساعت
precision exact half exact one exact exact
outlier_detection false true true true true true
kickstart true true false false false false

در همه‌ی استراتژی‌های آماده، rrp_blocked_action و not_in_sellers_action برابر deactivate_local است: تنوع هرگز به‌خاطر این دو وضعیت در دیجی‌کالا خاموش نمی‌شود و فقط قیمت‌گذاری آن در سلر ۳۶۰ متوقف می‌شود. smart_reactivation در همه خاموش است.

مرجع کامل گزینه‌ها

Section titled “مرجع کامل گزینه‌ها”

هر گزینه دقیقا همان پرسش فرم «استراتژی‌ها» در پنل است. گزینه‌ای که هنگام ساخت یا ویرایش نفرستید، مقدار پیش‌فرض را می‌گیرد؛ مقدار پیش‌فرض هر گزینه با نشان ✓ مشخص شده است.

بخش «تنظیمات پایه»

Section titled “بخش «تنظیمات پایه»”
فیلد برچسب در پنل مقدار برچسب مقدار در پنل معنی
title «عنوان» متن ۱ تا ۱۵۰ نویسه — اجباری. نباید با عنوان استراتژی‌های آماده یکی باشد (strategy_title_reserved).
description «توضیحات (اختیاری)» متن — پیش‌فرض خالی.
pricing_basis «نحوه محاسبه حداقل و حداکثر قیمت فروش» manual ✓ «قیمت گذاری دستی» حداقل و حداکثر را برای هر تنوع خودتان وارد می‌کنید (min_price، max_price). ربات هرگز بیرون از این بازه قیمت نمی‌گذارد.
profit_selling «سود بر اساس قیمت فروش» حداقل و حداکثر خودکار از حاشیه‌ی سود خالص (پس از کمیسیون و هزینه‌ها) نسبت به قیمت فروش محاسبه می‌شود.
profit_purchase «سود بر اساس قیمت خرید» همان محاسبه، نسبت به بهای خرید.
rrp_discount «کاهش بر اساس قیمت مرجع یا مصرف کننده» حداقل برابر قیمت مرجع منهای max_discount و حداکثر برابر خود قیمت مرجع.
min_margin_value و min_margin_unit «حداقل حاشیه سود (خالص)» عدد، و percent ✓ یا rial «درصد»، «ریال» فقط برای profit_selling و profit_purchase.
max_margin_value و max_margin_unit «حداکثر حاشیه سود (خالص)» عدد، و percent ✓ یا rial «درصد»، «ریال» فقط برای profit_selling و profit_purchase.
max_discount_value و max_discount_unit «حداکثر کاهش» عدد، و percent ✓ یا rial «درصد»، «ریال» فقط برای rrp_discount.
compete_basis «میزان رقابت بر پایه» smart ✓ «هوشمند» پیشنهادی. با فرمول رتبه‌ی بای‌باکس دیجی‌کالا قیمت لازم برای بردن بای‌باکس محاسبه می‌شود، نه یک ریال ارزان‌تر از رقیب. compete_value نادیده گرفته می‌شود.
rial «ریال» همیشه compete_value ریال پایین‌تر از رقیب صاحب بای‌باکس.
percent «درصد» همیشه compete_value درصد پایین‌تر از رقیب صاحب بای‌باکس.
compete_value «رقابت به میزان» عدد — فقط برای rial و percent.

بخش «سناریو»

Section titled “بخش «سناریو»”
فیلد برچسب در پنل مقدار برچسب مقدار در پنل معنی
compete_goal «شیوه‌ی رقابت» buybox ✓ «در اختیار گرفتن بای‌باکس» پیشنهادی.
lowest «داشتن کمترین قیمت در فهرست فروشندگان» ارزان‌ترین فروشنده بودن، نه لزوما برنده‌ی بای‌باکس.
highest_rank «داشتن بالاترین جایگاه در فهرست فروشندگان» مانند buybox رفتار می‌کند.
winner_action «رفتار در صورت در اختیار داشتن بای‌باکس» continue ✓ «ادامه‌ی استراتژی قیمت‌گذاری» قیمت تا مرز حفظ بای‌باکس افزایش می‌یابد تا بیشترین سود به دست آید.
stop «توقف استراتژی قیمت‌گذاری» تا وقتی بای‌باکس در اختیار شماست، قیمت تغییر نمی‌کند.
alone_action «رفتار در صورت تنها فروشنده بودن» raise ✓ «افزایش قیمت فروش طبق استراتژی» تا سقفی که raise_rule تعیین می‌کند.
set_min «قرار دادن حداقل قیمت به‌عنوان قیمت فروش»
stop «توقف استراتژی قیمت‌گذاری» قیمت تغییر نمی‌کند.
raise_rule «شیوه‌ی افزایش قیمت» cap_rrp ✓ «محدود کردن افزایش قیمت به قیمت مرجع»
cap_max «محدود کردن افزایش قیمت به حداکثر قیمت»
set_lowest «قرار دادن کمترین قیمت به‌عنوان قیمت فروش» کمترین قیمت رقبا قیمت فروش می‌شود.
rrp_min «قیمت‌گذاری بر اساس کمترین قیمت مجاز مرجع انجام شود» بر پایه‌ی کمترین قیمت مجاز مرجع دیجی‌کالا.
below_min_action «رفتار در صورت پایین‌تر بودن قیمت محاسبه‌شده از حداقل قیمت» raise ✓ «افزایش قیمت فروش طبق استراتژی» چون بردن بای‌باکس سودآور نیست، قیمت تا سقف بالا می‌رود.
set_min «قرار دادن حداقل قیمت به‌عنوان قیمت فروش»
deactivate_channel «غیرفعال کردن تنوع در کانال فروش» تنوع در دیجی‌کالا غیرفعال می‌شود.
ignore_min «قیمت‌گذاری بدون در نظر گرفتن حداقل قیمت» می‌تواند زیان مالی ایجاد کند (هشدار ۴).
floor_unreachable_action «رفتار در صورت ممکن نبودن رسیدن به حداقل قیمت» ceiling ✓ «فروش با بالاترین قیمت مجاز دیجی‌کالا» وقتی حداقل قیمت از ۱٫۱۴ برابر قیمت مرجع بالاتر است؛ فروش با سقف مجاز، که همچنان کمتر از حداقل شماست.
deactivate_channel «غیرفعال کردن تنوع در کانال فروش» تا زیر حداقل قیمت فروخته نشود.
stop «توقف استراتژی بدون تغییر قیمت»
after_deactivate_action «رفتار پس از غیرفعال شدن تنوع به‌خاطر حداقل قیمت» stay ✓ «غیرفعال بماند» تا خودتان آن را فعال کنید. فقط برای تنوع‌هایی که خود ربات غیرفعال کرده است.
reactivate «فعال‌سازی دوباره هر زمان فروش بالای حداقل قیمت ممکن شد» وقتی حداقل زیر سقف مجاز باشد و هیچ رقیبی ارزان‌تر نباشد.
smart_reactivation «فعال‌سازی هوشمند تنوع» off ✓ «خاموش» نیازمند ماژول مربوط؛ بدون ماژول همیشه off ذخیره می‌شود.
price «فقط تنوع‌های غیرفعال‌شده به دلیل قیمت» تنوعی که دیجی‌کالا خودش غیرفعال کرده است، با قیمتی برابر کمترین مقدار از بالاترین قیمت مجاز و سقف استراتژی دوباره فعال می‌شود.
price_delay «تنوع‌های غیرفعال‌شده به دلیل قیمت، تاخیر ارسال یا لغو سفارش»
rrp_blocked_action «رفتار در نبود قیمت مرجع» deactivate_local ✓ «غیرفعال کردن تنوع در سلر ۳۶۰» امن‌تر؛ فقط قیمت‌گذاری در سلر ۳۶۰ متوقف می‌شود.
deactivate_channel «غیرفعال کردن تنوع در کانال فروش» تنوع در دیجی‌کالا غیرفعال می‌شود.
apply_method «شیوه‌ی اعمال قیمت» direct ✓ «تغییر قیمت فروش (روش عادی)»
smart_discount «قیمت پایه در سقف مجاز و رقابت با تخفیف هوشمند» قیمت پایه در سقف مجاز دیجی‌کالا قرار می‌گیرد و قیمت رقابتی به‌صورت تخفیف هوشمند ثبت می‌شود (هشدار ۵).
discount_when «تخفیف هوشمند روی چه کالاهایی ثبت شود؟» always ✓ «روی همه‌ی کالاها» فقط با apply_method: smart_discount.
alone_product «فقط وقتی هیچ فروشنده‌ی دیگری روی کل کالا (DKP) نیست»
alone_variant «فقط وقتی هیچ فروشنده‌ی دیگری روی همین تنوع (DKPC) نیست»
smart_discount_mode «رفتار در صورت قرار داشتن کالا در تخفیف هوشمند» without_discount ✓ «ادامه‌ی استراتژی بر اساس قیمت فروش بدون تخفیف» برای تخفیفی که خودتان یا کمپین گذاشته است؛ با apply_method: smart_discount اثری ندارد.
with_discount «ادامه‌ی استراتژی بر اساس قیمت فروش با تخفیف» رقابت بر پایه‌ی قیمت پس از تخفیف، همان قیمتی که بای‌باکس با آن تعیین می‌شود.
not_in_sellers_action «رفتار در صورت نبودن در فهرست فروشندگان» deactivate_local ✓ «غیرفعال کردن تنوع در سلر ۳۶۰»
continue «ادامه‌ی استراتژی قیمت‌گذاری» رقابت با رقبای قابل مشاهده، محدود به بازه‌ی مرجع.

بخش «استثناها»

Section titled “بخش «استثناها»”
فیلد برچسب در پنل مقدار برچسب مقدار در پنل معنی
rivals_scope «دامنه‌ی رقبا» same_variant ✓ «فقط فروشندگان تنوع کالایی» بای‌باکس برای هر تنوع (رنگ) جداگانه است.
all_product «تمام فروشندگان محصول» همه‌ی فروشندگان کالا، با همه‌ی تنوع‌ها.
price_range «بازه‌ی قیمتی رقابت» all ✓ «رقابت با همه‌ی فروشندگان در هر بازه‌ی قیمتی»
above_min «رقابت فقط با فروشندگانی که قیمت فروششان از حداقل قیمت شما بالاتر است» جلوگیری از جنگ قیمت زیان‌ده.
lead_time_scope «بازه‌ی زمان ارسال برای رقابت» all ✓ «رقابت با همه‌ی فروشندگان در هر بازه‌ی زمانی ارسال»
mine «رقابت فقط با فروشندگانی که در بازه‌ی زمانی ارسال شما هستند» فروشندگان سریع‌تر، مانند انبار دیجی‌کالا، کنار گذاشته می‌شوند.
seller_blacklist «فروشندگانی که با آن‌ها رقابت نمی‌شود» فهرست شناسه، حداکثر ۲۰۰ — پیش‌فرض خالی. پیش از همه‌ی استثناهای دیگر اعمال می‌شود.
seller_whitelist «فروشندگانی که با آن‌ها رقابت می‌شود» فهرست شناسه، حداکثر ۲۰۰ — اگر خالی نباشد، فقط با این فروشندگان رقابت می‌شود.
no_rival_action «رفتار در نبود رقیب طبق استراتژی» default_rules ✓ «استفاده از استراتژی پیش‌فرض برای قیمت‌گذاری» استثناها نادیده گرفته می‌شوند.
set_min «قرار دادن حداقل قیمت به‌عنوان قیمت فروش»
stop «توقف استراتژی قیمت‌گذاری»

شناسه‌ی فروشندگان را از فهرست رقبا (rival_seller_id) بردارید.

بخش «تنظیمات پیشرفته»

Section titled “بخش «تنظیمات پیشرفته»”
فیلد برچسب در پنل مقدار برچسب مقدار در پنل معنی
interval_value و interval_unit «سرعت به‌روزرسانی» عدد (پیش‌فرض ۱) و واحد (پیش‌فرض hour) — هر چند وقت یک‌بار قیمت تنوع‌ها بازبینی شود. کمتر از ۵ دقیقه روی ۵ دقیقه ذخیره می‌شود و کف سرعت اشتراک هم اعمال می‌شود.
speed_min_value و speed_min_unit «مجاز به کاهش سرعت تا» عدد یا null، واحد (پیش‌فرض hour) — سرعت تطبیقی: کندترین فاصله در بازار آرام.
speed_max_value و speed_max_unit «مجاز به افزایش سرعت تا» عدد یا null، واحد (پیش‌فرض minute) — سریع‌ترین فاصله در بازار پرتحرک؛ حداقل ۵ دقیقه. این دو با هم فعال می‌شوند.
outlier_detection «الگوریتم شناسایی قیمت‌گذاری نامتعارف» false ✓ یا true — قیمت‌های غیرعادی رقبا کنار گذاشته می‌شوند.
calc_algorithm «نوع الگوریتم محاسبه قیمت» main_params ✓ «پارامترهای اصلی» فرمول رتبه‌ی بای‌باکس با قیمت، سرعت ارسال و امتیاز فروشنده.
precision «دقت در محاسبه پارامترهای اصلی» exact ✓ «دقیق» فقط با compete_basis: smart.
half «با حاشیه 0.5± درصد» حاشیه‌ی امنیت بیشتر زیر قیمت محاسبه‌شده.
one «با حاشیه 1± درصد» محتاط‌ترین.
kickstart «قیمت‌گذاری ضربتی؟» false ✓ یا true — پس از ذخیره، همه‌ی تنوع‌های متصل بدون انتظار برای نوبت در اولین دور قیمت‌گذاری می‌شوند.

واحدهای زمان (interval_unit و مانند آن): minute دقیقه، hour ساعت، day روز، week هفته، month ماه (۳۰ روز).

بخش «تنظیمات زمان‌بندی»

Section titled “بخش «تنظیمات زمان‌بندی»”
فیلد برچسب در پنل مقدار معنی
active_from_hour «ساعت فعال بودن» (شروع) ۰ تا ۲۴، پیش‌فرض ۰ ساعت شروع فعالیت به وقت تهران.
active_to_hour «ساعت فعال بودن» (پایان) ۰ تا ۲۴، پیش‌فرض ۲۴ ساعت پایان فعالیت. ۰ تا ۲۴ یعنی شبانه‌روزی؛ بازه‌ی معکوس، مثلا ۲۲ تا ۶، هم پذیرفته است.

فیلدهای فقط خواندنی استراتژی

Section titled “فیلدهای فقط خواندنی استراتژی”
فیلد معنی
id شناسه‌ی استراتژی.
is_preset، preset_key استراتژی آماده است و کلید آن.
recommended استراتژی پیشنهادی سلر ۳۶۰.
hidden استراتژی آماده‌ی پنهان‌شده.
editable قابل ویرایش و حذف است؛ برای استراتژی آماده false.
variant_count، bot_on_count تنوع‌های متصل و از میان آن‌ها تنوع‌هایی که ربات روشن دارند.
created_at، updated_at زمان ساخت و آخرین تغییر.

📏 سقف‌های اشتراک

Section titled “📏 سقف‌های اشتراک”
فیلد برچسب در پنل معنی
variant_cap «سقف تنوع» حداکثر تنوع‌هایی که ربات روی آن‌ها کار می‌کند؛ خالی یعنی بدون سقف.
speed_floor_minutes «سرعت به‌روزرسانی» سریع‌ترین فاصله‌ی بازبینی مجاز اشتراک؛ خالی یعنی بدون کف.
min_interval_minutes — همیشه ۵: کمترین فاصله‌ی بازبینی در هر حال.
bot_on_count — تنوع‌هایی که اکنون ربات روشن و استراتژی دارند.
over_quota «تنوع‌های خارج از سقف اشتراک» تنوع‌های بیرون از سقف که قیمت‌گذاری نمی‌شوند.

فاصله‌ی واقعی بازبینی هر تنوع، کندترین مقدار از سرعت استراتژی و کف سرعت اشتراک است و هرگز کمتر از ۵ دقیقه نمی‌شود. دلیل این کف: قیمت ثبت‌شده حدود ۲ دقیقه بعد در صفحه‌ی عمومی دیجی‌کالا دیده می‌شود و بازبینی سریع‌تر، ربات را به واکنش به قیمت‌های کهنه وامی‌دارد.

🔢 تازگی

Section titled “🔢 تازگی”
  • وضعیت ربات و ربات تنوع‌ها: با هر دور ربات به‌روز می‌شوند؛ زمان‌ها در last_tick_at، last_run_at و last_repriced_at است.
  • سلامت: health بر پایه‌ی ۳ ساعت گذشته محاسبه می‌شود.
  • تغییر تنظیمات: تغییر ربات تنوع، استراتژی یا حداقل قیمت فقط تنظیمات سلر ۳۶۰ را عوض می‌کند و همان لحظه چیزی در دیجی‌کالا ثبت نمی‌شود؛ قیمت‌ها در دورهای بعدی ربات تغییر می‌کنند. با روشن کردن ربات یا اتصال استراتژی، تنوع در نوبت بعدی زمان‌بند بررسی می‌شود.

⚠️ هشدارها

Section titled “⚠️ هشدارها”

📡 مسیرها

Section titled “📡 مسیرها”

GET /v1/bot — وضعیت و سلامت ربات فعال

Section titled “GET /v1/bot — وضعیت و سلامت ربات ”
GET /v1/bot HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...

پاسخ نمونه

{
  "status": "ok",
  "data": {
    "enabled": true,
    "live": true,
    "tick_seconds": 30,
    "last_run_at": "2026-11-12T10:14:30+03:30",
    "last_tick_at": "2026-11-12T10:15:00+03:30",
    "last_summary": {
      "evaluated": 157, "changed": 12, "applied": 12,
      "skipped": 0, "not_due": 120, "over_quota": 0, "rate_limited": false
    },
    "rate_limited_until": null,
    "health": { "writes_failing": false, "pending_changes": 0, "last_applied_at": "2026-11-12T10:14:31+03:30" },
    "counts": { "managed": 157, "winning": 121, "losing": 30, "inactive": 6 }
  }
}

PUT /v1/bot — کلید اصلی ربات فعال

Section titled “PUT /v1/bot — کلید اصلی ربات ”

کلید اصلی را روشن یا خاموش می‌کند. خاموش کردن کلید اصلی تنظیمات تنوع‌ها را تغییر نمی‌دهد. پاسخ، همان ساختار GET /v1/bot است.

PUT /v1/bot HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: bot-on-1405-08-22
Content-Type: application/json


{ "enabled": true }
کد HTTP خطا معنی تکرار بی‌خطر است؟
400 invalid_parameter بدنه نامعتبر است. خیر؛ بدنه را اصلاح کنید.
403 panel_unavailable پنل به دیجی‌کالا وصل نیست. خیر؛ اتصال را بررسی کنید.
403 subscription_inactive اشتراک فعال نیست. خیر.

GET /v1/bot/variants — ربات همه‌ی تنوع‌ها فعال

Section titled “GET /v1/bot/variants — ربات همه‌ی تنوع‌ها ”

تنظیمات ربات هر تنوعی که ردیف تنظیمات ربات دارد.

پارامتر نوع اجباری توضیح
state یکی از مقادیر state خیر فقط تنوع‌هایی با این وضعیت.
strategy_id عدد خیر فقط تنوع‌های متصل به این استراتژی.
stop_code یکی از مقادیر stop_code خیر فقط تنوع‌هایی که با این دلیل متوقف شده‌اند.
page، size عدد خیر صفحه‌بندی.

پاسخ نمونه

{
  "status": "ok",
  "data": [
    {
      "variant_id": 84780448,
      "sku": "PE-5144",
      "enabled": true,
      "strategy_id": 412,
      "strategy_title": "بای‌باکس با حاشیه‌ی امن",
      "state": "running",
      "stop_code": null,
      "stop_reason": null,
      "floor_mode": "cost_plus",
      "min_price": 21000000,
      "max_price": 27500000,
      "target_profit_pct": 12.0,
      "target_profit": null,
      "floor": 21800000,
      "floor_source": "cost_plus",
      "base_floor": null,
      "floor_restore_at": null,
      "effective_interval_minutes": 15,
      "last_repriced_at": "2026-11-12T09:40:12+03:30",
      "last_decision": {
        "at": "2026-11-12T09:40:12+03:30",
        "new_price": 23990000,
        "changed": true,
        "status": "applied",
        "reason": "بای‌باکس در اختیار رقیب است → کاهش تا قیمت بردن"
      },
      "write_fail_streak": 0,
      "write_blocked_until": null,
      "write_fail_reason": null
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 4, "total_rows": 157 }
}

GET /v1/bot/variants/{variant_id} — ربات یک تنوع فعال

Section titled “GET /v1/bot/variants/{variant_id} — ربات یک تنوع ”

همان ساختار، برای یک تنوع. برای تنوعی که هنوز ردیف تنظیمات ربات ندارد، مقادیر پیش‌فرض با enabled: false برمی‌گردد.

PATCH /v1/bot/variants/{variant_id} — تغییر ربات یک تنوع فعال

Section titled “PATCH /v1/bot/variants/{variant_id} — تغییر ربات یک تنوع ”

فقط فیلدهای ارسال‌شده تغییر می‌کنند و دست‌کم یک فیلد لازم است.

PATCH /v1/bot/variants/84780448 HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: bot-84780448-attach-412
Content-Type: application/json


{ "strategy_id": 412, "min_price": 21800000, "max_price": 27500000, "enabled": true }
فیلد بدنه نوع توضیح
enabled true یا false روشن یا خاموش کردن ربات همین تنوع. روشن کردن بدون استراتژی متصل رد می‌شود.
strategy_id عدد یا null استراتژی متصل. null استراتژی را جدا و ربات تنوع را خاموش می‌کند. استراتژی پنهان قابل اتصال نیست.
floor_mode manual یا cost_plus روش تعیین حداقل قیمت.
min_price عدد یا null حداقل قیمت دستی به ریال، دست‌کم ۱۰۰. فرستادن عدد، floor_mode را manual می‌کند مگر floor_mode را هم بفرستید.
max_price عدد یا null حداکثر قیمت به ریال، دست‌کم ۱۰۰.
target_profit_pct عدد یا null سود هدف حالت cost_plus به درصد بهای خرید؛ ۰ تا ۱۰۰۰.

پاسخ موفق: کد 200 با ساختار کامل ربات تنوع.

خطاهای این مسیر

کد HTTP خطا معنی تکرار بی‌خطر است؟
400 invalid_parameter بدنه خالی یا نامعتبر است. خیر؛ بدنه را اصلاح کنید.
404 variant_not_found تنوعی با این شناسه در این پنل نیست. خیر.
404 strategy_not_found استراتژی‌ای با این شناسه در این پنل نیست. خیر.
409 bot_strategy_required برای روشن کردن ربات ابتدا یک استراتژی متصل کنید. با strategy_id در همان بدنه و کلید یکتای تازه.
409 bot_quota_full سقف تنوع اشتراک پر است؛ هیچ تغییری انجام نشد. خیر؛ سقف را با GET /v1/bot/limits ببینید.
409 strategy_hidden استراتژی پنهان است. پس از بازگرداندن استراتژی.
409 idempotency_mismatch این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است. خیر؛ کلید تازه بسازید.
409 idempotency_in_progress درخواستی با همین کلید در حال انجام است. بله، چند ثانیه بعد.

GET /v1/bot/strategies — فهرست استراتژی‌ها فعال

Section titled “GET /v1/bot/strategies — فهرست استراتژی‌ها ”

استراتژی‌های پنل، آخرین تغییر اول، شامل شش استراتژی آماده.

پارامتر نوع اجباری توضیح
include_hidden 0 یا 1 خیر پیش‌فرض 0. با 1 استراتژی‌های آماده‌ی پنهان‌شده هم برمی‌گردند.
preset 0 یا 1 خیر فقط استراتژی‌های آماده (1) یا فقط استراتژی‌های خودتان (0).
page، size عدد خیر صفحه‌بندی.

POST /v1/bot/strategies — ساخت استراتژی فعال

Section titled “POST /v1/bot/strategies — ساخت استراتژی ”

بدنه همان گزینه‌های بخش «مرجع کامل گزینه‌ها» است؛ فقط title اجباری است. پاسخ موفق: کد 201 با استراتژی کامل.

POST /v1/bot/strategies HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: strategy-create-safe-buybox
Content-Type: application/json


{
  "title": "بای‌باکس با حاشیه‌ی امن",
  "description": "برای کالاهای پررقابت.",
  "pricing_basis": "manual",
  "compete_basis": "smart",
  "compete_goal": "buybox",
  "winner_action": "continue",
  "alone_action": "raise",
  "raise_rule": "cap_max",
  "below_min_action": "set_min",
  "rivals_scope": "same_variant",
  "price_range": "above_min",
  "seller_blacklist": [1083422],
  "interval_value": 15,
  "interval_unit": "minute",
  "precision": "half",
  "outlier_detection": true
}

پاسخ نمونه (کد 201، کوتاه‌شده)

{
  "status": "ok",
  "data": {
    "id": 412,
    "title": "بای‌باکس با حاشیه‌ی امن",
    "is_preset": false,
    "preset_key": null,
    "recommended": false,
    "hidden": false,
    "editable": true,
    "variant_count": 0,
    "bot_on_count": 0,
    "pricing_basis": "manual",
    "compete_basis": "smart",
    "below_min_action": "set_min",
    "floor_unreachable_action": "ceiling",
    "interval_value": 15,
    "interval_unit": "minute",
    "smart_reactivation": "off",
    "active_from_hour": 0,
    "active_to_hour": 24,
    "created_at": "2026-11-12T10:20:00+03:30",
    "updated_at": "2026-11-12T10:20:00+03:30"
  }
}

GET /v1/bot/strategies/{strategy_id} — یک استراتژی فعال

Section titled “GET /v1/bot/strategies/{strategy_id} — یک استراتژی ”

استراتژی با همه‌ی گزینه‌ها. اگر استراتژی در این پنل نباشد، کد 404 و خطای strategy_not_found برمی‌گردد.

PUT /v1/bot/strategies/{strategy_id} — ویرایش استراتژی فعال

Section titled “PUT /v1/bot/strategies/{strategy_id} — ویرایش استراتژی ”

همه‌ی گزینه‌ها جایگزین می‌شوند (هشدار ۸). با kickstart: true همه‌ی تنوع‌های متصل در نوبت بعدی زمان‌بند بدون انتظار قیمت‌گذاری می‌شوند.

DELETE /v1/bot/strategies/{strategy_id} — حذف استراتژی فعال

Section titled “DELETE /v1/bot/strategies/{strategy_id} — حذف استراتژی ”

همه‌ی تنوع‌های متصل جدا می‌شوند و ربات آن‌ها خاموش می‌شود. پاسخ: { "detached": 14 }، تعداد تنوع‌های جداشده.

POST /v1/bot/strategies/{strategy_id}/copy — کپی فعال

Section titled “POST /v1/bot/strategies/{strategy_id}/copy — کپی ”

یک استراتژی تازه با همه‌ی گزینه‌ها و عنوان «(کپی)» می‌سازد (کد 201). کپی یک استراتژی آماده، استراتژی خود شماست و قابل ویرایش و حذف است. هیچ تنوعی به کپی متصل نمی‌شود.

POST /v1/bot/strategies/{strategy_id}/hide و /unhide — پنهان کردن و بازگرداندن فعال

Section titled “POST /v1/bot/strategies/{strategy_id}/hide و /unhide — پنهان کردن و بازگرداندن ”

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

خطاهای مسیرهای تغییر استراتژی

کد HTTP خطا معنی تکرار بی‌خطر است؟
400 invalid_parameter گزینه‌ای بیرون از مقادیر مجاز، یا پنهان کردن استراتژی غیرآماده. خیر؛ بدنه را اصلاح کنید.
404 strategy_not_found استراتژی‌ای با این شناسه در این پنل نیست. خیر.
409 strategy_locked استراتژی آماده ویرایش یا حذف نمی‌شود. خیر؛ کپی بگیرید.
409 idempotency_mismatch این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است. خیر؛ کلید تازه بسازید.
422 strategy_title_reserved عنوان مخصوص یکی از استراتژی‌های آماده است. خیر؛ عنوان دیگری انتخاب کنید.

POST /v1/bot/strategies/{strategy_id}/variants — اتصال و جدا کردن گروهی فعال

Section titled “POST /v1/bot/strategies/{strategy_id}/variants — اتصال و جدا کردن گروهی ”

تا ۵۰۰ شناسه در هر فهرست.

  • اتصال، روشن بودن ربات تنوع را تغییر نمی‌دهد؛ اما اگر ربات تنوعی روشن باشد، با اتصال شروع به کار می‌کند و در سقف اشتراک شمرده می‌شود.
  • اگر تنوع‌هایی که با این درخواست فعال می‌شوند در سقف جا نشوند، کل درخواست رد می‌شود (bot_quota_full).
  • جدا کردن، ربات تنوع را خاموش می‌کند. اتصال به استراتژی پنهان رد می‌شود (strategy_hidden). اتصال، استراتژی ارزی همان تنوع‌ها را برمی‌دارد.
POST /v1/bot/strategies/412/variants HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: strategy-412-attach-2026-11-12
Content-Type: application/json


{ "attach": [84780448, 84780449], "detach": [71200512] }

پاسخ نمونه

{ "status": "ok", "data": { "variant_count": 42, "not_found": [] } }

not_found شناسه‌هایی است که در این پنل یافت نشدند و نادیده گرفته شدند.

POST /v1/bot/floors — تغییر گروهی حداقل قیمت فعال

Section titled “POST /v1/bot/floors — تغییر گروهی حداقل قیمت ”

همان ابزار «روش تغییر حداقل قیمت» در صفحه‌ی وضعیت بای‌باکس پنل. حداقلی که اینجا تغییر می‌کند همان حداقلی است که ربات رعایت می‌کند.

  1. ابتدا با apply: false (پیش‌فرض) پیش‌نمایش بگیرید؛ چیزی ذخیره نمی‌شود.
  2. ردیف‌های ok: false را با note بررسی کنید.
  3. همان درخواست را با apply: true و کلید یکتای تازه بفرستید؛ فقط ردیف‌های ok ذخیره می‌شوند.
فیلد بدنه نوع اجباری توضیح
variant_ids فهرست عدد بله ۱ تا ۱۰۰۰ تنوع.
action متن بله یکی از روش‌های جدول زیر.
value عدد برای pct و profit_pts بیشتر از ۰ و حداکثر ۹۰.
margin عدد خیر فقط to_win؛ فاصله‌ی اطمینان زیر قیمت بردن به درصد، ۰ تا ۲۰، پیش‌فرض ۱.
price عدد برای set حداقل قیمت تازه به ریال.
days 0، 1، 3، 7 یا 14 خیر پس از چند روز حداقل خودکار به پایه برگردد (فقط pct، to_win و profit_pts)؛ پیش‌فرض 0 یعنی برنمی‌گردد.
allow_loss true یا false خیر پیش‌فرض false. حداقل زیر نقطه‌ی سربه‌سر هم مجاز باشد.
apply true یا false خیر پیش‌فرض false: فقط پیش‌نمایش.
روش (action) برچسب در پنل معنی
pct «کاهش درصدی» حداقل قیمت value درصد کاهش یابد.
to_win «تا قیمت بردن» حداقل قیمت margin درصد زیر قیمت تخمینی بردن بای‌باکس قرار گیرد؛ فقط اگر از حداقل فعلی کمتر باشد.
profit_pts «کاهش درصد سود هدف» سود هدف value واحد درصد کاهش یابد؛ فقط حالت cost_plus با سود هدف درصدی.
set — حداقل قیمت برابر price شود.
restore — بازگشت به حداقل قیمت پایه.

قواعد:

  • روش هر کالا حفظ می‌شود: در حالت دستی حداقل قیمت ریالی تغییر می‌کند؛ در حالت cost_plus درصد سود هدف طوری دوباره محاسبه می‌شود که حداقل روی قیمت تازه بنشیند.
  • حداقل تازه به پایین و به مضرب ۱۰۰ ریال گرد می‌شود.
  • هیچ حداقلی زیر نقطه‌ی سربه‌سر (سود خالص صفر) نمی‌رود، مگر با allow_loss: true.
  • پیش از اولین کاهش، حداقل فعلی به‌عنوان «حداقل قیمت پایه» (base_floor) نگه داشته می‌شود و با days یا action: restore به آن برمی‌گردد.
  • هر اعمال تا ۲۴ ساعت در «بازگردانی» پنل قابل برگرداندن است (undo_expires_at).
POST /v1/bot/floors HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: floors-preview-2026-11-12-01
Content-Type: application/json


{ "variant_ids": [84780448, 84780449], "action": "pct", "value": 5, "days": 7, "apply": false }

پاسخ نمونه (پیش‌نمایش)

{
  "status": "ok",
  "data": {
    "applied": false,
    "done": 1,
    "undo_expires_at": null,
    "rows": [
      {
        "variant_id": 84780448,
        "mode": "cost_plus",
        "old_floor": 21800000,
        "new_floor": 20710000,
        "old_target_profit_pct": 12.0,
        "new_target_profit_pct": 6.4,
        "profit_pct": 3.9,
        "breakeven": { "value": 19900000, "estimated": true },
        "ok": true,
        "loss": false
      },
      {
        "variant_id": 84780449,
        "mode": "manual",
        "old_floor": 20500000,
        "new_floor": null,
        "breakeven": { "value": 20100000, "estimated": true },
        "ok": false,
        "loss": false,
        "note": "حداقل تازه زیر نقطه‌ی سربه‌سر است."
      }
    ]
  }
}

breakeven تخمین سلر ۳۶۰ است (estimated: true)، نه عددی که دیجی‌کالا اعلام کرده باشد.

کد HTTP خطا معنی تکرار بی‌خطر است؟
400 invalid_parameter مثلا value برای pct فرستاده نشده است. خیر؛ بدنه را اصلاح کنید.
409 idempotency_mismatch این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است؛ برای اعمال پس از پیش‌نمایش کلید تازه بسازید. خیر.

GET /v1/bot/limits — سقف‌های اشتراک فعال

Section titled “GET /v1/bot/limits — سقف‌های اشتراک ”
{
  "status": "ok",
  "data": { "variant_cap": 500, "speed_floor_minutes": 15, "min_interval_minutes": 5, "bot_on_count": 157, "over_quota": 0 }
}

🔔 رویدادهای وب‌هوک

Section titled “🔔 رویدادهای وب‌هوک”

همه‌ی رویدادهای این بخش با دسترسی bot:read دریافت می‌شوند.

رویداد چه وقت
bot.stalled کلید اصلی روشن است و بیش از ۳۰ دقیقه هیچ دوری اجرا نشده است (جز در زمان توقف به‌خاطر محدودیت دیجی‌کالا). یک بار هنگام شروع این وضعیت.
bot.writes_failing در ۳ ساعت گذشته ربات تغییر قیمت تعیین کرده اما هیچ‌یک در دیجی‌کالا ثبت نشده است.
bot.rate_limited سقف درخواست دیجی‌کالا پر شده و ربات دست‌کم ۱۵ دقیقه منتظر می‌ماند؛ پس از rate_limited_until خودکار ادامه می‌دهد و اقدامی لازم نیست.
bot.variant_stopped ربات قیمت‌گذاری یک تنوع را متوقف یا خاموش کرد (stop_code)، یا تنوع پس از ۵ رد پیاپی ۶ ساعت کنار گذاشته شد (state: parked).
bot.plan_quota_over تعداد تنوع‌های دارای ربات از سقف اشتراک بیشتر شد؛ unpriced_variant_ids تا ۲۰۰ شناسه از تنوع‌های بیرون از سقف را دارد.

نمونه‌ی پیام bot.variant_stopped

{
  "id": "evt_01J0B2MZ",
  "type": "bot.variant_stopped",
  "created_at": "2026-11-12T11:02:44+03:30",
  "panel_id": 1,
  "livemode": true,
  "data": {
    "variant": {
      "variant_id": 84780448,
      "sku": "PE-5144",
      "enabled": true,
      "strategy_id": 412,
      "state": "stopped",
      "stop_code": "needed_price_below_floor",
      "stop_reason": "برای بردن بای‌باکس باید زیر حداقل قیمت شما می‌رفت.",
      "floor": 21800000,
      "floor_source": "cost_plus"
    }
  }
}

پیام‌ها ممکن است تکراری یا جابه‌جا برسند (معرفی وب‌هوک). پیش از استفاده از هر پیام، امضای آن را بررسی کنید.

💻 نمونه‌کد: اتصال استراتژی و روشن کردن ربات یک تنوع

Section titled “💻 نمونه‌کد: اتصال استراتژی و روشن کردن ربات یک تنوع”
Terminal window
curl -X PATCH https://api.seller360.ir/v1/bot/variants/84780448 \
  -H "Authorization: Bearer $S360_API_KEY" \
  -H "Idempotency-Key: bot-84780448-attach-412" \
  -H "Content-Type: application/json" \
  -d '{"strategy_id": 412, "min_price": 21800000, "max_price": 27500000, "enabled": true}'

🔗 لینک‌های مرتبط

Section titled “🔗 لینک‌های مرتبط”