ساخت خودکار محموله و انبارش هوشمند

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

📖 مقدمه

برای ارسال کالا به انبار دیجی‌کالا (محموله‌ی انبارش) باید نوبت خالی پیدا کنید، و نوبت‌ها در چند دقیقه پر می‌شوند. سلر ۳۶۰ این کار را با دو ابزار انجام می‌دهد:

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

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

کار	مسیر	در دسترس
فهرست پیش‌نویس‌ها	`GET /v1/consignment-drafts`	فعال
ساخت پیش‌نویس	`POST /v1/consignment-drafts`	فعال
خواندن یک پیش‌نویس	`GET /v1/consignment-drafts/{draft_id}`	فعال
تغییر تنظیمات پیش‌نویس	`PATCH /v1/consignment-drafts/{draft_id}`	فعال
حذف پیش‌نویس	`DELETE /v1/consignment-drafts/{draft_id}`	فعال
تعیین اقلام پیش‌نویس	`PUT /v1/consignment-drafts/{draft_id}/items`	فعال
رونوشت پیش‌نویس برای روزهای دیگر	`POST /v1/consignment-drafts/{draft_id}/copies`	فعال
تلاش‌های ساخت یک پیش‌نویس	`GET /v1/consignment-drafts/{draft_id}/runs`	فعال
همین حالا بساز (در صف)	`POST /v1/consignment-drafts/{draft_id}/build`	فعال
تایید و جست‌وجوی نوبت	`POST /v1/consignment-drafts/{draft_id}/approval`	فعال
فهرست مجاز انبارش و سقف هر تنوع	`GET /v1/consignment-eligibility`	فعال
خواندن تنظیمات انبارش هوشمند	`GET /v1/replenish-settings`	فعال
تغییر تنظیمات انبارش هوشمند	`PATCH /v1/replenish-settings`	فعال
قانون‌های انبارش هوشمند	`GET /v1/replenish-rules`	فعال
قانون یک تنوع	`GET /v1/replenish-rules/{variant_id}`	فعال
ثبت یا تغییر قانون یک تنوع	`PUT /v1/replenish-rules/{variant_id}`	فعال
حذف قانون یک تنوع	`DELETE /v1/replenish-rules/{variant_id}`	فعال
سابقه‌ی بررسی‌های روزانه	`GET /v1/replenish-checks`	فعال
بررسی همین حالا	`POST /v1/replenish-checks`	فعال

و با رویدادهای وب‌هوک consignment_draft.built، consignment_draft.missed و replenish.skipped خبردار شوید.

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

دسترسی (Scope)

دسترسی	برای
`shipping:read`	همه‌ی خواندن‌های این صفحه و رویدادهای `consignment_draft.` و `replenish.`
`shipping:write`	ساخت و تغییر پیش‌نویس، قانون و تنظیمات، «همین حالا بساز»، تایید و «بررسی همین حالا»
`stock:read`	پیشنهاد می‌شود: برای دیدن موجودی پیش از تعیین اقلام (موجودی)

فعال بودن بخش‌ها

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

آدرس پایه

https://api.seller360.ir

📦 پیش‌نویس محموله‌ی انبارش

فیلدهای پیش‌نویس (`ConsignmentDraft`)

فیلد	برچسب در پنل	معنی
`id`، `code`	—	شناسه، و کد کوتاه: ماه و روز شمسی روز تحویل و شماره‌ی پیش‌نویس آن روز (مثلا `0825-1`).
`title`	—	عنوان دلخواه شما؛ حداکثر ۱۲۰ نویسه.
`origin`	—	`seller`: ساخته‌ی شما؛ `replenish`: ساخته‌ی انبارش هوشمند.
`enabled`	—	روشن یعنی ربات برای آن نوبت جست‌وجو و محموله را ثبت می‌کند.
`waiting_approval`	«پیش‌نویس تاییدنشده»	پیش‌نویس انبارش هوشمند که منتظر تایید شماست.
`mode`	«خودکار کامل» یا «تایید در تلگرام»	`auto`: ثبت خودکار کامل؛ `confirm`: پیش از هر ثبت، در تلگرام یا بله تایید خواسته می‌شود.
`warehouse_id`، `warehouse_title`	—	انبار مقصد.
`shipping_nature_id`	«اندازه‌ی محموله»	`1` کوچک، `2` متوسط، `3` سنگین.
`target_date`	—	روز تحویل.
`deadline_at`	«پایان مهلت»	آخرین لحظه‌ی تلاش ربات.
`searching_from`	—	اولین روزی که ربات برای این پیش‌نویس جست‌وجو می‌کند.
`hours`	«ساعت تحویل»	ساعت‌های شروع قابل قبول؛ فهرست خالی یعنی هر ساعت.
`hour_order`	«از زودترین ساعت» یا «از دیرترین ساعت»	ربات از کدام سر ساعت‌های شما شروع کند.
`split`	—	اگر یک نوبت جای همه را نداشت، تا سه تکه در ساعت‌های دیگر همان روز.
`follow_allowed_max`	—	اگر سقف انبارش کم شد، به همان اندازه بساز.
`tag`	برچسب کارت	جایگاه پیش‌نویس در چرخه‌ی کار (جدول وضعیت‌ها).
`ending`، `ended_at`	—	چگونه و چه وقت تمام شد: `built`، `missed` یا `stopped`؛ تا وقتی تمام نشده، خالی است.
`problem`	—	دلیل فارسی اینکه پیش‌نویس روشن نمی‌تواند کار کند؛ وگرنه خالی.
`items`	«کالاهای این پیش‌نویس»	اقلام.
`total_units`	—	جمع واحدها.
`remaining_units`	—	واحدهایی که هنوز در محموله‌ای ثبت نشده‌اند.
`open_slots`	—	نوبت‌های باز سازگار که پایش همین حالا می‌شناسد (حداکثر ۶).
`last_built_on`	—	آخرین روزی که از این پیش‌نویس محموله ساخته شد.
`paused_until`	—	ربات تا این زمان برای این پیش‌نویس صبر می‌کند (مثلا پس از شلوغی دیجی‌کالا).

