رفتن به محتوا

تراکنش‌های مالی

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

دیجی‌کالا از ۱۶ شهریور ۱۴۰۵ صورت‌حساب دوره‌ای صادر نمی‌کند. به جای آن، هر جابه‌جایی پول یک ردیف مالی جداست: فروش یک واحد، کمیسیون همان فروش، هزینه‌ی پردازش و ارسال، ماندگاری یک روز یک واحد در انبار، یک جریمه. ردیف‌هایی که «قابل تسویه» می‌شوند، هر چند روز یک بار با هم در یک واریز پرداخت می‌شوند (صفحه‌ی تسویه‌ها).

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

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

کار مسیر در دسترس
فهرست ردیف‌های مالی با فیلتر بازه، دسته، وضعیت، واریز، تنوع و سریال GET /v1/finance/transactions فعال
خواندن یک ردیف مالی GET /v1/finance/transactions/{row_id} فعال

و با رویدادهای وب‌هوک penalty.created و penalty.rising از جریمه‌های تازه و افزایش محسوس جریمه‌ها خبردار شوید.

دسترسی برای
finance:read همه‌ی مسیرهای این صفحه و رویدادهای penalty.*
catalog:read پیشنهاد می‌شود: برای خواندن عنوان و کد تنوع‌ها (GET /v1/variants)

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

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

https://api.seller360.ir
فیلد برچسب در پنل معنی
row_id — شناسه‌ی ردیف در دیجی‌کالا.
transaction_time «تاریخ ثبت» روزی که دیجی‌کالا ردیف را ثبت کرده است. برای فروش، همان روز فروش.
settlement_time — روز تسویه به روایت دیجی‌کالا؛ ممکن است خالی باشد.
notation_id — شناسه‌ی نوع ردیف در دیجی‌کالا (مثلا 60 فروش نقدی، 22 کمیسیون فروش).
notation_name «نوع تراکنش» عنوان نوع ردیف، همان‌طور که دیجی‌کالا می‌نویسد (مثلا «فروش - نقدی»).
category «نوع» دسته‌ی صورت‌حساب که سلر ۳۶۰ از روی notation_id می‌سازد (جدول پایین).
amount «مبلغ» مبلغ با علامت، شامل مالیات، به ریال. مثبت یعنی پول ورودی و منفی یعنی پول خروجی.
vat «مالیات» مالیات درون amount، با همان علامت، به ریال.
status «وضعیت» accepted («تایید شده») یا released («قابل تسویه»).
released_seen_at — اولین روزی که سلر ۳۶۰ ردیف را «قابل تسویه» دید.
payout_id «شناسه تسویه» واریزی که این ردیف را پرداخت کرده است؛ خالی یعنی هنوز پرداخت نشده.
is_correction — true برای ردیف اصلاحی دیجی‌کالا.
variant_id «DKPC» عدد کد تنوع، اگر ردیف به یک تنوع تعلق داشته باشد.
product_id «DKP» عدد کد کالا.
product_title «کالا» عنوان کالا.
serial «سریال» سریال واحد کالا؛ اگر ردیف به واحدی تعلق نداشته باشد، خالی است.
shipment_id «شناسه مرسوله» فقط برای ردیف فروش: شناسه‌ی محموله‌ی سفارش (هشدار ۵).
link — ردیف به چه چیزی پیوند خورده است (جدول نوع پیوند).
link_ref — شناسه‌ی تنوع یا شماره‌ی محموله، بسته به link.
synced_at — زمان آخرین خواندن این ردیف از دیجی‌کالا.
مبلغ بدون مالیات = amount − vat
پول ورودی : amount > 0 (فروش، کسورات برگشتی بابت مرجوعی)
پول خروجی : amount < 0 (کمیسیون، پردازش و ارسال، ماندگاری، جریمه، برگشت از فروش)

برای جمع زدن ردیف‌ها کافی است amount را با علامتش جمع کنید؛ هیچ ستونی جدا برای «بدهکار» و «بستانکار» لازم نیست.

