سود و زیان و مالیات

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

📖 مقدمه

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

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

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

کار	مسیر	در دسترس
خلاصه‌ی سود و زیان یک بازه با مقایسه	GET /v1/reports/profit/summary	فعال
سود و زیان روزانه	GET /v1/reports/profit/daily	فعال
سود و زیان ماهانه‌ی یک سال شمسی	GET /v1/reports/profit/monthly	فعال
سود و زیان هر کالا	GET /v1/reports/profit/products	فعال
کسورات دیجی‌کالا به تفکیک	GET /v1/reports/profit/deductions	فعال
گزارش مالیات بر ارزش افزوده‌ی یک فصل	GET /v1/reports/vat	فعال
فهرست هزینه‌ها	GET /v1/finance/expenses	فعال
ثبت هزینه	POST /v1/finance/expenses	فعال
خواندن، ویرایش و حذف یک هزینه	GET، PUT، DELETE /v1/finance/expenses/{expense_id}	فعال
نرخ کمیسیون هر دسته و برند	GET /v1/finance/commission-rates	فعال

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

دسترسی (Scope)

دسترسی	برای
reports:read	همه‌ی مسیرهای /v1/reports/profit/* و /v1/reports/vat
finance:read	خواندن هزینه‌ها و نرخ کمیسیون
finance:write	ثبت، ویرایش و حذف هزینه

هزینه‌ها فقط در سلر ۳۶۰ ثبت می‌شوند و چیزی در دیجی‌کالا تغییر نمی‌کند. قیمت خرید کالاها در بخش خرید ثبت می‌شود و دسترسی جدای خود را دارد. جزئیات کلید در ورود و دسترسی‌ها است.

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

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

آدرس پایه

https://api.seller360.ir

🧮 صورت سود و زیان

سه قاعده‌ی موتور سود

1. روز فروش (تعهدی). هر رقم روی روز فروشی می‌نشیند که به آن تعلق دارد، نه روزی که پول جابه‌جا شده است. مرجوعی و کسورات برگشتی آن، از روی سریال، به روز فروش همان واحد برده می‌شوند. هزینه‌هایی که به هیچ فروشی تعلق ندارند (ماندگاری، حمل، جریمه) روی روزی می‌نشینند که دیجی‌کالا ثبت کرده است.
2. هر روز یک منبع. از اولین روز تراکنش‌های پنل (range.cutover) فقط ردیف‌های مالی شمرده می‌شوند؛ پیش از آن، صورت‌حساب‌های قدیمی که پیش از آن روز به پایان رسیده‌اند.
3. قیمت خرید نامعلوم هرگز سود نیست و حدس زده نمی‌شود. سود فقط برای واحدهایی حساب می‌شود که در روز فروش قیمت خرید دارند؛ بقیه کنار گذاشته می‌شوند و هر جمع می‌گوید چه مقدار کنار رفته است.

آبشار سود و زیان (waterfall)

key	عنوان در پنل	معنی
sales	«فروش ناخالص»	فروش بدون مالیات.
returns	«مرجوعی (پس از کسورات برگشتی)»	برگشت از فروش به‌اضافه‌ی کسوراتی که دیجی‌کالا بابت مرجوعی برگرداند.
deductions	«کسورات دیجی‌کالا»	کمیسیون، پلتفرم، پردازش و ارسال، ماندگاری، حمل، جریمه، سایر، و مالیات.
net_payout	«خالص دریافتی از دیجی‌کالا»	جمع میانی.
unpriced	«فروش بدون قیمت خرید (در سود حساب نشده است)»	سهم فروش‌های بدون قیمت خرید از خالص دریافتی.
cost	«بهای خرید»	بهای خرید ثبت‌شده‌ی واحدهای دارای قیمت.
expenses	«هزینه‌های من»	هزینه‌هایی که ثبت کرده‌اید.
net_profit	«سود خالص»	جمع نهایی.

هر سطر amount (با علامت)، kind (line، subtotal یا total)، pct_of_sales و تفکیک parts دارد.

فیلدهای جمع (ProfitTotals)

همه‌ی جمع‌ها، چه برای یک بازه، چه یک روز، ماه یا کالا، این فیلدها را دارند:

فیلد	برچسب در پنل	معنی
sales	«فروش ناخالص»	فروش بدون مالیات.
units	«تعداد»	واحدهای فروخته‌شده.
returns	«برگشت از فروش»	منفی.
return_refund	«کسورات برگشتی بابت مرجوعی»	مثبت.
returns_net	«مرجوعی»	returns + return_refund
units_returned	—	واحدهای برگشتی.
deductions_by	«کسورات»	به تفکیک: commission، platform، fulfilment، storage، freight، penalty، other، tax.
deductions	«کسورات»	جمع کسورات با مالیات (منفی).
tax	«مالیات بر ارزش افزوده»	مالیات درون ردیف‌ها (درون deductions).
net_payout	«خالص دریافتی»	خالص دریافتی از دیجی‌کالا.
cost_known	«بهای خرید ثبت‌شده»	بهای خرید واحدهای دارای قیمت (مثبت).
expenses	«هزینه‌های من»	هزینه‌های شما (مثبت)؛ به تفکیک expenses_general («هزینه‌ی عمومی») و expenses_products («روی فروش کالاها»).
period_costs	—	کسوراتی که به هیچ کالایی تعلق ندارند (مثل حمل محموله).
profit_certain	—	سود واحدهای دارای قیمت خرید، پیش از کسورات بدون کالا و هزینه‌های عمومی.
net_profit	«سود خالص»	خالی (null) یعنی نامعلوم، نه صفر.
margin_pct	«حاشیه‌ی سود»	سود خالص نسبت به فروش پوشش‌داده‌شده.
real_pct	—	سود نسبت به بهای خرید.
nominal_pct	—	سود نسبت به فروش.
units_settled	—	واحدهای تسویه‌شده.
status	«وضعیت»	قطعی، تخمینی، ترکیبی یا بدون فروش (جدول پایین).

sales + returns_net + deductions                    = net_payout
net_payout − unpriced_net − cost_known − expenses   = net_profit

پوشش قیمت خرید

فیلد	برچسب در پنل	معنی
profit_covered_sales	—	فروش ناخالص واحدهایی که قیمت خرید دارند و سودشان حساب شده است.
unpriced_sales	«فروش بدون قیمت خرید»	فروش ناخالص واحدهای بدون قیمت خرید که در سود حساب نشده است.
unpriced_sales_pct	—	سهم فروش بدون قیمت خرید، درصد.
unpriced_units	«بی‌قیمت خرید»	تعداد واحدهای بدون قیمت خرید.
unpriced_net	—	خالص دریافتی فروش‌های بدون قیمت خرید.
accuracy_pct	«دقت محاسبات»	سهم واحدهای فروخته‌شده‌ی دارای قیمت خرید، درصد بدون اعشار.
profit_partial	—	true یعنی سود فقط بخشی از فروش را پوشش می‌دهد.
units_costed، units_missing_cost، products_missing_cost	—	شمار واحدها و کالاهای دارای و بدون قیمت.

🔄 وضعیت سود

وضعیت	برچسب در پنل	معنی
final	«قطعی»	همه‌ی واحدهای فروخته‌شده تسویه شده‌اند. روزهای پیش از اولین تراکنش (صورت‌حساب‌های قدیم) هم قطعی‌اند.
estimated	«تخمینی»	هنوز هیچ واحدی تسویه نشده است.
mixed	«ترکیبی»	بخشی تسویه شده است.
empty	«بدون فروش»	روز بدون فروش و بدون ردیف.

روزی که فروش ندارد اما ردیف دارد (مثلا فقط ماندگاری)، از روی ردیف‌های تسویه‌شده‌اش همین وضعیت را می‌گیرد. خلاصه‌ی بازه تعداد روزهای هر وضعیت را در days_by_status می‌دهد.

خطای تخمین: سلر ۳۶۰ اولین تخمین سود هر روز را تا ۹۰ روز نگه می‌دارد. وقتی روز قطعی شد، estimate_error در گزارش روزانه فاصله‌ی آن تخمین با سود قطعی را نشان می‌دهد (rial = قطعی منهای تخمین؛ مثبت یعنی بهتر از تخمین). برچسب آن در پنل «خطای تخمین» است.

🔢 تازگی

• منبع: همه‌ی گزارش‌های این صفحه از ردیف‌های مالی ساخته می‌شوند که هر شب ساعت ۰۴:۰۵ به وقت تهران همگام می‌شوند. پاسخ‌ها شیء تازگی (finance یا meta.finance) را با synced_at، history_complete، oldest_date و stale دارند (تراکنش‌های مالی).
• ارقام تخمینی تا تسویه تغییر می‌کنند: روزهای estimated و mixed را پس از هر همگام‌سازی دوباره بخوانید. رسیدن رویداد payout.created نشانه‌ی خوبی برای خواندن دوباره است.

⚠️ هشدارها

۱. سود خالی یعنی نامعلوم، نه صفر

اگر هیچ واحدی از یک کالا یا بازه قیمت خرید نداشته باشد، net_profit و profit برابر null است. آن را صفر نشان ندهید و در جمع‌ها صفر حساب نکنید. اگر برخی واحدها قیمت داشته باشند، سود فقط همان‌هاست و unpriced_units می‌گوید چند واحد بیرون مانده است. حاشیه‌ی سود (margin_pct) سود نسبت به فروش پوشش‌داده‌شده است، نه کل فروش.

۲. سود روی روز فروش است، نه روز واریز

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

۳. هیچ گزارشی صورت‌حساب‌های قدیم و تراکنش‌ها را با هم جمع نمی‌کند

صورت‌حساب‌هایی که دوره‌شان به اولین روز تراکنش‌ها می‌رسد، دوباره به‌صورت تراکنش صادر شده‌اند (برای یک پنل، صورت‌حساب‌های ۱۶ تا ۳۱ شهریور ۱۴۰۵). گزارش‌ها برای روزهای پیش از range.cutover فقط صورت‌حساب‌هایی را می‌شمارند که پیش از آن روز تمام شده‌اند. ارقام صورت‌حساب‌های قدیم را از منبع دیگری به این گزارش اضافه نکنید.

۴. مالیات گزارش، مالیات درون ردیف‌های دیجی‌کالاست

tax و vat جمع مالیاتی است که درون ردیف‌های مالی دیجی‌کالا آمده است و جزو کسورات (منفی) شمرده می‌شود. این عدد اظهارنامه‌ی مالیاتی شما را نمی‌سازد؛ برای اظهارنامه آن را در کنار فروش و برگشت از فروش فصل با مشاور مالیاتی خود بررسی کنید.

۵. هزینه‌ی تنوع حذف‌شده حساب نمی‌شود

اگر تنوعی که هزینه به آن تعلق داشت از پنل حذف شود، variant_missing برابر true می‌شود و آن هزینه در محاسبه منظور نمی‌شود. هزینه را ویرایش کنید و به تنوع دیگری یا به «همه‌ی فروش‌ها» (variant_id خالی) نسبت دهید.

۶. ویرایش هزینه همه‌ی فیلدها را جایگزین می‌کند

PUT /v1/finance/expenses/{expense_id} یک جایگزینی کامل است: فیلدی که ارسال نکنید مقدار پیش‌فرض خود را می‌گیرد (مثلا per_unit برابر false و category برابر other). همیشه هزینه را کامل بفرستید.

📡 مسیرها

همه‌ی گزارش‌ها بازه را با date_from و date_to (میلادی، شامل هر دو روز) می‌گیرند. بدون این دو، بازه از ابتدای ماه شمسی جاری تا امروز است. هر بازه حداکثر ۴۰۰ روز است.

GET /v1/reports/profit/summary — خلاصه‌ی سود و زیان فعال

صورت سود و زیان از بالا به پایین، شاخص‌ها، و همان شاخص‌ها برای بازه‌ی هم‌اندازه‌ی پیش از آن.

GET /v1/reports/profit/summary?date_from=2026-10-23&date_to=2026-11-11 HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...

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

{
  "status": "ok",
  "data": {
    "range": { "from": "2026-10-23", "to": "2026-11-11", "days": 20, "cutover": "2026-09-07" },
    "previous_range": { "from": "2026-10-03", "to": "2026-10-22", "days": 20, "cutover": "2026-09-07" },
    "kpis": { "sales": 3820000000, "net_profit": 331917117, "margin_pct": 9.2, "accuracy_pct": 93, "units": 104,
              "profit_covered_sales": 3610000000, "unpriced_sales": 210000000, "unpriced_sales_pct": 5.5, "unpriced_units": 7 },
    "previous": { "sales": 3524000000, "net_profit": 342600000, "margin_pct": 10.4, "accuracy_pct": 91, "units": 97,
                  "profit_covered_sales": 3290000000, "unpriced_sales": 234000000, "unpriced_sales_pct": 6.6, "unpriced_units": 8 },
    "change": { "sales_pct": 8.4, "net_profit_pct": -3.1, "margin_pts": -1.2, "accuracy_pts": 2 },
    "waterfall": [
      { "key": "sales", "title": "فروش ناخالص", "amount": 3820000000, "kind": "line", "pct_of_sales": 100.0, "parts": [] },
      { "key": "returns", "title": "مرجوعی (پس از کسورات برگشتی)", "amount": -84800000, "kind": "line", "pct_of_sales": -2.2, "parts": [] },
      { "key": "deductions", "title": "کسورات دیجی‌کالا", "amount": -740282883, "kind": "line", "pct_of_sales": -19.4,
        "parts": [ { "key": "commission", "title": "کمیسیون فروش", "amount": -458400000, "pct_of_sales": -12.0 } ] },
      { "key": "net_payout", "title": "خالص دریافتی از دیجی‌کالا", "amount": 2994917117, "kind": "subtotal", "pct_of_sales": 78.4, "parts": [] },
      { "key": "unpriced", "title": "فروش بدون قیمت خرید (در سود حساب نشده است)", "amount": -168000000, "kind": "line", "pct_of_sales": -4.4, "parts": [] },
      { "key": "cost", "title": "بهای خرید", "amount": -2410000000, "kind": "line", "pct_of_sales": -63.1, "parts": [] },
      { "key": "expenses", "title": "هزینه‌های من", "amount": -85000000, "kind": "line", "pct_of_sales": -2.2, "parts": [] },
      { "key": "net_profit", "title": "سود خالص", "amount": 331917117, "kind": "total", "pct_of_sales": 8.7, "parts": [] }
    ],
    "days_by_status": { "final": 9, "estimated": 4, "mixed": 6, "empty": 1 },
    "totals": { "sales": 3820000000, "net_payout": 2994917117, "net_profit": 331917117, "status": "mixed" },
    "finance": { "synced_at": "2026-11-12T04:07:41+03:30", "history_complete": true, "oldest_date": "2025-11-12", "stale": false }
  }
}

GET /v1/reports/profit/daily — سود و زیان روزانه فعال

یک ردیف برای هر روز بازه، حتی روز بدون فروش (status برابر empty)، همراه با estimate_error برای روزهای قطعی. پاسخ: range، days[]، totals و finance.

{
  "date": "2026-11-02", "sales": 183500000, "units": 5, "net_payout": 143870000, "cost_known": 120500000,
  "expenses": 4250000, "net_profit": 19120000, "status": "final",
  "estimate_error": { "estimated": 17820000, "rial": 1300000, "pct": 7.3, "estimated_on": "2026-11-03" }
}

GET /v1/reports/profit/monthly — سود و زیان ماهانه فعال

دوازده ماه یک سال شمسی و جمع سال. هر ماه jy، jm، label (مثلا «آبان 1405»)، from، to و همه‌ی فیلدهای جمع را دارد.

پارامتر	نوع	اجباری	توضیح
year	عدد	خیر	سال شمسی (از ۱۳۹۰)؛ بدون آن، سال جاری.

GET /v1/reports/profit/products — سود و زیان هر کالا فعال

یک ردیف برای هر گروه کالا. هزینه‌هایی که به هیچ کالایی تعلق ندارند در meta.unassigned (period_costs و expenses_general) می‌آیند تا جمع ردیف‌ها با کل یکی بماند.

پارامتر	نوع	اجباری	توضیح
date_from، date_to	تاریخ	خیر	بازه.
by	متن	خیر	variant هر تنوع (پیش‌فرض)، dkp هر کالا، supplier هر کد فروشنده.
filter	متن	خیر	all همه، بیشترین فروش اول (پیش‌فرض)؛ profitable سودده، بیشترین سود اول؛ loss زیان‌ده، بیشترین زیان اول؛ no_cost هر کالایی که دست‌کم یک واحد بدون قیمت خرید دارد.
page، size	عدد	خیر	صفحه‌بندی.

هر ردیف علاوه بر فیلدهای جمع، state دارد: profitable («سودآور»)، loss («زیان‌ده») یا no_cost (بدون قیمت خرید). meta.counts تعداد کالاهای هر گروه را برای ساخت زبانه‌ها می‌دهد.

{
  "key": "v84780448", "variant_id": 84780448, "variants": 1, "product_id": 22961150, "supplier_code": "5144",
  "title": "محافظ ولتاژ پارت الکتریک مدل PE5144",
  "sales": 440400000, "units": 12, "returns_net": -32600000, "units_returned": 1,
  "deductions": -83400000, "storage": 0, "net_payout": 324400000,
  "cost": 265100000, "cost_missing_units": 0, "expenses": 0,
  "profit": 59300000, "margin_pct": 13.5, "profit_partial": false, "status": "final", "state": "profitable"
}

GET /v1/reports/profit/deductions — کسورات به تفکیک فعال

هر سرفصل کسورات (headings[]: key، title، amount، count، pct_of_sales، prev_amount، change_pct، change_pts) با مقایسه با بازه‌ی پیش؛ جریمه‌ها به تفکیک عنوان دیجی‌کالا و کالا (penalties[])؛ و حداکثر ۱۰۰ کالا با بیشترین هزینه‌ی ماندگاری (storage_by_product[]).

key	عنوان
commission	کمیسیون فروش
platform	هزینه توسعه پلتفرم (فروش اعتباری)
fulfilment	هزینه پردازش و ارسال
storage	هزینه ماندگاری در انبار
freight	هزینه حمل بین فروشنده و دیجی‌کالا
penalty	جریمه‌ها
other	سایر کسورات
tax	مالیات بر ارزش افزوده (count آن خالی است)

GET /v1/reports/vat — گزارش مالیات فصلی فعال

سه ماه یک فصل شمسی و جمع فصل، برای اظهارنامه‌ی ارزش افزوده.

GET /v1/reports/vat?year=1405&season=3 HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...

پارامتر	نوع	اجباری	توضیح
year	عدد	خیر	سال شمسی؛ بدون آن، سال جاری.
season	1 تا 4	بله	1 بهار، 2 تابستان، 3 پاییز، 4 زمستان.

فیلد	برچسب در پنل	معنی
sales	«فروش»	فروش ناخالص بدون مالیات.
units	«تعداد»	واحدهای فروخته‌شده.
returns_net	«مرجوعی»	برگشت از فروش پس از کسورات برگشتی.
net_sales	«فروش خالص»	فروش منهای برگشت از فروش.
deductions_ex_vat	«کسورات بدون مالیات»	منفی.
vat	«مالیات بر ارزش افزوده»	با علامت.
net_payout	«خالص دریافتی»	خالص دریافتی از دیجی‌کالا.

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

{
  "status": "ok",
  "data": {
    "year": 1405, "season": 3, "label": "پاییز 1405",
    "range": { "from": "2026-09-23", "to": "2026-12-21", "days": 90, "cutover": "2026-09-07" },
    "months": [
      { "jy": 1405, "jm": 7, "label": "مهر 1405", "from": "2026-09-23", "to": "2026-10-22",
        "sales": 5600000000, "units": 156, "returns_net": -124000000, "net_sales": 5459000000,
        "deductions_ex_vat": -995000000, "vat": -91000000, "net_payout": 4390000000,
        "deductions_by": { "commission": -672000000, "platform": -31000000, "fulfilment": -280000000, "storage": -6000000,
                           "freight": -2000000, "penalty": -4000000, "other": 0, "tax": -91000000 } }
    ],
    "totals": { "sales": 11420000000, "units": 318, "returns_net": -254000000, "net_sales": 11132000000,
                "deductions_ex_vat": -2030000000, "vat": -186000000, "net_payout": 8950000000 },
    "finance": { "synced_at": "2026-11-12T04:07:41+03:30", "history_complete": true, "oldest_date": "2025-11-12", "stale": false }
  }
}

GET /v1/finance/expenses — فهرست هزینه‌ها فعال

تازه‌ترین ثبت اول. فیلترها: kind، category، variant_id، و صفحه‌بندی.

فیلد	برچسب در پنل	معنی
id	—	شناسه‌ی هزینه.
title	«عنوان»	عنوان هزینه؛ ۱ تا ۱۲۰ نویسه.
category	«دسته‌بندی»	packaging «بسته‌بندی»، salary «حقوق»، rent «اجاره»، ads «تبلیغات»، courier «پیک»، tools «ابزار»، other «سایر».
amount	«مبلغ»	به ریال، همیشه مثبت.
kind	«نوع»	one_off «یک‌باره» یا monthly «ماهانه».
date	—	روز هزینه‌ی یک‌باره.
start_date، end_date	—	بازه‌ی هزینه‌ی ماهانه؛ end_date خالی یعنی بدون پایان.
variant_id	«مربوط به»	تنوعی که هزینه به آن تعلق دارد؛ خالی یعنی «همه‌ی فروش‌ها».
per_unit	—	true یعنی مبلغ به ازای هر واحد فروخته‌شده است.
variant_missing	—	تنوع حذف شده است و هزینه حساب نمی‌شود (هشدار ۵).
note	—	یادداشت؛ حداکثر ۳۰۰ نویسه.

POST /v1/finance/expenses — ثبت هزینه فعال

هزینه‌ی یک‌باره کل مبلغ را روی date می‌نشاند. هزینه‌ی ماهانه از start_date تا end_date (یا بدون پایان) هر ماه شمسی، به‌طور یکسان روی روزهای همان ماه پخش می‌شود. با per_unit مبلغ به ازای هر واحد فروخته‌شده حساب می‌شود (واحدهای همان تنوع، یا همه‌ی فروش‌ها). سرآیند Idempotency-Key لازم است (کلید یکتای درخواست).

POST /v1/finance/expenses HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: exp-packaging-1405-08
Content-Type: application/json

{
  "title": "کارتن و نوار چسب آبان",
  "category": "packaging",
  "amount": 85000000,
  "kind": "monthly",
  "start_date": "2026-10-23",
  "end_date": null,
  "variant_id": null,
  "per_unit": false
}

فیلد بدنه	نوع	اجباری	توضیح
title	متن	بله	۱ تا ۱۲۰ نویسه.
amount	عدد	بله	ریال؛ از ۱ تا ۹٬۹۹۹٬۹۹۹٬۹۹۹٬۹۹۹.
category	متن	خیر	پیش‌فرض other.
kind	متن	خیر	پیش‌فرض one_off.
date	تاریخ	برای one_off	روز هزینه.
start_date	تاریخ	برای monthly	اولین روز.
end_date	تاریخ یا null	خیر	برای monthly؛ پیش از start_date نباشد.
variant_id	عدد یا null	خیر	تنوعی از همین پنل؛ خالی یعنی همه‌ی فروش‌ها.
per_unit	true یا false	خیر	پیش‌فرض false.
note	متن	خیر	حداکثر ۳۰۰ نویسه.

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

{
  "status": "ok",
  "data": {
    "id": 418, "title": "کارتن و نوار چسب آبان", "category": "packaging", "amount": 85000000, "kind": "monthly",
    "date": null, "start_date": "2026-10-23", "end_date": null, "variant_id": null, "variant_missing": false,
    "per_unit": false, "note": "", "created_at": "2026-11-12T10:15:03+03:30", "updated_at": "2026-11-12T10:15:03+03:30"
  }
}

خطاهای ثبت، ویرایش و حذف هزینه

کد HTTP	خطا	معنی	تکرار بی‌خطر است؟
400	invalid_parameter	فیلدی نامعتبر است (مثلا date برای هزینه‌ی یک‌باره نیامده یا end_date پیش از start_date است).	خیر؛ بدنه را اصلاح کنید.
400	idempotency_key_required	سرآیند Idempotency-Key ارسال نشده است.	بله، با افزودن سرآیند.
403	scope_missing	کلید دسترسی finance:write را ندارد.	خیر.
404	variant_not_found	variant_id در این پنل نیست.	خیر؛ تنوع را بررسی کنید.
404	not_found	هزینه‌ای با این شناسه نیست (ویرایش و حذف).	خیر.
409	idempotency_mismatch	این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است.	خیر؛ کلید تازه بسازید.
409	idempotency_in_progress	درخواستی با همین کلید در حال انجام است.	بله، چند ثانیه بعد.
429	rate_limited	سقف درخواست این کلید پر شده است.	بله، پس از Retry-After.

GET، PUT، DELETE /v1/finance/expenses/{expense_id} — یک هزینه فعال

GET همان ساختار را برمی‌گرداند. PUT همه‌ی فیلدها را با بدنه‌ی تازه جایگزین می‌کند (هشدار ۶) و هزینه پس از ویرایش را برمی‌گرداند. DELETE هزینه را حذف می‌کند و پاسخ {"id": 418, "deleted": true} در data می‌دهد. هر دو تغییر Idempotency-Key لازم دارند و خطاهایشان همان جدول بالاست.

GET /v1/finance/commission-rates — نرخ کمیسیون فعال

نرخ کمیسیون هر دسته و برند، به ترتیب نام دسته و برند. فیلترها: category_id، brand_id، و صفحه‌بندی.

{
  "category_id": 8597, "category_title": "محافظ ولتاژ",
  "main_category_id": 5966, "main_category_title": "لوازم برقی",
  "brand_id": 1532, "brand_title": "پارت الکتریک",
  "commission_pct": 12.0, "extra_commission_pct": null, "return_free_commission_pct": null,
  "current_lead_time": 1, "synced_at": "2026-11-12T04:20:11+03:30"
}

commission_pct نرخ کمیسیون، extra_commission_pct کمیسیون اضافه، return_free_commission_pct کمیسیون فروش با مرجوعی رایگان (همه درصد) و current_lead_time زمان آماده‌سازی فعلی به روز است.

خطاهای مسیرهای خواندن این صفحه: invalid_parameter (400؛ مثلا season نامعتبر یا بازه‌ی بیش از ۴۰۰ روز)، scope_missing (403)، not_found (404) و rate_limited (429). فهرست کامل در صفحه‌ی خطاها است.

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

گزارش‌های سود و زیان رویداد جدای خود ندارند. ارقام آن‌ها با همگام‌سازی شبانه‌ی تراکنش‌ها تغییر می‌کنند؛ رویدادهای مرتبط این‌ها هستند:

رویداد	کاربرد برای این صفحه
payout.created	واریز تازه؛ روزهای تخمینی ممکن است قطعی شده باشند. گزارش را دوباره بخوانید (تسویه‌ها).
penalty.created، penalty.rising	جریمه‌ی تازه یا افزایش محسوس جریمه‌ها؛ سرفصل penalty کسورات تغییر کرده است (تراکنش‌های مالی).

نمونه‌ی پیام payout.created

{
  "id": "evt_01J0D9A1",
  "type": "payout.created",
  "created_at": "2026-11-13T04:09:40+03:30",
  "panel_id": 1,
  "livemode": true,
  "data": {
    "payout": { "payout_id": 12215540, "status": "in_queue", "amount": 2772000000, "suggested_at": "2026-11-15", "date": "2026-11-15", "reconciled": true }
  }
}

پیش از استفاده از هر پیام، امضای آن را بررسی کنید.

💻 نمونه‌کد: سود خالص ماه جاری

curl

curl https://api.seller360.ir/v1/reports/profit/summary \
  -H "Authorization: Bearer $S360_API_KEY"

PHP

$ch = curl_init("https://api.seller360.ir/v1/reports/profit/summary");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("S360_API_KEY")],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$k = json_decode(curl_exec($ch), true)["data"]["kpis"];
$profit = $k["net_profit"] === null ? "نامعلوم" : number_format($k["net_profit"]) . " ریال";
echo "سود خالص: $profit (دقت {$k['accuracy_pct']} درصد)";

Python

import os, requests

k = requests.get(
    "https://api.seller360.ir/v1/reports/profit/summary",
    headers={"Authorization": f"Bearer {os.environ['S360_API_KEY']}"},
    timeout=30,
).json()["data"]["kpis"]
profit = "نامعلوم" if k["net_profit"] is None else f"{k['net_profit']:,} ریال"
print(f"سود خالص: {profit} (دقت {k['accuracy_pct']} درصد)")

Node.js

const res = await fetch('https://api.seller360.ir/v1/reports/profit/summary', {
  headers: { Authorization: `Bearer ${process.env.S360_API_KEY}` },
})
const { kpis } = (await res.json()).data
const profit = kpis.net_profit === null ? 'نامعلوم' : `${kpis.net_profit.toLocaleString()} ریال`
console.log(`سود خالص: ${profit} (دقت ${kpis.accuracy_pct} درصد)`)

C#

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization",
    $"Bearer {Environment.GetEnvironmentVariable("S360_API_KEY")}");
var body = await http.GetFromJsonAsync<JsonElement>(
    "https://api.seller360.ir/v1/reports/profit/summary");
var k = body.GetProperty("data").GetProperty("kpis");
var np = k.GetProperty("net_profit");
var profit = np.ValueKind == JsonValueKind.Null ? "نامعلوم" : $"{np.GetInt64():N0} ریال";
Console.WriteLine($"سود خالص: {profit}");

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

• تراکنش‌های مالی
• تسویه‌ها و پیش‌بینی تسویه
• گزارش فروش و آمار رسمی
• کلید یکتای درخواست
• فهرست خطاها
• مرجع خودکار مسیرهای گزارش