قیمت فروش

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

📖 مقدمه

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

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

کار	مسیر	در دسترس
خواندن قیمت همه‌ی تنوع‌ها	GET /v1/prices	فعال
خواندن قیمت یک تنوع	GET /v1/prices/{variant_id}	فعال
تغییر فوری قیمت یک تنوع	PUT /v1/prices/{variant_id}	فعال
تغییر قیمت چند تنوع در صف	POST /v1/prices/batch	فعال
تاریخچه‌ی تغییرات قیمت	GET /v1/price-changes	فعال
برگرداندن یک تغییر یا یک تغییر گروهی	POST /v1/price-changes/{change_id}/undo	فاز ۲

و با رویدادهای وب‌هوک price.changed و price.selling_at_loss از هر تغییر قیمت و هر فروش زیان‌ده خبردار شوید.

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

دسترسی (Scope)

دسترسی	برای
prices:read	خواندن قیمت‌ها و تاریخچه، و دریافت رویدادهای price.*
prices:write	تغییر فوری، تغییر در صف و برگرداندن
bot:write	پیشنهاد می‌شود: برای روشن کردن دوباره‌ی ربات تنوعی که با pause_bot خاموش شده است

کلید را با کمترین دسترسی لازم بسازید. نرم‌افزاری که فقط قیمت را نمایش می‌دهد، به prices:write نیاز ندارد. جزئیات ساخت کلید در صفحه‌ی ورود و دسترسی‌ها آمده است.

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

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

آدرس پایه

https://api.seller360.ir

🧮 مدل قیمت

فیلدها

فیلد	برچسب در پنل	معنی
selling_price	«قیمت فروش»	قیمت فروش پایه‌ی تنوع به ریال.
customer_price	«قیمت برای مشتری»	قیمتی که خریدار می‌پردازد؛ با تخفیف فعال برابر قیمت تخفیف، وگرنه برابر قیمت فروش. سایت شما اگر قیمت دیجی‌کالا را نشان می‌دهد، همین عدد را نشان دهد.
reference_price	«قیمت مرجع دیجی‌کالا»	قیمت مرجعی که دیجی‌کالا برای تنوع اعلام کرده است؛ خالی یعنی قیمت مرجعی اعلام نشده است.
reference_price_synced_at	—	زمان آخرین خواندن قیمت مرجع از دیجی‌کالا.
reference_price_stale	—	true اگر قیمت مرجع بیش از ۲۴ ساعت پیش خوانده شده باشد.
allowed_min_price	«کف مجاز»	کمترین قیمتی که دیجی‌کالا می‌پذیرد.
allowed_max_price	«سقف مجاز»	بیشترین قیمتی که دیجی‌کالا می‌پذیرد.
reference_min_price	—	کمترین قیمت مجاز مرجع که دیجی‌کالا برای این تنوع اعلام کرده است.
promotion_price	«قیمت تخفیف»	قیمت تخفیف فعال؛ جزئیات در صفحه‌ی تخفیف هوشمند و کمپین‌ها.
is_in_promotion	—	تنوع تخفیف فعال دارد.
buy_box_price	«قیمت بای‌باکس»	قیمت برنده‌ی بای‌باکس از همگام‌سازی روزانه‌ی پنل. وضعیت زنده در صفحه‌ی بای‌باکس و رقبا است.
is_buy_box_winner	«بای‌باکس در اختیار شماست»	برنده بودن بای‌باکس از همگام‌سازی روزانه‌ی پنل.
managed_by_bot	«قیمت‌گذاری ماشینی»	ربات قیمت‌گذاری روی این تنوع روشن است و استراتژی دارد.
managed_by_fx	—	قیمت این تنوع با استراتژی ارزی تعیین می‌شود.
floor	«حداقل قیمت»	حداقل قیمتی که ربات رعایت می‌کند؛ توضیح کامل در صفحه‌ی ربات قیمت‌گذاری.
pending_write	—	قیمتی که در صف تغییر دستی منتظر ثبت در دیجی‌کالاست، با تعداد تلاش‌های ناموفق (attempts، حداکثر ۵) و زمان ورود به صف (queued_at).
synced_at	—	زمان آخرین به‌روزرسانی نسخه‌ی محلی این تنوع.

