Skip to main content

رزرو سفارش

برای ثبت سفارش جدید، وب‌سرویس زیر در نظر گرفته شده است که در ادامه به جزئیات آن خواهیم پرداخت.

POST/v1.1/p2p-delivery/occupancies/reserve
نیاز به احراز هویت

Request Body​

روش مستقیم: رزرو با ارسال اطلاعات سفارش​
{
  "origin_address": {
    "city_id": 300,
    "full_address": "آدرس مبدا",
    "latitude": 35.60436,
    "longitude": 51.30924
  },
  "sender_person": {
    "firstname": "علی",
    "lastname": "محمدی",
    "phone_number": "+989120000000"
  },
  "recipient_person": {
    "firstname": "محمد",
    "lastname": "محمدی",
    "phone_number": "+989121111111"
  },
  "destination_address": {
    "city_id": 300,
    "full_address": "آدرس مقصد",
    "latitude": 35.70436,
    "longitude": 51.40924
  },
  "logistic_company": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "parcels": [
    {
      "dimension": {
        "width": 0.2,
        "height": 0.3,
        "length": 0.4
      },
      "weight": 1500,
      "value": 1000000,
      "submitter_id": "123456",
      "packaging_type": "box",
      "characteristics": "normal"
    }
  ],
  "pod": "12345",
  "ready_time": "2026-06-21 11:00:00"
}
روش دوم: رزرو با توکن بازه زمانی منتخب​

در روش دوم، ابتدا وب‌سرویس دریافت بازه‌های زمانی معتبر را فراخوانی کنید. هر عضو آرایه options در پاسخ آن وب‌سرویس دارای یک candidate_token است. پس از انتخاب بازه موردنظر، مقدار این فیلد را به‌عنوان candidate_shipping_window_token در درخواست رزرو ارسال کنید.

{
  "candidate_shipping_window_token": "candidate-token-1"
}
info

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

Response Body​

{
  "occupancy_uuid": "c82de21f-19b0-477e-a489-3705a6e04da9",
  "shipment_id": "667788",
  "external_id": "GNJ11113370",
  "parcels": [
    {
      "id": 1367,
      "submitter_id": "123456",
      "weight": 1500,
      "value": 1000000,
      "temp_size": {
        "uuid": "d20e3f63-00df-4138-9a61-46944a5e526d",
        "name": null,
        "length": 0.4,
        "width": 0.2,
        "height": 0.3
      }
    }
  ],
  "status": "reserved",
  "logistic_company": {
    "pk": 2,
    "uuid": "e6733e4d-13ee-4b36-97fc-c167d2b5753b",
    "name": "دیجی‌اکسپرس"
  },
  "sender": {
    "firstname": "علی",
    "lastname": "محمدی",
    "phone_number": "+989120000000",
    "full_name": "علی محمدی"
  },
  "recipient": {
    "firstname": "محمد",
    "lastname": "محمدی",
    "phone_number": "+989121111111",
    "full_name": "محمد محمدی"
  },
  "destination_location": {
    "city": {
      "id": 300,
      "name": "تهران",
      "province": {
        "id": 8,
        "name": "تهران"
      }
    },
    "address": "آدرس مقصد",
    "latitude": 35.70436,
    "longitude": 51.40924
  }
}

توضیحات فیلدهای درخواست​

در روش اصلی رزرو، درخواست شما باید شامل موارد زیر باشد.

  • origin_address(*): اطلاعات آدرس مبدا که باید شامل موارد زیر باشد:

    • city_id(*): آیدی شهر مبدا. برای دریافت لیست شهر‌ها و آیدی آن‌ها اینجا را مطالعه کنید.
    • full_address(*): آدرس پستی مبدا
    • ‍latitude: عرض جغرافیایی
    • ‍longitude: طول جغرافیایی

  • destination_address(*): اطلاعات آدرس مقصد که مشابه توضیحات ارائه شده برای آدرس مبدا است.

tip

در صورتی که اطلاعات طول و عرض جغرافیایی برای مبدا یا مقصد سفارش، ارسال نشود، آدرس لفظی ارائه شده، به مختصات جغرافیایی تبدیل می‌شود اما ارسال این اطلاعات توسط شما به مسیریابی دقیق‌تر کمک می‌کند.

  • ‍‍‍sender_person(*): اطلاعات شخص فرستنده که برای هماهنگی جهت دریافت مرسوله استفاده خواهد شد. این اطلاعات باید شامل موارد زیر باشد:

    • firstname(*): نام
    • lastname(*): نام خانوادگی
    • phone_number(*): شماره تماس

  • ‍‍‍recipient_person(*): اطلاعات شخص گیرنده که برای هماهنگی جهت تحویل مرسوله استفاده خواهد شد. این اطلاعات مشابه اطلاعات شخص فرستنده است.

  • logistic_company(*): سرویس پستی که می‌خواهید از آن برای ارسال مرسوله استفاده کنید.

  • pod: کد تحویل مرسوله که گیرنده باید هنگام تحویل گرفتن مرسوله، آن را به مامور ارسال، اعلام کند.

tip

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

  • ready_time: زمان آماده بودن مرسوله که نمی‌تواند در گذشته باشد. جمع‌آوری مرسوله بعد از این زمان، انجام خواهد شد و در صورتی که این فیلد را ارسال نکنید، جمع‌آوری مرسوله در نزدیک‌ترین زمان ممکن انجام می‌شود.

  • parcels(*): اطلاعات بسته‌های مربوط به این مرسوله که باید به صورت آرایه‌ای شامل اطلاعات زیر باشد:

    • dimension(*): ابعاد بسته در این قسمت مشخص می‌شود که شامل (*)width(عرض)، (*)height(ارتفاع) و (*)length(طول) است. این ابعاد باید بر حسب متر مشخص شود.
    • weight(*): وزن بسته بر حسب گرم
    • value(*): ارزش ریالی بسته که مبنای محاسبه هزینه بیمه مرسوله قرار میگیرد
    • submitter_id: آیدی بسته در سیستم شما که در پاسخ این سرویس و سایر سرویس‌ها به شما برمی‌گردد.
    • packaging_type: نوع بسته‌بندی فیزیکی بسته را مشخص می‌کند. مقدار آن باید packet برای بسته‌های دارای پاکت یا بسته‌بندی سبک، یا box برای بسته‌بندی جعبه‌ای باشد. این فیلد اختیاری است و مقدار پیش‌فرض آن box است.
    • characteristics: ویژگی عملیاتی یا حساسیت محتوای بسته را مشخص می‌کند. مقدار آن باید gold برای بسته‌های حاوی طلا، یا normal برای سایر بسته‌های عادی باشد. این فیلد اختیاری است و مقدار پیش‌فرض آن normal است.

روش دوم: رزرو با توکن بازه زمانی منتخب​

در این روش، به‌جای فیلدهای بالا فقط فیلد زیر را ارسال کنید:

warning

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

توضیحات فیلدهای پاسخ​

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

  • occupancy_uuid: عبارت است از uuid اختصاص یافته به این سفارش که جهت فراخوانی سایر وب‌سرویس‌‌ها مورد استفاده قرار خواهد گرفت.
  • external_id: آیدی مرسوله در سیستم پستی
  • parcels: آرایه‌ای از اطلاعات بسته‌های مربوط به این سفارش، مطابق با اطلاعات داده شده در درخواست شما.
  • status: وضعیت سفارش که در هنگام ثبت مرسوله ‍reserved خواهد بود.