تعهد ارسال

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

📖 مقدمه

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

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

کار	مسیر	در دسترس
تعهد ارسال هر تنوع	`GET /v1/commitments`	فعال
خلاصه‌ی تعهد ارسال پنل	`GET /v1/commitments/summary`	فعال
سفارش‌های ارسال توسط فروشنده	`GET /v1/ship-by-seller-orders`	فعال

و با رویداد وب‌هوک commitment.late از دیر شدن تعهد یک تنوع خبردار شوید. فهرست قلم‌به‌قلم سفارش‌های باز با روز تعهد هر قلم در صفحه‌ی سفارش‌ها (GET /v1/open-orders) است، و ساخت محموله برای این تعهدها در صفحه‌ی محموله‌ها.

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

دسترسی (Scope)

دسترسی	برای
`orders:read`	همه‌ی مسیرها و رویداد این صفحه
`shipping:write`	فقط اگر می‌خواهید برای تعهدها محموله بسازید (محموله‌ها)

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

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

آدرس پایه

https://api.seller360.ir

📦 مدل تعهد

فیلدهای هر ردیف (`Commitment`)

فیلد	برچسب در پنل	معنی
`variant_id`، `product_id`	«کد تنوع (DKPC)»، «کد کالا (DKP)»	شناسه‌های تنوع و کالا.
`supplier_code`، `sku`	«کد فروشنده»، «کد کالای فروشنده»	کد فروشنده در دیجی‌کالا و کد کالای سایت شما.
`title`، `image_url`	«کالا»	عنوان و تصویر.
`shipping_nature`	«اندازه‌ی مرسوله»	اندازه‌ی محموله به زبان دیجی‌کالا (کوچک، متوسط، سنگین)؛ روز تعهد را تعیین می‌کند.
`status`	«وضعیت»	`late`، `today` یا `later` (جدول وضعیت‌ها).
`delayed`	«دیرکرد»	واحدهایی که مهلت ارسال آن‌ها گذشته است و هر روز جریمه دارند.
`today`	«امروز»	واحدهایی که مهلت ارسال آن‌ها امروز است.
`next_days`	«آینده»	واحدهایی که مهلت آن‌ها از فردا به بعد است.
`due_now`	«گذشته و امروز»	واحدهایی که تا پایان امروز باید ارسال شوند (دیرکرد و امروز).
`total`	«جمع تعهد»	همه‌ی واحدهای مانده برای ارسال.
`deadline`	«مهلت ارسال»	روز مهلت نزدیک‌ترین واحد مانده.
`digikala_stock`	«انبار دیجی‌کالا»	موجودی این تنوع در انبار دیجی‌کالا، طبق صفحه‌ی تعهد ارسال دیجی‌کالا.
`on_the_way`	«در محموله»	واحدهایی که در محموله قرار گرفته‌اند و در راه انبار دیجی‌کالا هستند.
`ordered`	«فروش»	واحدهای سفارش‌داده‌شده، به گفته‌ی دیجی‌کالا.
`seller_stock`	«انبار شما»	موجودی انبار خودتان، طبق آخرین همگام‌سازی محصولات؛ اگر نامعلوم باشد خالی است.
`shortfall`	«کسری»	جمع تعهد منهای موجودی انبار شما؛ این تعداد باید تامین شود.
`unit_price`	«قیمت فروش»	قیمت فروش، به ریال.
`penalty_risk`	«جریمه‌ی تخمینی»	جریمه‌ی تخمینی اگر `due_now` تا پایان امروز ارسال نشود، به ریال.
`estimated`	—	همیشه `true`: `penalty_risk` تخمین سلر ۳۶۰ است، نه عدد دیجی‌کالا.
`synced_at`، `stale`	—	زمان آخرین تصویر، و `true` اگر قدیمی‌تر از ۲۰ دقیقه باشد.

رابطه‌ی اعداد

due_now   = delayed + today
total     = due_now + next_days
shortfall = max(0, total − seller_stock)

جریمه‌ی تخمینی

دیجی‌کالا برای هر روز تاخیر ضریبی دارد: یک ضریب برای روز اول و یک ضریب برای روزهای بعد (penalty_rates.first_day و penalty_rates.second_day در خلاصه). سلر ۳۶۰ جریمه‌ی واحدهایی را که تا پایان امروز ارسال نشوند، این‌گونه تخمین می‌زند:

