بازه‌های زمانی ارسال و ثبت دو مرحله‌ای (Shipping Time Window)

پیش‌نیاز: داشتن access_token و در اختیار داشتن اطلاعات زمان آماده‌سازی مرسوله، مبدأ، مقصد و برآورد فیزیکی محموله.

خروجی مرحله اول: دریافت یک یا چند بازه قابل ارائه برای جمع‌آوری و تحویل، به همراه یک token اختصاصی برای هر گزینه.

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

سرویس Shipping Time Window برای کانساینرهایی طراحی شده است که می‌خواهند پیش از ثبت نهایی مرسوله، بازه‌های واقعی و قابل ارائه دیجی‌اکسپرس را به مشتری نهایی خود نمایش دهند تا مشتری بتواند زمان تحویل را انتخاب کند.

این API به‌تنهایی هیچ Shipment یا Parcel جدیدی ایجاد نمی‌کند و جایگزین API ثبت سفارش نیست. این سرویس صرفاً بر اساس اطلاعاتی مانند زمان آماده بودن بار، مبدأ، مقصد، ماهیت فیزیکی مرسوله، ظرفیت عملیاتی و روزهای تعطیل کانساینر، گزینه‌های قابل ارائه را محاسبه می‌کند.

برای هر گزینه، یک توکن اختصاصی در پاسخ برگردانده می‌شود. پس از انتخاب بازه توسط مشتری، کانساینر باید توکن همان گزینه را همراه با اطلاعات ثبت سفارش به API اصلی Register Shipment ارسال کند.

تفاوت ثبت تک‌مرحله‌ای و ثبت با انتخاب بازه زمانی

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

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

فرآیند کلی ثبت با Shipping Time Window

فرآیند ثبت سفارش با انتخاب بازه زمانی شامل مراحل زیر است:

• کانساینر اطلاعات زمان آماده‌سازی، مبدأ، مقصد و برآورد فیزیکی مرسوله را به API مربوط به Shipping Time Window ارسال می‌کند.
• دیجی‌اکسپرس یک یا چند گزینه قابل ارائه را در آرایه options برمی‌گرداند.
• کانساینر بازه تحویل هر گزینه، یعنی promise_start_date_time و promise_end_date_time، را به مشتری نهایی نمایش می‌دهد.
• مشتری یکی از گزینه‌ها را انتخاب می‌کند.
• کانساینر token، همان گزینه را در API اصلی ثبت سفارش ارسال می‌کند.
• در مرحله ثبت نهایی، کانساینر باید یکی از دو روش زیر را انتخاب کند:
• ثبت با پارسل‌های مشخص یا Specified Parcels
• ثبت با ظرفیت تخمینی یا Estimated Capacity

دریافت بازه‌های زمانی قابل ارسال

Get Shipping Time Windows

این API یک سرویس استعلامی است. فراخوانی موفق آن به معنی ثبت سفارش نیست و هیچ shipment_id یا parcel_id جدیدی ایجاد نمی‌کند.

هر بار فراخوانی این API توکن‌‌های جدیدی تولید می‌کند؛ بنابراین کانساینر باید توکن همان گزینه‌ای را ذخیره کند که مشتری در آخرین استعلام معتبر انتخاب کرده است.

ساختار درخواست Shipping Time Window

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

برای مبدأ فقط یکی از origin_point_id یا origin_address ارسال شود.

برای مقصد فقط یکی از destination_point_id یا destination_address ارسال شود.

{
  "cargo_ready_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"
  },
  "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"
  },
  "all_parcels_as_single_box_estimated_max_dimensions_cm": [
    "string",
    "string",
    "string"
  ],
  "all_parcels_as_single_box_estimated_max_weight_grams": "string",
  "each_parcel_size_tier": "NORMAL",
  "off_day_dates": [
    "YYYY-MM-DD"
  ]
}

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

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

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

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

نکته درباره برآورد فیزیکی مرسوله

برآورد وزن و ابعاد در این API برای تعیین موارد زیر استفاده می‌شود:

• تشخیص ماهیت و گروه سایز مرسوله
• بررسی ظرفیت وزنی و حجمی مسیرها
• حذف روزهایی که ظرفیت کافی برای مرسوله وجود ندارد
• تعیین بازه‌های واقعی قابل ارائه به مشتری

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

• ارسال مشخصات واقعی تمام پارسل‌ها در آرایه parcels
• ارسال ظرفیت تخمینی در max_shipment_capacity_estimation_for_pre_reservation

همچنین گروه سایز اعلام‌شده باید با پارسل‌های مرحله ثبت نهایی سازگار باشد. برای مثال، اگر در مرحله دریافت Time Window مقدار NORMAL اعلام شده باشد، نباید در مرحله ثبت یا افزودن پارسل، بسته‌ای با مشخصات گروه LARGE برای همان مرسوله ارسال شود.

