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

انبار دیجی‌کالا و هزینه‌ی ماندگاری

مخاطب: برنامه‌نویس نرم‌افزار انبارداری، حسابداری یا داشبورد مدیریتی که می‌خواهد بداند کدام کالاها در انبار دیجی‌کالا مانده‌اند، از کی، و چه هزینه‌ای برای فروشنده دارند.

📖 مقدمه

Section titled “📖 مقدمه”

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

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

کار مسیر در دسترس
موجودی تنوع‌ها در انبارهای دیجی‌کالا GET /v1/warehouse/inventory فعال
سریال‌های کالا در انبار دیجی‌کالا GET /v1/warehouse/serials فعال
یک سریال با جابه‌جایی‌های آن GET /v1/warehouse/serials/{serial} فعال
هزینه‌ی ماندگاری هر تنوع GET /v1/storage-costs فعال
خلاصه و روند روزانه‌ی هزینه‌ی ماندگاری GET /v1/storage-costs/summary فعال

و با رویداد وب‌هوک storage.cost_rising از افزایش محسوس هزینه‌ی انبارداری خبردار شوید. همه‌ی مسیرهای این صفحه فقط خواندنی‌اند و چیزی در دیجی‌کالا نمی‌نویسند.

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

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

دسترسی (Scope)

Section titled “دسترسی (Scope)”
دسترسی برچسب در پنل برای
warehouse:read «خواندن انبار دیجی‌کالا و هزینه‌ی ماندگاری» همه‌ی مسیرهای این صفحه
catalog:read «خواندن کاتالوگ کالا» پیشنهاد می‌شود: برای خواندن عنوان و کد تنوع‌ها با کاتالوگ

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

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

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

آدرس پایه

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

🧮 مفاهیم

Section titled “🧮 مفاهیم”

موجودی انبار (WarehouseInventoryItem)

Section titled “موجودی انبار (WarehouseInventoryItem)”
فیلد برچسب در پنل معنی
variant_id «کد DKPC» تنوع.
warehouse_stock «موجودی در انبار دیجی‌کالا» جمع واحدهای تنوع در انبارهای دیجی‌کالا در فهرست شبانه.
return_stock «موجودی مرجوعی» واحدهای مرجوعی.
dead_stock «کالای راکد» تعداد کالای راکد به اعلام دیجی‌کالا.
has_return_to_seller_stock — موجودی در انتظار بازگشت به فروشنده دارد.
has_return_to_seller_package — بسته‌ی بازگشت به فروشنده دارد.
seen_on — روز فهرست شبانه‌ای که این ردیف از آن است.

سریال (WarehouseSerial)

Section titled “سریال (WarehouseSerial)”

هر واحد کالا در انبار دیجی‌کالا یک سریال دارد.

فیلد برچسب در پنل معنی
serial — شناسه‌ی واحد در انبار دیجی‌کالا.
variant_id «کد DKPC» تنوع.
warehouse_title — انباری که واحد در آن است.
age_days — روزهای ماندن در انبار، به شمارش دیجی‌کالا.
free_days «دوره‌ی رایگان انبارش» روزهای بدون هزینه برای این تنوع.
free_days_left — free_days منهای age_days؛ عدد منفی یعنی تعداد روزهای هزینه‌دار.
past_free — دوره‌ی رایگان تمام شده و هر روز هزینه دارد.
first_seen — اولین شبی که سریال در فهرست انبار بود.
last_seen — آخرین شبی که سریال در فهرست انبار بود.
in_warehouse — در آخرین فهرست کامل شبانه هست.

جابه‌جایی سریال (WarehouseSerialMove)

Section titled “جابه‌جایی سریال (WarehouseSerialMove)”
فیلد معنی
day شبی که وضعیت تازه برای اولین بار دیده شد؛ جابه‌جایی بین فهرست شب قبل و این شب رخ داده است.
from_warehouse انبار قبلی.
to_warehouse انبار تازه؛ null یعنی واحد از انبار خارج شد.
left_warehouse واحد از انبار دیجی‌کالا خارج شد.