دسته‌های صورت‌حساب (category)

Section titled “دسته‌های صورت‌حساب (category)”

سلر ۳۶۰ هر ردیف را از روی notation_id و در نبود آن از روی عنوانش در یکی از این دسته‌ها می‌گذارد. ردیف ناشناخته در other می‌آید و هرگز حذف نمی‌شود.

مقدار عنوان در پنل جهت معمول پول شامل
sale «فروش کالا» ورودی فروش نقدی و فروش اعتباری
damaged «فروش کالای آسیب‌دیده» ورودی فروش کالایی که آسیب‌دیده فروخته شده است
return «برگشت از فروش (مرجوعی)» خروجی پس گرفتن مبلغ فروش واحد مرجوعی
return_refund «کسورات برگشتی بابت مرجوعی» ورودی کمیسیون، هزینه‌ی پلتفرم، پردازش و ارسالی که دیجی‌کالا با مرجوعی برمی‌گرداند
commission «کمیسیون فروش» خروجی کمیسیون فروش نقدی و اعتباری
platform «هزینه توسعه پلتفرم (فروش اعتباری)» خروجی هزینه‌ی پلتفرم فروش‌های اعتباری
fulfilment «هزینه پردازش و ارسال» خروجی پردازش و ارسال سفارش
storage «هزینه ماندگاری در انبار» خروجی ماندگاری روزانه‌ی هر واحد در انبار دیجی‌کالا
freight «هزینه حمل بین فروشنده و دیجی‌کالا» خروجی حمل محموله‌ی انبارش
penalty «جریمه‌ها» خروجی جریمه‌ی تاخیر، مغایرت، مرجوعی معیوب و سایر جریمه‌ها
other «سایر» هر دو هر نوع ردیفی که سلر ۳۶۰ هنوز نمی‌شناسد
balance «مانده‌ی حساب پیش از تراکنش‌ها» ورودی مانده‌ی صورت‌حساب‌های قدیم که به حساب تازه منتقل شد
prior_payout «واریز قبلی از همین مانده» خروجی پرداختی که از همان مانده انجام شده است
early_settlement «تسویه‌ی زودهنگام» خروجی پولی که پیش از روز واریز برداشته‌اید

سه دسته‌ی آخر جابه‌جایی خود حساب‌اند، نه فروش یا هزینه (هشدار ۲).

مقدار معنی link_ref
serial دیجی‌کالا سریال واحد را در ردیف داده است. خالی؛ سریال در serial است.
serial_text سریال از متن ردیف خوانده شده است. خالی؛ سریال در serial است.
variant هزینه‌ی سطح تنوع بدون واحد مشخص، مثل جریمه‌ی تاخیر تامین. شناسه‌ی تنوع
package هزینه‌ی سطح محموله، مثل حمل. شماره‌ی محموله
account جابه‌جایی خود حساب: واریز یا مانده‌ی آغازین. خالی
none ردیف هنوز به چیزی پیوند نخورده است. خالی
وضعیت برچسب در پنل معنی
accepted «تایید شده» دیجی‌کالا ردیف را ثبت کرده است، اما هنوز قابل تسویه نیست.
released «قابل تسویه» ردیف آزاد شده است و در اولین واریز پس از امروز پرداخت می‌شود.

پرداخت شدن ردیف از payout_id خوانده می‌شود، نه از status. دیجی‌کالا وضعیت ردیف را پس از پرداخت تغییر نمی‌دهد؛ پس ردیف پرداخت‌شده همچنان released می‌ماند و فقط payout_id آن پر می‌شود.

