پیشنهاد خرید و سفارش خرید

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

📖 مقدمه

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

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

کار	مسیر	در دسترس
پیشنهاد خرید هر کالای فیزیکی	`GET /v1/purchase-suggestions`	فعال
فهرست سفارش‌های خرید	`GET /v1/purchase-orders`	فعال
ساخت سفارش خرید پیش‌نویس	`POST /v1/purchase-orders`	فعال
خواندن یک سفارش خرید	`GET /v1/purchase-orders/{purchase_order_id}`	فعال
ویرایش سفارش خرید	`PATCH /v1/purchase-orders/{purchase_order_id}`	فعال
ثبت سفارش نزد تامین‌کننده	`POST /v1/purchase-orders/{purchase_order_id}/send`	فعال
ثبت دریافت کالا	`POST /v1/purchase-orders/{purchase_order_id}/receipts`	فعال
لغو سفارش خرید	`POST /v1/purchase-orders/{purchase_order_id}/cancel`	فعال

و با رویدادهای وب‌هوک purchase.needed و purchase_order.late از نیاز به خرید و دیرکرد تامین‌کننده خبردار شوید. هیچ‌کدام از این مسیرها چیزی در دیجی‌کالا نمی‌نویسند. قیمت خرید هر تنوع در صفحه‌ی قیمت خرید آمده است.

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

دسترسی (Scope)

دسترسی	برچسب در پنل	برای
`purchasing:read`	«خواندن پیشنهاد خرید و سفارش خرید»	خواندن پیشنهادها و سفارش‌ها
`purchasing:write`	«ثبت سفارش خرید»	ساخت، ویرایش، ثبت، دریافت و لغو سفارش

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

ماژول «API و وب‌هوک» باید برای پنل فعال باشد؛ در غیر این صورت پاسخ 403 با خطای module_inactive برمی‌گردد. سفارش خرید فقط در سلر ۳۶۰ ثبت می‌شود؛ پس ثبت آن برای پنلی که اشتراک آن به پایان رسیده است هم ممکن است.

آدرس پایه

https://api.seller360.ir

🧮 پیشنهاد خرید

کالای فیزیکی (`group_key`)

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

تنوع‌های فعال و تاییدشده با یک کد فروشنده: group_key همان کد فروشنده است (مثلا 5144).
تنوع بدون کد فروشنده: group_key به شکل #84780448 است.

همه‌ی اعداد بر حسب واحد فیزیکیاند؛ تنوعی که بسته‌ی چندتایی است (pack_size) به تعداد واحد داخل بسته حساب می‌شود.

فرمول

daily_sales     = جمع فروش روزانه‌ی وزن‌دار (۷، ۳۰ و ۹۰ روز) تنوع‌های کنارگذاشته‌نشده × ضریب اطمینان پنل
stock.on_hand   = seller_available + owed + warehouse_available
stock.total     = on_hand + open_purchase_orders
quantity        = max(0, daily_sales × (زمان تامین + روزهای پوشش + روزهای اطمینان) − stock.total)
order_by        = امروز + stock.total ÷ daily_sales − زمان تامین − روزهای اطمینان

ضریب اطمینان (margin در تنظیمات تقسیم موجودی) «محافظه‌کار» ۰٫۸، «متعادل» ۱ یا «تهاجمی» ۱٫۲ است و بین تقسیم موجودی، پیشنهاد ارسال و پیشنهاد خرید مشترک است. زمان تامین، روزهای پوشش و روزهای اطمینان در پنل تعیین می‌شوند و پیش‌فرض آن‌ها ۷، ۳۰ و ۷ روز است.

یک مثال

فروش روزانه ۲ عدد، زمان تامین ۷ روز، روزهای پوشش ۳۰ و روزهای اطمینان ۷ روز؛ کل موجودی ۲۰ عدد:

محاسبه	نتیجه
نیاز: `2 × (7 + 30 + 7)`	۸۸ عدد
تعداد پیشنهادی: `88 − 20`	۶۸ عدد
روزهای پوشش موجودی: `20 ÷ 2`	۱۰ روز
مهلت سفارش: `10 − 7 − 7`	۴ روز پیش (وضعیت `order_now`)

فیلدهای پیشنهاد (`PurchaseSuggestion`)