فیلدهای هر قلم پیش‌نویس

فیلد	برچسب در پنل	معنی
`variant_id`، `title`	«کد تنوع»، «عنوان تنوع»	تنوع.
`count`	«تعداد ارسالی»	تعداد.
`allowed_max`	«حداکثر انبارش»	سقف انبارش این تنوع برای یک محموله، در آخرین خواندن.
`digikala_stock`	«موجودی انبار دیجی‌کالا (زنده)»	موجودی انبار دیجی‌کالا در آخرین خواندن.
`synced_at`	—	زمان آخرین خواندن سقف و موجودی.

فهرست مجاز انبارش (`ConsignmentEligibility`)

دیجی‌کالا برای هر تنوع می‌گوید آیا اجازه‌ی ارسال آن به انبار را می‌دهد و در یک محموله حداکثر چند عدد.

فیلد	برچسب در پنل	معنی
`variant_id`، `shipping_nature_id`	«کد تنوع»، «اندازه‌ی محموله»	تنوع و اندازه.
`allowed_max`	«حداکثر انبارش»	سقف انبارش برای یک محموله.
`digikala_stock`	«موجودی انبار دیجی‌کالا (زنده)»	موجودی انبار دیجی‌کالا.
`on_the_way`	—	واحدهای در راه انبار.
`synced_at`	—	زمان آخرین خواندن از دیجی‌کالا.

🔄 وضعیت‌ها

چرخه‌ی پیش‌نویس (`tag`)

برچسب	برچسب در پنل	معنی
`reserved`	«رزرو»	روز تحویل هنوز دور است؛ ربات از سه روز مانده به آن شروع به جست‌وجو می‌کند.
`active`	«فعال»	ربات در حال جست‌وجوی نوبت برای این محموله است.
`off`	«خاموش»	پیش‌نویس خاموش است؛ ربات برای آن نوبتی جست‌وجو نمی‌کند.
`built`	«ثبت شد»	محموله ثبت شد و کار این پیش‌نویس تمام شد.
`missed`	«مهلت تمام شد»	تا پایان مهلت، نوبتی با ظرفیت کافی پیدا نشد.
`stopped`	«متوقف با خطا»	ثبت به دلیلی متوقف شد که با تلاش دوباره حل نمی‌شود.

پیش‌نویس تمام‌شده (built، missed، stopped) ۷ روز پس از پایان از فهرست خارج می‌شود. روشن کردن دوباره‌ی پیش‌نویس تمام‌شده، آن را از نو شروع می‌کند.

هر تلاش ساخت (`ConsignmentDraftRun.status`)

وضعیت	معنی
`confirm_sent`	منتظر تایید شما در تلگرام یا بله.
`claimed`	در حال ساخت.
`created`	محموله ساخته شد؛ `package_id` و `package_number` پر است.
`failed`	دیجی‌کالا نپذیرفت و چیزی ساخته نشد.
`unknown`	پاسخ دیجی‌کالا نرسید و معلوم نیست محموله ساخته شد یا نه (هشدار ۲).
`cancelled`	شما رد کردید.
`expired`	تایید به موقع نرسید؛ دکمه‌ی تایید پس از ۲۰ دقیقه بی‌اثر می‌شود.
`deleted`	محموله‌ی ساخته‌شده بعدا حذف شد.

در ساخت تکه‌تکه، هر تکه یک تلاش جداست (piece_no از piece_count). فیلد items هر تلاش دقیقا همان چیزی است که برای دیجی‌کالا فرستاده شد، و detail توضیح فارسی نتیجه است.

🤖 انبارش هوشمند

قانون (`ReplenishRule`)

هر تنوع یک قانون دارد؛ هر پنل حداکثر ۳۰۰ قانون.

فیلد	برچسب در پنل	معنی
`variant_id`	«کالا»	تنوع.
`title`	«قانون»	متن دلخواه؛ حداکثر ۳۰۰ نویسه.
`enabled`	«فعال»	قانون روشن است.
`trigger_kind`، `trigger_value`	«کمتر از»	`units`: موجودی کمتر از این تعداد؛ `days`: روز فروش کمتر از این تعداد (۱ تا ۱۰۰٬۰۰۰).
`qty_kind`، `qty_value`	«تعداد ارسال»	`fixed`: عدد ثابت؛ `target`: تا سطح هدف؛ `days`: فروش چند روز؛ `suggested`: «پیشنهاد ارسال» سلر ۳۶۰. برای همه جز `suggested`، `qty_value` لازم است.
`case_size`	«مضرب ارسال (اختیاری)»	مضرب ارسال، مثلا کارتن ۱۲تایی.
`keep_seller`	«حداقل موجودی نزد شما»	حداقل موجودی که در انبار خودتان می‌ماند.
`decision`	«وضعیت امروز»	تصمیمی که همین لحظه درباره‌ی این قانون گرفته می‌شود.