penalty_risk = unit_price × نرخ کمیسیون دسته × (today × first_day + delayed × second_day)

این فرمول روی دو جریمه‌ی واقعی دیجی‌کالا بررسی شده است. یک مثال: کالایی با قیمت ۱۲٬۵۰۰٬۰۰۰ ریال، کمیسیون دسته‌ی ۶ درصد، ۳ واحد امروز و ۲ واحد دیرکرد، با ضریب‌های ۰٫۵ و ۱:

جزء	مقدار
قیمت × کمیسیون	۱۲٬۵۰۰٬۰۰۰ × ۰٫۰۶ = ۷۵۰٬۰۰۰ ریال
واحدهای امروز	۳ × ۰٫۵ = ۱٫۵
واحدهای دیرکرد	۲ × ۱ = ۲
`penalty_risk`	۷۵۰٬۰۰۰ × ۳٫۵ = ۲٬۶۲۵٬۰۰۰ ریال

اگر نرخ کمیسیون دسته‌ی کالا نامعلوم باشد، penalty_risk خالی (null) است. عدد رسمی جریمه‌ی کل پنل، همان‌گونه که دیجی‌کالا اعلام می‌کند، در penalty_total خلاصه است.

🔄 وضعیت‌ها

وضعیت	برچسب در پنل	معنی
`late`	«دیرکرد»	دست‌کم یک واحد مهلتش گذشته است و هر روز جریمه دارد.
`today`	«امروز»	واحدی که باید تا پایان امروز ارسال شود.
`later`	«روزهای آینده»	فقط تعهد روزهای بعد.

ردیف‌ها همیشه به این ترتیب‌اند: اول دیرکردها، سپس تعهدهای امروز، سپس روزهای بعد؛ در هر گروه، ردیف با due_now بیشتر بالاتر است.

🔢 تازگی

تصویر هر ۵ دقیقه: تعهدها، خلاصه و سفارش‌های ارسال توسط فروشنده هر ۵ دقیقه از دیجی‌کالا خوانده می‌شوند، و چند ثانیه پس از هر وب‌هوک سفارش دیجی‌کالا (حداکثر یک بار در ۳۰ ثانیه برای هر پنل).
نشان قدیمی بودن (stale): تصویر قدیمی‌تر از ۲۰ دقیقه stale: true دارد.
بخش‌های خوانده‌نشده: تصویر از پنج خواندن جدا ساخته می‌شود. اگر یکی از آن‌ها (مثلا به دلیل سقف دیجی‌کالا) انجام نشود، آن بخش مقدار قبلی خود را نگه می‌دارد و نام آن در unreadable_parts خلاصه می‌آید؛ بخش‌های دیگر تازه می‌شوند.

⚠️ هشدارها

📡 مسیرها

`GET /v1/commitments` — تعهد ارسال هر تنوع فعال

یک ردیف برای هر تنوعی که هنوز چیزی برای ارسال دارد.

GET /v1/commitments?status=late HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...

پارامترها

پارامتر	نوع	اجباری	توضیح
`status`	`late`، `today`، `later`	خیر	فقط ردیف‌هایی با این وضعیت.
`short`	`0` یا `1`	خیر	فقط ردیف‌هایی که موجودی شما کمتر از تعهد آن‌هاست (`1`).
`page`، `size`	عدد	خیر	صفحه‌بندی.

پاسخ نمونه

