رزرو سفارش

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

• 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
 }
}

رزرو به صورت ناشناس (بدون شماره تلفن)

در این نوع از رزرو، رزرو به صورت ناشناس و بدون اطلاعات شخصی مانند شماره تلفن، نام و نام خانوادگی برای گیرنده (‍picker) انجام می‌شود و با عنوان with anonymous picker شناخته می‌شود. در این نوع از رزرو نیازی به ارسال اطلاعات گیرنده مانند شماره تلفن نیست. در Response فراخوانی رزرو‌های ناشناس یک لینک با عنوان pickup_url‍ بازگردانده می‌شود که کاربر با ورود این لینک می‌تواند به وب‌اپ وارد شده و بسته‌ خود را مشاهده کرده و فرایند برداشتن بسته را طی کند. همانطور‌ که برای فرایند رزرو عادی سه روش بسته‌بندی دارد، این نوع از رزرو نیست شامل همان سه دسته نوع بسته‌بندی زیر است که توضیحات آن‌ها کاملا به مانند رزرو عادی است:

• no-packing
• manual-packing
• automatic-packing

برای هر کدام از این نوع از بسته‌بندی‌ها برای رزرو ناشناس یک API در نظر گرفته‌ شده است. این APIها کاملا به صورت مشابه با APIهای متناظر در رزرو عادی عمل می‌کنند. به‌طور مثال API رزرو no-packing در رزرو عادی و رزرو به صورت ناشناس داده‌های مشابه دریافت می‌کنند و فرمت خروجی مشابه دارند. تنها تفاوت در این است که picker و password نباید به‌عنوان داده ورودی در request body ارسال شود. همچنین در پاسخ  API، پراپرتی pickup_url که شامل لینک کاربر برای ورود به وب‌اپ و برداشتن بسته است نیز ارسال می‌شود. این API ها به صورت زیر هستند:

وب سرویس رزرو ناشناس no-packing

این API به صورت کاملا مشابه با no-packing در رزرو عادی عمل می‌کند. تمامی داده‌های ورودی و خروجی، خطا‌ها و status code‌ها یکسان است، فقط در ورودی picker دریافت نمی‌شود و در خروجی نیز picker_url ارسال می‌شود. فرمت خروجی این اندپوینت به صورت زیر است:

POST/v1.1/hub-management/occupancies/reserve/no-packing/flexible-time-scope/with-anonymous-picker

نیاز به احراز هویت

Request Body

{
  "station": "ff64cc6c-ecda-4980-bf83-76f8793804db",
  "time_scope": {
    "expected_check_in": "2025-04-12T12:29:03.902Z",
    "expected_duration": "23:00:00"
  },
  "package": {
    "parcels": [
      {
        "external_id": "313131"
      }
     ],
    "external_id": "313131"
  },
  "process": "manual_lastmile",
}

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
  },
  "pickup_url": "https://app.dev.ganje.net/ext/O3vzYW_IQ_e-wvzMIfb60g"
}

وب سرویس رزرو ناشناس manual-packing

این API به صورت کاملا مشابه با manual-packing در رزرو عادی عمل می‌کند. تمامی داده‌های ورودی و خروجی، خطا‌ها و status code‌ها یکسان است، فقط در ورودی picker دریافت نمی‌شود و در خروجی نیز picker_url ارسال می‌شود.‍‍ نمونه‌ای از ‍‍‍Response Body دریافتی از این API به صورت زیر است:

POST/v1.1/hub-management/occupancies/reserve/manual-packing/flexible-time-scope/with-anonymous-picker

نیاز به احراز هویت

Request Body

{
  "station": "309b55cd-fbad-4c34-88b5-ad1def041a14",
  "time_scope": {
    "expected_check_in": "2025-04-17T10:30:17.206Z",
    "expected_duration": "23:00:00"
  },
  "package": {
    "external_id": "12312",
    "packs": [
      {
        "size": "small",
        "parcels": [
          {
            "external_id": "32132",
            "weight": 0,
            "value": 0,
            "content": "test content"
          }
        ]
      }
    ],
    "extra_information": {}
  },
  "process": "lastmile",
}

Response Body

{
  "pk": 89,
  "uuid": "f2ca657c-4637-48bc-b9ef-a5541b6ec4dc",
  "verbose_id": null,
  "status": "Reserved",
  "process": "lastmile",
  "station": {
    "uuid": "a8e647f0-29cd-4e27-ae3d-cb70025cff3f",
    "address": null,
    "location": null,
    "nickname": "test_station_3",
    "postal_code": null,
    "images": [],
    "districts": []
  },
  "dates": {
    "time_scope": {
      "expected_check_in": "2025-04-17 14:00:17",
      "expected_duration": "0 23:00:00"
    },
    "order_date": "2025-04-20 06:37:56",
    "check_in": null,
    "check_out": null,
    "cancel_date": null,
    "extend_date": null
  },
  "pickup_url": "https://app.dev.ganje.net/ext/O3vzYW_IQ_e-wvzMIfb60g"
}

وب سرویس رزرو ناشناس automatic-packing

این API به صورت کاملا مشابه با automatic-packing در رزرو عادی عمل می‌کند. تمامی داده‌های ورودی و خروجی، خطا‌ها و status code‌ها یکسان است، فقط در ورودی picker دریافت نمی‌شود و در خروجی نیز picker_url ارسال می‌شود. فرمت خروجی این اندپوینت به صورت زیر است:

POST/v1.1/hub-management/occupancies/reserve/automatic-packing/flexible-time-scope/with-anonymous-picker

نیاز به احراز هویت

Request Body

{
  "station": "309b55cd-fbad-4c34-88b5-ad1def041a14",
  "time_scope": {
    "expected_check_in": "2025-04-12T12:29:03.902Z",
    "expected_duration": "23:00:00"
  },
  "package": {
    "parcels": [
      {
        "external_id": "313131",
        "dimension": {
          "width": 0,
          "height": 0,
          "length": 0
        }
      }
    ],
    "external_id": "313131"
  },
  "process": "lastmile",
}

Response Body

{
  "pk": 88,
  "uuid": "5cdb5ac1-6efc-4ed5-a548-641429a999af",
  "verbose_id": null,
  "status": "Reserved",
  "process": "lastmile",
  "station": {
    "uuid": "a8e647f0-29cd-4e27-ae3d-cb70025cff3f",
    "address": null,
    "location": null,
    "nickname": "test_station_3",
    "postal_code": null,
    "images": [],
    "districts": []
  },
  "dates": {
    "time_scope": {
      "expected_check_in": "2025-04-19 15:59:03",
      "expected_duration": "0 23:00:00"
    },
    "order_date": "2025-04-20 06:36:13",
    "check_in": null,
    "check_out": null,
    "cancel_date": null,
    "extend_date": null
  },
  "pickup_url": "https://app.dev.ganje.net/ext/ifJIIrCJQMSrMiWY3h_JXQ"
}

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

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

در صورت موفقیت‌آمیز بودن، پاسخ وب سرویس با 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"
 ]
}