بازه‌ی مجاز

دیجی‌کالا قیمتی بیرون از بازه‌ی اطراف قیمت مرجع را نمی‌پذیرد. سلر ۳۶۰ این بازه را این‌گونه محاسبه و اعلام می‌کند:

allowed_min_price = 0.5  × reference_price   (گرد به بالا تا مضرب ۱۰۰ ریال)
allowed_max_price = 1.14 × reference_price   (گرد به پایین تا مضرب ۱۰۰ ریال)

هر قیمت فروش باید مضرب ۱۰۰ ریال و داخل همین بازه باشد. در اندازه‌گیری مستقیم روی دیجی‌کالا، سقف واقعی اندکی بالاتر از ۱٫۱۴ برابر بود؛ سلر ۳۶۰ عمدا با ۱٫۱۴ کار می‌کند تا قیمت مرجعی که چند ساعت از آخرین خواندن آن گذشته است، باعث رد شدن قیمت نشود.

یک مثال

	مقدار (ریال)
قیمت مرجع	24,500,000
کف مجاز (۰٫۵ برابر)	12,250,000
سقف مجاز (۱٫۱۴ برابر)	27,930,000
قیمت 28,000,000	رد می‌شود (price_out_of_band)
قیمت 23,990,050	رد می‌شود؛ مضرب ۱۰۰ ریال نیست
قیمت 23,990,000	پذیرفته می‌شود

نویسنده‌ی قیمت

قیمت هر تنوع در هر لحظه فقط یک نویسنده‌ی خودکار دارد؛ یا ربات قیمت‌گذاری، یا استراتژی ارزی، هرگز هر دو.

وضعیت	managed_by_bot	managed_by_fx	تغییر از API
بدون نویسنده‌ی خودکار	false	false	انجام می‌شود.
ربات روشن و استراتژی متصل	true	false	رد می‌شود (price_managed_by_bot)، مگر با pause_bot: true.
استراتژی ارزی	false	true	رد می‌شود (price_managed_by_fx).

🔢 تازگی

• نسخه‌ی محلی: مسیرهای خواندن از نسخه‌ی محلی سلر ۳۶۰ پاسخ می‌دهند و هرگز در لحظه از دیجی‌کالا نمی‌خوانند. زمان آخرین به‌روزرسانی هر تنوع در synced_at است.
• قیمت مرجع: سن قیمت مرجع در reference_price_synced_at است. اگر بیش از ۲۴ ساعت گذشته باشد، reference_price_stale برابر true می‌شود و بازه‌ی مجاز ممکن است دقیق نباشد. با پارامتر reference_stale=1 همین تنوع‌ها را پیدا کنید.
• تغییر فوری: اگر بیش از ۲۴ ساعت از آخرین خواندن قیمت مرجع گذشته باشد، PUT /v1/prices/{variant_id} پیش از هر کاری قیمت مرجع را دوباره از دیجی‌کالا می‌خواند؛ بنابراین بازه‌ای که بر اساس آن رد یا پذیرفته می‌شوید، هرگز کهنه‌تر از یک روز نیست. خواندن قیمت مرجع از سهمیه‌ی بسیار محدود دیجی‌کالا برای فهرست کالاها مصرف می‌کند که ربات و همگام‌سازی پنل نیز به آن نیاز دارند؛ به همین دلیل در هر تغییر تکرار نمی‌شود.
• صفحه‌ی عمومی دیجی‌کالا: قیمت ثبت‌شده حدود ۲ دقیقه بعد در صفحه‌ی عمومی کالا دیده می‌شود.
• تاریخچه: تغییرات قیمت تا ۳۶۵ روز نگه داشته می‌شوند.

⚠️ هشدارها

۱. قیمت بیرون از بازه هرگز گرد نمی‌شود

قیمتی که بیرون از allowed_min_price تا allowed_max_price باشد یا مضرب ۱۰۰ ریال نباشد، با کد 422 و خطای price_out_of_band رد می‌شود. سلر ۳۶۰ آن را به لبه‌ی بازه منتقل یا گرد نمی‌کند؛ بازه‌ی مجاز در detail خطا اعلام می‌شود. تصمیم درباره‌ی قیمت تازه با شماست.

۲. ربات قیمت شما را دوباره تغییر می‌دهد