فیلد	برچسب در پنل	معنی
`group_key`	«کالا»	کد فروشنده، یا `#<variant_id>` برای تنوع بدون کد.
`supplier_code`	«کد فروشنده»	کد فروشنده.
`variant_id`	«کد DKPC»	پرفروش‌ترین تنوع کالا، به‌عنوان نماینده.
`status`	«وضعیت»	وضعیت پیشنهاد (جدول بعد).
`quantity`	«عدد»	تعداد پیشنهادی خرید.
`daily_sales`	«فروش روزانه و اطمینان آن»	فروش روزانه پس از ضریب اطمینان.
`confidence`، `low_confidence`	—	اطمینان به سرعت فروش: `high`، `medium`، `low` یا `manual` (برآورد دستی شما).
`days_left`	«روزهای باقی‌مانده»	`stock.on_hand` تقسیم بر `daily_sales`.
`stockout_on`	—	روزی که موجودی تمام می‌شود.
`cover_days_total`	—	`stock.total` تقسیم بر `daily_sales`.
`days_to_order`	—	`cover_days_total` منهای زمان تامین و روزهای اطمینان.
`order_by`	«آخرین مهلت سفارش»	آخرین روز ثبت سفارش خرید.
`stock`	«کل موجودی»	اجزای موجودی (جدول بعد).
`periods`	—	`lead_time_days`، `cover_days` و `safety_days` همین کالا.
`excluded`	—	کالا از برنامه‌ریزی خرید کنار گذاشته شده است.
`draft_quantity`	«در سفارش خرید»	تعداد همین کالا در سفارش‌های خرید پیش‌نویس.
`unit_cost`، `line_cost`	«هزینه‌ی خرید»	قیمت خرید هر واحد و `quantity × unit_cost`، به ریال.
`variants`	—	سهم هر تنوع: `daily_sales`، `pack_size`، `excluded`، `confidence` و `quantity`.
`estimated`	—	همیشه `true`؛ همه‌ی اعداد برآوردی‌اند.

اجزای موجودی (`stock`)

فیلد	برچسب در پنل	معنی
`seller_available`	«باقی‌مانده در انبار فروشنده»	همان عدد صفحه‌ی موجودی.
`owed`	—	واحدهایی که تقسیم موجودی از روی تنوع‌ها برداشته و هنوز برنگردانده است؛ در انبار شما هستند.
`warehouse_available`	«باقی‌مانده در انبار دیجی‌کالا»	انبار دیجی‌کالا منهای رزرو.
`consignment_in_transit`	«در محموله‌ی انبارش»	فقط برای نمایش؛ داخل `seller_available` است.
`open_purchase_orders`	«در سفارش خرید»	سفارش‌داده و هنوز نرسیده.
`on_hand`، `total`	«کل موجودی»	طبق فرمول بالا.

🚦 وضعیت‌های پیشنهاد

`status`	برچسب در پنل	معنی	`quantity`
`out_of_stock`	«ناموجود»	موجودی تمام شده است.	مثبت
`order_now`	«همین حالا سفارش دهید»	مهلت سفارش امروز است یا گذشته است.	مثبت
`order_soon`	«به‌زودی سفارش دهید»	مهلت سفارش تا ۷ روز دیگر است.	مثبت
`healthy`	«سالم»	موجودی کافی است.	صفر
`overstock`	«مازاد»	موجودی بیش از دو برابر روزهای پوشش است.	صفر
`no_data`	«داده‌ی ناکافی»	سابقه‌ی فروش برای برآورد کافی نیست.	صفر
`excluded`	«خارج از برنامه‌ریزی»	کالا کنار گذاشته شده است.	صفر

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

🧾 سفارش خرید

وضعیت‌ها و چرخه

`status`	برچسب در پنل	معنی	بعدی
`draft`	«پیش‌نویس»	ساخته شده و هنوز نزد تامین‌کننده ثبت نشده است.	`sent` یا `cancelled`
`sent`	«سفارش داده شده»	نزد تامین‌کننده ثبت شده است؛ واحدهای آن «در راه» حساب می‌شوند.	`partial`، `received` یا `cancelled`
`partial`	«دریافت ناقص»	بخشی از کالا رسیده است.	`received`
`received`	«دریافت کامل»	همه‌ی اقلام رسیده یا سفارش با `close: true` بسته شده است.	—
`cancelled`	«لغوشده»	لغو شده است.	—

