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

گزارش فروش و آمار رسمی

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

📖 مقدمه

Section titled “📖 مقدمه”

صفحه‌ی «فروش» پنل سلر ۳۶۰ دو نوع گزارش دارد و این صفحه هر دو را پوشش می‌دهد:

  • گزارش فروش سلر ۳۶۰: از روی اقلام سفارش‌ها ساخته می‌شود و سه نما دارد: فروش خالص، مرجوعی و لغو. مبلغ‌ها ناخالص (قیمت × تعداد) و به ریال‌اند. این گزارش درباره‌ی حجم و روند است و رقم سود ندارد؛ سود در سود و زیان است.
  • آمار رسمی دیجی‌کالا: همان اعدادی که دیجی‌کالا بالای نمودار پنل فروشنده نشان می‌دهد: فروش، تعداد، سفارش، بازدید و رضایت، و برای هر کالا بازدید و نرخ تبدیل.

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

کار مسیر در دسترس
گزارش فروش، مرجوعی یا لغو یک بازه GET /v1/reports/sales فعال
فروش هر کالا با روند GET /v1/reports/sales/products فعال
واحدهای مرجوعی و وضعیت آن‌ها GET /v1/reports/sales/returned-units فعال
آمار رسمی دیجی‌کالا GET /v1/reports/official-stats فعال
آمار رسمی هر کالا: بازدید، سفارش و نرخ تبدیل GET /v1/reports/official-stats/products فعال

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

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

دسترسی (Scope)

Section titled “دسترسی (Scope)”
دسترسی برای
reports:read همه‌ی مسیرهای این صفحه
orders:read پیشنهاد می‌شود: برای خواندن سفارش‌ها و رویدادهای سفارش، از جمله order.returned

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

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

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

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

آدرس پایه

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

📊 گزارش فروش

Section titled “📊 گزارش فروش”

سه نمای گزارش (type)

Section titled “سه نمای گزارش (type)”
type برچسب در پنل چه چیزی شمرده می‌شود روی کدام روز
sales «فروش خالص» اقلام فروش؛ لغوشده‌ها بیرون و مرجوعی‌ها کسر شده. روز ثبت سفارش
returns «مرجوعی» اقلامی که دست‌کم یک واحد آن‌ها برگشته است؛ تعداد = واحدهای برگشتی. روز رسیدن واحد برگشتی به انبار
canceled «لغو» اقلام کاملا لغوشده؛ تعداد = کل تعداد قلم. روز ثبت سفارش

فیلدها

Section titled “فیلدها”
فیلد برچسب در پنل معنی
totals.qty «تعداد» تعداد واحد.
totals.amount «فروش ناخالص» مبلغ ناخالص (قیمت × تعداد)، ریال.
totals.orders «سفارش» تعداد اقلام سفارش.
previous_range، previous_totals «دوره‌ی قبل» همان جمع‌ها برای بازه‌ی هم‌اندازه‌ی پیش.
change.amount_pct، change.qty_pct — تغییر نسبت به بازه‌ی پیش، درصد؛ خالی یعنی بازه‌ی پیش صفر بوده است.
daily[] — یک ردیف برای هر روز: date، qty، amount، orders و maybe_incomplete.
mix.payment — ترکیب بازه به تفکیک نوع پرداخت (مثلا «نقدی» و «اعتباری»).
mix.shipping «روش ارسال» ترکیب به تفکیک روش ارسال.
mix.category «دسته‌بندی» ترکیب به تفکیک دسته.
return_conditions «وضعیت کالای برگشتی» فقط برای returns: تعداد واحدهای resellable، defective و unknown.
data_freshness — تازگی داده (بخش تازگی).

هر گروه mix شش گروه بزرگ‌تر و یک گروه «سایر» دارد؛ کلید _ یعنی مقدار نامشخص و _rest یعنی «سایر».

روند هر کالا (trend)

Section titled “روند هر کالا (trend)”
مقدار معنی
rising رو به رشد: دست‌کم ۲۵ درصد بیشتر از بازه‌ی پیش و دست‌کم ۳ واحد.
falling رو به کاهش: دست‌کم ۲۵ درصد کمتر از بازه‌ی پیش.
flat ثابت.
new تازه: بازه‌ی پیش فروشی نداشت.

