تسویه‌ها و پیش‌بینی تسویه
مخاطب: برنامه‌نویس نرم‌افزار حسابداری یا مدیریت نقدینگی که می‌خواهد واریزهای دیجی‌کالا را با حساب بانکی تطبیق دهد، بداند هر واریز بابت کدام فروش‌ها و هزینه‌ها بوده است، و پیش‌بینی کند پول فروش‌های امروز چه روزی به حساب می‌رسد.
📖 مقدمه
Section titled “📖 مقدمه”دیجی‌کالا ردیف‌های مالی «قابل تسویه» را هر چند روز یک بار با هم در یک واریز به حساب شما می‌فرستد. پنل دیجی‌کالا هر واریز را فقط به‌صورت چند جمع کلی نشان می‌دهد. سلر ۳۶۰ هر واریز را به ردیف‌های مالی آن پیوند می‌زند و سه پرسش را پاسخ می‌دهد:
- این واریز بابت کدام فروش‌ها، مرجوعی‌ها و هزینه‌ها بوده است، کالا به کالا و ردیف به ردیف؛
- چه سهمی از آن مانده‌ی صورت‌حساب‌های قدیم بوده و چه سهمی پول فروش‌های تازه؛
- چه پولی هنوز در راه است و تقریبا چه روزی می‌رسد.
با مسیرهای این صفحه می‌توانید:
| کار | مسیر | در دسترس |
|---|---|---|
| فهرست واریزها | GET /v1/finance/payouts |
فعال |
| یک واریز با صورت‌حساب و تطبیق آن | GET /v1/finance/payouts/{payout_id} |
فعال |
| سهم هر کالا از یک واریز | GET /v1/finance/payouts/{payout_id}/products |
فعال |
| رویدادهای مالی یک واریز (فروش، مرجوعی، ماندگاری و…) | GET /v1/finance/payouts/{payout_id}/events |
فعال |
| پیش‌بینی سه واریز آینده | GET /v1/finance/payout-forecast |
فعال |
| خواندن شرایط تسویه‌ی پنل | GET /v1/finance/payout-terms |
فعال |
| ثبت شرایط تسویه‌ی پنل | PATCH /v1/finance/payout-terms |
فعال |
| پول در راه | GET /v1/finance/in-flight |
فعال |
و با رویدادهای وب‌هوک payout.created، payout.late، payout.overdue، payout.rejected و payout.forecast_missed از واریز تازه، دیرکرد، برگشت از بانک و فاصله با پیش‌بینی خبردار شوید.
⚙️ پیش‌نیازها
Section titled “⚙️ پیش‌نیازها”دسترسی (Scope)
Section titled “دسترسی (Scope)”| دسترسی | برای |
|---|---|
finance:read |
همه‌ی مسیرهای خواندن این صفحه و رویدادهای payout.* |
finance:write |
فقط ثبت شرایط تسویه (PATCH /v1/finance/payout-terms) |
ثبت شرایط تسویه فقط در سلر ۳۶۰ انجام می‌شود و چیزی در دیجی‌کالا تغییر نمی‌کند. جزئیات کلید و دسترسی‌ها در ورود و دسترسی‌ها است.
فعال بودن ماژول
Section titled “فعال بودن ماژول”ماژول «API و وب‌هوک» و ماژول «حسابداری و فروش» باید برای پنل فعال باشند؛ در غیر این صورت همه‌ی مسیرها با کد 403 و خطای module_inactive (ماژول API) یا module_required (ماژول این بخش، با نام آن در detail) پاسخ می‌دهند.
آدرس پایه
Section titled “آدرس پایه”https://api.seller360.ir🏦 واریز
Section titled “🏦 واریز”فیلدهای واریز
Section titled “فیلدهای واریز”| فیلد | برچسب در پنل | معنی |
|---|---|---|
payout_id |
«شناسه تسویه» | شناسه‌ی واریز در دیجی‌کالا. |
status |
«وضعیت» | وضعیت واریز (جدول پایین). |
amount |
«مبلغ واریز» | مبلغ واریز به ریال. |
suggested_at |
— | تاریخ پیشنهادی دیجی‌کالا برای واریز. |
paid_on |
— | تاریخ پرداخت، اگر پرداخت شده باشد. |
date |
«تاریخ واریز» | تاریخ پرداخت، و اگر نباشد تاریخ پیشنهادی. |
tracking_code |
— | کد رهگیری بانک؛ تا پرداخت نشده خالی است. |
rows |
— | تعداد ردیف‌های مالی این واریز. |
rows_total |
— | جمع ردیف‌های مالی این واریز به ریال. |
reconciled |
«آشتی» | true اگر جمع ردیف‌ها دقیقا با مبلغ واریز یکی باشد. |
sales_count |
— | تعداد ردیف‌های فروش. |
gross_sale |
«فروش» | فروش ناخالص بدون مالیات، به ریال. |
returns |
«برگشت» | برگشت از فروش بدون مالیات، به ریال (منفی). |
new_net |
«از فروش‌های جدید» | خالص بخش تراکنش‌ها (فروش و کسورات، با مالیات). |
legacy_net |
«از صورت‌حساب‌های قدیم» | سهم مانده‌ی حساب پیش از تراکنش‌ها در این واریز. |
from_old_invoices |
— | true برای واریزی بدون هیچ ردیف تراکنش که فقط مانده‌ی قدیم را پرداخت کرده است. |
forecast |
«پیش‌بینی سلر ۳۶۰» | پیش‌بینی‌ای که سلر ۳۶۰ در آخرین همگام‌سازی پیش از روز واریز داشت (low، high، expected)؛ ممکن است خالی باشد. |
وضعیت واریز
Section titled “وضعیت واریز”| وضعیت | برچسب در پنل | معنی |
|---|---|---|
in_queue |
«در صف تسویه» | دیجی‌کالا واریز را ثبت کرده است و در صف پرداخت است. |
send_to_bank |
«ارسال به بانک» | واریز به بانک فرستاده شده است. |
paid |
«تسویه‌شده» | پول به حساب شما رسیده است؛ کد رهگیری در tracking_code. |
rejected |
«رد شده» | بانک واریز را برگشت داده است؛ پول به حساب شما نرسیده است. |
in_queue ──► send_to_bank ──► paid └────► rejectedصورت‌حسابی که تا ریال جمع می‌شود
Section titled “صورت‌حسابی که تا ریال جمع می‌شود”صورت‌حساب هر واریز (statement) از سطرهای بدون مالیات به تفکیک دسته‌ی صورت‌حساب ساخته می‌شود و مالیات سطر جدای خود را دارد. به این ترتیب:
مجموع lines[].amount + vat = new_netnew_net + legacy.net + early_settlement = totaltotal = amount واریز| فیلد | برچسب در پنل | معنی |
|---|---|---|
lines[] |
«کسورات»، «فروش / مرجوعی» | هر دسته با title، amount (با علامت)، count، pct_of_sale و تفکیک parts به عنوان‌های دیجی‌کالا. |
vat |
«مالیات بر ارزش افزوده» | جمع مالیات با علامت. |
gross_sale |
«فروش» | فروش ناخالص بدون مالیات. |
new_net |
«از فروش‌های جدید» | جمع سطرها به‌اضافه‌ی مالیات. |
legacy.balance |
«مانده‌ی صورت‌حساب‌های قدیم» | سهم مانده‌ی پیش از تراکنش‌ها. |
legacy.prior_payout |
«واریزهای قبلی از همین مانده» | آنچه پیش‌تر از همان مانده پرداخت شده است. |
early_settlement |
«تسویه‌ی زودهنگام دریافت‌شده» | تسویه‌ی زودهنگامی که پیش‌تر برداشته‌اید و از این واریز کم شده است (منفی). |
total |
«مبلغ واریز» | برابر مبلغ واریز. |
پاسخ یک واریز، بخش reconcile را هم دارد: rows_total (جمع ردیف‌ها)، amount (مبلغ واریز)، diff (اختلاف به ریال)، ok و no_rows. اگر دیجی‌کالا جمع‌های خودش را برای واریز اعلام کرده باشد، در official (final_credit، final_debit، vat، billing_event_count) می‌آید.
📅 زمان رسیدن پول
Section titled “📅 زمان رسیدن پول”شرایط تسویه
Section titled “شرایط تسویه”دو عدد که دیجی‌کالا برای هر فروشنده بر اساس حجم فروش تعیین می‌کند و در پنل دیجی‌کالا زیر «پروفایل ← اطلاعات مالی» نشان می‌دهد، زمان رسیدن پول را مشخص می‌کنند:
| فیلد | برچسب در پنل | معنی | منبع |
|---|---|---|---|
calc_days |
«بازه محاسبه صورت‌حساب» | هر چند روز یک واریز. | API دیجی‌کالا (calc_source برابر digikala)، یا عدد ثبت‌شده‌ی شما |
pay_days |
«بازه پرداخت (فروش نقدی)» | فروش نقدی در روز چندم «قابل تسویه» می‌شود. | در API دیجی‌کالا نیست؛ باید شما ثبت کنید |
credit_days |
«آزاد شدن فروش اعتباری» | فروش اعتباری در روز چندم آزاد می‌شود؛ پیش‌فرض دو برابر pay_days. |
عدد ثبت‌شده‌ی شما یا پیش‌فرض |
cash_day، credit_day |
— | روز آزاد شدن نقدی و اعتباری که در محاسبه به کار رفته است. | محاسبه‌ی سلر ۳۶۰ |
next_settlement |
— | تاریخ واریز بعدی به روایت دیجی‌کالا. | API دیجی‌کالا |
منشا هر عدد در calc_source، pay_source و credit_source است: seller (شما ثبت کرده‌اید)، digikala (از API دیجی‌کالا) یا default (عدد پیش‌فرض؛ دوره‌ی ۵ روزه و بازه‌ی پرداخت ۱۰ روزه).
قاعده‌ی شمردن روزها
Section titled “قاعده‌ی شمردن روزها”روز فروش روز اول شمرده می‌شود؛ همان‌طور که دیجی‌کالا «بازه پرداخت» را بیان می‌کند. با بازه‌ی پرداخت ۱۰ روزه:
| بخش | روز آزاد شدن | یعنی |
|---|---|---|
| فروش نقدی | روز ۱۰ | ۹ روز پس از روز فروش (cash_release_days برابر 9) |
| فروش اعتباری | روز ۲۰ | ۱۹ روز پس از روز فروش (credit_release_days برابر 19) |
و هر واریز فقط آنچه را پیش از روز خودش آزاد شده است می‌برد، نه آنچه همان روز آزاد می‌شود. این قاعده‌ها روی داده‌ی واقعی اندازه‌گیری شده‌اند: در پنلی با بازه‌ی پرداخت ۱۰ روزه، هر ۷۹ فروش نقدی ۲۴ شهریور ۱۴۰۵ در ۲ مهر (روز نهم پس از فروش) آزاد شد؛ و واریز ۱ مهر فروش‌های نقدی تا ۲۲ شهریور را داشت و فروش‌های ۲۳ شهریور، که خود ۱ مهر آزاد شدند، به واریز بعدی رفتند.
پیش‌بینی هر واریز
Section titled “پیش‌بینی هر واریز”GET /v1/finance/payout-forecast سه واریز پیش رو را برمی‌گرداند. هر ردیف پرداخت‌نشده به روزی که باید «قابل تسویه» شود و به اولین واریز پس از آن روز نسبت داده می‌شود. مبلغ هر واریز از بخش‌هایی ساخته می‌شود که منشا هر عدد را نشان می‌دهند:
| فیلد | برچسب در پنل | معنی |
|---|---|---|
certain |
«قابل تسویه» | ردیف‌هایی که هم‌اکنون «قابل تسویه»اند، یا مبلغ قطعی واریزی که دیجی‌کالا ثبت کرده است. |
cash |
«فروش نقدی» | فروش‌های نقدی ثبت‌شده و هزینه‌هایشان که تا آن روز آزاد می‌شوند. |
credit |
«فروش اعتباری» | فروش‌های اعتباری ثبت‌شده که تا آن روز آزاد می‌شوند. |
costs_est |
«هزینه‌های روزانه (تخمین)» | ماندگاری، جریمه و حمل تخمینی، بر پایه‌ی میانگین ۱۴ روز. |
future_est |
«فروش روزهای آینده (تخمین)» | فروش‌هایی که هنوز انجام نشده‌اند، بر پایه‌ی میانگین ۱۴ روز. |
late |
— | بخشی از مبلغ که روز آزاد شدنش گذشته و هنوز منتظر است (درون cash و credit هم شمرده شده است). |
early |
— | تسویه‌ی زودهنگامی که پیش‌تر برداشته شده و از این واریز کم می‌شود (درون certain). |
low |
— | certain + cash + credit + costs_est |
high |
— | low + future_est |
expected |
«پیش‌بینی سلر ۳۶۰» | عدد پیش‌بینی؛ برابر high. |
fixed |
«اعلام دیجی‌کالا» | true یعنی دیجی‌کالا این واریز را ثبت کرده و مبلغ قطعی است؛ payout_id و status هم پر می‌شوند. |
estimated |
— | عکس fixed. |
پیش‌بینی یک عدد مورد انتظار است و فروش اعتباری را هم در خود دارد. فاصله‌ی low تا high فقط از فروش‌هایی می‌آید که هنوز انجام نشده‌اند. بخش money_path نمونه‌ی کاربردی شرایط تسویه برای فروشی است که امروز انجام شود: روز آزاد شدن و واریز بخش نقدی و اعتباری، و واریزی که هزینه‌های امروز در آن کم می‌شود (cost_payout).
پول در راه
Section titled “پول در راه”GET /v1/finance/in-flight پولی را نشان می‌دهد که دیجی‌کالا ثبت کرده اما هنوز واریز نکرده است:
| فیلد | برچسب در پنل | معنی |
|---|---|---|
released |
«قابل تسویه‌ی فعلی» | ردیف‌های «قابل تسویه» که هنوز در هیچ واریزی نیامده‌اند (amount، count). |
accepted |
— | ردیف‌های «تایید شده» که هنوز قابل تسویه نشده‌اند. |
cash_schedule[] |
«فروش نقدی در راه، روزبه‌روز» | خالص فروش‌های نقدی در انتظار، به تفکیک روزی که باید آزاد شوند؛ past یعنی آن روز گذشته و پول هنوز آزاد نشده است. |
credit_waiting |
— | تعداد فروش‌های اعتباری در انتظار و قدیمی‌ترین روز آن‌ها. |
queued[] |
— | واریزهایی که در صف تسویه یا در راه بانک‌اند. |
early_drawn |
— | تسویه‌ی زودهنگامی که برداشته شده و هنوز در هیچ واریزی نیامده است (عدد مثبت). |
🔢 تازگی
Section titled “🔢 تازگی”- همگام‌سازی: واریزها و تراکنش‌ها هر شب ساعت ۰۴:۰۵ به وقت تهران کامل خوانده می‌شوند و ساعت ۰۴:۵۰ یک بار دیگر تکمیل می‌شوند. پیش‌بینی پس از هر همگام‌سازی دوباره ساخته می‌شود.
- فیلدهای تازگی: فهرست واریزها در
metaهمان فیلدهایsynced_at،history_complete،oldest_dateوstaleرا دارد که در تراکنش‌های مالی توضیح داده شده است. پیش‌بینی و پول در راه زمان آخرین همگام‌سازی را درsynced_atدارند. - پیش‌بینی نگه‌داشته‌شده:
forecastهر واریز همان پیش‌بینی‌ای است که سلر ۳۶۰ پیش از روز واریز داشت و پس از آن بازنویسی نمی‌شود؛ پس می‌توانید دقت پیش‌بینی را در طول زمان بسنجید.
⚠️ هشدارها
Section titled “⚠️ هشدارها”📡 مسیرها
Section titled “📡 مسیرها”GET /v1/finance/payouts — فهرست واریزها فعال
Section titled “GET /v1/finance/payouts — فهرست واریزها ”همه‌ی واریزهای دیجی‌کالا، تازه‌ترین اول، هر کدام با خلاصه‌ی صورت‌حساب و پیش‌بینی نگه‌داشته‌شده.
GET /v1/finance/payouts?status=paid&date_from=2026-10-23&date_to=2026-11-11 HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
page، size |
عدد | خیر | صفحه‌بندی. |
status |
متن | خیر | in_queue، send_to_bank، paid یا rejected. |
date_from |
تاریخ | خیر | اولین روز بازه (میلادی). بدون بازه، از ابتدای ماه شمسی جاری تا امروز. |
date_to |
تاریخ | خیر | آخرین روز بازه، شامل همان روز؛ حداکثر ۴۰۰ روز. |
پاسخ نمونه
{ "status": "ok", "data": [ { "payout_id": 12209179, "status": "paid", "amount": 2994917117, "suggested_at": "2026-11-05", "paid_on": "2026-11-05", "date": "2026-11-05", "tracking_code": "140508140012345", "rows": 1842, "rows_total": 2994917117, "reconciled": true, "sales_count": 104, "gross_sale": 3820000000, "returns": -96000000, "new_net": 2994917117, "legacy_net": 0, "from_old_invoices": false, "forecast": { "low": 2950000000, "high": 3120000000, "expected": 3120000000 }, "synced_at": "2026-11-06T04:07:41+03:30" } ], "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 4 }, "meta": { "synced_at": "2026-11-12T04:07:41+03:30", "history_complete": true, "oldest_date": "2025-11-12", "stale": false }}GET /v1/finance/payouts/{payout_id} — یک واریز با صورت‌حساب فعال
Section titled “GET /v1/finance/payouts/{payout_id} — یک واریز با صورت‌حساب ”واریز، تطبیق آن با ردیف‌های مالی و صورت‌حساب به تفکیک دسته. اگر واریز در این پنل نباشد، کد 404 و خطای not_found برمی‌گردد.
GET /v1/finance/payouts/12209179 HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...پاسخ نمونه (کوتاه‌شده)
{ "status": "ok", "data": { "payout": { "payout_id": 12209179, "status": "paid", "amount": 2994917117, "date": "2026-11-05", "reconciled": true }, "reconcile": { "rows": 1842, "rows_total": 2994917117, "amount": 2994917117, "ok": true, "diff": 0, "no_rows": false }, "official": { "final_credit": 3831200000, "final_debit": 773982883, "vat": 62300000, "billing_event_count": 1842 }, "statement": { "lines": [ { "category": "sale", "title": "فروش کالا", "side": "credit", "amount": 3820000000, "count": 104, "pct_of_sale": 100.0, "parts": [ { "title": "فروش - نقدی", "amount": 3180000000, "count": 87 }, { "title": "فروش - اعتباری", "amount": 640000000, "count": 17 } ] }, { "category": "return", "title": "برگشت از فروش (مرجوعی)", "side": "debit", "amount": -96000000, "count": 3, "pct_of_sale": 2.5, "parts": [] }, { "category": "return_refund", "title": "کسورات برگشتی بابت مرجوعی", "side": "credit", "amount": 11200000, "count": 9, "pct_of_sale": 0.3, "parts": [] }, { "category": "commission", "title": "کمیسیون فروش", "side": "debit", "amount": -458400000, "count": 104, "pct_of_sale": 12.0, "parts": [] }, { "category": "platform", "title": "هزینه توسعه پلتفرم (فروش اعتباری)", "side": "debit", "amount": -21000000, "count": 17, "pct_of_sale": 0.5, "parts": [] }, { "category": "fulfilment", "title": "هزینه پردازش و ارسال", "side": "debit", "amount": -190000000, "count": 104, "pct_of_sale": 5.0, "parts": [] }, { "category": "storage", "title": "هزینه ماندگاری در انبار", "side": "debit", "amount": -4200000, "count": 1490, "pct_of_sale": 0.1, "parts": [] }, { "category": "freight", "title": "هزینه حمل بین فروشنده و دیجی‌کالا", "side": "debit", "amount": -1382883, "count": 1, "pct_of_sale": 0.0, "parts": [] }, { "category": "penalty", "title": "جریمه‌ها", "side": "debit", "amount": -3000000, "count": 1, "pct_of_sale": 0.1, "parts": [] } ], "vat": -62300000, "vat_pct_of_sale": 1.6, "gross_sale": 3820000000, "new_net": 2994917117, "legacy": { "balance": 0, "prior_payout": 0, "net": 0 }, "early_settlement": 0, "total": 2994917117 } }}جمع سطرها 3057217117 ریال است؛ با مالیات -62300000 ریال می‌شود 2994917117، یعنی دقیقا مبلغ واریز.
GET /v1/finance/payouts/{payout_id}/products — سهم هر کالا فعال
Section titled “GET /v1/finance/payouts/{payout_id}/products — سهم هر کالا ”پول هر کالا در همین واریز و سود آن نسبت به قیمت خرید روز فروش؛ بیشترین خالص دریافتی اول. مبالغی که به هیچ کالایی تعلق ندارند (مثل حمل محموله) در meta.overhead می‌آیند تا جمع کالاها و این مبالغ با واریز یکی بماند.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
page، size |
عدد | خیر | صفحه‌بندی. |
by |
متن | خیر | variant هر تنوع (پیش‌فرض)، dkp هر کالا، supplier هر کد فروشنده. |
هر ردیف: key، variant_id، title، units_sold، units_returned، مبالغ هر دسته (sale، return، commission، fulfilment و…)، vat، net، cost، cost_missing_units، profit، margin_pct، میانگین‌های هر واحد (avg_sale_price، avg_net، avg_cost، avg_profit) و ستون‌های کسر (ded_commission، ded_fulfilment، ded_tax و…). ستون‌های ded_* اندازهی کسرند: عدد مثبت یعنی آنچه دیجی‌کالا کم کرده است.
{ "status": "ok", "data": [ { "key": "v84780448", "variant_id": 84780448, "variants": 1, "product_id": 22961150, "supplier_code": "5144", "title": "محافظ ولتاژ پارت الکتریک مدل PE5144", "units_sold": 12, "units_returned": 1, "sale": 440400000, "return": -36700000, "return_refund": 4100000, "commission": -52800000, "fulfilment": -23400000, "vat": -7200000, "net": 324400000, "cost": 265100000, "cost_missing_units": 0, "profit": 59300000, "margin_pct": 13.5, "avg_sale_price": 36700000, "avg_net": 29490909, "avg_cost": 24100000, "avg_profit": 5390909, "ded_commission": 52800000, "ded_fulfilment": 23400000, "ded_return_refund": -4100000, "ded_tax": 7200000 } ], "pager": { "page": 1, "item_per_page": 50, "total_pages": 2, "total_rows": 63 }, "meta": { "overhead": { "lines": [ { "category": "freight", "title": "هزینه حمل بین فروشنده و دیجی‌کالا", "amount": -1382883 } ], "vat": 0, "total": -1382883 }, "totals": { "net": 2994917117, "sale": 3820000000, "profit_known": 342000000, "products_with_profit": 58, "products": 63 } }}GET /v1/finance/payouts/{payout_id}/events — رویدادهای مالی یک واریز فعال
Section titled “GET /v1/finance/payouts/{payout_id}/events — رویدادهای مالی یک واریز ”واریز به شکل فهرست اتفاق‌ها، تازه‌ترین اول: هر فروش با کمیسیون و هزینه‌هایش یک رویداد است، هر مرجوعی با کسورات برگشتی‌اش یک رویداد، و ماندگاری روزانه‌ی یک سریال یک رویداد با تعداد روز (days). با پارامتر kind فقط یک نوع را بخوانید:
kind |
عنوان |
|---|---|
sale |
فروش |
credit_sale |
فروش اعتباری |
damaged |
فروش کالای آسیب‌دیده |
return |
مرجوعی |
storage |
ماندگاری در انبار |
penalty |
جریمه |
freight |
حمل محموله |
fees_only |
کسورات بدون فروش در این واریز |
other |
سایر |
balance |
مانده‌ی حساب پیش از تراکنش‌ها |
prior_payout |
واریز قبلی از همین مانده |
early_settlement |
تسویه‌ی زودهنگام |
{ "kind": "sale", "date": "2026-10-26", "title": "محافظ ولتاژ پارت الکتریک مدل PE5144", "variant_id": 84780448, "serial": "8BAC741A", "shipment_id": 1186905159, "order_id": 385760690, "units": 1, "gross": 36700000, "deductions": -6290000, "vat": -611000, "net": 29799000, "rows": 3, "days": null, "notation_names": ""}GET /v1/finance/payout-forecast — پیش‌بینی سه واریز آینده فعال
Section titled “GET /v1/finance/payout-forecast — پیش‌بینی سه واریز آینده ”GET /v1/finance/payout-forecast HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...پاسخ نمونه (امروز ۲۲ آبان ۱۴۰۵، دوره‌ی ۵ روزه، بازه‌ی پرداخت ۱۰ روزه)
{ "status": "ok", "data": { "payouts": [ { "date": "2026-11-15", "certain": 2772000000, "cash": 0, "credit": 0, "costs_est": 0, "future_est": 0, "late": 0, "early": 0, "low": 2772000000, "high": 2772000000, "expected": 2772000000, "fixed": true, "estimated": false, "payout_id": 12215540, "status": "in_queue" }, { "date": "2026-11-20", "certain": 0, "cash": 1460000000, "credit": 210000000, "costs_est": -45000000, "future_est": 0, "late": 0, "early": 0, "low": 1625000000, "high": 1625000000, "expected": 1625000000, "fixed": false, "estimated": true, "payout_id": null, "status": null }, { "date": "2026-11-25", "certain": 0, "cash": 640000000, "credit": 95000000, "costs_est": -45000000, "future_est": 824000000, "late": 0, "early": 0, "low": 690000000, "high": 1514000000, "expected": 1514000000, "fixed": false, "estimated": true, "payout_id": null, "status": null } ], "cash_release_days": 9, "credit_release_days": 19, "cash_day": 10, "credit_day": 20, "daily_costs": -9000000, "daily_sales": 412000000, "terms": { "calc_days": 5, "calc_source": "digikala", "api_calc_days": 5, "pay_days": 10, "pay_source": "seller", "credit_days": 20, "credit_source": "default", "cash_day": 10, "credit_day": 20, "next_settlement": "2026-11-15", "summary_at": "2026-11-13T04:06:02+03:30", "set_at": "2026-10-01T11:20:00+03:30" }, "money_path": { "sale": "2026-11-13", "cash_release": "2026-11-22", "cash_payout": "2026-11-25", "credit_release": "2026-12-02", "credit_payout": "2026-12-05", "cost_payout": "2026-11-15" }, "synced_at": "2026-11-13T04:07:41+03:30" }}در money_path، فروش نقدی امروز (۲۲ آبان) در روز دهم، یعنی ۱ آذر (2026-11-22)، آزاد می‌شود و چون واریز فقط آنچه را پیش از روز خود آزاد شده است می‌برد، با واریز ۴ آذر (2026-11-25) می‌رسد.
GET /v1/finance/payout-terms — شرایط تسویه فعال
Section titled “GET /v1/finance/payout-terms — شرایط تسویه ”همان شیء terms بالا را برمی‌گرداند.
PATCH /v1/finance/payout-terms — ثبت شرایط تسویه فعال
Section titled “PATCH /v1/finance/payout-terms — ثبت شرایط تسویه ”فقط فیلدهایی که می‌فرستید تغییر می‌کنند. مقدار null عدد ثبت‌شده را پاک می‌کند تا عدد دیجی‌کالا یا پیش‌فرض دوباره به کار رود. این تغییر فقط در سلر ۳۶۰ ثبت می‌شود و پیش‌بینی را از همان لحظه تغییر می‌دهد. سرآیند Idempotency-Key لازم است (کلید یکتای درخواست).
PATCH /v1/finance/payout-terms HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...Idempotency-Key: terms-1405-08-22Content-Type: application/json
{ "pay_days": 10, "credit_days": null }| فیلد بدنه | نوع | اجباری | توضیح |
|---|---|---|---|
calc_days |
عدد یا null |
خیر | دوره‌ی تسویه؛ ۱ تا ۶۰. |
pay_days |
عدد یا null |
خیر | بازه‌ی پرداخت؛ ۱ تا ۶۰. |
credit_days |
عدد یا null |
خیر | روز آزاد شدن فروش اعتباری؛ ۱ تا ۱۲۰. |
دست‌کم یک فیلد لازم است. پاسخ موفق: کد 200 با شرایط تسویه پس از تغییر.
خطاهای این مسیر
| کد HTTP | خطا | معنی | تکرار بی‌خطر است؟ |
|---|---|---|---|
400 |
invalid_parameter |
بدنه خالی است یا عددی بیرون از بازه‌ی مجاز است. | خیر؛ بدنه را اصلاح کنید. |
400 |
idempotency_key_required |
سرآیند Idempotency-Key ارسال نشده است. |
بله، با افزودن سرآیند. |
403 |
scope_missing |
کلید دسترسی finance:write را ندارد. |
خیر. |
409 |
idempotency_mismatch |
این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است. | خیر؛ کلید تازه بسازید. |
409 |
idempotency_in_progress |
درخواستی با همین کلید در حال انجام است. | بله، چند ثانیه بعد. |
429 |
rate_limited |
سقف درخواست این کلید پر شده است. | بله، پس از Retry-After. |
GET /v1/finance/in-flight — پول در راه فعال
Section titled “GET /v1/finance/in-flight — پول در راه ”{ "status": "ok", "data": { "released": { "amount": 1120000000, "count": 642 }, "accepted": { "amount": 4380000000, "count": 2310 }, "cash_schedule": [ { "date": "2026-11-13", "amount": 286000000, "sales": 41, "past": false }, { "date": "2026-11-14", "amount": 301000000, "sales": 44, "past": false } ], "cash_release_days": 9, "cash_day": 10, "credit_waiting": { "sales": 37, "oldest": "2026-10-25" }, "queued": [ { "payout_id": 12215540, "amount": 2772000000, "date": "2026-11-15", "status": "in_queue" } ], "early_drawn": 0, "synced_at": "2026-11-13T04:07:41+03:30" }}خطاهای مسیرهای خواندن این صفحه همان خطاهای تراکنش‌های مالی است (invalid_parameter، scope_missing، not_found، rate_limited). فهرست کامل در صفحه‌ی خطاها است.
🔔 رویدادهای وب‌هوک
Section titled “🔔 رویدادهای وب‌هوک”| رویداد | چه وقت |
|---|---|
payout.created |
دیجی‌کالا واریز تازه‌ای را در صف تسویه گذاشته، به بانک فرستاده یا پرداخت کرده است. پس از همگام‌سازی شبانه، یک بار برای هر واریز. |
payout.late |
واریزی که در صف یا در راه بانک است، بیش از آستانه‌ی شما (پیش‌فرض ۳ روز) از تاریخ پیشنهادی دیجی‌کالا گذشته و هنوز پرداخت نشده است. |
payout.overdue |
بر پایه‌ی آخرین واریز و دوره‌ی تسویه، واریز بعدی انتظار می‌رفت اما با یک روز فرصت هنوز در دیجی‌کالا ثبت نشده است. فقط پس از همگام‌سازی‌ای که بعد از آن روز انجام شده است فرستاده می‌شود، تا «خوانده نشده» با «پرداخت نشده» اشتباه نشود. |
payout.rejected |
بانک واریز را برگشت داده است. معمولا شماره‌ی شبای ثبت‌شده در پنل دیجی‌کالا باید بررسی شود. |
payout.forecast_missed |
مبلغ آخرین واریز (۷ روز اخیر) بیش از آستانه‌ی شما (پیش‌فرض ۵ درصد) با پیش‌بینی سلر ۳۶۰ فاصله دارد. |
نمونه‌ی پیام payout.forecast_missed
{ "id": "evt_01J0C2M4", "type": "payout.forecast_missed", "created_at": "2026-11-06T04:10:03+03:30", "panel_id": 1, "livemode": true, "data": { "payout": { "payout_id": 12209179, "status": "paid", "amount": 2994917117, "date": "2026-11-05", "reconciled": true }, "forecast": { "low": 3036167117, "high": 3036167117, "expected": 3036167117 }, "diff": -41250000, "diff_pct": 1.4, "threshold_pct": 1 }}پیام‌ها ممکن است تکراری یا با ترتیب جابه‌جا برسند؛ با id رویداد تکراری‌ها را کنار بگذارید. پیش از استفاده از هر پیام، امضای آن را بررسی کنید.
💻 نمونه‌کد: تطبیق یک واریز با حساب بانکی
Section titled “💻 نمونه‌کد: تطبیق یک واریز با حساب بانکی”curl https://api.seller360.ir/v1/finance/payouts/12209179 \ -H "Authorization: Bearer $S360_API_KEY"$ch = curl_init("https://api.seller360.ir/v1/finance/payouts/12209179");curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("S360_API_KEY")], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 20,]);$p = json_decode(curl_exec($ch), true)["data"];if (!$p["reconcile"]["ok"]) { // اختلاف به ریال در $p["reconcile"]["diff"]؛ تفکیک را قطعی ندانید}foreach ($p["statement"]["lines"] as $line) { echo $line["title"], ": ", $line["amount"], "\n";}import os, requests
p = requests.get( "https://api.seller360.ir/v1/finance/payouts/12209179", headers={"Authorization": f"Bearer {os.environ['S360_API_KEY']}"}, timeout=20,).json()["data"]if not p["reconcile"]["ok"]: print("اختلاف:", p["reconcile"]["diff"]) # تفکیک را قطعی ندانیدfor line in p["statement"]["lines"]: print(line["title"], line["amount"])const res = await fetch('https://api.seller360.ir/v1/finance/payouts/12209179', { headers: { Authorization: `Bearer ${process.env.S360_API_KEY}` },})const p = (await res.json()).dataif (!p.reconcile.ok) { // اختلاف به ریال در p.reconcile.diff؛ تفکیک را قطعی ندانید}for (const line of p.statement.lines) console.log(line.title, line.amount)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/finance/payouts/12209179");var p = body.GetProperty("data");if (!p.GetProperty("reconcile").GetProperty("ok").GetBoolean()){ // اختلاف به ریال در reconcile.diff؛ تفکیک را قطعی ندانید}foreach (var line in p.GetProperty("statement").GetProperty("lines").EnumerateArray()) Console.WriteLine($"{line.GetProperty("title")}: {line.GetProperty("amount")}");