پیش‌نویس: POST /v1/purchase-orders با اقلام از group_key پیشنهادها.
ویرایش: تامین‌کننده، یادداشت و تاریخ رسیدن تا وقتی سفارش باز است؛ اقلام فقط در پیش‌نویس.
ثبت نزد تامین‌کننده: POST .../send؛ از این لحظه واحدهای باقی‌مانده در open_purchase_orders پیشنهادها می‌آیند.
دریافت: هر تحویل با POST .../receipts؛ سفارش partial و در پایان received می‌شود.
لغو: فقط پیش‌نویس، یا سفارش ثبت‌شده‌ای که هنوز چیزی از آن نرسیده است.

فیلد allowed_actions در هر سفارش می‌گوید کدام کار همین حالا مجاز است (edit_lines، edit_header، send، receive، cancel)؛ پیش از نمایش دکمه‌ها آن را بخوانید.

فیلدهای سفارش (`PurchaseOrder`)

فیلد	برچسب در پنل	معنی
`id`	—	شناسه‌ی سفارش در API.
`number`	«شماره»	شماره‌ی نمایشی سفارش در پنل.
`status`	«وضعیت»	جدول بالا.
`supplier_name`	«تامین‌کننده»	نام تامین‌کننده.
`note`	—	یادداشت.
`expected_at`	«پیش‌بینی رسیدن»	تاریخ پیش‌بینی رسیدن.
`sent_at`، `closed_at`، `cancelled_at`	—	زمان ثبت نزد تامین‌کننده، بسته شدن و لغو.
`late`	—	باز است، تاریخ رسیدن گذشته و همه‌ی اقلام نرسیده است.
`days_to_expected`	—	روزهای مانده تا رسیدن؛ منفی یعنی دیرکرد.
`lines`	«اقلام»	اقلام سفارش (جدول بعد).
`totals`	«جمع تعداد»، «مبلغ»	جمع اقلام، تعداد سفارشی، دریافتی و باقی‌مانده، و مبلغ کل و دریافتی به ریال؛ `missing_cost` تعداد اقلام بدون قیمت.
`accuracy`	«دقت دریافت»	تعداد اقلام دریافت‌شده برابر، کمتر یا بیشتر از سفارش.
`fx_totals`	—	جمع ارزی؛ فقط برای پنل‌های دارای ماژول «قیمت ارزی».

فیلدهای قلم (`PurchaseOrderLine`)

فیلد	برچسب در پنل	معنی
`id`	—	شناسه‌ی قلم؛ برای ویرایش و دریافت.
`group_key`، `supplier_code`، `variant_id`	«کالا»	کالای فیزیکی و تنوع نماینده.
`ordered_qty`	«تعداد سفارش»	تعداد سفارشی.
`received_qty`	«دریافتی»	جمع دریافت‌ها.
`remaining`	«باقی‌مانده»	سفارشی منهای دریافتی.
`difference`	«اختلاف با سفارش»	دریافتی منهای سفارشی؛ منفی کسری و مثبت اضافه.
`unit_cost`	«قیمت واحد»	ریال.
`line_cost`، `received_cost`	«مبلغ»	مبلغ سفارشی و دریافتی، ریال.
`fx_currency`، `fx_amount`، `fx_rate`	—	قیمت ارزی و نرخ ریالی در لحظه‌ی ثبت.
`last_received_at`	—	زمان آخرین دریافت.

🔢 تازگی

پیشنهاد خرید: از همان داده‌ای ساخته می‌شود که صفحه‌ی «پیشنهاد خرید» پنل نشان می‌دهد؛ موجودی آن با پایش موجودی دیجی‌کالا و فروش آن با همگام‌سازی سفارش‌ها به‌روز می‌شود.
سفارش خرید: هر تغییر فوری است و در همان پاسخ دیده می‌شود؛ ثبت سفارش و دریافت کالا بلافاصله در پیشنهادها اثر می‌کند.

⚠️ هشدارها

📡 مسیرها

`GET /v1/purchase-suggestions` — پیشنهاد خرید فعال

GET /v1/purchase-suggestions?actionable=1 HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...

پارامتر	نوع	اجباری	توضیح
`page`، `size`	عدد	خیر	صفحه‌بندی؛ پیش‌فرض ۵۰، بیشینه ۵۰۰.
`status`	یکی از وضعیت‌ها	خیر	فقط این وضعیت.
`actionable`	`0` یا `1`	خیر	`1`: فقط `out_of_stock`، `order_now` و `order_soon`.
`group_key`	متن	خیر	فقط این کالای فیزیکی.