وضعیت واحد برگشتی (return_condition)

Section titled “وضعیت واحد برگشتی (return_condition)”
مقدار برچسب در پنل معنی
resellable «قابل فروش مجدد» واحد سالم برگشته و دوباره فروختنی است.
defective «معیوب» واحد معیوب برگشته است.
unknown «نامشخص» دیجی‌کالا هنوز چیزی ثبت نکرده است که حکم را روشن کند.

حکم بر پایه‌ی آن چیزی است که دیجی‌کالا برای همان سریال ثبت کرده است. منبع حکم در return_condition_source می‌آید: status وضعیت سریال، agent_note یادداشت کارشناس، reason دلیل مرجوعی، و خالی یعنی نامعلوم.

🔢 تازگی و روزهای ناپایدار

Section titled “🔢 تازگی و روزهای ناپایدار”

گزارش فروش

Section titled “گزارش فروش”

سفارش‌ها هر شب و پس از هر رویداد سفارش دیجی‌کالا خوانده می‌شوند. شیء data_freshness می‌گوید تا کجا می‌توانید به ارقام اتکا کنید:

فیلد معنی
last_sync_at زمان آخرین دریافت سفارش‌ها.
hours_since_sync چند ساعت از آخرین دریافت گذشته است.
unsettled_days چند روز پیش از آخرین دریافت ممکن است هنوز تغییر کند؛ اکنون 2.
incomplete_from اولین روزی که ارقامش ممکن است هنوز تغییر کند.

دلیل روزهای ناپایدار: سفارش شب پیش از یک دریافت ممکن است پس از آن به فهرست دیجی‌کالا برسد، و وضعیت هر قلم (لغو، مرجوعی) در یکی دو روز بعد قطعی می‌شود. روزهای پس از آخرین دریافت اصلا خوانده نشده‌اند. در daily[]، روزهای ناپایدار maybe_incomplete: true دارند؛ برچسب آن در پنل «ممکن است هنوز کامل نباشد» است.

آمار رسمی دیجی‌کالا

Section titled “آمار رسمی دیجی‌کالا”

آمار رسمی در هر درخواست مستقیم از دیجی‌کالا خوانده می‌شود و زمان آن در fetched_at است. دیجی‌کالا فروش را از لحظه‌ی ثبت سفارش می‌شمارد؛ پس این اعداد برای روزهای اخیر از گزارش فروش جلوتر است. بازه‌ها فقط سه مقدار دارند: last_7_days (پیش‌فرض)، last_14_days و last_30_days.

⚠️ هشدارها

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

📡 مسیرها

Section titled “📡 مسیرها”

GET /v1/reports/sales — گزارش فروش، مرجوعی یا لغو فعال

Section titled “GET /v1/reports/sales — گزارش فروش، مرجوعی یا لغو ”
GET /v1/reports/sales?type=sales&date_from=2026-10-23&date_to=2026-11-11 HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
پارامتر نوع اجباری توضیح
type متن خیر sales (پیش‌فرض)، returns یا canceled.
date_from تاریخ خیر اولین روز بازه (میلادی). بدون بازه، از ابتدای ماه شمسی جاری تا امروز.
date_to تاریخ خیر آخرین روز بازه، شامل همان روز؛ هر بازه حداکثر ۴۰۰ روز.

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

{
  "status": "ok",
  "data": {
    "type": "sales",
    "range": { "from": "2026-10-23", "to": "2026-11-11", "days": 20 },
    "totals": { "qty": 96, "amount": 3540000000, "orders": 88 },
    "previous_range": { "from": "2026-10-03", "to": "2026-10-22", "days": 20 },
    "previous_totals": { "qty": 88, "amount": 3150000000, "orders": 81 },
    "change": { "amount_pct": 12.4, "qty_pct": 9.1 },
    "daily": [
      { "date": "2026-11-09", "qty": 5, "amount": 183500000, "orders": 5, "maybe_incomplete": false },
      { "date": "2026-11-10", "qty": 4, "amount": 146800000, "orders": 4, "maybe_incomplete": true },
      { "date": "2026-11-11", "qty": 3, "amount": 110100000, "orders": 3, "maybe_incomplete": true }
    ],
    "mix": {
      "payment": [ { "key": "نقدی", "label": "نقدی", "amount": 2900000000, "qty": 79 },
                   { "key": "اعتباری", "label": "اعتباری", "amount": 640000000, "qty": 17 } ],
      "shipping": [],
      "category": []
    },
    "data_freshness": {
      "last_sync_at": "2026-11-11T22:40:05+03:30",
      "incomplete_from": "2026-11-10",
      "unsettled_days": 2,
      "hours_since_sync": 6
    }
  }
}