موجودی‌ای که قانون روی آن سنجیده می‌شود

موجودی موثر = باقی‌مانده در انبار دیجی‌کالا + محموله‌های انبارش در راه + پیش‌نویس‌های باز
روز فروش    = موجودی موثر ÷ فروش روزانه‌ی وزنی
تعداد نهایی ≤ موجودی آزاد شما − keep_seller
تعداد نهایی ≤ سقف انبارش یک محموله (allowed_max)

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

تصمیم هر قانون (`decision.status`)

وضعیت	معنی
`send`	زیر آستانه است و در محموله‌ی امروز قرار می‌گیرد.
`companion`	نزدیک آستانه است و همراه محموله‌ای که به هر حال می‌رود ارسال می‌شود (`companion_pct`).
`ok`	موجودی کافی است.
`locked`	این تنوع محموله یا پیش‌نویس باز دارد.
`not_eligible`	در فهرست مجاز انبارش نیست.
`no_stock`	موجودی آزاد نزد شما نیست.
`ceiling`	سقف انبارش صفر است.
`no_sales`	قانون به فروش روزانه نیاز دارد و فروشی نیست.
`zero`	تعداد محاسبه‌شده صفر است.
`off`	قانون خاموش است.

در decision، فیلد qty تعداد ارسالی، level عددی که شرط روی آن سنجیده شد (واحد یا روز، با یک رقم اعشار)، و capped_by محدودیتی است که تعداد را کم کرد: seller (موجودی آزاد شما) یا ceiling (سقف انبارش).

تنظیمات (`ReplenishSettings`)

فیلد	برچسب در پنل	معنی
`enabled`	«روشن کردن انبارش هوشمند»	بررسی روزانه انجام شود. روشن کردن بدون انبار پذیرفته نمی‌شود.
`trial`	«حالت آزمایشی»	بررسی انجام و گزارش می‌شود، اما پیش‌نویسی ساخته نمی‌شود.
`warehouse_id`، `shipping_nature_id`	—	انبار و اندازه‌ی پیش‌نویس‌ها.
`weekdays`	—	روزهای هفته‌ای که تحویل می‌دهید؛ ۰ شنبه تا ۶ جمعه. فهرست خالی یعنی هر روز.
`lead_days`	«تحویل بار»	روز تحویل دست‌کم چند روز پس از بررسی (۱ تا ۳).
`hours`، `hour_order`، `mode`، `split`، `follow_allowed_max`	—	همان تنظیم‌های پیش‌نویس، برای پیش‌نویس‌هایی که ساخته می‌شوند.
`approval`	«پس از تایید من» یا «بلافاصله پس از ساخت پیش‌نویس»	پیش‌نویس صبح تا تایید شما خاموش می‌ماند.
`companion_pct`	—	تنوعی که تا این درصد بالای آستانه است، همراه محموله ارسال می‌شود؛ ۰ یعنی خاموش.

نتیجه‌ی بررسی روزانه (`ReplenishCheck.status`)

وضعیت	معنی
`built`	پیش‌نویس ساخته شد (`draft_id`).
`trial`	حالت آزمایشی؛ فقط گزارش.
`nothing`	هیچ قانونی فعال نشد.
`skipped`	اعداد به اندازه‌ی کافی تازه نبودند و تصمیمی گرفته نشد.
`failed`	پیش‌نویس ساخته نشد.

🔐 کدام تنظیم‌ها اجازه‌ی ساخت محموله‌ی واقعی را می‌دهند

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

کار	اثر	فاز
`PATCH /v1/consignment-drafts/{draft_id}` با `enabled: true`	ربات به محض یافتن نوبت مناسب، محموله را در دیجی‌کالا ثبت می‌کند.	فعال
`POST /v1/consignment-drafts/{draft_id}/build`	محموله همین حالا ثبت می‌شود؛ حالت تایید و مهلت پیش‌نویس در نظر گرفته نمی‌شوند.	فعال
`POST /v1/consignment-drafts/{draft_id}/approval`	پیش‌نویس منتظر تایید انبارش هوشمند روشن می‌شود و ربات برای آن نوبت می‌گیرد.	فعال
`PATCH /v1/replenish-settings` با `trial: false`	بررسی روزانه پیش‌نویس واقعی می‌سازد. با `approval: true` پیش‌نویس تا تایید شما خاموش می‌ماند.	فعال
`PATCH /v1/replenish-settings` با `trial: false` و `approval: false`	ربات پیش‌نویس صبح را بدون تایید شما در دیجی‌کالا ثبت می‌کند. این ترکیب از API پذیرفته نمی‌شود (`feature_unavailable`) و فقط از پنل سلر ۳۶۰ قابل تنظیم است.	فقط از پنل

تنظیم mode در هر دو حالت یک لایه‌ی دیگر است: با confirm، پیش از هر ثبت در تلگرام یا بله از شما تایید خواسته می‌شود و اگر تا ۲۰ دقیقه پاسخ ندهید، تلاش expired می‌شود.