{
  "status": "ok",
  "data": [
    {
      "group_key": "5144",
      "supplier_code": "5144",
      "variant_id": 84780448,
      "product_id": 22961150,
      "title": "محافظ ولتاژ پارت الکتریک مدل PE5144",
      "status": "order_soon",
      "quantity": 81,
      "daily_sales": 3.2,
      "days_left": 11.3,
      "stockout_on": "2026-11-24",
      "cover_days_total": 18.8,
      "days_to_order": 4.8,
      "order_by": "2026-11-17",
      "confidence": "high",
      "low_confidence": false,
      "stock": {
        "seller_available": 30,
        "owed": 0,
        "warehouse_available": 6,
        "consignment_in_transit": 12,
        "open_purchase_orders": 24,
        "on_hand": 36,
        "total": 60
      },
      "periods": { "lead_time_days": 7, "cover_days": 30, "safety_days": 7 },
      "excluded": false,
      "draft_quantity": 0,
      "unit_cost": 18500000,
      "line_cost": 1498500000,
      "variants": [
        { "variant_id": 84780448, "title": "سفید", "daily_sales": 2.1, "excluded": false, "pack_size": 1, "confidence": "high", "quantity": 53 },
        { "variant_id": 84780452, "title": "مشکی", "daily_sales": 1.1, "excluded": false, "pack_size": 1, "confidence": "medium", "quantity": 28 }
      ],
      "estimated": true
    }
  ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 1, "total_rows": 9 }
}

`GET /v1/purchase-orders` — سفارش‌های خرید فعال

بزرگ‌ترین شماره اول، با اقلام.

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

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

POST /v1/purchase-orders HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: po-1405-08-23-noor
Content-Type: application/json

{
  "supplier_name": "بازرگانی نور",
  "expected_at": "2026-11-25",
  "lines": [
    { "group_key": "5144", "quantity": 120, "unit_cost": 18500000 },
    { "group_key": "6100", "quantity": 30 }
  ]
}

فیلد بدنه	نوع	اجباری	توضیح
`supplier_name`	متن	خیر	تا ۲۰۰ نویسه.
`note`	متن	خیر	تا ۲۰۰۰ نویسه.
`expected_at`	تاریخ یا `null`	خیر	تاریخ پیش‌بینی رسیدن.
`lines[].group_key`	متن	بله	کالای فیزیکی؛ کلید تکراری جمع می‌شود.
`lines[].quantity`	عدد	بله	۱ تا ۱٬۰۰۰٬۰۰۰.
`lines[].unit_cost`	عدد یا `null`	خیر	ریال؛ خالی یعنی پر شدن خودکار (هشدار ۶).
`lines[].fx_currency`، `fx_amount`، `fx_rate`	—	خیر	فقط با ماژول «قیمت ارزی»؛ `fx_rate` خالی یعنی نرخ امروز.

پاسخ موفق: کد 201 با سفارش در وضعیت draft.

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

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

`GET /v1/purchase-orders/{purchase_order_id}` — یک سفارش فعال

{
  "status": "ok",
  "data": {
    "id": 204,
    "number": 37,
    "status": "partial",
    "supplier_name": "بازرگانی نور",
    "note": null,
    "expected_at": "2026-11-25",
    "sent_at": "2026-11-13T12:05:00+03:30",
    "closed_at": null,
    "cancelled_at": null,
    "created_at": "2026-11-13T11:48:20+03:30",
    "updated_at": "2026-11-20T16:22:05+03:30",
    "late": false,
    "days_to_expected": 5,
    "lines": [
      {
        "id": 3121,
        "group_key": "5144",
        "supplier_code": "5144",
        "variant_id": 84780448,
        "product_id": 22961150,
        "title": "محافظ ولتاژ پارت الکتریک مدل PE5144",
        "image_url": "https://dkstatic.digikala.com/digikala-products/a1b2c3.jpg",
        "ordered_qty": 120,
        "received_qty": 40,
        "remaining": 80,
        "difference": -80,
        "unit_cost": 18500000,
        "line_cost": 2220000000,
        "received_cost": 740000000,
        "fx_currency": null,
        "fx_amount": null,
        "fx_rate": null,
        "last_received_at": "2026-11-20T16:22:05+03:30"
      }
    ],
    "totals": { "lines": 1, "ordered": 120, "received": 40, "remaining": 80, "cost": 2220000000, "missing_cost": 0, "received_cost": 740000000 },
    "accuracy": { "ordered": 1, "matched": 0, "under": 1, "over": 0 },
    "allowed_actions": { "edit_lines": false, "edit_header": true, "send": false, "receive": true, "cancel": false }
  }
}