اگر ربات روی تنوعی روشن باشد و قیمت آن را از بیرون تغییر دهید، ربات در دور بعد قیمت را طبق استراتژی برمی‌گرداند. به همین دلیل تغییر قیمت چنین تنوعی با کد 409 و خطای price_managed_by_bot رد می‌شود. اگر واقعا می‌خواهید قیمت را خودتان تعیین کنید، pause_bot: true بفرستید.

۳. ربات خاموش‌شده خودکار روشن نمی‌شود

با pause_bot: true ربات فقط همان تنوع خاموش می‌شود و استراتژی آن متصل باقی می‌ماند. خاموش شدن ربات بخشی از همین تغییر است: اگر قیمت در دیجی‌کالا ثبت نشود یا نتیجه‌ی آن معلوم نباشد، ربات روشن می‌ماند. پس از ثبت موفق، ربات این تنوع خاموش می‌ماند تا خودتان آن را با PATCH /v1/bot/variants/{variant_id} و enabled: true روشن کنید. کلید اصلی ربات و تنوع‌های دیگر تغییری نمی‌کنند.

۴. قیمت کمتر از حداقل قیمت رد نمی‌شود

تغییر دستی قیمتی کمتر از حداقل قیمت شما (floor) رد نمی‌شود؛ فقط در warnings با کد below_floor اعلام می‌شود. اگر بهای خرید تنوع ثبت شده باشد و فروش با قیمت تازه زیان‌ده شود، رویداد price.selling_at_loss فرستاده می‌شود.

۵. تغییر فوری در صف نمی‌ماند

سقف نوشتن قیمت در دیجی‌کالا میان API و ربات قیمت‌گذاری مشترک است و بخش پایانی سقف هر دوره (یک‌پنجم آن) برای ربات کنار گذاشته می‌شود. اگر سقف درخواست دیجی‌کالا برای این پنل پر باشد، ربات منتظر باز شدن سقف باشد یا به بخش ربات رسیده باشد، PUT /v1/prices/{variant_id} قیمت را در صف نمی‌گذارد و با کد 503 و خطای digikala_rate_limited و سرآیند Retry-After پاسخ می‌دهد. برای تغییرهایی که می‌توانند صبر کنند، از POST /v1/prices/batch استفاده کنید؛ آن مسیر در صف می‌ماند و در نوبت بعد فرستاده می‌شود.

۶. صف برای هر تنوع فقط یک قیمت نگه می‌دارد

صف تغییر دستی همان صفی است که پنل سلر ۳۶۰ هم از آن استفاده می‌کند. اگر پیش از ارسال، قیمت تازه‌تری برای همان تنوع (از API یا از پنل) ثبت شود، جای قیمت قبلی را می‌گیرد. قلمی که دیجی‌کالا ۵ بار پیاپی رد کند، از صف خارج و در نتیجه‌ی کار با وضعیت refused اعلام می‌شود.

۷. برگرداندن فقط وقتی انجام می‌شود که قیمت دست نخورده باشد

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

📡 مسیرها

GET /v1/prices — قیمت همه‌ی تنوع‌ها فعال

قیمت فروش، قیمت مرجع، بازه‌ی مجاز و نویسنده‌ی فعلی قیمت هر تنوع، به ترتیب شناسه‌ی تنوع.

GET /v1/prices?page=1&size=100&managed_by_bot=0 HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...

پارامترها

پارامتر	نوع	اجباری	توضیح
page	عدد	خیر	شماره‌ی صفحه؛ پیش‌فرض ۱.
size	عدد	خیر	تعداد در هر صفحه.
variant_ids	متن	خیر	فهرست شناسه‌ی تنوع‌ها با ویرگول، حداکثر ۱۰۰ شناسه؛ مثلا 84780448,84780449.
sku	متن	خیر	تنوعی که با این کد کالای سایت شما جفت شده است.
managed_by_bot	0 یا 1	خیر	فقط تنوع‌هایی که ربات روی آن‌ها روشن است (1) یا نیست (0).
in_promotion	0 یا 1	خیر	فقط تنوع‌هایی که تخفیف فعال دارند (1) یا ندارند (0).
reference_stale	0 یا 1	خیر	فقط تنوع‌هایی که قیمت مرجع آن‌ها بیش از ۲۴ ساعت پیش خوانده شده است (1).

