ثبت دریافت کالا

POST

/v1/purchase-orders/{purchase_order_id}/receipts

curl --request POST \
  --url https://api.seller360.ir/v1/purchase-orders/204/receipts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "lines": [ { "line_id": 3121, "quantity": 40, "received_before": 0 } ], "close": false, "received_on": "2026-04-15" }'

• سرور اصلی (کلید `s360_live_…`، و کلید `s360_test_…` روی پنل نمایشی)

تعداد رسیده‌ی هر قلم در همین تحویل (به دریافت‌های قبلی اضافه می‌شود و می‌تواند از سفارش بیشتر باشد). اگر received_before با دریافت ثبت‌شده‌ی قلم برابر نباشد، هیچ چیزی ثبت نمی‌شود (version_conflict)، تا یک تحویل دو بار ثبت نشود. با دریافت کامل همه‌ی اقلام یا close: true سفارش received می‌شود و در غیر این صورت partial. اگر کاردکس روشن باشد، هر واحد دریافتی یک حرکت purchase با قیمت واحد همان قلم ثبت می‌کند.

Authorizations

• apiKey

Parameters

Path Parameters

purchase_order_id

required

integer

Example

204

شناسه‌ی سفارش (نه شماره‌ی نمایشی number).

Header Parameters

Idempotency-Key

required

string

>= 8 characters <= 255 characters

یک شناسه‌ی یکتا برای هر تغییر (مثلا UUID). اگر پاسخ را دریافت نکردید، همان درخواست را با همان کلید تکرار کنید؛ تغییر دو بار انجام نمی‌شود. پاسخ اول تا ۲۴ ساعت نگه داشته می‌شود.

Request Body^required

Media typeapplication/json

object

lines

required

Array<object>

>= 1 items

object

line_id

required

integer

Example

3121

quantity

required

integer

<= 1000000

Example

40

received_before

تعداد دریافت‌شده‌ی قبلی این قلم که شما دیده‌اید.

integer

Example

0

close

سفارش با همین دریافت بسته شود، حتی اگر کامل نرسیده باشد.

boolean

received_on

روز دریافت؛ پیش‌فرض امروز.

string format: date

Responses

201

دریافت ثبت شد.

Media typeapplication/json

object

status

required

Allowed value: ok

data

required

data

required

object

purchase_order

required

object

id

required

integer

number

required

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

integer

status

required

«پیش‌نویس»، «سفارش داده شده»، «دریافت ناقص»، «دریافت کامل» یا «لغوشده».

string

Allowed values: draft sent partial received cancelled

supplier_name

string | null

note

string | null

expected_at

تاریخ پیش‌بینی رسیدن.

string | null format: date

sent_at

string | null format: date-time

closed_at

string | null format: date-time

cancelled_at

string | null format: date-time

created_at

required

string format: date-time

updated_at

string format: date-time

late

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

boolean

days_to_expected

integer | null

lines

required

Array<object>

object

id

required

integer

group_key

required

string

supplier_code

string | null

variant_id

integer | null

product_id

integer | null

title

string

image_url

string | null format: uri

ordered_qty

required

integer

received_qty

required

integer

remaining

required

integer

difference

دریافتی − سفارشی؛ منفی کسری و مثبت اضافه.

integer

unit_cost

ریال.

integer | null

line_cost

ریال.

integer | null

received_cost

ریال.

integer | null

fx_currency

string | null

fx_amount

number | null

fx_rate

ریال به ازای هر واحد ارز در لحظه‌ی ثبت.

number | null

last_received_at

string | null format: date-time

totals

required

object

lines

integer

ordered

integer

received

integer

remaining

integer

cost

جمع اقلام دارای قیمت، ریال.

integer

missing_cost

تعداد اقلام بدون قیمت.

integer

received_cost

ریال.

integer

accuracy

تطابق دریافت با سفارش (برای سفارش کامل‌شده معنادار است).

object

ordered

integer

matched

integer

under

integer

over

integer

fx_totals

فقط برای پنل‌های دارای ماژول «قیمت ارزی».

Array<object>

object

currency

string

amount

number

allowed_actions

object

edit_lines

boolean

edit_header

boolean

send

boolean

receive

boolean

cancel

boolean

receipt

required

object

units

required

واحدهای ثبت‌شده در این دریافت.

integer

lines

required

integer

kardex_on

required

boolean

kardex_movements

integer

kardex_skipped

اقلام بدون کد فروشنده که در کاردکس ثبت نشدند.