🔢 تازگی

نوبت‌های باز پیش‌نویس (open_slots) از پاسخ مشترک پایش نوبت است که هر ۳۰ ثانیه تازه می‌شود؛ خواندن پیش‌نویس هیچ درخواستی به دیجی‌کالا نمی‌فرستد.
سقف انبارش در GET /v1/consignment-eligibility از آخرین خواندن است (synced_at)، و پیش از هر ذخیره‌ی اقلام و هر ساخت، همان لحظه دوباره از دیجی‌کالا خوانده می‌شود.
بررسی روزانه هر روز ساعت ۰۶:۱۵ به وقت تهران، پس از همگام‌سازی شبانه‌ی محصولات و محموله‌ها اجرا می‌شود. اگر همگام‌سازی محصولات قدیمی‌تر از ۸ ساعت یا همگام‌سازی محموله‌ها قدیمی‌تر از ۲۶ ساعت باشد، نتیجه skipped است.
جست‌وجوی ربات از سه روز مانده به روز تحویل شروع می‌شود؛ پیش از آن، برچسب پیش‌نویس reserved است.

⚠️ هشدارها

📡 مسیرها

`GET /v1/consignment-drafts` — فهرست پیش‌نویس‌ها فعال

پارامتر	نوع	اجباری	توضیح
`tag`	`reserved`، `active`، `off`، `built`، `missed`، `stopped`	خیر	فقط پیش‌نویس‌هایی با این برچسب.
`origin`	`seller`، `replenish`	خیر	فقط ساخته‌ی شما یا انبارش هوشمند.
`target_date`	تاریخ	خیر	فقط پیش‌نویس‌های این روز تحویل.
`page`، `size`	عدد	خیر	صفحه‌بندی.

پاسخ نمونه