هزینه‌ی ماندگاری هر تنوع (StorageCostItem)

Section titled “هزینه‌ی ماندگاری هر تنوع (StorageCostItem)”

همه‌ی مبلغ‌ها به ریال‌اند. اعداد گذشته واقعی‌اند و اعداد آینده برآوردی (estimated).

فیلد برچسب در پنل معنی
cost_30d، cost_7d «هزینه‌ی انبارداری» هزینه‌ی واقعی ۳۰ و ۷ روز گذشته، از تراکنش‌های مالی.
daily_rate — هزینه‌ی روزانه‌ی هر واحد هزینه‌دار، از آخرین تراکنش ماندگاری.
fee_units — واحدهایی که اکنون هزینه می‌دهند.
soon_units — واحدهایی که تا ۷ روز دیگر هزینه‌دار می‌شوند.
soon_unsold — از آن‌ها، واحدهایی که با سرعت فروش فعلی تا آن زمان فروخته نمی‌شوند.
warehouse_available «باقی‌مانده در انبار دیجی‌کالا» انبار دیجی‌کالا منهای رزرو.
daily_sales، sales_30d — فروش روزانه و فروش ۳۰ روز.
days_to_sell — روزهای فروش باقی‌مانده در انبار دیجی‌کالا؛ null یعنی فروشی ندارد.
projected_cost — هزینه‌ی برآوردی تا فروش همه‌ی واحدها، حداکثر تا ۳۶۵ روز (projected_capped).
projected_share_pct — هزینه‌ی برآوردی هر واحد نسبت به قیمت فروش، درصد.
monthly_share_pct — هزینه‌ی ۳۰ روز یک واحد نسبت به قیمت فروش، درصد.
recommendation — پیشنهاد اقدام (جدول بعد).
days_saved — روزهای هزینه‌ای که با فروش در یک هفته صرفه‌جویی می‌شود؛ حداکثر ۹۰.
break_even_discount — تخفیف هر واحد که هزینه‌ی ماندگاری آن را جبران می‌کند.
daily_cost_now — هزینه‌ی روزانه‌ی فعلی همه‌ی واحدهای هزینه‌دار؛ با بازگشت آن‌ها حذف می‌شود.
return_quantity — تعداد پیشنهادی درخواست بازگشت: واحدهای هزینه‌دار، حداکثر به اندازه‌ی باقی‌مانده در انبار.
warehouses — تقسیم واحدها و واحدهای هزینه‌دار بین انبارها.

🚦 پیشنهادها

Section titled “🚦 پیشنهادها”
مقدار recommendation برچسب در پنل چه وقت
return «درخواست بازگشت کالا» واحد هزینه‌دار دارد و در ۳۰ روز فروشی نداشته است، یا هزینه‌ی برآوردی هر واحد تا فروش بیش از ۲۰ درصد قیمت فروش است.
faster «فروش سریع‌تر» آن نسبت بیش از ۵ درصد است.
soon «به‌زودی هزینه‌دار می‌شود» واحدهایی تا ۷ روز دیگر از دوره‌ی رایگان خارج می‌شوند و تا آن زمان فروخته نمی‌شوند.
watch «تحت نظر» هیچ‌کدام از موارد بالا.

🔢 تازگی

Section titled “🔢 تازگی”
  • فهرست انبار و سریال‌ها: هر شب از دیجی‌کالا خوانده می‌شود. روز فهرست هر ردیف در seen_on و روز آخرین فهرست کامل سریال‌ها در serials_on خلاصه آمده است.
  • هزینه‌ها: از تراکنش‌های مالی دیجی‌کالا محاسبه می‌شوند که هر شب ساعت ۰۴:۰۵ به وقت تهران دریافت می‌شوند.
  • سه روز اخیر: ممکن است تراکنش‌های این روزها هنوز کامل نرسیده باشد؛ در روند روزانه با fresh: true مشخص شده‌اند.

⚠️ هشدارها

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

📡 مسیرها

Section titled “📡 مسیرها”

GET /v1/warehouse/inventory — موجودی در انبارهای دیجی‌کالا فعال