integer

Example

{
  "status": "ok",
  "data": {
    "purchase_order": {
      "id": 204,
      "number": 37,
      "status": "draft",
      "supplier_name": "بازرگانی نور",
      "days_to_expected": -3,
      "lines": [
        {
          "id": 3121,
          "group_key": "5144",
          "supplier_code": "5144",
          "variant_id": 84780448,
          "product_id": 22961150,
          "ordered_qty": 120,
          "received_qty": 40,
          "remaining": 80,
          "difference": -80,
          "unit_cost": 185000000,
          "line_cost": 22200000000,
          "received_cost": 7400000000,
          "fx_currency": "USD",
          "fx_amount": 28.5,
          "fx_rate": 6491228
        }
      ],
      "totals": {
        "lines": 3,
        "ordered": 150,
        "received": 40,
        "remaining": 110,
        "cost": 27750000000,
        "missing_cost": 0,
        "received_cost": 7400000000
      },
      "fx_totals": [
        {
          "currency": "USD",
          "amount": 4200
        }
      ]
    },
    "receipt": {
      "units": 40,
      "lines": 1,
      "kardex_movements": 1,
      "kardex_skipped": 0
    }
  }
}

Headers

X-Request-Id

string

کد پیگیری این درخواست.

X-RateLimit-Limit

integer

سقف درخواست این نوع (خواندن یا نوشتن) در هر دقیقه برای این کلید.

X-RateLimit-Remaining

integer

درخواست‌های باقی‌مانده تا پایان دقیقه‌ی جاری.

X-RateLimit-Reset

integer

زمان شروع دقیقه‌ی بعد، به ثانیه از ۱۹۷۰ (Unix).

400

پارامتر یا بدنه‌ی نامعتبر.

Media typeapplication/json

object

status

required

Allowed value: error

error

required

object

code

required

string

Allowed values: missing_api_key invalid_api_key https_required scope_missing module_inactive panel_unavailable subscription_inactive not_found variant_not_found method_not_allowed invalid_parameter idempotency_key_required idempotency_mismatch idempotency_in_progress insufficient_stock version_conflict stock_write_locked sku_taken price_out_of_band price_managed_by_bot webhook_url_invalid webhook_limit_reached rate_limited digikala_rate_limited digikala_refused module_required digikala_outcome_unknown digikala_unavailable internal_error stock_split_in_progress kardex_disabled movement_type_not_allowed stock_count_finalized purchase_order_status_invalid product_key_unknown purchase_price_range_invalid product_locked_for_moderation catalog_row_invalid demo_panel_unsupported build_in_progress package_not_built_here shipping_write_unavailable pickup_unavailable feature_unavailable commitment_exceeded warehouse_not_listed slot_watch_exists draft_limit_reached draft_not_buildable draft_overdue draft_not_waiting consignment_not_allowed slot_unavailable no_open_slot replenish_rule_limit replenish_inactive price_managed_by_fx bot_strategy_required bot_quota_full strategy_not_found strategy_locked strategy_hidden strategy_title_reserved competitor_not_found change_not_undoable undo_window_expired already_undone undo_in_progress promotion_not_eligible promotion_managed_by_bot promotion_no_floor promotion_below_floor promotion_invalid promotion_not_active campaign_not_found campaign_closed fx_strategy_not_found fx_no_pending_price

message

required

پیام فارسی برای برنامه‌نویس.

string

detail

آنچه دقیقا نادرست بود، مثلا نام پارامتر.

string

doc_url

required

string format: uri

request_id

required

string

Example

{
  "status": "error",
  "error": {
    "code": "missing_api_key"
  }
}

Headers

X-Request-Id

string

کد پیگیری این درخواست.

X-RateLimit-Limit

integer

سقف درخواست این نوع (خواندن یا نوشتن) در هر دقیقه برای این کلید.

X-RateLimit-Remaining

integer

درخواست‌های باقی‌مانده تا پایان دقیقه‌ی جاری.

X-RateLimit-Reset

integer

زمان شروع دقیقه‌ی بعد، به ثانیه از ۱۹۷۰ (Unix).

401

کلید ارسال نشده یا نامعتبر است.

Media typeapplication/json

object

status

required

Allowed value: error

error

required

object

code

required

string

