پرش به مطلب اصلی

رزرو سفارش

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

  • no-packing: بدون بسته‌بندی
  • manual-packing: بسته‌بندی دستی
  • automatic-packing: بسته‌بندی خودکار

در صورتی که از سایز لاکرهای گنجه آگاهی دارید و می‌دانید سفارش شما مناسب کدام یک از این سایز‌ها است، می‌توانید از سرویس manual-packing استفاده کنید؛ اما در صورتی که ابعاد بسته(ها) را می‌دانید و می‌خواهید گنجه با توجه به این ابعاد، خودش لاکر مناسب را اختصاص دهد، از سرویس automatic-packing استفاده کنید. همچنین در صورتی که می‌خواهید از سرویس گنجدار استفاده کنید، باید از روش no-packing استفاده کنید.

موارد مشترک بین ریکوئست وب سرویس‌های رزرو​

هر دو API باید با متد POST و همراه با توکن معتبر فراخوانی شوند. همچنین در ادامه توضیح فیلدهای مشترک بین این دو API را در ادامه می‌آوریم. فیلد‌های اجباری با (*) مشخص می‌شوند.

  • station(*): در این فیلد باید uuid گنجه یا گنجدار مدنظر قرار گیرد.
  • time_scope_date: در صورتی که می‌خواهید سفارش برای بازه‌ی زمانی کاری پیش‌فرض گنجه رزرو شود، این فیلد را به صورت زیر ارسال کنید.
"time_scope_date": {
   "expected_check_in_date": "2024-10-31",
   "expected_check_out_date": "2024-10-31"
}

که در آن expected_check_in_date تاریخ ورود سفارش به گنجه و expected_check_out_date تاریخ مهلت برداشت سفارش از گنجه است. در صورتی که می‌خواهید سفارش برای یک بازه‌ی یک روزه رزرو شود، این دو تاریخ باید یکسان باشند.

  • time_scope: در صورتی که می‌خواهید سفارش برای یک بازه‌ی زمانی دلخواه رزرو شود، این فیلد را به صورت زیر ارسال کنید.
"time_scope": {
   "expected_check_in": "2024-10-31 14:30:00",
   "expected_duration": "1 08:00:00"
}

که در آن expected_check_in تاریخ و ساعت شروع رزرو و expected_duration مهلت برداشت سفارش از گنجه است. لازم به ذکر است که expected_duration می‌تواند بر حسب ثانیه و یا به فرمت D HH:MM:SS باشد.

نکته: وجود دقیقا یکی از فیلد‌های time_scope_date و time_scope در درخواست شما الزامی است.

  • package(*): در این فیلد مشخصات سفارش قرار می‌گیرد اما با توجه به نوع API مدنظر، ساختار متفاوتی باید داشته باشد که در توضیحات مربوط به هر API به آن پرداخته می‌شود.
  • process(*): نام سرویس مورد نظر که در بخش رزرو سفارش مربوط به هر سرویس مشخص شده است.
  • logistic_company: در این فیلد باید uuid شرکتی که ارسال سفارش توسط آن انجام می‌شود، قرار گیرد.
  • picker: شماره‌ی تلفن همراه گیرنده‌ی سفارش
  • dropper: شماره‌ی تلفن همراه تحویل‌دهنده‌ی سفارش
  • password: کد تحویلی که گیرنده با استفاده از آن می‌تواند سفارش را تحویل بگیرد. (به صورت عددی و حداکثر ۵ رقم)
  • picker_full_name: نام و نام خانوادگی گیرنده‌ی سفارش

وب سرویس رزرو no-packing​

همان‌طور که اشاره شد، مورد متفاوت در این API فیلد package است. این فیلد باید به صورت زیر ارسال شود:

"package": {
    "external_id": "string",
    "parcels": [
        {
            "external_id": "string"
        }
    ],
    "shop": "string"
}