{
  "status": "ok",
  "data": [
    {
      "id": 318,
      "code": "0825-1",
      "title": "ارسال هفتگی کرج",
      "origin": "seller",
      "enabled": true,
      "waiting_approval": false,
      "mode": "auto",
      "warehouse_id": 1,
      "warehouse_title": "انبار کرج",
      "shipping_nature_id": 1,
      "target_date": "2026-11-16",
      "deadline_at": "2026-11-15T23:59:00+03:30",
      "searching_from": "2026-11-13",
      "hours": [9, 10, 13],
      "hour_order": "early",
      "split": true,
      "follow_allowed_max": false,
      "tag": "active",
      "ending": null,
      "ended_at": null,
      "problem": null,
      "items": [
        { "variant_id": 84780448, "count": 40, "title": "محافظ ولتاژ پارت الکتریک مدل PE5144", "allowed_max": 60, "digikala_stock": 12, "synced_at": "2026-11-13T09:58:40+03:30" },
        { "variant_id": 84780512, "count": 80, "title": "محافظ ولتاژ پارت الکتریک مدل PE5146", "allowed_max": 120, "digikala_stock": 3, "synced_at": "2026-11-13T09:58:40+03:30" }
      ],
      "total_units": 120,
      "remaining_units": 120,
      "open_slots": [
        { "date": "2026-11-14", "capacity_id": 9081733, "starts_at": 10, "ends_at": 11, "remained": 3 }
      ],
      "last_built_on": null,
      "paused_until": null,
      "created_at": "2026-11-12T16:40:12+03:30",
      "updated_at": "2026-11-13T09:58:40+03:30"
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 3 }
}

`POST /v1/consignment-drafts` — ساخت پیش‌نویس فعال

پیش‌نویس برای یک روز تحویل (حداکثر ۷ روز بعد) ساخته می‌شود و خاموش است. اقلام را سپس با PUT /v1/consignment-drafts/{draft_id}/items تعیین کنید.

فیلد بدنه	نوع	اجباری	توضیح
`warehouse_id`	عدد	بله	باید با همین اندازه در `GET /v1/warehouses` آمده باشد.
`shipping_nature_id`	`1`، `2`، `3`	بله	اندازه‌ی محموله.
`target_date`	تاریخ	بله	روز تحویل، از امروز تا ۷ روز بعد.
`title`	متن	خیر	حداکثر ۱۲۰ نویسه.
`deadline_at`	زمان	خیر	آخرین لحظه‌ی تلاش ربات؛ دیرتر از پایان روز تحویل پذیرفته نمی‌شود.
`hours`	فهرست عدد	خیر	ساعت‌های شروع قابل قبول؛ خالی یعنی هر ساعت.
`hour_order`	`early`، `late`	خیر	از زودترین یا دیرترین ساعت.
`mode`	`auto`، `confirm`	خیر	ثبت خودکار کامل یا تایید در تلگرام.
`split`	بولی	خیر	ساخت تا سه تکه در ساعت‌های دیگر همان روز.
`follow_allowed_max`	بولی	خیر	اگر سقف کم شد، به همان اندازه بساز.

خطاهای این مسیر

کد HTTP	خطا	معنی	تکرار بی‌خطر است؟
`400`	`invalid_parameter`	بدنه نامعتبر است؛ مثلا روز تحویل بیش از ۷ روز بعد است.	خیر؛ بدنه را اصلاح کنید.
`409`	`draft_limit_reached`	پنل به سقف ۳۰ پیش‌نویس رسیده است.	خیر؛ پیش‌نویسی را حذف کنید.
`409`	`idempotency_mismatch`	این کلید قبلا با بدنه‌ی دیگری استفاده شده است.	خیر؛ کلید تازه بسازید.
`409`	`idempotency_in_progress`	درخواستی با همین کلید در حال انجام است.	بله، چند ثانیه بعد.
`422`	`warehouse_not_listed`	این انبار با این اندازه در فهرست انبارهای پنل نیست.	خیر.

`PATCH /v1/consignment-drafts/{draft_id}` — تغییر تنظیمات فعال

فقط فیلدهای ارسال‌شده تغییر می‌کنند؛ فیلدها مانند ساخت پیش‌نویس، به‌علاوه‌ی enabled. روشن کردن (enabled: true) یعنی اجازه‌ی ثبت خودکار در دیجی‌کالا و از فاز ۳ پذیرفته می‌شود.

کد HTTP	خطا	معنی	تکرار بی‌خطر است؟
`404`	`not_found`	پیش‌نویس در این پنل نیست.	خیر.
`422`	`draft_not_buildable`	پیش‌نویس در وضعیت فعلی روشن نمی‌شود؛ مثلا اقلام ندارد. دلیل در `detail` است.	خیر؛ دلیل را برطرف کنید.
`422`	`draft_overdue`	مهلت پیش‌نویس گذشته است.	خیر؛ روز تحویل یا مهلت را تغییر دهید.

`DELETE /v1/consignment-drafts/{draft_id}` — حذف پیش‌نویس فعال

{ "status": "ok", "data": { "id": 318, "deleted": true } }

`PUT /v1/consignment-drafts/{draft_id}/items` — تعیین اقلام فعال

همه‌ی اقلام را با این فهرست جایگزین می‌کند (حداکثر ۴۰ تنوع). پیش از ذخیره، فهرست مجاز انبارش همان لحظه از دیجی‌کالا خوانده می‌شود. چیزی در دیجی‌کالا ثبت نمی‌شود.

PUT /v1/consignment-drafts/318/items HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: draft-318-items-v2
Content-Type: application/json

{ "items": [ { "variant_id": 84780448, "count": 40 }, { "variant_id": 84780512, "count": 80 } ] }

پاسخ نمونه

{
  "status": "ok",
  "data": {
    "draft": { "id": 318, "code": "0825-1", "total_units": 120, "remaining_units": 120, "tag": "off" },
    "warnings": ["جمع پیش‌نویس‌های باز کد تنوع 84780512 از سقف انبارش آن بیشتر است."]
  }
}

کد HTTP	خطا	معنی	تکرار بی‌خطر است؟
`422`	`consignment_not_allowed`	یک تنوع در فهرست مجاز نیست یا تعداد آن از سقف بیشتر است.	خیر؛ فهرست مجاز را بخوانید.
`502`	`digikala_refused`	دیجی‌کالا فهرست مجاز را نداد؛ چیزی ذخیره نشد.	پس از بررسی علت.
`503`	`digikala_unavailable`، `digikala_rate_limited`	دیجی‌کالا در دسترس نیست یا سقف آن پر است.	بله، پس از `Retry-After`.

`POST /v1/consignment-drafts/{draft_id}/copies` — رونوشت برای روزهای دیگر فعال

برای هر روز داده‌شده (۱ تا ۷ روز) یک پیش‌نویس تازه با همان انبار، اقلام و تنظیمات می‌سازد؛ رونوشت‌ها خاموش ساخته می‌شوند.

{ "target_dates": ["2026-11-16", "2026-11-18"] }

پاسخ 201 شامل drafts و warnings است. اگر رونوشت‌ها از سقف ۳۰ پیش‌نویس بگذرند، 409 و draft_limit_reached برمی‌گردد.

`GET /v1/consignment-drafts/{draft_id}/runs` — تلاش‌های ساخت فعال

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

{
  "status": "ok",
  "data": [
    {
      "id": 5521,
      "status": "created",
      "date": "2026-11-14",
      "capacity_id": 9081733,
      "starts_at": 10,
      "ends_at": 11,
      "units": 120,
      "items": [ { "variant_id": 84780448, "count": 40 }, { "variant_id": 84780512, "count": 80 } ],
      "package_id": 51874402,
      "package_number": "P-1405-51874402",
      "piece_no": 1,
      "piece_count": 1,
      "detail": "محموله در انبار کرج برای ساعت ۱۰ تا ۱۱ ثبت شد.",
      "built_at": "2026-11-13T10:22:41+03:30",
      "created_at": "2026-11-13T10:22:37+03:30"
    }
  ]
}

`POST /v1/consignment-drafts/{draft_id}/build` — همین حالا بساز فعال

محموله‌ی این پیش‌نویس را همین حالا در دیجی‌کالا ثبت می‌کند: در نوبتی که انتخاب کرده‌اید (date و capacity_id از GET /v1/warehouse-slots)، یا اگر بدنه‌ای نفرستید، در زودترین نوبت باز سازگار با تنظیمات پیش‌نویس. حالت تایید و مهلت پیش‌نویس در نظر گرفته نمی‌شوند، اما سقف انبارش و جای نوبت همان لحظه دوباره از دیجی‌کالا خوانده می‌شوند. ساختی که همه‌ی اقلام را ارسال کند، پیش‌نویس را تمام می‌کند.

{ "date": "2026-11-14", "capacity_id": 9081733 }

فیلد بدنه	نوع	اجباری	توضیح
`date`	تاریخ	خیر	روز نوبت، از امروز تا سه روز بعد؛ همراه `capacity_id`.
`capacity_id`	عدد	خیر	شناسه‌ی نوبت از `GET /v1/warehouse-slots`.

پاسخ فوری 202 با کاری از نوع consignment_draft_build است؛ نتیجه با job.completed، تلاش تازه در runs و رویداد consignment_draft.built اعلام می‌شود.

کد HTTP	خطا	معنی	تکرار بی‌خطر است؟
`403`	`shipping_write_unavailable`	ساخت محموله برای این پنل ممکن نیست.	خیر.
`404`	`not_found`	پیش‌نویس در این پنل نیست.	خیر.
`409`	`stock_write_locked`	تقسیم موجودی در حال اجراست.	بله، پس از `Retry-After` و با همان کلید.
`409`	`build_in_progress`	ساخت دیگری برای این پنل در جریان است.	بله، پس از پایان آن.
`409`	`slot_unavailable`	این نوبت دیگر باز نیست یا پیش‌تر برای همین پیش‌نویس رزرو شده است.	خیر؛ نوبت دیگری انتخاب کنید.
`409`	`no_open_slot`	نوبت بازی سازگار با تنظیمات پیش‌نویس وجود ندارد.	بله، پس از باز شدن نوبت (`slot.opened`).
`409`	`idempotency_mismatch`، `idempotency_in_progress`	کلید یکتای درخواست	مانند صفحه‌ی کلید یکتا.
`422`	`draft_not_buildable`	پیش‌نویس در وضعیت فعلی قابل ساخت نیست؛ دلیل در `detail`.	خیر؛ دلیل را برطرف کنید.
`422`	`consignment_not_allowed`	یک تنوع دیگر مجاز نیست یا از سقف تازه بیشتر است.	خیر؛ اقلام را اصلاح کنید.

`POST /v1/consignment-drafts/{draft_id}/approval` — تایید و جست‌وجوی نوبت فعال

پیش‌نویسی را که انبارش هوشمند ساخته و منتظر تایید شماست روشن می‌کند تا ربات برای آن نوبت بگیرد. بدنه ندارد. برای پیش‌نویسی که منتظر تایید نیست، 409 و draft_not_waiting برمی‌گردد؛ اگر مهلت آن گذشته باشد، 422 و draft_overdue.

`GET /v1/consignment-eligibility` — فهرست مجاز و سقف انبارش فعال

پارامتر	نوع	اجباری	توضیح
`shipping_nature_id`	`1`، `2`، `3`	خیر	فقط این اندازه‌ی محموله.
`variant_id`	عدد	خیر	فقط این تنوع.
`page`، `size`	عدد	خیر	صفحه‌بندی.

{
  "status": "ok",
  "data": [
    { "variant_id": 84780448, "shipping_nature_id": 1, "allowed_max": 60, "digikala_stock": 12, "on_the_way": 0, "synced_at": "2026-11-13T09:58:40+03:30" }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 3, "total_rows": 118 }
}

`GET /v1/replenish-settings` و `PATCH /v1/replenish-settings` — تنظیمات انبارش هوشمند فعال

اگر تنظیمات هرگز ذخیره نشده باشد، مقادیر پیش‌فرض با enabled: false برمی‌گردد. در PATCH فقط فیلدهای ارسال‌شده تغییر می‌کنند؛ روشن کردن بدون انبار با خطای invalid_parameter رد می‌شود. خاموش کردن هم‌زمان trial و approval در پنلی که انبارش هوشمند آن روشن است از API پذیرفته نمی‌شود (feature_unavailable). پیش از خاموش کردن trial، جدول بخش «کدام تنظیم‌ها اجازه‌ی ساخت محموله‌ی واقعی را می‌دهند» در همین صفحه را ببینید.

{
  "status": "ok",
  "data": {
    "enabled": true,
    "trial": true,
    "warehouse_id": 1,
    "warehouse_title": "انبار کرج",
    "shipping_nature_id": 1,
    "weekdays": [0, 2, 4],
    "lead_days": 2,
    "hours": [9, 10],
    "hour_order": "early",
    "mode": "confirm",
    "split": true,
    "follow_allowed_max": true,
    "approval": true,
    "companion_pct": 20
  }
}

`GET /v1/replenish-rules` — قانون‌ها فعال

هر قانون با تصمیمی که همین لحظه درباره‌ی آن گرفته می‌شود. GET /v1/replenish-rules/{variant_id} همان ساختار را برای یک تنوع برمی‌گرداند.

{
  "status": "ok",
  "data": [
    {
      "variant_id": 84780448,
      "title": "اگر موجودی به زیر ۸۰ رسید، ۲۰ عدد بفرست.",
      "enabled": true,
      "trigger_kind": "units",
      "trigger_value": 80,
      "qty_kind": "fixed",
      "qty_value": 20,
      "case_size": null,
      "keep_seller": 5,
      "decision": { "status": "send", "qty": 20, "level": 64.0, "capped_by": null }
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 14 }
}

`PUT /v1/replenish-rules/{variant_id}` — ثبت یا تغییر قانون فعال

قانون تازه همه‌ی فیلدهای لازم را می‌خواهد (enabled، trigger_kind، trigger_value، qty_kind، keep_seller، و qty_value جز برای suggested)؛ در قانون موجود فقط فیلدهای ارسال‌شده تغییر می‌کنند.

{ "enabled": true, "trigger_kind": "days", "trigger_value": 14, "qty_kind": "days", "qty_value": 30, "case_size": 12, "keep_seller": 5 }

کد HTTP	خطا	معنی	تکرار بی‌خطر است؟
`400`	`invalid_parameter`	فیلد لازم نیامده یا بیرون از بازه است.	خیر؛ بدنه را اصلاح کنید.
`409`	`replenish_rule_limit`	پنل به سقف ۳۰۰ قانون رسیده است.	خیر؛ قانونی را حذف کنید.
`409`	`idempotency_mismatch`، `idempotency_in_progress`	کلید یکتای درخواست	مانند صفحه‌ی کلید یکتا.

`DELETE /v1/replenish-rules/{variant_id}` — حذف قانون فعال

{ "status": "ok", "data": { "variant_id": 84780448, "deleted": true } }

`GET /v1/replenish-checks` — سابقه‌ی بررسی‌ها فعال

هر بررسی صبح و نتیجه‌ی آن، تازه‌ترین اول. با status فقط بررسی‌هایی با یک نتیجه را بخوانید.

{
  "status": "ok",
  "data": [
    {
      "id": 77,
      "day": "2026-11-13",
      "ran_at": "2026-11-13T06:15:08+03:30",
      "status": "built",
      "message": "پیش‌نویس ۰۸۲۴-۲ با ۶۰ واحد برای روز تحویل ۱۴۰۵/۸/۲۴ ساخته شد.",
      "units": 60,
      "target_date": "2026-11-15",
      "draft_id": 319,
      "lines": [
        { "variant_id": 84780448, "title": "محافظ ولتاژ پارت الکتریک مدل PE5144", "status": "send", "qty": 20, "level": 64.0, "capped_by": null },
        { "variant_id": 84780512, "title": "محافظ ولتاژ پارت الکتریک مدل PE5146", "status": "companion", "qty": 40, "level": 92.0, "capped_by": "ceiling" }
      ]
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 2, "total_rows": 61 }
}

`POST /v1/replenish-checks` — بررسی همین حالا فعال

بررسی روزانه را همین حالا با همان قواعد اجرا می‌کند: در هر روز حداکثر یک پیش‌نویس، و هرگز روی اعداد کهنه (skipped). اگر امروز پیش‌تر بررسی‌ای پیش‌نویس یا گزارش آزمایشی ساخته باشد، همان را برمی‌گرداند. در دیجی‌کالا چیزی ثبت نمی‌شود؛ پیش‌نویس ساخته‌شده از مسیر عادی پیش‌نویس‌ها ثبت می‌شود. اگر انبارش هوشمند خاموش باشد، 409 و replenish_inactive برمی‌گردد.

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

رویداد	چه وقت
`consignment_draft.built`	پس از هر تلاش موفق (ربات یا «همین حالا بساز»). در ساخت تکه‌تکه، برای هر تکه یک رویداد (`run.piece_no` از `run.piece_count`).
`consignment_draft.missed`	مهلت یک پیش‌نویس بدون ساخت محموله تمام شد: نوبتی با ظرفیت کافی پیدا نشد یا پیش‌نویس انبارش هوشمند تایید نشد.
`replenish.skipped`	بررسی صبح به دلیل کهنه بودن اعداد موجودی یا محموله‌ها تصمیمی نگرفت؛ دلیل در `check.message` است.
`job.completed`	کار «همین حالا بساز» تمام شد (کارهای در صف).

نمونه‌ی پیام consignment_draft.built

{
  "id": "evt_01HZYH6W",
  "type": "consignment_draft.built",
  "created_at": "2026-11-13T10:22:43+03:30",
  "panel_id": 1,
  "livemode": true,
  "data": {
    "draft": {
      "id": 318,
      "code": "0825-1",
      "title": "ارسال هفتگی کرج",
      "origin": "seller",
      "enabled": false,
      "mode": "auto",
      "warehouse_id": 1,
      "shipping_nature_id": 1,
      "tag": "built",
      "ending": "built",
      "items": [ { "variant_id": 84780448, "count": 40 }, { "variant_id": 84780512, "count": 80 } ],
      "total_units": 120,
      "remaining_units": 0
    },
    "run": {
      "id": 5521,
      "status": "created",
      "date": "2026-11-14",
      "capacity_id": 9081733,
      "starts_at": 10,
      "ends_at": 11,
      "units": 120,
      "items": [ { "variant_id": 84780448, "count": 40 }, { "variant_id": 84780512, "count": 80 } ],
      "package_id": 51874402,
      "package_number": "P-1405-51874402",
      "piece_no": 1,
      "piece_count": 1,
      "built_at": "2026-11-13T10:22:41+03:30",
      "created_at": "2026-11-13T10:22:37+03:30"
    }
  }
}

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

💻 نمونه‌کد: ساخت پیش‌نویس محموله‌ی انبارش

پیش‌نویس خاموش ساخته می‌شود و چیزی در دیجی‌کالا ثبت نمی‌کند. قدم بعد، تعیین اقلام با PUT /v1/consignment-drafts/{draft_id}/items است.

curl -X POST https://api.seller360.ir/v1/consignment-drafts \
  -H "Authorization: Bearer $S360_API_KEY" \
  -H "Idempotency-Key: draft-karaj-2026-11-16" \
  -H "Content-Type: application/json" \
  -d '{"title": "ارسال هفتگی کرج", "warehouse_id": 1, "shipping_nature_id": 1,
       "target_date": "2026-11-16", "hours": [9, 10, 13], "mode": "confirm"}'

$ch = curl_init("https://api.seller360.ir/v1/consignment-drafts");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("S360_API_KEY"),
        "Idempotency-Key: draft-karaj-2026-11-16",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "title" => "ارسال هفتگی کرج",
        "warehouse_id" => 1,
        "shipping_nature_id" => 1,
        "target_date" => "2026-11-16",
        "hours" => [9, 10, 13],
        "mode" => "confirm",
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
]);
$res = json_decode(curl_exec($ch), true);
$draftId = $res["data"]["id"];