Allowed values: missing_api_key invalid_api_key https_required scope_missing module_inactive panel_unavailable subscription_inactive not_found variant_not_found method_not_allowed invalid_parameter idempotency_key_required idempotency_mismatch idempotency_in_progress insufficient_stock version_conflict stock_write_locked sku_taken price_out_of_band price_managed_by_bot webhook_url_invalid webhook_limit_reached rate_limited digikala_rate_limited digikala_refused module_required digikala_outcome_unknown digikala_unavailable internal_error stock_split_in_progress kardex_disabled movement_type_not_allowed stock_count_finalized purchase_order_status_invalid product_key_unknown purchase_price_range_invalid product_locked_for_moderation catalog_row_invalid demo_panel_unsupported build_in_progress package_not_built_here shipping_write_unavailable pickup_unavailable feature_unavailable commitment_exceeded warehouse_not_listed slot_watch_exists draft_limit_reached draft_not_buildable draft_overdue draft_not_waiting consignment_not_allowed slot_unavailable no_open_slot replenish_rule_limit replenish_inactive price_managed_by_fx bot_strategy_required bot_quota_full strategy_not_found strategy_locked strategy_hidden strategy_title_reserved competitor_not_found change_not_undoable undo_window_expired already_undone undo_in_progress promotion_not_eligible promotion_managed_by_bot promotion_no_floor promotion_below_floor promotion_invalid promotion_not_active campaign_not_found campaign_closed fx_strategy_not_found fx_no_pending_price

message

required

پیام فارسی برای برنامه‌نویس.

string

detail

آنچه دقیقا نادرست بود، مثلا نام پارامتر.

string

doc_url

required

string format: uri

request_id

required

string

Example

{
  "status": "error",
  "error": {
    "code": "missing_api_key"
  }
}

403

کلید دسترسی لازم را ندارد، یا ماژول یا پنل فعال نیست.

Media typeapplication/json

object

status

required

Allowed value: error

error

required

object

code

required

string

Allowed values: missing_api_key invalid_api_key https_required scope_missing module_inactive panel_unavailable subscription_inactive not_found variant_not_found method_not_allowed invalid_parameter idempotency_key_required idempotency_mismatch idempotency_in_progress insufficient_stock version_conflict stock_write_locked sku_taken price_out_of_band price_managed_by_bot webhook_url_invalid webhook_limit_reached rate_limited digikala_rate_limited digikala_refused module_required digikala_outcome_unknown digikala_unavailable internal_error stock_split_in_progress kardex_disabled movement_type_not_allowed stock_count_finalized purchase_order_status_invalid product_key_unknown purchase_price_range_invalid product_locked_for_moderation catalog_row_invalid demo_panel_unsupported build_in_progress package_not_built_here shipping_write_unavailable pickup_unavailable feature_unavailable commitment_exceeded warehouse_not_listed slot_watch_exists draft_limit_reached draft_not_buildable draft_overdue draft_not_waiting consignment_not_allowed slot_unavailable no_open_slot replenish_rule_limit replenish_inactive price_managed_by_fx bot_strategy_required bot_quota_full strategy_not_found strategy_locked strategy_hidden strategy_title_reserved competitor_not_found change_not_undoable undo_window_expired already_undone undo_in_progress promotion_not_eligible promotion_managed_by_bot promotion_no_floor promotion_below_floor promotion_invalid promotion_not_active campaign_not_found campaign_closed fx_strategy_not_found fx_no_pending_price

message

required

پیام فارسی برای برنامه‌نویس.

string

detail

آنچه دقیقا نادرست بود، مثلا نام پارامتر.

string

doc_url

required

string format: uri

request_id

required

string

Example

{
  "status": "error",
  "error": {
    "code": "missing_api_key"
  }
}

404

مورد درخواست‌شده در این پنل وجود ندارد.

Media typeapplication/json

object

status

required

Allowed value: error

error

required

object

code

required

string

Allowed values: missing_api_key invalid_api_key https_required scope_missing module_inactive panel_unavailable subscription_inactive not_found variant_not_found method_not_allowed invalid_parameter idempotency_key_required idempotency_mismatch idempotency_in_progress insufficient_stock version_conflict stock_write_locked sku_taken price_out_of_band price_managed_by_bot webhook_url_invalid webhook_limit_reached rate_limited digikala_rate_limited digikala_refused module_required digikala_outcome_unknown digikala_unavailable internal_error stock_split_in_progress kardex_disabled movement_type_not_allowed stock_count_finalized purchase_order_status_invalid product_key_unknown purchase_price_range_invalid product_locked_for_moderation catalog_row_invalid demo_panel_unsupported build_in_progress package_not_built_here shipping_write_unavailable pickup_unavailable feature_unavailable commitment_exceeded warehouse_not_listed slot_watch_exists draft_limit_reached draft_not_buildable draft_overdue draft_not_waiting consignment_not_allowed slot_unavailable no_open_slot replenish_rule_limit replenish_inactive price_managed_by_fx bot_strategy_required bot_quota_full strategy_not_found strategy_locked strategy_hidden strategy_title_reserved competitor_not_found change_not_undoable undo_window_expired already_undone undo_in_progress promotion_not_eligible promotion_managed_by_bot promotion_no_floor promotion_below_floor promotion_invalid promotion_not_active campaign_not_found campaign_closed fx_strategy_not_found fx_no_pending_price