ثبت فروش ──► accepted ──(بازه‌ی پرداخت)──► released ──(روز واریز)──► payout_id پر می‌شود

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

  • زمان همگام‌سازی: تراکنش‌ها و واریزها هر شب ساعت ۰۴:۰۵ به وقت تهران کامل از دیجی‌کالا خوانده می‌شوند، و ساعت ۰۴:۵۰ یک بار دیگر ردیف‌های تازه اضافه می‌شوند. دکمه‌ی «دریافت تراکنش‌های تازه» در پنل همین همگام‌سازی را بی‌درنگ اجرا می‌کند.
  • فیلدهای تازگی: هر پاسخ فهرستی در meta چهار فیلد دارد:
فیلد معنی
synced_at زمان آخرین همگام‌سازی تراکنش‌ها و واریزها.
history_complete آیا تاریخچه‌ی یک‌ساله‌ی تراکنش‌ها کامل خوانده شده است. دریافت اولیه ممکن است چند شب طول بکشد.
oldest_date قدیمی‌ترین روزی که تراکنش‌های آن خوانده شده است.
stale true اگر آخرین همگام‌سازی موفق بیش از ۳۶ ساعت پیش بوده باشد.

تا وقتی history_complete برابر false است، جمع‌های بلندمدت شما ناقص‌اند. پیش از گزارش سالانه این فیلد را بررسی کنید. قواعد کلی تازگی داده‌ها در قالب درخواست و پاسخ آمده است.

GET /v1/finance/transactions — فهرست ردیف‌های مالی فعال

Section titled “GET /v1/finance/transactions — فهرست ردیف‌های مالی ”

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

GET /v1/finance/transactions?date_from=2026-11-01&date_to=2026-11-11&unpaid=1&page=1&size=200 HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...

پارامترها

پارامتر نوع اجباری توضیح
page عدد خیر شماره‌ی صفحه؛ پیش‌فرض ۱.
size عدد خیر تعداد در هر صفحه.
date_from تاریخ خیر اولین روز بازه (میلادی، مثلا 2026-11-01). بدون date_from و date_to، از ابتدای ماه شمسی جاری تا امروز.
date_to تاریخ خیر آخرین روز بازه، شامل همان روز. هر بازه حداکثر ۴۰۰ روز است.
category متن خیر فقط ردیف‌های یک دسته (جدول دسته‌ها).
status accepted یا released خیر وضعیت ردیف در دیجی‌کالا.
payout_id عدد خیر فقط ردیف‌هایی که در این واریز پرداخت شده‌اند.
unpaid 0 یا 1 خیر فقط پرداخت‌نشده‌ها (1) یا فقط پرداخت‌شده‌ها (0).
variant_id عدد خیر فقط ردیف‌های یک تنوع (عدد کد DKPC).
serial متن خیر فقط ردیف‌های یک سریال؛ حداکثر ۶۴ نویسه.
link متن خیر فقط ردیف‌هایی با این نوع پیوند (جدول نوع پیوند).

پاسخ نمونه

{
"status": "ok",
"data": [
{
"row_id": 912345678,
"transaction_time": "2026-11-02",
"settlement_time": null,
"notation_id": 22,
"notation_name": "کمیسیون فروش",
"category": "commission",
"amount": -4576188,
"vat": -416017,
"status": "accepted",
"released_seen_at": null,
"payout_id": null,
"is_correction": false,
"variant_id": 84780448,
"product_id": 22961150,
"product_title": "محافظ ولتاژ پارت الکتریک مدل PE5144",
"serial": "8BAC741A",
"shipment_id": null,
"link": "serial",
"link_ref": "",
"synced_at": "2026-11-12T04:07:41+03:30"
},
{
"row_id": 912345677,
"transaction_time": "2026-11-02",
"settlement_time": null,
"notation_id": 60,
"notation_name": "فروش - نقدی",
"category": "sale",
"amount": 36700000,
"vat": 0,
"status": "accepted",
"released_seen_at": null,
"payout_id": null,
"is_correction": false,
"variant_id": 84780448,
"product_id": 22961150,
"product_title": "محافظ ولتاژ پارت الکتریک مدل PE5144",
"serial": "8BAC741A",
"shipment_id": 1186905159,
"link": "serial",
"link_ref": "",
"synced_at": "2026-11-12T04:07:41+03:30"
}
],
"pager": { "page": 1, "item_per_page": 200, "total_pages": 12, "total_rows": 2310 },
"meta": {
"synced_at": "2026-11-12T04:07:41+03:30",
"history_complete": true,
"oldest_date": "2025-11-12",
"stale": false
}
}