import os, requests

res = requests.post(
    "https://api.seller360.ir/v1/consignment-drafts",
    headers={
        "Authorization": f"Bearer {os.environ['S360_API_KEY']}",
        "Idempotency-Key": "draft-karaj-2026-11-16",
    },
    json={
        "title": "ارسال هفتگی کرج",
        "warehouse_id": 1,
        "shipping_nature_id": 1,
        "target_date": "2026-11-16",
        "hours": [9, 10, 13],
        "mode": "confirm",
    },
    timeout=20,
).json()
draft_id = res["data"]["id"]

const res = await fetch('https://api.seller360.ir/v1/consignment-drafts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.S360_API_KEY}`,
    'Idempotency-Key': 'draft-karaj-2026-11-16',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'ارسال هفتگی کرج',
    warehouse_id: 1,
    shipping_nature_id: 1,
    target_date: '2026-11-16',
    hours: [9, 10, 13],
    mode: 'confirm',
  }),
})
const body = await res.json()
const draftId = body.data.id

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post,
    "https://api.seller360.ir/v1/consignment-drafts");
req.Headers.Add("Authorization", $"Bearer {Environment.GetEnvironmentVariable("S360_API_KEY")}");
req.Headers.Add("Idempotency-Key", "draft-karaj-2026-11-16");
req.Content = JsonContent.Create(new {
    title = "ارسال هفتگی کرج",
    warehouse_id = 1,
    shipping_nature_id = 1,
    target_date = "2026-11-16",
    hours = new[] { 9, 10, 13 },
    mode = "confirm",
});
var res = await http.SendAsync(req);
var body = await res.Content.ReadFromJsonAsync<JsonElement>();
var draftId = body.GetProperty("data").GetProperty("id").GetInt32();