در این نمونه آخرین دریافت ۲۰ آبان ساعت ۲۲:۴۰ بوده است؛ پس ارقام ۱۹ و ۲۰ آبان (2026-11-10 و 2026-11-11) ممکن است هنوز تغییر کنند.

GET /v1/reports/sales/products — فروش هر کالا فعال

Section titled “GET /v1/reports/sales/products — فروش هر کالا ”

هر گروه کالا در بازه، بیشترین تعداد اول، با مقایسه‌ی تعداد با بازه‌ی هم‌اندازه‌ی پیش و برچسب روند.

پارامتر نوع اجباری توضیح
type متن خیر sales، returns یا canceled.
date_from، date_to تاریخ خیر بازه.
by متن خیر variant هر تنوع (پیش‌فرض)، dkp هر کالا، supplier هر کد فروشنده.
page، size عدد خیر صفحه‌بندی. 
{
  "key": "v84780448", "variant_id": 84780448, "variants": 1, "product_id": 22961150, "supplier_code": "5144",
  "title": "محافظ ولتاژ پارت الکتریک مدل PE5144", "image_url": null,
  "qty": 12, "amount": 440400000, "orders": 11, "avg_price": 36700000,
  "prev_qty": 8, "growth_pct": 50.0, "trend": "rising"
}

برچسب‌های ستون در پنل: «کالا»، «تعداد»، «فروش ناخالص»، «سفارش»، «میانگین قیمت» و «روند». برای type=returns، هر ردیف return_conditions هم دارد.

GET /v1/reports/sales/returned-units — واحدهای مرجوعی فعال

Section titled “GET /v1/reports/sales/returned-units — واحدهای مرجوعی ”

هر واحدی که در بازه برگشته است، تازه‌ترین اول، حداکثر ۵۰۰ واحد. با condition فقط یک وضعیت را بخوانید (resellable، defective یا unknown).

{
  "serial": "8BAC741A", "order_id": 372597331, "variant_id": 75670684, "product_id": 22961150, "supplier_code": "5144",
  "title": "محافظ ولتاژ پارت الکتریک مدل PE5144",
  "returned_at": "2026-11-04T13:22:10+03:30",
  "reason": "مشکلات فنی / معیوب", "digikala_status": "مرجوعی",
  "return_condition": "defective", "return_condition_source": "reason",
  "penalized": false
}

penalized برابر true یعنی دیجی‌کالا برای این واحد جریمه‌ی مرجوعی کالای اشتباه یا معیوب ثبت کرده است (رویداد penalty.created در تراکنش‌های مالی).

GET /v1/reports/official-stats — آمار رسمی دیجی‌کالا فعال

Section titled “GET /v1/reports/official-stats — آمار رسمی دیجی‌کالا ”
GET /v1/reports/official-stats?range=last_7_days HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
فیلد برچسب در پنل معنی
summary.net_sales «فروش خالص» فروش خالص بازه به ریال، به گزارش دیجی‌کالا.
summary.items «واحد فروخته‌شده» واحدهای فروخته‌شده‌ی خالص.
summary.orders «سفارش» تعداد سفارش.
summary.visits «بازدید» بازدید صفحه‌های کالاهای شما.
summary.satisfaction «رضایت خریداران» رضایت مشتری به روایت دیجی‌کالا.
summary.*_pct — تغییر نسبت به بازه‌ی پیش، اگر دیجی‌کالا بدهد.
chart[] «روند روزانه · فروش خالص و بازدید» برای هر روز: gross_sales، net_sales، items، visits، orders.
fetched_at — زمان دریافت این اعداد از دیجی‌کالا. 
{
  "status": "ok",
  "data": {
    "range": "last_7_days",
    "summary": {
      "net_sales": 3612000000, "net_sales_pct": 6.2,
      "items": 99, "items_pct": 4.2,
      "orders": 91, "orders_pct": 3.4,
      "visits": 14820, "visits_pct": -2.1,
      "satisfaction": 4.3, "satisfaction_pct": null
    },
    "chart": [
      { "date": "2026-11-12", "gross_sales": 541000000, "net_sales": 512000000, "items": 14, "visits": 2104, "orders": 13 }
    ],
    "fetched_at": "2026-11-13T10:02:44+03:30"
  }
}