`PATCH /v1/purchase-orders/{purchase_order_id}` — ویرایش فعال

فیلدی که فرستاده نشود تغییر نمی‌کند.

فیلد بدنه	نوع	توضیح
`supplier_name`، `note`، `expected_at`	—	تا وقتی سفارش باز است.
`lines[].id`	عدد	قلم موجود؛ فقط در پیش‌نویس.
`lines[].quantity`	عدد	صفر قلم را حذف می‌کند.
`lines[].unit_cost`	عدد یا `null`	ریال؛ قیمت ارزی قلم را پاک می‌کند.
`lines[].fx_currency`، `fx_amount`، `fx_rate`	—	فقط با ماژول «قیمت ارزی».

`POST /v1/purchase-orders/{purchase_order_id}/send` — ثبت نزد تامین‌کننده فعال

بدنه ندارد. سفارش پیش‌نویس را sent می‌کند. برای سفارش غیر پیش‌نویس، کد 409 و خطای purchase_order_status_invalid برمی‌گردد.

`POST /v1/purchase-orders/{purchase_order_id}/receipts` — ثبت دریافت کالا فعال

تعداد رسیده‌ی هر قلم در همین تحویل.

POST /v1/purchase-orders/204/receipts HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: po-204-receipt-1405-08-29
Content-Type: application/json

{
  "lines": [ { "line_id": 3121, "quantity": 40, "received_before": 0 } ],
  "received_on": "2026-11-20"
}

فیلد بدنه	نوع	اجباری	توضیح
`lines[].line_id`	عدد	بله	شناسه‌ی قلم.
`lines[].quantity`	عدد	بله	تعداد رسیده در همین تحویل؛ ۰ تا ۱٬۰۰۰٬۰۰۰.
`lines[].received_before`	عدد	خیر	تعداد دریافت‌شده‌ی قبلی این قلم که شما دیده‌اید (هشدار ۱).
`close`	`true` یا `false`	خیر	سفارش با همین دریافت بسته شود، حتی اگر کامل نرسیده باشد؛ پیش‌فرض `false`.
`received_on`	تاریخ	خیر	روز دریافت؛ پیش‌فرض امروز.

پاسخ نمونه (کد 201)

{
  "status": "ok",
  "data": {
    "purchase_order": { "id": 204, "number": 37, "status": "partial", "totals": { "ordered": 120, "received": 40, "remaining": 80 } },
    "receipt": { "units": 40, "lines": 1, "kardex_on": true, "kardex_movements": 1, "kardex_skipped": 0 }
  }
}

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

کد HTTP	خطا	معنی	تکرار بی‌خطر است؟
`400`	`invalid_parameter`	فیلدی نادرست است یا جا افتاده است.	خیر؛ بدنه را اصلاح کنید.
`404`	`not_found`	این سفارش در این پنل نیست.	خیر.
`409`	`version_conflict`	`received_before` با دریافت ثبت‌شده برابر نیست؛ هیچ چیزی ثبت نشد.	خیر؛ سفارش را بخوانید و تصمیم بگیرید.
`409`	`purchase_order_status_invalid`	سفارش در وضعیتی نیست که دریافت بپذیرد.	خیر.
`409`	`idempotency_mismatch`	این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است.	خیر؛ کلید تازه بسازید.
`409`	`idempotency_in_progress`	درخواستی با همین کلید در حال انجام است.	بله، چند ثانیه بعد.

`POST /v1/purchase-orders/{purchase_order_id}/cancel` — لغو فعال

بدنه ندارد. فقط سفارش پیش‌نویس یا ثبت‌شده‌ای که هنوز چیزی از آن نرسیده است لغو می‌شود؛ در غیر این صورت کد 409 و خطای purchase_order_status_invalid برمی‌گردد.

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

رویداد	چه وقت
`purchase.needed`	پیشنهاد یک کالای فیزیکی وارد وضعیت `out_of_stock`، `order_now` یا `order_soon` شد و سفارش خرید بازی آن را پوشش نمی‌دهد. کالاهای با سابقه‌ی فروش کم فقط وقتی ناموجودند اعلام می‌شوند.
`purchase_order.late`	تاریخ پیش‌بینی رسیدن سفارش ثبت‌شده گذشته است و همه‌ی اقلام نرسیده است؛ یک بار برای هر سفارش در هر روز.

رویداد stock.stockout_soon در صفحه‌ی موجودی از دید فروش همین هشدار را می‌دهد.

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

