تراکنشهای مالی
مخاطب: برنامهنویس نرمافزار حسابداری، داشبورد مالی یا انبارداری که میخواهد تکتک پولهایی را که دیجیکالا برای فروش، کمیسیون، ارسال، ماندگاری، جریمه و مرجوعی ثبت میکند، بخواند و در دفاتر خود ثبت کند.
📖 مقدمه
Section titled “📖 مقدمه”دیجیکالا از ۱۶ شهریور ۱۴۰۵ صورتحساب دورهای صادر نمیکند. به جای آن، هر جابهجایی پول یک ردیف مالی جداست: فروش یک واحد، کمیسیون همان فروش، هزینهی پردازش و ارسال، ماندگاری یک روز یک واحد در انبار، یک جریمه. ردیفهایی که «قابل تسویه» میشوند، هر چند روز یک بار با هم در یک واریز پرداخت میشوند (صفحهی تسویهها).
سلر ۳۶۰ این ردیفها را هر شب از دیجیکالا میخواند، به هر ردیف یک دستهی صورتحساب میدهد و آن را به سریال، تنوع یا محمولهای که به آن تعلق دارد پیوند میزند. صفحهی «تسویهها» در پنل سلر ۳۶۰ (فهرست «ردیفهای مالی» هر واریز) از همین داده ساخته میشود.
با مسیرهای این صفحه میتوانید:
| کار | مسیر | در دسترس |
|---|---|---|
| فهرست ردیفهای مالی با فیلتر بازه، دسته، وضعیت، واریز، تنوع و سریال | GET /v1/finance/transactions |
فعال |
| خواندن یک ردیف مالی | GET /v1/finance/transactions/{row_id} |
فعال |
و با رویدادهای وبهوک penalty.created و penalty.rising از جریمههای تازه و افزایش محسوس جریمهها خبردار شوید.
⚙️ پیشنیازها
Section titled “⚙️ پیشنیازها”دسترسی (Scope)
Section titled “دسترسی (Scope)”| دسترسی | برای |
|---|---|
finance:read |
همهی مسیرهای این صفحه و رویدادهای penalty.* |
catalog:read |
پیشنهاد میشود: برای خواندن عنوان و کد تنوعها (GET /v1/variants) |
این صفحه هیچ مسیر نوشتنی ندارد؛ ردیفهای مالی را فقط دیجیکالا میسازد. کلید نرمافزاری که فقط تراکنشها را میخواند، به finance:write نیاز ندارد. جزئیات ساخت کلید و دسترسیها در ورود و دسترسیها است.
فعال بودن ماژول
Section titled “فعال بودن ماژول”ماژول «API و وبهوک» و ماژول «حسابداری و فروش» باید برای پنل فعال باشند؛ در غیر این صورت همهی مسیرها با کد 403 و خطای module_inactive (ماژول API) یا module_required (ماژول این بخش، با نام آن در detail) پاسخ میدهند.
آدرس پایه
Section titled “آدرس پایه”https://api.seller360.ir🧾 ردیف مالی
Section titled “🧾 ردیف مالی”فیلدها
Section titled “فیلدها”| فیلد | برچسب در پنل | معنی |
|---|---|---|
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 |
— | زمان آخرین خواندن این ردیف از دیجیکالا. |
رابطهی اعداد
Section titled “رابطهی اعداد”مبلغ بدون مالیات = 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)
Section titled “نوع پیوند (link)”| مقدار | معنی | link_ref |
|---|---|---|
serial |
دیجیکالا سریال واحد را در ردیف داده است. | خالی؛ سریال در serial است. |
serial_text |
سریال از متن ردیف خوانده شده است. | خالی؛ سریال در serial است. |
variant |
هزینهی سطح تنوع بدون واحد مشخص، مثل جریمهی تاخیر تامین. | شناسهی تنوع |
package |
هزینهی سطح محموله، مثل حمل. | شمارهی محموله |
account |
جابهجایی خود حساب: واریز یا ماندهی آغازین. | خالی |
none |
ردیف هنوز به چیزی پیوند نخورده است. | خالی |
🔄 وضعیت ردیف
Section titled “🔄 وضعیت ردیف”| وضعیت | برچسب در پنل | معنی |
|---|---|---|
accepted |
«تایید شده» | دیجیکالا ردیف را ثبت کرده است، اما هنوز قابل تسویه نیست. |
released |
«قابل تسویه» | ردیف آزاد شده است و در اولین واریز پس از امروز پرداخت میشود. |
پرداخت شدن ردیف از payout_id خوانده میشود، نه از status. دیجیکالا وضعیت ردیف را پس از پرداخت تغییر نمیدهد؛ پس ردیف پرداختشده همچنان released میماند و فقط payout_id آن پر میشود.
ثبت فروش ──► accepted ──(بازهی پرداخت)──► released ──(روز واریز)──► payout_id پر میشودزمان رسیدن از «تایید شده» به «قابل تسویه» به شرایط تسویهی پنل بستگی دارد و در صفحهی تسویهها و پیشبینی تسویه توضیح داده شده است.
🔢 تازگی
Section titled “🔢 تازگی”- زمان همگامسازی: تراکنشها و واریزها هر شب ساعت ۰۴:۰۵ به وقت تهران کامل از دیجیکالا خوانده میشوند، و ساعت ۰۴:۵۰ یک بار دیگر ردیفهای تازه اضافه میشوند. دکمهی «دریافت تراکنشهای تازه» در پنل همین همگامسازی را بیدرنگ اجرا میکند.
- فیلدهای تازگی: هر پاسخ فهرستی در
metaچهار فیلد دارد:
| فیلد | معنی |
|---|---|
synced_at |
زمان آخرین همگامسازی تراکنشها و واریزها. |
history_complete |
آیا تاریخچهی یکسالهی تراکنشها کامل خوانده شده است. دریافت اولیه ممکن است چند شب طول بکشد. |
oldest_date |
قدیمیترین روزی که تراکنشهای آن خوانده شده است. |
stale |
true اگر آخرین همگامسازی موفق بیش از ۳۶ ساعت پیش بوده باشد. |
تا وقتی history_complete برابر false است، جمعهای بلندمدت شما ناقصاند. پیش از گزارش سالانه این فیلد را بررسی کنید. قواعد کلی تازگی دادهها در قالب درخواست و پاسخ آمده است.
⚠️ هشدارها
Section titled “⚠️ هشدارها”📡 مسیرها
Section titled “📡 مسیرها”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.1Host: api.seller360.irAuthorization: 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.1Host: api.seller360.irAuthorization: Bearer s360_live_...خطاهای مسیرهای این صفحه
| کد HTTP | خطا | معنی |
|---|---|---|
400 |
invalid_parameter |
یکی از پارامترها نامعتبر است (مثلا بازهی بیش از ۴۰۰ روز یا دستهی ناشناخته). |
403 |
scope_missing |
کلید دسترسی finance:read را ندارد. |
404 |
not_found |
ردیفی با این شناسه در این پنل نیست. |
429 |
rate_limited |
سقف درخواست این کلید پر شده است؛ پس از Retry-After دوباره تلاش کنید. |
فهرست همهی خطاها در صفحهی خطاها و سقفها در سقف درخواست است.
🔔 رویدادهای وبهوک
Section titled “🔔 رویدادهای وبهوک”| رویداد | چه وقت |
|---|---|
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 “💻 نمونهکد: جمع پول پرداختنشدهی یک بازه”این نمونه همهی صفحههای ردیفهای پرداختنشده را میخواند و ردیفهای حساب را کنار میگذارد (هشدار ۲).
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"$total = 0;$page = 1;do { $q = http_build_query(["date_from" => "2026-11-01", "date_to" => "2026-11-11", "unpaid" => 1, "size" => 200, "page" => $page]); $ch = curl_init("https://api.seller360.ir/v1/finance/transactions?$q"); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("S360_API_KEY")], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 20, ]); $res = json_decode(curl_exec($ch), true); foreach ($res["data"] as $row) { if ($row["link"] !== "account") { $total += $row["amount"]; // ریال، با علامت } } $page++;} while ($page <= $res["pager"]["total_pages"]);import os, requests
total, page = 0, 1while True: res = requests.get( "https://api.seller360.ir/v1/finance/transactions", headers={"Authorization": f"Bearer {os.environ['S360_API_KEY']}"}, params={"date_from": "2026-11-01", "date_to": "2026-11-11", "unpaid": 1, "size": 200, "page": page}, timeout=20, ).json() total += sum(r["amount"] for r in res["data"] if r["link"] != "account") if page >= res["pager"]["total_pages"]: break page += 1let total = 0for (let page = 1; ; page++) { const q = new URLSearchParams({ date_from: '2026-11-01', date_to: '2026-11-11', unpaid: '1', size: '200', page: String(page), }) const res = await fetch(`https://api.seller360.ir/v1/finance/transactions?${q}`, { headers: { Authorization: `Bearer ${process.env.S360_API_KEY}` }, }) const body = await res.json() for (const row of body.data) if (row.link !== 'account') total += row.amount if (page >= body.pager.total_pages) break}using var http = new HttpClient();http.DefaultRequestHeaders.Add("Authorization", $"Bearer {Environment.GetEnvironmentVariable("S360_API_KEY")}");long total = 0;for (var page = 1; ; page++){ var url = "https://api.seller360.ir/v1/finance/transactions" + $"?date_from=2026-11-01&date_to=2026-11-11&unpaid=1&size=200&page={page}"; var body = await http.GetFromJsonAsync<JsonElement>(url); foreach (var row in body.GetProperty("data").EnumerateArray()) if (row.GetProperty("link").GetString() != "account") total += row.GetProperty("amount").GetInt64(); if (page >= body.GetProperty("pager").GetProperty("total_pages").GetInt32()) break;}مبالغ ریالی را در نوع عدد صحیح ۶۴ بیتی نگه دارید؛ جمع یک سال فروش از سقف عدد صحیح ۳۲ بیتی بیشتر میشود.