در ادامه توضیح مربوط به هر کدام از فیلدها آمده است:

  • external_id(*): شناسه‌ی مرسوله در سرویس تامین‌کننده
  • shop: در صورتی که تامین‌کننده، سفارش‌های مربوط به فروشگاه‌های متفاوتی را ارسال می‌کند، می‌توانید در این فیلد نام فروشگاه را مشخص کنید.
  • parcels(*): در این فیلد آرایه‌ای از مشخصات بسته‌های مربوط به این مرسوله، می‌آید. مشخصات هر بسته شامل موارد زیر است:
    • external_id(*): شناسه‌ی بسته در سرویس تامین‌کننده

خلاصۀ این اندپوینت به شرح زیر است:

POST/v1.1/hub-management/occupancies/reserve/no-packing/flexible-time-scope
نیاز به احراز هویت

Request Body​

{
 "station": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "time_scope_date": {
   "expected_check_in_date": "2024-10-31",
   "expected_check_out_date": "2024-10-31"
 },
 "package": {
   "external_id": "Example1",
   "parcels": [
      {
        "external_id": "Example1_1"
      }
    ]
   "shop": "string"
 },
 "process": "manual_lastmile",
 "logistic_company": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "picker": "+989120000000",
 "password": "12345",
 "picker_full_name": "علی محمدی"
}

Response Body​

{
 "pk": 10000,
 "uuid": "c82de21f-19b0-477e-a489-3705a6e04da9",
 "verbose_id": null,
 "status": "Reserved",
 "process": "manual_lastmile",
 "station": {
   "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "address": "آدرس گنجه",
   "location": null,
   "nickname": "نام گنجه",
   "postal_code": null,
   "images": [],
   "districts": []
 },
 "dates": {
   "time_scope": {
     "expected_check_in": "2024-10-31 08:00:00",
     "expected_duration": "10:00:00"
   },
   "order_date": "2024-10-31 09:35:24",
   "check_in": null,
   "check_out": null,
   "cancel_date": null,
   "extend_date": null
 }
}

وب سرویس رزرو manual-packing​

همان‌طور که اشاره شد، مورد متفاوت در این API فیلد package است. این فیلد باید به صورت زیر ارسال شود:

"package": {
   "external_id": "string",
   "packs": [
     {
       "size": "small",
       "parcels": [
         {
           "external_id": "string",
           "weight": 0,
           "value": 0,
           "content": "string"
         }
       ]
     }
   ],
   "shop": "string"
 }

در ادامه توضیح مربوط به هر کدام از فیلدها آمده است:

  • external_id(*): شناسه‌ی مرسوله در سرویس تامین‌کننده
  • shop: در صورتی که تامین‌کننده، سفارش‌های مربوط به فروشگاه‌های متفاوتی را ارسال می‌کند، می‌توانید در این فیلد نام فروشگاه را مشخص کنید.
  • packs(*): در این فیلد باید نحوه‌ی قرارگیری هر کدام از بسته‌های موجود در مرسوله را به صورت زیر مشخص کنید. مقدار این فیلد باید آرایه‌ای از آیتم‌هایی به صورت زیر باشد:
{
 "size": "small",
 "parcels": [
   {
     "external_id": "string",
     "weight": 0,
     "value": 0,
     "content": "string"
   }
 ]
}

که در آن size، سایز لاکر مدنظر است. همچنین parcels آرایه‌ای از مشخصات بسته‌های مربوط به این آیتم است که باید به صورت زیر باشد:

{
 "external_id": "string",
 "weight": 0,
 "value": 0,
 "content": "string"
}

که در آن توضیح هر فیلد مطابق زیر است:

  • external_id(*): شناسه‌ی بسته در سرویس تامین‌کننده
  • weight: وزن بسته بر حسب گرم
  • value: ارزش بسته بر حسب ریال
  • content: محتویات بسته

