ثبت سفارش (Register Shipment)

پیش‌نیاز: داشتن access_token | خروجی: دریافت shipment_id و shipment_code

دو روش برای ثبت ارسال وجود دارد که نمی‌توان هر دو را با هم ترکیب کرد:

روش اول : ثبت با پارسل مشخص (Specified Parcels)

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

• Authorization: <access_token>

ساختار درخواست (Request Body):

{
  "consignor_unique_reference_id": "string",
  "revive_if_already_registered_and_failed": true,
  "cargo_ready_date_time": "string",
  "promise_start_date_time": "string",
  "promise_end_date_time": "string",
  "origin_point_id": "string",
  "origin_address": {
    "city_id": "string",
    "full_address": "string",
    "building_number": "string",
    "unit": "string",
    "postal_code": "string",
    "latitude": "string",
    "longitude": "string",
    "description": "string"
  },
  "cargo_submitter_person": {
    "first_name": "string",
    "last_name": "string",
    "national_code": "string",
    "first_mobile": "string",
    "second_mobile": "string",
    "phone": "string"
  },
  "destination_point_id": "string",
  "destination_address": {
    "city_id": "string",
    "full_address": "string",
    "building_number": "string",
    "unit": "string",
    "postal_code": "string",
    "latitude": "string",
    "longitude": "string",
    "description": "string"
  },
  "recipient_person": {
    "first_name": "string",
    "last_name": "string",
    "national_code": "string",
    "first_mobile": "string",
    "second_mobile": "string",
    "phone": "string"
  },
  "constant_proof_of_delivery_code_for_all_parcels": "string",
  "parcels": [
    {
      "dimensionsInCMs": [
        "string"
      ],
      "content_value_price_rials": "string",
      "description": "string",
      "items_description": "string",
      "weight_grams": "string",
      "consignor_reference_id": "string",
      "payable_price_rials_by_recipient": "string",
      "scannable_codes": [
        "string"
      ],
      "characteristics": [
        "string"
      ],
      "packaging_type": "string"
    }
  ]
}

جدول پارامترهای اصلی

جدول پارامترهای هر آیتم در origin_address - destination_address

جدول پارامترهای هر آیتم در cargo_submitter_person / recipient_person

جدول پارامترهای هر آیتم در parcels

راهنمای جامع قابلیت Revive (احیای سفارش‌های ناموفق)

اگر در جدول پارامترهای اصلی، فیلد revive_if_already_registered_and_failed را برابر با true قرار دهید، قابلیت Revive فعال می‌شود. این ویژگی برای زمانی است که یک سفارش پس از ثبت، به وضعیت نهایی ناموفق (مانند Cancel، Reject یا Pickup Fail) رسیده باشد و شما بخواهید بدون تغییر دادن کد مرجع خود (consignor_unique_reference_id)، سفارش را اصلاح و مجدداً ارسال کنید.

جدول فرآیند و رفتار سیستم در حالت Revive

نکات کلیدی بیزینسی و فنی در احیای سفارش

• ادغام در API اصلی: توجه داشته باشید که Revive یک API جداگانه ندارد؛ این قابلیت در فیلد revive_if_already_registered_and_failed در API ثبت سفارش نسخه دو (Register V2) عمل می‌کند.
• تغییر حتمی بارکد لیبل: حیاتی‌ترین نکته لجستیکی این است که پس از Revive موفق، با اینکه شناسه یکتا (consignor_unique_reference_id) شما ثابت مانده، اما سیستم کد پارسل (parcel_code) جدیدی تولید می‌کند. بنابراین حتماً باید لیبل جدید را مجدداً دریافت و روی بسته بچسبانید؛ رانندگان دیجی‌اکسپرس امکان اسکن بارکد قبلی را ندارند.
• کاربرد اصلی: این فرآیند صرفاً زمانی کاربرد دارد که بسته هنوز به دست مشتری نرسیده و به هر دلیلی در مراحل اولیه (مثل خطا در آدرس یا عدم حضور شما در زمان پیکاپ) لغو یا رد شده است و شما تمایلی به تولید یک Reference ID جدید در سیستم خود ندارید.