ساختار پاسخ موفق Shipping Time Window

Response Body (HTTP 200)

{
  "options": [
    {
      "token": "string",
      "promise_start_date_time": "string",
      "promise_end_date_time": "string",
      "pickup_start_date_time": "string",
      "pickup_end_date_time": "string",
      "expires_at_date_time": "string",
      "route_start_date_time_cut_off": "string",
      "service_level": "STANDARD"
    }
  ]
}

جدول پارامترهای خروجی Shipping Time Window

قوانین اعتبار و مصرف توکن

• هر گزینه در آرایه options دارای یک token مستقل است.
• توکن فقط تا زمان اعلام‌شده در expires_at_date_time معتبر است.
• سیستم کانساینر نباید برای اعتبار توکن یک مدت ثابت، مانند 24 ساعت، در نظر بگیرد؛ همیشه باید زمان دقیق برگشتی در expires_at_date_time ملاک قرار گیرد.
• محدودیت route_start_date_time_cut_off نیز باید در کنار زمان انقضای توکن رعایت شود.
• در صورت منقضی شدن توکن یا عبور از محدودیت عملیاتی گزینه، API مربوط به Shipping Time Window باید مجدداً فراخوانی شود.
• هر فراخوانی جدید ممکن است توکن‌های جدیدی تولید کند؛ بنابراین از ذخیره یا استفاده طولانی‌مدت از توکن‌های قدیمی خودداری شود.
• دریافت توکن به‌تنهایی به معنی ثبت یا رزرو نهایی Shipment نیست. ثبت قطعی فقط پس از فراخوانی موفق API ثبت سفارش انجام می‌شود.
• پس از ثبت موفق سفارش با یک توکن، همان توکن نباید برای ایجاد Shipment دیگری استفاده شود.

اطلاعاتی که در مرحله Shipping Time Window داخل Token ثبت و Lock شده‌اند، در Final Register نباید مجددا در Body ارسال شوند. این موارد شامل cargo_ready_date_time، اطلاعات مبدأ، اطلاعات مقصد، promise_start_date_time، promise_end_date_time و service_level هستند.

در Final Register، علاوه بر اطلاعات عمومی موردنیاز ثبت سفارش، token گزینه انتخاب‌شده ارسال می‌شود و بر اساس روش ثبت، فقط یکی از parcels یا max_shipment_capacity_estimation_for_pre_reservation مقداردهی می‌شود.

ارسال همزمان parcels و max_shipment_capacity_estimation_for_pre_reservation مجاز نیست؛ این دو روش در ساختار فعلی ثبت سفارش نیز به‌عنوان روش‌های مجزا تعریف شده‌اند.

نهایی‌سازی سفارش با توکن انتخاب‌شده

پس از انتخاب گزینه توسط مشتری، کانساینر باید API اصلی ثبت سفارش را فراخوانی کند:

Method: POST
Endpoint: https://api-demo.digiexpress.ir/api/v2/shipments
Authorization: <access_token>

در این مرحله، اطلاعات پایه ثبت سفارش مطابق بخش اصلی Register Shipment ارسال می‌شوند. علاوه بر آن، فیلدهای زیر باید بر اساس گزینه انتخاب‌شده مقداردهی شوند:

روش اول: ثبت با پارسل‌های مشخص و Time Window

Register with Specified Parcels and Selected Time Window

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

در این حالت:

• آرایه parcels باید ارسال شود.
• آبجکت max_shipment_capacity_estimation_for_pre_reservation نباید ارسال شود.
• توکن و زمان‌های گزینه انتخاب‌شده باید در همان درخواست قرار گیرند.
• پس از ثبت موفق، امکان اضافه یا حذف کردن پارسل‌های این Shipment وجود ندارد.

ساختار درخواست

فیلدهای Token-bound در این ساختار ارسال نمی‌شوند؛ زمان آماده‌سازی، اطلاعات مبدأ، اطلاعات مقصد، بازه تعهد و service_level داخل token قرار دارند.

{
  "consignor_unique_reference_id": "string",
  "revive_if_already_registered_and_failed": true,
  "order_number": "string",
  "cargo_submitter_person": {
    "first_name": "string",
    "last_name": "string",
    "national_code": "string",
    "first_mobile": "string",
    "second_mobile": "string",
    "phone": "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",
        "string",
        "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"
    }
  ],
  "token": "string"
}

رفتار سیستم

در صورت معتبر بودن توکن و تطابق اطلاعات ثبت با گزینه انتخاب‌شده، دریافت HTTP 200 به معنی ثبت موفق و قطعی Shipment در همان لحظه است.

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