ساخت خودکار محموله و انبارش هوشمند

📖 مقدمه

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

دسترسی (Scope)

فعال بودن بخش‌ها

آدرس پایه

📦 پیش‌نویس محموله‌ی انبارش

فیلدهای پیش‌نویس (ConsignmentDraft)

فیلدهای هر قلم پیش‌نویس

فهرست مجاز انبارش (ConsignmentEligibility)

🔄 وضعیت‌ها

چرخه‌ی پیش‌نویس (tag)

هر تلاش ساخت (ConsignmentDraftRun.status)

🤖 انبارش هوشمند

قانون (ReplenishRule)

موجودی‌ای که قانون روی آن سنجیده می‌شود

تصمیم هر قانون (decision.status)

تنظیمات (ReplenishSettings)

نتیجه‌ی بررسی روزانه (ReplenishCheck.status)

🔐 کدام تنظیم‌ها اجازه‌ی ساخت محموله‌ی واقعی را می‌دهند

🔢 تازگی

⚠️ هشدارها

📡 مسیرها

GET /v1/consignment-drafts — فهرست پیش‌نویس‌ها فعال

POST /v1/consignment-drafts — ساخت پیش‌نویس فعال

PATCH /v1/consignment-drafts/{draft_id} — تغییر تنظیمات فعال

DELETE /v1/consignment-drafts/{draft_id} — حذف پیش‌نویس فعال

PUT /v1/consignment-drafts/{draft_id}/items — تعیین اقلام فعال

POST /v1/consignment-drafts/{draft_id}/copies — رونوشت برای روزهای دیگر فعال

GET /v1/consignment-drafts/{draft_id}/runs — تلاش‌های ساخت فعال

POST /v1/consignment-drafts/{draft_id}/build — همین حالا بساز فعال

POST /v1/consignment-drafts/{draft_id}/approval — تایید و جست‌وجوی نوبت فعال

GET /v1/consignment-eligibility — فهرست مجاز و سقف انبارش فعال

GET /v1/replenish-settings و PATCH /v1/replenish-settings — تنظیمات انبارش هوشمند فعال

GET /v1/replenish-rules — قانون‌ها فعال

PUT /v1/replenish-rules/{variant_id} — ثبت یا تغییر قانون فعال

DELETE /v1/replenish-rules/{variant_id} — حذف قانون فعال

GET /v1/replenish-checks — سابقه‌ی بررسی‌ها فعال

POST /v1/replenish-checks — بررسی همین حالا فعال