پاسخ نمونه

{
  "status": "ok",
  "data": [
    {
      "variant_id": 84780448,
      "sku": "PE-5144",
      "selling_price": 23990000,
      "customer_price": 23490000,
      "reference_price": 24500000,
      "reference_price_synced_at": "2026-11-12T06:10:41+03:30",
      "reference_price_stale": false,
      "allowed_min_price": 12250000,
      "allowed_max_price": 27930000,
      "reference_min_price": 22050000,
      "promotion_price": 23490000,
      "is_in_promotion": true,
      "buy_box_price": 23490000,
      "is_buy_box_winner": true,
      "managed_by_bot": false,
      "managed_by_fx": false,
      "floor": 21800000,
      "pending_write": null,
      "synced_at": "2026-11-12T10:02:17+03:30"
    }
  ],
  "pager": { "page": 1, "item_per_page": 100, "total_pages": 5, "total_rows": 449 }
}

GET /v1/prices/{variant_id} — قیمت یک تنوع فعال

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

PUT /v1/prices/{variant_id} — تغییر فوری قیمت فعال

قیمت فروش یک تنوع را در دیجی‌کالا تغییر می‌دهد و پس از ثبت قطعی در دیجی‌کالا با کد 200 پاسخ می‌دهد. مراحل همان مراحل ویرایش قیمت در صفحه‌ی محصولات پنل است:

1. اگر قیمت مرجع بیش از ۲۴ ساعت پیش خوانده شده باشد، دوباره از دیجی‌کالا خوانده می‌شود.
2. قیمت باید مضرب ۱۰۰ ریال و داخل بازه‌ی مجاز باشد؛ در غیر این صورت price_out_of_band (هشدار ۱).
3. اگر ربات روی تنوع روشن باشد و pause_bot نفرستاده باشید، price_managed_by_bot. با pause_bot: true ابتدا ربات همین تنوع خاموش می‌شود (هشدار ۳).
4. اگر تنوع استراتژی ارزی داشته باشد، price_managed_by_fx.
5. قیمت در دیجی‌کالا نوشته می‌شود، با منشا api در تاریخچه ثبت می‌شود و رویداد price.changed فرستاده می‌شود.

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

{ "selling_price": 23790000, "pause_bot": true }

فیلد بدنه	نوع	اجباری	توضیح
selling_price	عدد	بله	قیمت فروش به ریال؛ دست‌کم ۱۰۰، مضرب ۱۰۰ و داخل بازه‌ی مجاز.
pause_bot	true یا false	خیر	پیش‌فرض false. اگر ربات روی این تنوع روشن باشد، ابتدا ربات فقط همین تنوع خاموش شود و سپس قیمت نوشته شود.

پاسخ نمونه (کد 200)

{
  "status": "ok",
  "data": {
    "price": {
      "variant_id": 84780448,
      "sku": "PE-5144",
      "selling_price": 23790000,
      "customer_price": 23790000,
      "reference_price": 24500000,
      "allowed_min_price": 12250000,
      "allowed_max_price": 27930000,
      "is_in_promotion": false,
      "managed_by_bot": false,
      "managed_by_fx": false,
      "floor": 21800000,
      "pending_write": null,
      "synced_at": "2026-11-12T10:15:04+03:30"
    },
    "change_id": "pcl_8812034",
    "bot_paused": true,
    "warnings": []
  }
}

اگر قیمت کمتر از حداقل قیمت شما باشد، تغییر انجام می‌شود و warnings این‌گونه است:

"warnings": [
  { "code": "below_floor", "message": "این قیمت کمتر از حداقل قیمت شما (۲۱٬۸۰۰٬۰۰۰ ریال) است." }
]

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