ساختار پاسخ این روش همان ساختار پاسخ موفق Specified Parcels در بخش اصلی ثبت سفارش است.

روش دوم: ثبت با ظرفیت تخمینی و Time Window

Register with Estimated Capacity and Selected Time Window

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

در این حالت:

• آبجکت max_shipment_capacity_estimation_for_pre_reservation باید ارسال شود.
• آرایه parcels نباید ارسال شود.
• توکن و زمان‌های گزینه انتخاب‌شده باید در همان درخواست قرار گیرند.
• پس از ثبت موفق، پارسل‌های واقعی از طریق APIهای Add Parcel و Delete Parcel مدیریت می‌شوند.

ساختار درخواست

{
  "consignor_unique_reference_id": "string",
  "select_random_found_route": true,
  "revive_if_already_registered_and_failed": true,
  "order_number": "string",
  "cargo_submitter_person": {
    "first_name": "string",
    "last_name": "string",
    "national_code": "string",
    "first_mobile": "string",
    "second_mobile": "string",
    "phone": "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",
      "string",
      "string"
    ]
  },
  "token": "string"
}

رفتار سیستم

در صورت معتبر بودن توکن و تطابق اطلاعات درخواست با گزینه انتخاب‌شده، دریافت HTTP 200 به معنی ثبت قطعی Shipment و نهایی شدن مسیر است.

با این حال، در این مرحله هنوز پارسل فیزیکی ایجاد نشده است؛ بنابراین امکان دریافت لیبل پارسل بلافاصله پس از ثبت اولیه وجود ندارد.

کانساینر باید پس از آماده شدن هر بسته، API مربوط به Add Parcel را فراخوانی کند. پس از دریافت پاسخ موفق HTTP 200 از متد افزودن پارسل، parcel_id و parcel_code ایجاد می‌شوند و لیبل همان پارسل بلافاصله قابل دریافت خواهد بود.

ساختار پاسخ این روش همان ساختار پاسخ موفق Estimated Capacity در بخش اصلی ثبت سفارش است.

نتیجه ثبت و زمان دریافت لیبل

ارسال وب‌هوک‌های عملیاتی و تغییرات وضعیت در هر دو روش همچنان ادامه خواهد داشت. همزمان بودن Register به معنی حذف وب‌هوک نیست؛ بلکه فقط به این معناست که نتیجه ثبت اولیه و انتخاب مسیر در همان پاسخ API قطعی شده است.

نکات و قوانین مهم فلو Shipping Time Window

• API مربوط به Shipping Time Window یک API استعلامی است و به‌تنهایی هیچ سفارشی ثبت نمی‌کند.
• زمان‌های برگشتی بر اساس اطلاعات همان درخواست، ظرفیت لحظه‌ای و روزهای قابل ارائه محاسبه می‌شوند.
• هر گزینه دارای توکن مستقل است.
• توکن گزینه انتخاب‌شده باید در فیلد token درخواست Register قرار گیرد.
• promise_start_date_time، promise_end_date_time و service_level جزئی از اطلاعات گزینه انتخاب‌شده هستند و داخل Token ذخیره می‌شوند؛ بنابراین در Final Register نباید مجددا ارسال شوند.
• pickup_start_date_time و pickup_end_date_time فقط خروجی سرویس Time Window هستند و لازم نیست در Register ارسال شوند.
• اطلاعات مبدأ، مقصد و زمان آماده‌سازی ثبت نهایی باید با اطلاعاتی که گزینه‌ها بر اساس آن‌ها محاسبه شده‌اند سازگار باشند.
• اطلاعات تخمینی مرحله Time Window جایگزین مشخصات واقعی یا ظرفیت تخمینی مرحله Register نمی‌شوند.
• در ثبت با پارسل مشخص، parcels اجباری است و ظرفیت تخمینی نباید ارسال شود.
• در ثبت با ظرفیت تخمینی، آبجکت ظرفیت اجباری است و parcels نباید ارسال شود.
• پارسل‌های نهایی باید با each_parcel_size_tier اعلام‌شده در مرحله Time Window سازگار باشند.
• off_day_dates مربوط به روزهای عدم امکان پیکاپ از مبدأ کانساینر است، نه روزهای عدم حضور مشتری در مقصد.
• سیستم کانساینر باید زمان دقیق expires_at_date_time را ملاک قرار دهد و نباید مدت اعتبار توکن را به‌صورت ثابت در کد خود پیاده‌سازی کند.
• در صورت انقضای توکن، استعلام Shipping Time Window باید مجدداً انجام شود.
• در صورت ثبت با ظرفیت تخمینی، تمام قوانین فعلی Add Parcel و Delete Parcel بدون تغییر برقرار هستند.