message

required

پیام فارسی برای برنامه‌نویس.

string

detail

آنچه دقیقا نادرست بود، مثلا نام پارامتر.

string

doc_url

required

string format: uri

request_id

required

string

Example

{
  "status": "error",
  "error": {
    "code": "missing_api_key"
  }
}

Headers

X-Request-Id

string

کد پیگیری این درخواست.

X-RateLimit-Limit

integer

سقف درخواست این نوع (خواندن یا نوشتن) در هر دقیقه برای این کلید.

X-RateLimit-Remaining

integer

درخواست‌های باقی‌مانده تا پایان دقیقه‌ی جاری.

X-RateLimit-Reset

integer

زمان شروع دقیقه‌ی بعد، به ثانیه از ۱۹۷۰ (Unix).

409

تغییر با وضعیت فعلی سازگار نیست (موجودی ناکافی، نسخه‌ی تغییرکرده، قفل یا کلید یکتای تکراری).

Media typeapplication/json

object

status

required

Allowed value: error

error

required

object

code

required

string

Allowed values: missing_api_key invalid_api_key https_required scope_missing module_inactive panel_unavailable subscription_inactive not_found variant_not_found method_not_allowed invalid_parameter idempotency_key_required idempotency_mismatch idempotency_in_progress insufficient_stock version_conflict stock_write_locked sku_taken price_out_of_band price_managed_by_bot webhook_url_invalid webhook_limit_reached rate_limited digikala_rate_limited digikala_refused module_required digikala_outcome_unknown digikala_unavailable internal_error stock_split_in_progress kardex_disabled movement_type_not_allowed stock_count_finalized purchase_order_status_invalid product_key_unknown purchase_price_range_invalid product_locked_for_moderation catalog_row_invalid demo_panel_unsupported build_in_progress package_not_built_here shipping_write_unavailable pickup_unavailable feature_unavailable commitment_exceeded warehouse_not_listed slot_watch_exists draft_limit_reached draft_not_buildable draft_overdue draft_not_waiting consignment_not_allowed slot_unavailable no_open_slot replenish_rule_limit replenish_inactive price_managed_by_fx bot_strategy_required bot_quota_full strategy_not_found strategy_locked strategy_hidden strategy_title_reserved competitor_not_found change_not_undoable undo_window_expired already_undone undo_in_progress promotion_not_eligible promotion_managed_by_bot promotion_no_floor promotion_below_floor promotion_invalid promotion_not_active campaign_not_found campaign_closed fx_strategy_not_found fx_no_pending_price

message

required

پیام فارسی برای برنامه‌نویس.

string

detail

آنچه دقیقا نادرست بود، مثلا نام پارامتر.

string

doc_url

required

string format: uri

request_id

required

string

Example

{
  "status": "error",
  "error": {
    "code": "missing_api_key"
  }
}

Headers

X-Request-Id

string

کد پیگیری این درخواست.

X-RateLimit-Limit

integer

سقف درخواست این نوع (خواندن یا نوشتن) در هر دقیقه برای این کلید.

X-RateLimit-Remaining

integer

درخواست‌های باقی‌مانده تا پایان دقیقه‌ی جاری.

X-RateLimit-Reset

integer

زمان شروع دقیقه‌ی بعد، به ثانیه از ۱۹۷۰ (Unix).

422

درخواست درست است اما قاعده‌ی کسب‌وکار اجازه نمی‌دهد (مثلا قیمت بیرون از بازه).

Media typeapplication/json

object

status

required

Allowed value: error

error

required

object

code

required

string