پس از ارسال درخواست، در صورتی که مراحل بالا را به درستی انجام داده باشید و سیستم مرسوله را با موفقیت ثبت یا احیا کند، پاسخ (HTTP 200 (OK دریافت خواهید کرد.

در ادامه، نمونه ساختار پاسخ موفق (Response Body) سیستم و جدول تشریح فیلدهای فنی و بیزینسی آن آمده است:

Response موفق (200): API Specified Parcels

{
  "order_id": "string",
  "order_number": "string",
  "shipment_id": "string",
  "shipment_code": "string",
  "consignor_unique_reference_id": "string",
  "parcel_summaries": [
    {
      "parcel_id": "string",
      "parcel_code": "string",
      "consignor_reference_id": "string",
      "scannable_codes": [
        "string"
      ]
    }
  ],
  "estimated_capacity": {
    "parcels_total_estimated_weight_grams": "string",
    "parcels_total_estimated_volume_in_cm3": "string",
    "parcels_used_weight_grams": "string",
    "parcels_used_volume_in_cm3": "string",
    "parcels_remained_weight_grams": "string",
    "parcels_remained_volume_in_cm3": "string"
  },
  "parcel_size_tier": "NORMAL"
}

جدول پارامترهای خروجی موفق ثبت سفارش (Response Body)

مقادیر -1 در estimated_capacity به این معناست که از روش Specified Parcels استفاده شده و ظرفیت تخمینی وجود ندارد.

حتماً shipment_id دریافتی را در سیستم خود ذخیره کنید. در صورتی که به هر دلیلی این شناسه ذخیره نشد، می‌توانید مجدداً متد را با همان consignor_unique_reference_id قبلی فراخوانی (Call) کنید؛ در این حالت، سیستم خطای تکراری بودن کد مرجع را می‌دهد، اما کل ریسپانس اولیه (که شامل shipment_id نیز می‌شود) را مجدداً در پاسخ برمی‌گرداند.

دریافت HTTP 200 به معنای تحویل قطعی نیست. ممکن است پس از 200 سیستم به دلایلی (مثل آدرس خارج از ایران یا بازه تحویل پشتیبانی‌نشده) shipment را رد کند و نتیجه از طریق Webhook اطلاع‌رسانی شود.

در بخش مبدأ (Origin):

اگر بار را از انبار/مغازه خودتان تحویل می‌دهید، فقط آدرس مبدأ (origin_address) را بفرستید.

اگر بار را خودتان به یکی از هاب‌های دیجی‌اکسپرس می‌رسانید، فقط شناسه هاب مبدأ (origin_point_id) را بفرستید.

ارسال همزمان آدرس مبدأ و شناسه هاب مبدأ خطای سیستمی ایجاد می‌کند.

در بخش مقصد (Destination):

اگر بار مستقیم به دست مشتری نهایی می‌رسد، فقط آدرس مقصد (destination_address) را بفرستید.

اگر بار باید به یک هاب یا نقطه توزیع خاص برود، فقط شناسه هاب مقصد (destination_point_id) را بفرستید.

❌ارسال همزمان آدرس مقصد و شناسه هاب مقصد خطای سیستمی ایجاد می‌کند.

راهنمای جامع قابلیت scannable_codes

قابلیت scannable_codes برای زمانی استفاده می‌شود که کانساینر بخواهد علاوه بر parcel_code تولیدشده توسط دیجیاکسپرس، کد یا کدهای اختصاصی خودش نیز برای همان پارسل قابل اسکن و قابل شناسایی باشند.

این فیلد در سطح هر parcel ارسال می‌شود و به‌صورت آرایه‌ای از رشته‌ها است. بنابراین کانساینر می‌تواند برای هر پارسل یک یا چند کد قابل اسکن ارسال کند.

{
  "scannable_codes": [
    "WAREHOUSE-BC-100245",
    "WMS-PKG-88991234"
  ]
}

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

کاربرد عملیاتی

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

با ارسال scannable_codes، کانساینر می‌تواند کدهای داخلی خودش مثل بارکد انبار، شناسه WMS، کد بسته‌بندی، کد پستی، کد سفارش یا هر شناسه قابل اسکن دیگری را نیز به همان پارسل متصل کند. در این حالت، سیستم دیجیاکسپرس می‌تواند آن کدها را مثل parcel_code شناسایی کند.

قوانین اعتبارسنجی

مقدارهای ارسال‌شده در scannable_codes باید در سطح کل سیستم دیجی‌اکسپرس یکتا باشند. این یکتایی فقط در سطح همان کانساینر بررسی نمی‌شود؛ یعنی اگر یک کد قبلاً توسط هر کانساینر دیگری در سیستم ثبت شده باشد، امکان استفاده مجدد از آن وجود ندارد.

طول هر مقدار باید بین ۱۲ تا ۳۶ کاراکتر باشد. مقدار ۱۲ کاراکتری و مقدار ۳۶ کاراکتری نیز معتبر هستند.

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

● همان کد قبلا برای پارسل دیگری در سیستم دیجی‌اکسپرس ثبت شده باشد. ● همان کد قبلاً توسط کانساینر دیگری ثبت شده باشد. ● داخل همان آرایه scannable_codes یک مقدار دوبار تکرار شده باشد.

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

رفتار روی لیبل دیجی‌اکسپرس

اگر برای یک پارسل چند مقدار در scannable_codes ارسال شود، همه آن‌ها در سیستم دیجی‌اکسپرس برای شناسایی همان پارسل معتبر هستند؛ اما روی لیبل استاندارد دیجی‌اکسپرس فقط اولین مقدار آرایه قرار می‌گیرد.

{
  "scannable_codes": [
    "WAREHOUSE-BC-100245",
    "WMS-PKG-88991234",
    "POST-TRACK-2478912345"
  ]
}

در این مثال، مقدار WAREHOUSE-BC-100245 روی لیبل دیجی‌اکسپرس، پشت Barcode و QR Code قرار می‌گیرد. اما اگر مقدارهای WMS-PKG-88991234 یا POST-TRACK-2478912345 نیز در عملیات دیجی‌اکسپرس اسکن یا جستجو شوند، سیستم همچنان همان پارسل را شناسایی می‌کند.

رفتار در فرآیند Revive

اگر یک Shipment به وضعیت نهایی ناموفق برسد و کانساینر بخواهد همان سفارش را با قابلیت Revive احیا کند، می‌تواند همان scannable_codes قبلی را دوباره برای پارسل‌های سفارش احیاشده ارسال کند.

در فرآیند Revive، اطلاعات قبلی پارسل‌ها پاک می‌شود و سفارش با اطلاعات جدید ثبت می‌شود. به همین دلیل، استفاده مجدد از همان کدهای قابل اسکن قبلی برای همان سفارش احیاشده مجاز است.

اما اگر کانساینر بخواهد همان کد را در یک Shipment جدید و مستقل استفاده کند، سیستم آن را به‌عنوان کد تکراری شناسایی می‌کند و درخواست با خطا مواجه می‌شود.

نکات مهم

● scannable_codes جایگزین parcel_code نیست. ● scannable_codes جایگزین consignor_reference_id نیست. ● این فیلد فقط در سطح parcel ارسال می‌شود، نه در سطح Shipment. ● همه مقدارهای داخل آرایه باید string باشند. ● هر مقدار باید بین ۱۲ تا ۳۶ کاراکتر باشد. ● هر مقدار باید در سطح کل سیستم دیجی‌اکسپرس یکتا باشد. ● اگر چند مقدار ارسال شود، همه آن‌ها قابل اسکن هستند، اما فقط اولین مقدار روی لیبل دیجی‌اکسپرس قرار می‌گیرد. ● در صورت Revive همان سفارش، امکان استفاده مجدد از scannable_codes قبلی وجود دارد.

روش دوم: ثبت با ظرفیت تخمینی (Estimated Capacity)

این روش برای زمانی طراحی شده است که اطلاعات فیزیکی دقیق پارسل‌ها در لحظه ثبت سفارش مشخص نیست. در این سناریو، شما ابتدا یک ظرفیت کلی در سیستم رزرو می‌کنید و بعداً پارسل‌ها را به مرور به مرسوله اضافه خواهید کرد.

ساختار درخواست (Request Body): ساختار کلی مشابه روش قبل (Specified Parcels) است، با این تفاوت که به جای آرایه parcels، آبجکت "max_shipment_capacity_estimation_for_pre_reservation" ارسال می‌شود:

"consignor_unique_reference_id": "string",
 "revive_if_already_registered_and_failed": true,
 "cargo_ready_date_time": "string",
 "promise_start_date_time": "string",
 "promise_end_date_time": "string",
 "origin_point_id": "string",
 "origin_address": {
 "city_id": "string",
 "full_address": "string",
 "building_number": "string",
 "unit": "string",
 "postal_code": "string",
 "latitude": "string",
 "longitude": "string",
 "description": "string"
 },
 "cargo_submitter_person": {
 "first_name": "string",
 "last_name": "string",
 "national_code": "string",
 "first_mobile": "string",
 "second_mobile": "string",
 "phone": "string"
 },
 "destination_point_id": "string",
 "destination_address": {
 "city_id": "string",
 "full_address": "string",
 "building_number": "string",
 "unit": "string",
 "postal_code": "string",
 "latitude": "string",
 "longitude": "string",
 "description": "string"
 },
 "recipient_person": {
 "first_name": "string",
 "last_name": "string",
 "national_code": "string",
 "first_mobile": "string",
 "second_mobile": "string",
 "phone": "string"
 },
 "constant_proof_of_delivery_code_for_all_parcels": "string",
"max_shipment_capacity_estimation_for_pre_reservation": {
 "parcels_total_estimated_weight_grams": "string",
 "each_parcel_size_tier": "NORMAL",
 "all_parcels_as_single_box_estimated_max_dimensions_cm": [
 "string"
 ]
 },
}

جدول پارامترهای هر آیتم در Estimated Capacity:

جدول ماتریس سایزبندی بسته‌ها (Parcel Size Tier)

یک Parcel در صورتی در دسته LARGE قرار می‌گیرد که حداقل یکی از شرایط زیر برقرار باشد: حداقل یکی از ابعاد بیشتر از 140 سانتی‌متر باشد؛ یا وزن Parcel بیشتر از 40 کیلوگرم باشد.

نکات و قوانین بسیار مهم رزرو ظرفیت

• شما به هیچ عنوان نمی‌توانید همزمان دو فیلد parcels و max_shipment_capacity_estimation_for_pre_reservation را در یک درخواست بفرستید. ارسال همزمان این دو فیلد منجر به خطای ساختاری می‌شود و باید متناسب با فلو، یکی را انتخاب کنید.
• قانون جداسازی سایز مرسولات: پارسل‌های دسته LARGE (بزرگ‌سایز) نمی‌توانند در یک Shipment مشترک با پارسل‌های NORMAL یا MEDIUM قرار بگیرند.
• مثال بیزینسی: اگر یک سفارش مشتری شامل یک عدد "گوشی موبایل" و یک عدد "یخچال" باشد، به دلیل تفاوت ساختاری در تخصیص خودرو، این دو کالا حتماً باید در دو Shipment جداگانه ثبت شوند.

Response موفق (200): در صورتی که درخواست ثبت سفارش با روش ظرفیت تخمینی (Estimated Capacity) با موفقیت در سیستم ثبت شود، پاسخ (HTTP 200 (OK همراه با ساختار (Response Body) زیر صادر خواهد شد:

{
  "order_id": "string",
  "order_number": "string",
  "shipment_id": "string",
  "shipment_code": "string",
  "consignor_unique_reference_id": "string",
  "parcel_summaries": [
    {
      "parcel_id": "string",
      "parcel_code": "string",
      "consignor_reference_id": "string",
      "scannable_codes": [
        "string"
      ]
    }
  ],
  "estimated_capacity": {
    "parcels_total_estimated_weight_grams": "string",
    "parcels_total_estimated_volume_in_cm3": "string",
    "parcels_used_weight_grams": "string",
    "parcels_used_volume_in_cm3": "string",
    "parcels_remained_weight_grams": "string",
    "parcels_remained_volume_in_cm3": "string"
  },
  "parcel_size_tier": "NORMAL"
}

جدول پارامترهای خروجی ثبت سفارش با ظرفیت تخمینی

قوانین و پویایی ظرفیت مرسوله: با توجه به فرآیند پردازش انبار شما، پس از هر بار فراخوانی موفق سرویس افزودن پارسل (Add Parcel) به این مرسوله، مشخصات فیزیکی بسته واقعی ثبت شده و به صورت خودکار مقادیر مصرف‌شده (used) افزایش یافته و از مقدار ظرفیت باقی‌مانده کانساینر (remained_weight و remained_volume) کسر خواهد شد. ( تمامی این موارد از طریق وب هوک نیز اطلاع رسانی خواهد شد )

مدیریت پارسل‌ها (تغییرات مرسوله‌های تخمینی)

پیش‌نیاز: این مرحله مخصوص سفارش‌هایی است که در گام قبل به صورت ظرفیت تخمینی (Estimated Capacity) ثبت شده‌اند و شما برای مدیریت آن‌ها به shipment_id یا consignor_unique_reference_id نیاز دارید.

شرط لجستیکی و زمانی بسیار مهم :

• موفقیت در مسیریابی: شما تنها زمانی می‌توانید به یک مرسوله (Shipment) پارسل جدید اضافه کرده یا از آن حذف کنید که عملیات مسیریابی (Routing) آن در سیستم با موفقیت انجام شده باشد. در صورت عدم تخصیص روت (خطای No Route Found)، امکان مدیریت پارسل‌ها وجود نخواهد داشت.
• بازه زمانی: تمام فرآیندهای این مرحله تنها تا زمانی در سیستم مجاز است که بازه جمع‌آوری (Pick-up) مرسوله شروع نشده باشد و بار هنوز نزد فرستنده بوده و وارد پروسه عملیاتی دیجی‌اکسپرس نشده باشد.

افزودن پارسل به ارسال (Add Parcel)

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

• انعطاف در شناسایی: در آدرس (URL) این اندپوینت، سیستم هم shipment_id (آیدی دیجی‌اکسپرس) و هم consignor_unique_reference_id (کد مرجع شما) را می‌پذیرد.
• ارسال گروهی: پارسل‌ها به صورت یک آرایه دریافت می‌شوند؛ بنابراین می‌توانید در یک درخواست، چندین بسته را به صورت همزمان به مرسوله اضافه کنید.
• امکان چاپ فوری لیبل: فرآیند افزودن پارسل به صورت همزمان (Sync) پردازش می‌شود و به محض دریافت ریسپانس 200، می‌توانید فوراً API چاپ لیبل بارکد آن پارسل را صدا بزنید.

ساختار درخواست افزودن پارسل (Request Body) :

"parcels": [
 {
 "dimensionsInCMs": [
 "string"
 ],
 "content_value_price_rials": "string",
 "description": "string",
 "items_description": "string",
 "weight_grams": "string",
 "consignor_reference_id": "string",
 "payable_price_rials_by_recipient": "string",
 "scannable_codes": [
 "string"
 ],
 "characteristics": [
 "string"
 ],
 "packaging_type": "string"
 }
 ]

جدول پارامترهای ورودی آرایه Parcels

ساختار پاسخ موفق افزودن پارسل (Response Body - HTTP 200)

{
  "parcels_total_estimated_weight_grams": "string",
  "parcels_total_estimated_volume_in_cm3": "string",
  "parcels_used_weight_grams": "string",
  "parcels_used_volume_in_cm3": "string",
  "parcels_remained_weight_grams": "string",
  "parcels_remained_volume_in_cm3": "string",
  "new_added_parcels": [
    {
      "parcel_id": "string",
      "parcel_code": "string",
      "consignor_reference_id": "string",
      "scannable_codes": [
        "string"
      ]
    }
  ],
  "all_parcels": [
    {
      "parcel_id": "string",
      "parcel_code": "string",
      "consignor_reference_id": "string",
      "scannable_codes": [
        "string"
      ]
    }
  ]
}

جدول پارامترهای خروجی متد افزودن پارسل

حذف پارسل از ارسال (Delete Parcel)

اگر نیاز به حذف یک بسته از یک مرسوله ثبت‌شده داشته باشید، از این سرویس استفاده می‌شود. پس از حذف موفق، ظرفیت اشغال شده توسط آن بسته دقیقاً به میزان وزن و حجم آن به مقدار «ظرفیت باقی‌مانده» مرسوله بازگردانده می‌شود. شما به دو روش می‌توانید پارسل را حذف کنید:

روش اول: استفاده از شناسه‌های اختصاصی شما (Reference IDs)

این روش زمانی کاربرد دارد که شما در لایه درخواست افزودن، از شناسه‌های اختصاصی خودتان (consignor_reference) استفاده کرده باشید.

• {shipment_ref}: شناسه یکتای مرسوله در سمت شما (consignor_unique_reference_id).
• {parcel_ref}: شناسه یکتای بسته در سمت شما (consignor_reference_id).

روش دوم: استفاده از شناسه‌های سیستمی دیجی‌اکسپرس (System IDs)

این روش ساده‌تر است و نیازی به ارسال شناسه مرسوله (Shipment) ندارد، زیرا آیدی یا کد پارسل در کل هسته سیستم دیجی‌اکسپرس یکتاست.

• {parcel_id_or_code}: آیدی متنی (UUID) یا بارکد پارسل (مانند DP...) که در ریسپانس‌های قبلی دریافت کرده‌اید.

قانون حذف آخرین پارسل: اگر مرسوله‌ای کلاً شامل یک پارسل باشد و شما همان یک پارسل را هم حذف کنید، کل سفارش لغو نمی‌شود؛ بلکه مرسوله همچنان در وضعیت "رزرو ظرفیت خالی" در سیستم باقی می‌ماند تا بسته جدید به آن اضافه کنید (مگر اینکه کل مرسوله را از طریق API ابطال، Cancel کنید).

ساختار پاسخ موفق حذف پارسل از ارسال (Response Body - HTTP 200) :

{
  "parcels_total_estimated_weight_grams": "string",
  "parcels_total_estimated_volume_in_cm3": "string",
  "parcels_used_weight_grams": "string",
  "parcels_used_volume_in_cm3": "string",
  "parcels_remained_weight_grams": "string",
  "parcels_remained_volume_in_cm3": "string",
  "removed_parcels": [
    {
      "parcel_id": "string",
      "parcel_code": "string",
      "consignor_reference_id": "string",
      "scannable_codes": [
        "string"
      ]
    }
  ],
  "remaining_parcels": [
    {
      "parcel_id": "string",
      "parcel_code": "string",
      "consignor_reference_id": "string",
      "scannable_codes": [
        "string"
      ]
    }
  ],
  "parcel_size_tier": "NORMAL"
}

جدول پارامترهای خروجی متد حذف پارسل