{
  "status": "ok",
  "data": [
    {
      "variant_id": 84780448,
      "product_id": 22961150,
      "supplier_code": "5144",
      "sku": "PE-5144",
      "title": "محافظ ولتاژ پارت الکتریک مدل PE5144",
      "image_url": "https://dkstatics-public.digikala.com/digikala-products/22961150.jpg",
      "shipping_nature": "کوچک",
      "status": "late",
      "delayed": 2,
      "today": 3,
      "next_days": 5,
      "due_now": 5,
      "total": 10,
      "deadline": "2026-11-12",
      "digikala_stock": 0,
      "on_the_way": 4,
      "ordered": 14,
      "seller_stock": 6,
      "shortfall": 4,
      "unit_price": 12500000,
      "penalty_risk": 2625000,
      "estimated": true,
      "synced_at": "2026-11-13T10:05:12+03:30",
      "stale": false
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 3 }
}

`GET /v1/commitments/summary` — خلاصه‌ی تعهد ارسال پنل فعال

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

فیلد	برچسب در پنل	معنی
`past_today`	«تعهد ارسال گذشته و امروز»	`total`، `shipped` («محموله‌شده») و `unshipped` («محموله‌نشده»).
`future`	«تعهد ارسال آینده»	همان سه عدد برای روزهای بعد.
`past_today_updated_at`، `future_updated_at`	—	زمانی که دیجی‌کالا اعداد را ثابت کرد.
`penalty_total`	«جریمه‌ی حدودی اعلام دیجی‌کالا»	جریمه‌ی کل اعلام‌شده‌ی دیجی‌کالا، به ریال.
`penalty_risk`	«جریمه‌ی تخمینی»	جمع جریمه‌ی تخمینی همه‌ی ردیف‌ها، به ریال.
`penalty_rates`	—	ضریب جریمه‌ی روز اول و روزهای بعد.
`days_ahead`	«روزهای تعهد آینده»	واحدهای مانده برای هر روز آینده (حداکثر ۱۰ روز)، با تفکیک تنوع.
`new_today`	«سفارش‌های تازه‌ی امروز»	شمار اقلام، واحدها و مبلغ (ریال) سفارش‌های باز امروز.
`ship_by_seller`	«سفارش‌های ارسال فروشنده»	شمار سفارش‌های ارسال توسط فروشنده؛ اگر دیجی‌کالا عددی نداده باشد خالی است.
`unreadable_parts`	—	بخش‌هایی که در آخرین خواندن خوانده نشدند (`summary`، `rows`، `days`، `orders`، `sbs`، `nearby`) و دلیل آن.

پاسخ نمونه

{
  "status": "ok",
  "data": {
    "past_today": { "total": 18, "shipped": 12, "unshipped": 6 },
    "past_today_updated_at": "2026-11-13T06:02:44+03:30",
    "future": { "total": 23, "shipped": 4, "unshipped": 19 },
    "future_updated_at": "2026-11-13T06:02:44+03:30",
    "penalty_total": 12500000,
    "penalty_risk": 4500000,
    "estimated": true,
    "penalty_rates": { "first_day": 0.5, "second_day": 1 },
    "days_ahead": [
      { "date": "2026-11-14", "units": 7, "variants": [{ "variant_id": 84780448, "units": 3 }] },
      { "date": "2026-11-15", "units": 12, "variants": [{ "variant_id": 84780448, "units": 2 }] }
    ],
    "new_today": { "items": 4, "units": 5, "amount": 61500000 },
    "ship_by_seller": { "past": 1, "future": 3, "total": 4 },
    "unreadable_parts": [],
    "synced_at": "2026-11-13T10:05:12+03:30",
    "stale": false
  }
}

`GET /v1/ship-by-seller-orders` — سفارش‌های ارسال توسط فروشنده فعال

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

پارامتر	نوع	اجباری	توضیح
`critical`	`0` یا `1`	خیر	فقط سفارش‌هایی که دیجی‌کالا فوری علامت زده است (`1`).
`page`، `size`	عدد	خیر	صفحه‌بندی.

فیلد	برچسب در پنل	معنی
`order_id`، `shipment_id`	«شماره‌ی سفارش»	شناسه‌ی سفارش و مرسوله.
`order_date`	«تاریخ ثبت»	زمان ثبت سفارش، همان‌گونه که دیجی‌کالا می‌دهد.
`commitment_date`	«مهلت ارسال»	مهلت ارسال.
`promise_date`، `post_promise_date`	«وعده‌ی تحویل به مشتری»	تاریخ وعده‌ی تحویل به خریدار.
`is_critical`	—	دیجی‌کالا این سفارش را فوری علامت زده است.
`shipping_provider`	«روش ارسال»	شرکت ارسال (نه نام یا شماره‌ی شخص).
`item_count`	«تعداد کالا»	شمار کالاها.
`shipping_cost`	«هزینه‌ی ارسال»	ریال.
`has_printed`	—	برچسب ارسال چاپ شده است.
`status`، `status_title`	«وضعیت»	کلید و عنوان فارسی وضعیت دیجی‌کالا.
`shipping_nature`	«اندازه‌ی مرسوله»	اندازه‌ی محموله.
`variants`	«کالاها»	حداکثر ۲۰ تنوع، هر کدام با `count` و قیمت به ریال.

پاسخ نمونه

{
  "status": "ok",
  "data": [
    {
      "order_id": 385944712,
      "shipment_id": 402196551,
      "order_date": "2026-11-12T18:20:05+03:30",
      "commitment_date": "2026-11-14",
      "promise_date": "2026-11-17",
      "post_promise_date": null,
      "is_critical": false,
      "shipping_provider": "پست",
      "item_count": 2,
      "shipping_cost": 450000,
      "has_printed": true,
      "status": "processing",
      "status_title": "در حال پردازش و ارسال",
      "shipping_nature": "کوچک",
      "variants": [
        {
          "variant_id": 84780448,
          "product_id": 22961150,
          "title": "محافظ ولتاژ پارت الکتریک مدل PE5144",
          "supplier_code": "5144",
          "count": 2,
          "unit_price": 12500000,
          "total_price": 25000000,
          "image_url": "https://dkstatics-public.digikala.com/digikala-products/22961150.jpg"
        }
      ],
      "synced_at": "2026-11-13T10:05:12+03:30"
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 4 }
}

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

رویداد	چه وقت
`commitment.late`	در تصویر تازه‌ی تعهدها، تعداد واحدهای دیرکرد (`delayed`) یک تنوع از صفر بیشتر یا بیشتر از قبل شود. برای هر تنوع در هر روز حداکثر یک بار برای هر افزایش.

نمونه‌ی پیام commitment.late

{
  "id": "evt_01HZYA4M",
  "type": "commitment.late",
  "created_at": "2026-11-13T06:05:31+03:30",
  "panel_id": 1,
  "livemode": true,
  "data": {
    "commitment": {
      "variant_id": 84780448,
      "supplier_code": "5144",
      "title": "محافظ ولتاژ پارت الکتریک مدل PE5144",
      "status": "late",
      "delayed": 2,
      "today": 3,
      "next_days": 5,
      "due_now": 5,
      "total": 10,
      "seller_stock": 6,
      "shortfall": 4,
      "unit_price": 12500000,
      "penalty_risk": 2625000,
      "estimated": true,
      "synced_at": "2026-11-13T06:05:28+03:30",
      "stale": false
    },
    "previous_delayed": 0
  }
}

رویدادهای سفارش تازه، لغو و مرجوعی در صفحه‌ی سفارش‌ها آمده است. پیش از استفاده از هر پیام، امضای آن را بررسی کنید.

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

curl -G https://api.seller360.ir/v1/commitments \
  -H "Authorization: Bearer $S360_API_KEY" \
  --data-urlencode "short=1"

$ch = curl_init("https://api.seller360.ir/v1/commitments?short=1");
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 $c) {
    // $c["supplier_code"]: کسری $c["shortfall"] واحد، جریمه‌ی تخمینی $c["penalty_risk"] ریال
}

import os, requests

res = requests.get(
    "https://api.seller360.ir/v1/commitments",
    headers={"Authorization": f"Bearer {os.environ['S360_API_KEY']}"},
    params={"short": 1},
    timeout=20,
).json()
for c in res["data"]:
    print(c["supplier_code"], c["shortfall"], c["penalty_risk"])

const res = await fetch('https://api.seller360.ir/v1/commitments?short=1', {
  headers: { Authorization: `Bearer ${process.env.S360_API_KEY}` },
})
const body = await res.json()
for (const c of body.data) {
  console.log(c.supplier_code, c.shortfall, c.penalty_risk)
}

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/commitments?short=1");
foreach (var c in body.GetProperty("data").EnumerateArray()) {
    Console.WriteLine($"{c.GetProperty("supplier_code")} {c.GetProperty("shortfall")}");
}

تعهد ارسال

📖 مقدمه

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

دسترسی (Scope)

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

آدرس پایه

📦 مدل تعهد

فیلدهای هر ردیف (Commitment)

رابطه‌ی اعداد

جریمه‌ی تخمینی

🔄 وضعیت‌ها

🔢 تازگی

⚠️ هشدارها

📡 مسیرها

GET /v1/commitments — تعهد ارسال هر تنوع فعال

GET /v1/commitments/summary — خلاصه‌ی تعهد ارسال پنل فعال

GET /v1/ship-by-seller-orders — سفارش‌های ارسال توسط فروشنده فعال

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

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

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

فیلدهای هر ردیف (`Commitment`)

`GET /v1/commitments` — تعهد ارسال هر تنوع فعال

`GET /v1/commitments/summary` — خلاصه‌ی تعهد ارسال پنل فعال

`GET /v1/ship-by-seller-orders` — سفارش‌های ارسال توسط فروشنده فعال