Section titled “GET /v1/warehouse/inventory — موجودی در انبارهای دیجی‌کالا ”

از آخرین فهرست شبانه‌ی انبار دیجی‌کالا.

GET /v1/warehouse/inventory?variant_id=84780448 HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
پارامتر نوع اجباری توضیح
page، size عدد خیر صفحه‌بندی؛ پیش‌فرض ۵۰، بیشینه ۵۰۰.
variant_id عدد خیر فقط این تنوع. 
{
  "status": "ok",
  "data": [
    {
      "variant_id": 84780448,
      "warehouse_stock": 14,
      "return_stock": 1,
      "dead_stock": 3,
      "has_return_to_seller_stock": false,
      "has_return_to_seller_package": false,
      "seen_on": "2026-11-12"
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 1 }
}

GET /v1/warehouse/serials — سریال‌ها فعال

Section titled “GET /v1/warehouse/serials — سریال‌ها ”

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

پارامتر نوع اجباری توضیح
page، size عدد خیر صفحه‌بندی.
variant_id عدد خیر فقط این تنوع.
in_warehouse 0 یا 1 خیر موجود در آخرین فهرست (1، پیش‌فرض) یا خارج‌شده (0).
past_free 0 یا 1 خیر 1: فقط واحدهایی که دوره‌ی رایگان آن‌ها تمام شده است. 
{
  "status": "ok",
  "data": [
    {
      "serial": "DKS-4F81A20C",
      "variant_id": 84780448,
      "warehouse_title": "انبار مرکزی",
      "age_days": 41,
      "free_days": 30,
      "free_days_left": -11,
      "past_free": true,
      "first_seen": "2026-10-03",
      "last_seen": "2026-11-12",
      "in_warehouse": true
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 9 }
}

GET /v1/warehouse/serials/{serial} — یک سریال و جابه‌جایی‌های آن فعال

Section titled “GET /v1/warehouse/serials/{serial} — یک سریال و جابه‌جایی‌های آن ”

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

{
  "status": "ok",
  "data": {
    "serial": "DKS-77C0B913",
    "variant_id": 84780448,
    "warehouse_title": null,
    "age_days": 52,
    "free_days": 30,
    "free_days_left": -22,
    "past_free": true,
    "first_seen": "2026-09-14",
    "last_seen": "2026-11-04",
    "in_warehouse": false,
    "moves": [
      { "day": "2026-10-29", "from_warehouse": "انبار مرکزی", "to_warehouse": "انبار مرجوعی مرکزی", "left_warehouse": false },
      { "day": "2026-11-05", "from_warehouse": "انبار مرجوعی مرکزی", "to_warehouse": null, "left_warehouse": true }
    ]
  }
}

GET /v1/storage-costs — هزینه‌ی ماندگاری هر تنوع فعال

Section titled “GET /v1/storage-costs — هزینه‌ی ماندگاری هر تنوع ”

تنوع‌هایی که در ۳۰ روز گذشته هزینه‌ی ماندگاری داشته‌اند، یا واحدی دارند که دوره‌ی رایگان آن تمام شده یا تا ۷ روز دیگر تمام می‌شود؛ پرهزینه‌ترین اول.

GET /v1/storage-costs?recommendation=return HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
پارامتر نوع اجباری توضیح
page، size عدد خیر صفحه‌بندی.
recommendation return، faster، soon، watch خیر فقط تنوع‌هایی با این پیشنهاد. 
{
  "status": "ok",
  "data": [
    {
      "variant_id": 84780448,
      "product_id": 22961150,
      "supplier_code": "5144",
      "title": "محافظ ولتاژ پارت الکتریک مدل PE5144 | سفید | گارانتی ۱۸ ماهه پارت الکتریک",
      "selling_price": 32500000,
      "cost_30d": 1850000,
      "cost_7d": 520000,
      "daily_rate": 8200,
      "fee_units": 9,
      "soon_units": 4,
      "soon_unsold": 2,
      "warehouse_available": 14,
      "daily_sales": 0.7,
      "sales_30d": 19,
      "days_to_sell": 20.0,
      "projected_cost": 1312000,
      "projected_capped": false,
      "projected_share_pct": 0.3,
      "monthly_share_pct": 0.8,
      "recommendation": "watch",
      "days_saved": 13,
      "break_even_discount": 106600,
      "daily_cost_now": 73800,
      "return_quantity": 9,
      "warehouses": [ { "title": "انبار مرکزی", "units": 14, "fee_units": 9 } ],
      "estimated": true
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 48 }
}

GET /v1/storage-costs/summary — خلاصه و روند روزانه فعال

Section titled “GET /v1/storage-costs/summary — خلاصه و روند روزانه ”

جمع ۳۰ و ۷ روز، تمرکز هزینه و هزینه‌ی روزانه‌ی ۹۰ روز گذشته.

فیلد برچسب در پنل معنی
end — آخرین روزی که تراکنش ماندگاری دارد.
serials_on — روز آخرین فهرست کامل سریال‌ها.
total_30d، previous_30d، change_pct «هزینه‌ی انبارداری» جمع ۳۰ روز، ۳۰ روز پیش از آن، و درصد تغییر.
total_7d، average_7d «میانگین ۷ روز» جمع ۷ روز و میانگین روزانه‌ی آن.
concentration «تمرکز هزینه» کمترین تعداد تنوع‌هایی که دست‌کم ۶۰ درصد هزینه‌ی ۳۰ روز را می‌سازند (variants از of، با pct درصد).
by_recommendation — هزینه‌ی ۳۰ روز و تعداد تنوع برای هر پیشنهاد.
daily — هزینه‌ی هر روز؛ spike یعنی بیش از ۱٫۵ برابر میانگین ۱۴ روز پیش از آن («روز پرهزینه»)، fresh یعنی یکی از ۳ روز اخیر. 
{
  "status": "ok",
  "data": {
    "end": "2026-11-11",
    "serials_on": "2026-11-12",
    "total_30d": 42000000,
    "previous_30d": 35500000,
    "change_pct": 18.3,
    "total_7d": 11200000,
    "average_7d": 1600000,
    "concentration": { "variants": 6, "pct": 63.4, "of": 48 },
    "by_recommendation": [
      { "recommendation": "return", "cost_30d": 21400000, "count": 4 },
      { "recommendation": "faster", "cost_30d": 9800000, "count": 7 }
    ],
    "daily": [
      { "date": "2026-11-10", "cost": 1720000, "average_7d": 1580000, "spike": false, "fresh": true },
      { "date": "2026-11-11", "cost": 1690000, "average_7d": 1600000, "spike": false, "fresh": true }
    ]
  }
}

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

Section titled “🔔 رویدادهای وب‌هوک”
رویداد چه وقت
storage.cost_rising میانگین روزانه‌ی هزینه‌ی ماندگاری سه روز اخیر از میانگین روزانه‌ی چهارده روز پیش از آن بیش از آستانه‌ی هشدار «افزایش هزینه‌ی انبارداری» شما (پیش‌فرض ۵۰ درصد) بیشتر شده است؛ پس از ثبت تراکنش‌های مالی شبانه.

نمونه‌ی پیام storage.cost_rising

{
  "id": "evt_01J0B2M4",
  "type": "storage.cost_rising",
  "created_at": "2026-11-13T04:21:37+03:30",
  "panel_id": 1,
  "livemode": true,
  "data": {
    "end_date": "2026-11-11",
    "recent_daily_average": 2480000,
    "base_daily_average": 1540000,
    "rise_pct": 61,
    "threshold_pct": 50
  }
}

فیلد rise_pct وقتی میانگین پایه صفر باشد null است. پیش از استفاده از هر پیام، امضای آن را بررسی کنید.

💻 نمونه‌کد: کالاهایی که باید برگردند

Section titled “💻 نمونه‌کد: کالاهایی که باید برگردند”
Terminal window
curl "https://api.seller360.ir/v1/storage-costs?recommendation=return&size=100" \
  -H "Authorization: Bearer $S360_API_KEY"

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

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