{
  "id": "evt_01J0C9RT",
  "type": "purchase_order.late",
  "created_at": "2026-11-28T09:00:12+03:30",
  "panel_id": 1,
  "livemode": true,
  "data": {
    "purchase_order": {
      "id": 204,
      "number": 37,
      "status": "partial",
      "supplier_name": "بازرگانی نور",
      "expected_at": "2026-11-25",
      "late": true,
      "days_to_expected": -3,
      "totals": { "lines": 1, "ordered": 120, "received": 40, "remaining": 80 }
    },
    "days_late": 3
  }
}

پیام purchase.needed در data.suggestion همان ساختار پیشنهاد خرید را دارد. پیش از استفاده از هر پیام، امضای آن را بررسی کنید.

💻 نمونه‌کد: ثبت دریافت کالا

curl -X POST https://api.seller360.ir/v1/purchase-orders/204/receipts \
  -H "Authorization: Bearer $S360_API_KEY" \
  -H "Idempotency-Key: po-204-receipt-1405-08-29" \
  -H "Content-Type: application/json" \
  -d '{"lines": [{"line_id": 3121, "quantity": 40, "received_before": 0}]}'

$ch = curl_init("https://api.seller360.ir/v1/purchase-orders/204/receipts");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("S360_API_KEY"),
        "Idempotency-Key: po-204-receipt-1405-08-29",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "lines" => [["line_id" => 3121, "quantity" => 40, "received_before" => 0]],
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
]);
$res = json_decode(curl_exec($ch), true);
if (($res["error"]["code"] ?? null) === "version_conflict") {
    // این تحویل پیش‌تر ثبت شده است؛ سفارش را دوباره بخوانید
}

import os, requests

res = requests.post(
    "https://api.seller360.ir/v1/purchase-orders/204/receipts",
    headers={
        "Authorization": f"Bearer {os.environ['S360_API_KEY']}",
        "Idempotency-Key": "po-204-receipt-1405-08-29",
    },
    json={"lines": [{"line_id": 3121, "quantity": 40, "received_before": 0}]},
    timeout=20,
).json()
if res["status"] == "error" and res["error"]["code"] == "version_conflict":
    ...  # این تحویل پیش‌تر ثبت شده است؛ سفارش را دوباره بخوانید

const res = await fetch('https://api.seller360.ir/v1/purchase-orders/204/receipts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.S360_API_KEY}`,
    'Idempotency-Key': 'po-204-receipt-1405-08-29',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ lines: [{ line_id: 3121, quantity: 40, received_before: 0 }] }),
})
const body = await res.json()
if (body.error?.code === 'version_conflict') {
  // این تحویل پیش‌تر ثبت شده است؛ سفارش را دوباره بخوانید
}

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post,
    "https://api.seller360.ir/v1/purchase-orders/204/receipts");
req.Headers.Add("Authorization", $"Bearer {Environment.GetEnvironmentVariable("S360_API_KEY")}");
req.Headers.Add("Idempotency-Key", "po-204-receipt-1405-08-29");
req.Content = JsonContent.Create(new {
    lines = new[] { new { line_id = 3121, quantity = 40, received_before = 0 } },
});
var res = await http.SendAsync(req);
var body = await res.Content.ReadFromJsonAsync<JsonElement>();

پیشنهاد خرید و سفارش خرید

📖 مقدمه

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

دسترسی (Scope)

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

آدرس پایه

🧮 پیشنهاد خرید

کالای فیزیکی (group_key)

فرمول

یک مثال

فیلدهای پیشنهاد (PurchaseSuggestion)

اجزای موجودی (stock)

🚦 وضعیت‌های پیشنهاد

🧾 سفارش خرید

وضعیت‌ها و چرخه

فیلدهای سفارش (PurchaseOrder)

فیلدهای قلم (PurchaseOrderLine)

🔢 تازگی

⚠️ هشدارها

📡 مسیرها

GET /v1/purchase-suggestions — پیشنهاد خرید فعال

GET /v1/purchase-orders — سفارش‌های خرید فعال

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

GET /v1/purchase-orders/{purchase_order_id} — یک سفارش فعال

PATCH /v1/purchase-orders/{purchase_order_id} — ویرایش فعال

POST /v1/purchase-orders/{purchase_order_id}/send — ثبت نزد تامین‌کننده فعال

POST /v1/purchase-orders/{purchase_order_id}/receipts — ثبت دریافت کالا فعال

POST /v1/purchase-orders/{purchase_order_id}/cancel — لغو فعال