کد HTTP	خطا	معنی	تکرار بی‌خطر است؟
400	invalid_parameter	بدنه نامعتبر است؛ نام فیلد در detail می‌آید.	خیر؛ بدنه را اصلاح کنید.
400	idempotency_key_required	سرآیند Idempotency-Key ارسال نشده است.	بله، با کلید یکتا.
403	subscription_inactive	اشتراک پنل فعال نیست.	خیر؛ پس از تمدید اشتراک.
404	variant_not_found	تنوعی با این شناسه در این پنل نیست.	خیر.
409	price_managed_by_bot	ربات روی این تنوع روشن است؛ هیچ تغییری انجام نشد.	با pause_bot: true و کلید یکتای تازه.
409	price_managed_by_fx	قیمت با استراتژی ارزی تعیین می‌شود.	خیر؛ ابتدا استراتژی ارزی را بردارید.
409	idempotency_mismatch	این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است.	خیر؛ کلید تازه بسازید.
409	idempotency_in_progress	درخواستی با همین کلید در حال انجام است.	بله، چند ثانیه بعد.
422	price_out_of_band	قیمت بیرون از بازه‌ی مجاز است یا مضرب ۱۰۰ ریال نیست؛ بازه در detail.	خیر؛ قیمت را اصلاح کنید.
502	digikala_refused	دیجی‌کالا قیمت را نپذیرفت؛ هیچ تغییری ثبت نشد.	پس از بررسی علت.
503	digikala_rate_limited	سقف درخواست دیجی‌کالا پر است؛ قیمت در صف نماند (هشدار ۵).	بله، پس از Retry-After و با همان Idempotency-Key.
503	digikala_unavailable	دیجی‌کالا در دسترس نیست.	بله، پس از Retry-After و با همان Idempotency-Key.

فهرست همه‌ی خطاها در صفحه‌ی خطاها و قواعد کلید یکتا در کلید یکتای درخواست است.

POST /v1/prices/batch — تغییر قیمت چند تنوع در صف فعال

تا ۱۰۰ تنوع در هر درخواست. پاسخ فوری 202 فقط یعنی «در صف ثبت شد»؛ نتیجه با GET /v1/jobs/{job_id} و رویداد job.completed اعلام می‌شود (نوع کار price_batch؛ جزئیات در کارهای در صف).

• هر قلم با همان قواعد تغییر فوری جداگانه بررسی می‌شود (بازه‌ی مجاز، ربات، استراتژی ارزی، pause_bot). قلم ردشده با کد خطای خودش در items نتیجه می‌آید و بقیه‌ی اقلام انجام می‌شوند.
• اقلام پذیرفته‌شده در همان صف تغییر دستی پنل قرار می‌گیرند. این صف در هر نوبت زمان‌بند پیش از ربات به دیجی‌کالا فرستاده می‌شود و هر قلم با یک درخواست جداگانه ثبت و تایید می‌شود.
• اگر سقف درخواست دیجی‌کالا پر باشد، اقلام در صف می‌مانند و در نوبت بعد فرستاده می‌شوند (هشدار ۶).

POST /v1/prices/batch HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: price-batch-1405-08-22-morning
Content-Type: application/json

{
  "items": [
    { "variant_id": 84780448, "selling_price": 23790000 },
    { "variant_id": 84780449, "selling_price": 24190000, "pause_bot": true }
  ]
}

فیلد هر قلم	نوع	اجباری	توضیح
variant_id	عدد	بله	شناسه‌ی تنوع.
selling_price	عدد	بله	قیمت فروش به ریال، مضرب ۱۰۰.
pause_bot	true یا false	خیر	همان رفتار تغییر فوری؛ پیش‌فرض false.

پاسخ نمونه (کد 202)

{
  "status": "ok",
  "data": { "id": "job_8f2c1e", "kind": "price_batch", "status": "queued", "created_at": "2026-11-12T10:15:03+03:30" }
}

نتیجه‌ی کار پس از پایان

{
  "status": "ok",
  "data": {
    "id": "job_8f2c1e",
    "kind": "price_batch",
    "status": "partial",
    "created_at": "2026-11-12T10:15:03+03:30",
    "finished_at": "2026-11-12T10:15:41+03:30",
    "items": [
      { "variant_id": 84780448, "status": "applied", "error": null },
      { "variant_id": 84780449, "status": "refused", "error": "price_out_of_band" }
    ]
  }
}

GET /v1/price-changes — تاریخچه‌ی تغییرات قیمت فعال

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

GET /v1/price-changes?variant_id=84780448&created_from=2026-11-11T00:00:00%2B03:30 HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...