توضیح تکمیلی: هر مرسوله (که متعلق به یک گیرنده است) می‌تواند شامل چندین بسته باشد که در این API شما باید مشخص کنید که کدام ترکیب از بسته‌ها در کدام سایز لاکر قرار گیرد. برای مثال مرسوله‌ای را در نظر بگیرید که شامل ۵ بسته است. با توجه به ابعاد بسته‌ها، شما تشخیص می‌دهید که بسته‌ی ۱ باید به تنهایی در لاکر large قرار گیرد، بسته‌های ۲ و ۳ در لاکر medium قرار گیرند و بسته‌‌های ۴ و ۵ در یک لاکر medium دیگر. در این صورت مقدار فیلد package باید به صورت زیر باشد:

{
 "external_id": "Test1234",
 "packs": [
   {
     "size": "large",
     "parcels": [
       {
         "external_id": "Test1234_1"
       }
     ]
   },
   {
     "size": "medium",
     "parcels": [
       {
         "external_id": "Test1234_2"
       },
       {
         "external_id": "Test1234_3"
       }
     ]
   },
   {
     "size": "medium",
     "parcels": [
       {
         "external_id": "Test1234_4"
       },
       {
         "external_id": "Test1234_5"
       }
     ]
   }
 ]
}

خلاصۀ این اندپوینت به شرح زیر است:

POST/v1.1/hub-management/occupancies/reserve/manual-packing/flexible-time-scope
نیاز به احراز هویت

Request Body​

{
 "station": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "time_scope_date": {
   "expected_check_in_date": "2024-10-31",
   "expected_check_out_date": "2024-10-31"
 },
 "package": {
   "external_id": "Example1",
   "packs": [
     {
       "size": "small",
       "parcels": [
         {
           "external_id": "Example1_1",
           "weight": 250,
           "value": 100000
         }
       ]
     }
   ],
   "shop": "string"
 },
 "process": "lastmile",
 "logistic_company": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "picker": "+989120000000",
 "password": "12345",
 "picker_full_name": "علی محمدی"
}

Response Body​

{
 "pk": 10000,
 "uuid": "c82de21f-19b0-477e-a489-3705a6e04da9",
 "verbose_id": null,
 "status": "Reserved",
 "process": "lastmile",
 "station": {
   "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "address": "آدرس گنجه",
   "location": null,
   "nickname": "نام گنجه",
   "postal_code": null,
   "images": [],
   "districts": []
 },
 "dates": {
   "time_scope": {
     "expected_check_in": "2024-10-31 08:00:00",
     "expected_duration": "10:00:00"
   },
   "order_date": "2024-10-31 09:35:24",
   "check_in": null,
   "check_out": null,
   "cancel_date": null,
   "extend_date": null
 }
}

وب سرویس رزرو automatic-packing​

همان‌طور که اشاره شد، مورد متفاوت در این API فیلد package است. این فیلد باید به صورت زیر ارسال شود:

"package": {
 "parcels": [
   {
     "external_id": "string",
     "dimension": {
       "width": 0,
       "height": 0,
       "length": 0
     }
   }
 ],
 "external_id": "string",
 "shop": "string"
}

در ادامه توضیح مربوط به هر کدام از فیلدها آمده است:

  • external_id(*): شناسه‌ی مرسوله در سرویس تامین‌کننده
  • shop: در صورتی که تامین‌کننده، سفارش‌های مربوط به فروشگاه‌های متفاوتی را ارسال می‌کند، می‌توانید در این فیلد نام فروشگاه را مشخص کنید.
  • parcels(*): در این فیلد آرایه‌ای از مشخصات بسته‌های مربوط به این مرسوله، می‌آید. مشخصات هر بسته شامل موارد زیر است:
    • external_id(*): شناسه‌ی بسته در سرویس تامین‌کننده
    • dimension(*): ابعاد بسته در این قسمت مشخص می‌شود که شامل (*)width(عرض)، (*)height(ارتفاع) و (*)length(طول) است. این ابعاد باید بر حسب متر مشخص شود.

خلاصۀ این اندپوینت به شرح زیر است:

POST/v1.1/hub-management/occupancies/reserve/automatic-packing/flexible-time-scope
نیاز به احراز هویت

Request Body​