GET /v1/reports/official-stats/products — آمار رسمی هر کالا فعال

Section titled “GET /v1/reports/official-stats/products — آمار رسمی هر کالا ”

بازدید، سفارش و نرخ تبدیل هر کالا (سطح DKP) به روایت دیجی‌کالا. پارامترها: range و صفحه‌بندی.

فیلد برچسب در پنل معنی
product_id «DKP» عدد کد کالا.
gross_sales، net_sales «فروش ناخالص»، «فروش خالص» ریال.
gross_items، net_items «تعداد» واحدها.
visits «بازدید» تعداد بازدید صفحه‌ی این کالا در دیجی‌کالا در همین بازه.
orders «سفارش» تعداد سفارش.
conversion_rate «نرخ تبدیل» نرخ تبدیل بازدید به سفارش، درصد با یک رقم اعشار. 
{
  "product_id": 22961150, "title": "محافظ ولتاژ پارت الکتریک مدل PE5144", "image_url": null,
  "gross_sales": 478000000, "net_sales": 440400000, "gross_items": 13, "net_items": 12,
  "visits": 1830, "orders": 11, "conversion_rate": 0.6
}

خطاهای مسیرهای این صفحه

کد HTTP خطا معنی تکرار بی‌خطر است؟
400 invalid_parameter پارامتر نامعتبر است (مثلا type یا range ناشناخته، یا بازه‌ی بیش از ۴۰۰ روز). خیر؛ پارامتر را اصلاح کنید.
403 scope_missing کلید دسترسی reports:read را ندارد. خیر.
409 demo_panel_unsupported آمار رسمی در پنل نمایشی در دسترس نیست. خیر.
429 rate_limited سقف درخواست این کلید پر شده است. بله، پس از Retry-After.
502 digikala_refused دیجی‌کالا پاسخ نامعتبر داد (فقط آمار رسمی). بله، کمی بعد.
503 digikala_rate_limited سقف دیجی‌کالا پر است (فقط آمار رسمی). بله، پس از Retry-After.
503 digikala_unavailable دیجی‌کالا در دسترس نیست (فقط آمار رسمی). بله، پس از Retry-After.

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

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

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

گزارش فروش و آمار رسمی رویداد جدای خود ندارند. برای خبر فوری از مرجوعی، رویداد order.returned را با دسترسی orders:read دریافت کنید؛ این رویداد در بخش «سفارش و ارسال» توضیح داده شده است.

نمونه‌ی پیام order.returned (کوتاه‌شده)

{
  "id": "evt_01J0E4R7",
  "type": "order.returned",
  "created_at": "2026-11-04T13:30:02+03:30",
  "panel_id": 1,
  "livemode": true,
  "data": {
    "order": { "order_id": 372597331 },
    "returns": [
      { "order_id": 372597331, "variant_id": 75670684, "product_id": 22961150, "supplier_code": "5144",
        "title": "محافظ ولتاژ پارت الکتریک مدل PE5144", "quantity": 1, "returned_quantity": 1,
        "returned_at": "2026-11-04T13:22:10+03:30" }
    ]
  }
}

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

💻 نمونه‌کد: فروش قطعی روزبه‌روز

Section titled “💻 نمونه‌کد: فروش قطعی روزبه‌روز”

این نمونه گزارش فروش را می‌خواند و روزهای ناپایدار را جدا می‌کند (هشدار ۳).

Terminal window
curl -G https://api.seller360.ir/v1/reports/sales \
  -H "Authorization: Bearer $S360_API_KEY" \
  --data-urlencode "type=sales" \
  --data-urlencode "date_from=2026-10-23" \
  --data-urlencode "date_to=2026-11-11"

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

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