پارامتر	نوع	اجباری	توضیح
variant_id	عدد	خیر	فقط تغییرات این تنوع.
source	bot، panel، api، fx	خیر	فقط تغییرات با این منشا.
status	applied، failed، dry	خیر	فقط تغییرات با این وضعیت.
direction	up یا down	خیر	فقط افزایش یا فقط کاهش قیمت.
batch_id	متن	خیر	فقط اقلام یک تغییر گروهی.
created_from، created_to	زمان	خیر	بازه‌ی زمان تغییر.
page، size	عدد	خیر	صفحه‌بندی.

منشا تغییر (source)

مقدار	معنی
bot	ربات قیمت‌گذاری، طبق استراتژی متصل؛ شناسه‌ی استراتژی در strategy_id.
panel	تغییر دستی در پنل سلر ۳۶۰، تکی یا گروهی.
api	تغییر از همین API.
fx	قیمت‌گذاری ارزی.

وضعیت تغییر (status)

مقدار	معنی
applied	پاسخ دیجی‌کالا ثبت قیمت را تایید کرد.
failed	تصمیم گرفته شد اما در دیجی‌کالا ثبت نشد (رد، محدودیت یا خطای ارتباط).
dry	شبیه‌سازی، فقط در پنل نمایشی؛ هرگز قرار نبود ثبت شود.

پاسخ نمونه