{
 "station": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "time_scope_date": {
   "expected_check_in_date": "2024-10-31",
   "expected_check_out_date": "2024-10-31"
 },
 "package": {
   "parcels": [
     {
       "external_id": "Example2_1",
       "dimension": {
         "width": 0.1,
         "height": 0.25,
         "length": 0.15
       }
     }
   ],
   "external_id": "Example2"
 },
 "process": "lastmile",
 "logistic_company": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "picker": "+989120000000",
 "password": "12345",
 "picker_full_name": "علی محمدی"
}

Response Body​

{
 "pk": 10000,
 "uuid": "c82de21f-19b0-477e-a489-3705a6e04da9",
 "verbose_id": null,
 "status": "Reserved",
 "process": "lastmile",
 "station": {
   "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "address": "آدرس گنجه",
   "location": null,
   "nickname": "نام گنجه",
   "postal_code": null,
   "images": [],
   "districts": []
 },
 "dates": {
   "time_scope": {
     "expected_check_in": "2024-10-31 08:00:00",
     "expected_duration": "10:00:00"
   },
   "order_date": "2024-10-31 09:35:24",
   "check_in": null,
   "check_out": null,
   "cancel_date": null,
   "extend_date": null
 }
}

موارد مشترک بین ریسپانس وب سرویس‌های رزرو​

حالت‌های موفق​

در صورت موفقیت‌آمیز بودن، پاسخ وب سرویس با status code 201 مطابق زیر خواهد بود:

{
 "pk": 10000,
 "uuid": "c82de21f-19b0-477e-a489-3705a6e04da9",
 "verbose_id": null,
 "status": "Reserved",
 "process": "lastmile",
 "station": {
   "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "address": "آدرس گنجه",
   "location": null,
   "nickname": "نام گنجه",
   "postal_code": null,
   "images": [],
   "districts": []
 },
 "dates": {
   "time_scope": {
     "expected_check_in": "2024-10-31 08:00:00",
     "expected_duration": "10:00:00"
   },
   "order_date": "2024-10-31 09:35:24",
   "check_in": null,
   "check_out": null,
   "cancel_date": null,
   "extend_date": null
 }
}

در این شرایط، سه حالت ممکن است اتفاق بیفتد:

  1. در صورتی که رزرو به صورت کامل و موفقیت‌آمیز انجام شود، مقدار فیلد status برابر با Reserved خواهد بود.
  2. در صورتی که ظرفیت گنجه برای سایز مورد نظر تکمیل باشد، مقدار فیلد status برابر با In Queue خواهد بود.
  3. در حالت automatic-packing، در صورتی که ابعاد ارائه شده برای بسته‌ها، مناسب جایگذاری در گنجه نباشد، مقدار فیلد status برابر با Not Packed خواهد بود.

حالت‌های خطا​

  • uuid گنجه صحیح نباشد: status code = 400
{
 "station": [
   "Station does not exist."
 ]
}
  • uuid شرکت لجستیک صحیح نباشد: status code = 400
{
 "logistic_company": [
   "Logistic Company with uuid 3fa85f64-5717-4562-b3fc-2c963f66afa6 does not exist"
 ]
}
  • فرمت شماره تلفن گیرنده صحیح نباشد: status code = 400
{
 "picker": [
   "Enter a valid phone number."
 ]
}
  • فرمت کد تحویل صحیح نباشد: status code = 400
{
 "password": [
   "Password must be 5 characters long and only contains digit."
 ]
}
  • هیچ کدام از فیلدهای time_scope و time_scope_date در درخواست نباشد: status code = 400
{
 "time_scope": "time_scope or time_scope_date should be specified"
}
  • تاریخ داده شده در فیلد time_scope_date در روزهای کاری گنجه انتخاب شده نباشد: status code = 400
{
 "time_scope": "Invalid for this station"
}
  • برای external_id داده شده، سفارش فعالی از قبل برای شما وجود داشته باشد: status code = 400
{
 "non_field_error": [
   "This package already has an active lastmile occupancy"
 ]
}