Allowed values: missing_api_key invalid_api_key https_required scope_missing module_inactive panel_unavailable subscription_inactive not_found variant_not_found method_not_allowed invalid_parameter idempotency_key_required idempotency_mismatch idempotency_in_progress insufficient_stock version_conflict stock_write_locked sku_taken price_out_of_band price_managed_by_bot webhook_url_invalid webhook_limit_reached rate_limited digikala_rate_limited digikala_refused module_required digikala_outcome_unknown digikala_unavailable internal_error stock_split_in_progress kardex_disabled movement_type_not_allowed stock_count_finalized purchase_order_status_invalid product_key_unknown purchase_price_range_invalid product_locked_for_moderation catalog_row_invalid demo_panel_unsupported build_in_progress package_not_built_here shipping_write_unavailable pickup_unavailable feature_unavailable commitment_exceeded warehouse_not_listed slot_watch_exists draft_limit_reached draft_not_buildable draft_overdue draft_not_waiting consignment_not_allowed slot_unavailable no_open_slot replenish_rule_limit replenish_inactive price_managed_by_fx bot_strategy_required bot_quota_full strategy_not_found strategy_locked strategy_hidden strategy_title_reserved competitor_not_found change_not_undoable undo_window_expired already_undone undo_in_progress promotion_not_eligible promotion_managed_by_bot promotion_no_floor promotion_below_floor promotion_invalid promotion_not_active campaign_not_found campaign_closed fx_strategy_not_found fx_no_pending_price

message

required

پیام فارسی برای برنامه‌نویس.

string

detail

آنچه دقیقا نادرست بود، مثلا نام پارامتر.

string

doc_url

required

string format: uri

request_id

required

string

Example

{
  "status": "error",
  "error": {
    "code": "missing_api_key"
  }
}

Headers

X-Request-Id

string

کد پیگیری این درخواست.

X-RateLimit-Limit

integer

سقف درخواست این نوع (خواندن یا نوشتن) در هر دقیقه برای این کلید.

X-RateLimit-Remaining

integer

درخواست‌های باقی‌مانده تا پایان دقیقه‌ی جاری.

X-RateLimit-Reset

integer

زمان شروع دقیقه‌ی بعد، به ثانیه از ۱۹۷۰ (Unix).

429

سقف درخواست گذشته است.

Media typeapplication/json

object

status

required

Allowed value: error

error

required

object

code

required

string

Allowed values: missing_api_key invalid_api_key https_required scope_missing module_inactive panel_unavailable subscription_inactive not_found variant_not_found method_not_allowed invalid_parameter idempotency_key_required idempotency_mismatch idempotency_in_progress insufficient_stock version_conflict stock_write_locked sku_taken price_out_of_band price_managed_by_bot webhook_url_invalid webhook_limit_reached rate_limited digikala_rate_limited digikala_refused module_required digikala_outcome_unknown digikala_unavailable internal_error stock_split_in_progress kardex_disabled movement_type_not_allowed stock_count_finalized purchase_order_status_invalid product_key_unknown purchase_price_range_invalid product_locked_for_moderation catalog_row_invalid demo_panel_unsupported build_in_progress package_not_built_here shipping_write_unavailable pickup_unavailable feature_unavailable commitment_exceeded warehouse_not_listed slot_watch_exists draft_limit_reached draft_not_buildable draft_overdue draft_not_waiting consignment_not_allowed slot_unavailable no_open_slot replenish_rule_limit replenish_inactive price_managed_by_fx bot_strategy_required bot_quota_full strategy_not_found strategy_locked strategy_hidden strategy_title_reserved competitor_not_found change_not_undoable undo_window_expired already_undone undo_in_progress promotion_not_eligible promotion_managed_by_bot promotion_no_floor promotion_below_floor promotion_invalid promotion_not_active campaign_not_found campaign_closed fx_strategy_not_found fx_no_pending_price

message

required

پیام فارسی برای برنامه‌نویس.

string

detail

آنچه دقیقا نادرست بود، مثلا نام پارامتر.

string

doc_url

required

string format: uri

request_id

required

string

Example

{
  "status": "error",
  "error": {
    "code": "missing_api_key"
  }
}

Headers

Retry-After

integer

چند ثانیه صبر کنید و دوباره تلاش کنید.

X-RateLimit-Limit

integer

سقف درخواست این نوع (خواندن یا نوشتن) در هر دقیقه برای این کلید.

X-RateLimit-Remaining

integer

درخواست‌های باقی‌مانده تا پایان دقیقه‌ی جاری.

X-RateLimit-Reset

integer

زمان شروع دقیقه‌ی بعد، به ثانیه از ۱۹۷۰ (Unix).