{
  "status": "ok",
  "data": [
    {
      "id": "pcl_8812051",
      "variant_id": 84780448,
      "sku": "PE-5144",
      "created_at": "2026-11-12T09:40:12+03:30",
      "source": "bot",
      "strategy_id": 412,
      "old_price": 24200000,
      "new_price": 23990000,
      "change_pct": -0.9,
      "reason": "بای‌باکس در اختیار رقیب است → کاهش تا قیمت بردن",
      "status": "applied",
      "batch_id": null,
      "undoable": false,
      "undo_expires_at": null,
      "undone_at": null
    },
    {
      "id": "pcl_8812034",
      "variant_id": 84780448,
      "sku": "PE-5144",
      "created_at": "2026-11-11T18:05:33+03:30",
      "source": "api",
      "strategy_id": null,
      "old_price": 24500000,
      "new_price": 24200000,
      "change_pct": -1.2,
      "reason": "تغییر از API",
      "status": "applied",
      "batch_id": null,
      "undoable": true,
      "undo_expires_at": "2026-11-12T18:05:33+03:30",
      "undone_at": null
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 2 }
}

POST /v1/price-changes/{change_id}/undo — برگرداندن تغییر فاز ۲

قیمت را به مقدار پیش از این تغییر برمی‌گرداند؛ همان قواعد «بازگردانی» پنل:

• فقط تغییرات با منشا panel یا api قابل برگرداندن هستند (undoable در تاریخچه). تغییرات ربات و قیمت ارزی برگردانده نمی‌شوند.
• فقط تا ۲۴ ساعت پس از تغییر و فقط یک بار.
• پیش از مقایسه، قیمت فعلی از دیجی‌کالا خوانده می‌شود و فقط اگر هنوز همان قیمت این تغییر باشد، برگردانده می‌شود (هشدار ۷). اقلامی که دیجی‌کالا برای آن‌ها در دسترس نبود، در مهلت ۲۴ ساعت با درخواست دوباره‌ی همین مسیر تلاش می‌شوند.

برگرداندن در صف انجام می‌شود (202، نوع کار price_undo).

POST /v1/price-changes/pcl_8812034/undo HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: undo-pcl_8812034
Content-Type: application/json

{ "scope": "change" }

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

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

کد HTTP	خطا	معنی	تکرار بی‌خطر است؟
404	not_found	تغییری با این شناسه در این پنل نیست.	خیر.
409	already_undone	این تغییر پیش‌تر برگردانده شده است.	خیر.
409	undo_in_progress	برگرداندن این تغییر در حال انجام است.	خیر؛ نتیجه‌ی کار قبلی را بخوانید.
409	idempotency_mismatch	این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است.	خیر؛ کلید تازه بسازید.
422	change_not_undoable	تغییر ربات یا قیمت ارزی است.	خیر.
422	undo_window_expired	بیش از ۲۴ ساعت از تغییر گذشته است.	خیر.

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

رویداد	چه وقت
price.changed	پس از هر تغییر قیمت فروش که در دیجی‌کالا ثبت شده است، با منشا آن. منشا digikala یعنی تغییری که بیرون از سلر ۳۶۰ (مثلا در پنل دیجی‌کالا) انجام شده و در همگام‌سازی دیده شده است؛ برای این منشا change_id خالی است. تصمیم‌هایی از ربات که در دیجی‌کالا ثبت نشده‌اند، این رویداد را نمی‌فرستند.
price.selling_at_loss	سود خالص هر فروش تنوعی فعال و موجود (پس از کمیسیون، هزینه‌ی پردازش و ارسال، مالیات و بهای خرید ثبت‌شده) منفی است. اگر بهای خرید دقیق نیست، ابتدا آن را اصلاح کنید.

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

نمونه‌ی پیام price.changed

{
  "id": "evt_01J0A7QX",
  "type": "price.changed",
  "created_at": "2026-11-12T09:40:14+03:30",
  "panel_id": 1,
  "livemode": true,
  "data": {
    "price": {
      "variant_id": 84780448,
      "sku": "PE-5144",
      "selling_price": 23990000,
      "customer_price": 23990000,
      "reference_price": 24500000,
      "managed_by_bot": true,
      "managed_by_fx": false,
      "floor": 21800000,
      "synced_at": "2026-11-12T09:40:14+03:30"
    },
    "previous_selling_price": 24200000,
    "source": "bot",
    "change_id": "pcl_8812051",
    "strategy_id": 412
  }
}

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

💻 نمونه‌کد: تغییر فوری قیمت

curl

curl -X PUT https://api.seller360.ir/v1/prices/84780448 \
  -H "Authorization: Bearer $S360_API_KEY" \
  -H "Idempotency-Key: price-1405-08-22-84780448-23790000" \
  -H "Content-Type: application/json" \
  -d '{"selling_price": 23790000, "pause_bot": true}'

PHP

$ch = curl_init("https://api.seller360.ir/v1/prices/84780448");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("S360_API_KEY"),
        "Idempotency-Key: price-1405-08-22-84780448-23790000",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["selling_price" => 23790000, "pause_bot" => true]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$res = json_decode(curl_exec($ch), true);
if (($res["error"]["code"] ?? null) === "price_out_of_band") {
    // بازه‌ی مجاز در $res["error"]["detail"] است؛ قیمت را اصلاح کنید
}

Python

import os, requests

res = requests.put(
    "https://api.seller360.ir/v1/prices/84780448",
    headers={
        "Authorization": f"Bearer {os.environ['S360_API_KEY']}",
        "Idempotency-Key": "price-1405-08-22-84780448-23790000",
    },
    json={"selling_price": 23790000, "pause_bot": True},
    timeout=30,
).json()
if res["status"] == "error" and res["error"]["code"] == "price_out_of_band":
    print(res["error"].get("detail"))  # بازه‌ی مجاز
elif res["status"] == "ok" and res["data"]["bot_paused"]:
    ...  # ربات این تنوع خاموش شد؛ بعدا خودتان روشن کنید

Node.js

const res = await fetch('https://api.seller360.ir/v1/prices/84780448', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.S360_API_KEY}`,
    'Idempotency-Key': 'price-1405-08-22-84780448-23790000',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ selling_price: 23790000, pause_bot: true }),
})
const body = await res.json()
if (body.error?.code === 'price_out_of_band') {
  console.log(body.error.detail) // بازه‌ی مجاز
}

C#

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Put,
    "https://api.seller360.ir/v1/prices/84780448");
req.Headers.Add("Authorization", $"Bearer {Environment.GetEnvironmentVariable("S360_API_KEY")}");
req.Headers.Add("Idempotency-Key", "price-1405-08-22-84780448-23790000");
req.Content = JsonContent.Create(new { selling_price = 23790000, pause_bot = true });
var res = await http.SendAsync(req);
var body = await res.Content.ReadFromJsonAsync<JsonElement>();

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

• ربات قیمت‌گذاری و استراتژی‌ها
• بای‌باکس و رقبا
• تخفیف هوشمند و کمپین‌ها
• کارهای در صف
• کلید یکتای درخواست
• سقف درخواست
• فهرست خطاها
• مرجع خودکار مسیرها