در این نمونه، کمیسیون -4576188 ریال است که -416017 ریال آن مالیات است؛ پس کمیسیون بدون مالیات -4160171 ریال است.

GET /v1/finance/transactions/{row_id} — یک ردیف مالی فعال

Section titled “GET /v1/finance/transactions/{row_id} — یک ردیف مالی ”

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

GET /v1/finance/transactions/912345678 HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...

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

کد HTTP خطا معنی
400 invalid_parameter یکی از پارامترها نامعتبر است (مثلا بازه‌ی بیش از ۴۰۰ روز یا دسته‌ی ناشناخته).
403 scope_missing کلید دسترسی finance:read را ندارد.
404 not_found ردیفی با این شناسه در این پنل نیست.
429 rate_limited سقف درخواست این کلید پر شده است؛ پس از Retry-After دوباره تلاش کنید.

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

رویداد چه وقت
penalty.created دیجی‌کالا برای این پنل جریمه‌ای ثبت کرده است. دیجی‌کالا برای جریمه پیامی نمی‌فرستد؛ این رویداد از روی تراکنش‌ها ساخته می‌شود و پس از همگام‌سازی شبانه، یک بار برای هر ردیف جریمه فرستاده می‌شود.
penalty.rising جمع جریمه‌های ۷ روز کامل اخیر بیش از آستانه‌ی شما (پیش‌فرض ۵۰ درصد) از میانگین هفتگی ۲۸ روز پیش از آن بیشتر است. مبالغ این رویداد اندازه‌ی جریمه و عدد مثبت‌اند.

نوع جریمه در penalty_type می‌آید: late جریمه‌ی تاخیر در ارسال به انبار، mismatch جریمه‌ی مغایرت کالا در ورودی انبار، defect جریمه‌ی مرجوعی کالای اشتباه یا معیوب، و penalty سایر جریمه‌ها.

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

{
"id": "evt_01J0B7QK",
"type": "penalty.created",
"created_at": "2026-11-12T04:09:12+03:30",
"panel_id": 1,
"livemode": true,
"data": {
"transaction": {
"row_id": 912401233,
"transaction_time": "2026-11-11",
"notation_id": 136,
"notation_name": "جریمه عدم ارسال تعهد",
"category": "penalty",
"amount": -3000000,
"vat": 0,
"status": "accepted",
"payout_id": null,
"variant_id": 84780448,
"product_title": "محافظ ولتاژ پارت الکتریک مدل PE5144",
"serial": "",
"link": "variant",
"link_ref": "84780448",
"synced_at": "2026-11-12T04:07:41+03:30"
},
"penalty_type": "penalty"
}
}

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

💻 نمونه‌کد: جمع پول پرداخت‌نشده‌ی یک بازه

Section titled “💻 نمونه‌کد: جمع پول پرداخت‌نشده‌ی یک بازه”

این نمونه همه‌ی صفحه‌های ردیف‌های پرداخت‌نشده را می‌خواند و ردیف‌های حساب را کنار می‌گذارد (هشدار ۲).

Terminal window
curl -G https://api.seller360.ir/v1/finance/transactions \
-H "Authorization: Bearer $S360_API_KEY" \
--data-urlencode "date_from=2026-11-01" \
--data-urlencode "date_to=2026-11-11" \
--data-urlencode "unpaid=1" \
--data-urlencode "size=200" \
--data-urlencode "page=1"

مبالغ ریالی را در نوع عدد صحیح ۶۴ بیتی نگه دارید؛ جمع یک سال فروش از سقف عدد صحیح ۳۲ بیتی بیشتر می‌شود.