Reservation Plugin

The present document introduces the Ganje Reservation Plugin service and explains its technical, user, and operational utilization by online stores. This document explains the simplest solution in terms of the technical development required for an online store, which is why it is referred to as a general service.

User and Operational Processes

The Ganje public service is placed as a delivery method on the checkout page of online stores' shopping carts. When a customer places an order in the store, they will see this option. By selecting it, a window containing information about the Ganje service opens, allowing the user to submit their request without leaving the online store or navigating to a separate page.

Initially, to familiarize themselves with the service, its functionality, and its benefits, the user will view some introductory information. Then, they will see a list of lockers (along with their working hours and neighborhood). After selecting a locker, the available slots will be displayed, and the user can choose their preferred day from the available options to receive their order.

After confirming the information, a request is registered in the locker, and the user continues with the remaining steps of their purchase process in the online store.

On the specified day and date, the store's courier can visit the locker and scan the QR code on it to place the user's order inside the locker. After the locker door is closed, a text message is automatically sent to the user from Ganje, notifying them that their order has been placed. After receiving the message, the user can visit the locker, use the link provided in the SMS, and scan the QR code on the locker to open the door and retrieve their order.

Operational Notes

Each customer can register only one request in the locker for each order.
If the user does not retrieve their order within 24 hours, the order will be marked as "returned," and the store's courier must visit the locker to collect it.
To expedite and simplify the connection between online stores and the lockers, order reports and related processes are handled through the Ganje user panel and the operations team.
Operational issues are resolved by the Ganje support team.

Necessary Actions for Technical Development

Adding the "Send via Ganje" option
Sending a request to register a pre-order
Redirecting the user to the link sent in the previous request's response (modal on the website)

APIs Used

All available APIs are authenticated via JWT token. You can obtain the token using your username and password from the following web service:

POST/v1.1/account/jwt/create/

Request Body

{
  "username": "username",
  "password": "1234"
}

Response

{
  "refresh": "string",
  "access": "string",
  "pk": 0,
  "uuid": "string",
  "expire_duration": 0,
  "expires_at": "date-time"
}

API Response Codes

Status Code	Description
`200`	return access and refresh tokens
`401`	Invalid username or password

After receiving the token from the API above, include it in the header of the remaining APIs as follows to authenticate the requests:

headers: {
  authorization: "Bearer <access_token>"
}

The only essential API required to use the public service is as follows:

POST/v1.1/hub-management/occupancies/pre-order

🛠 Request Params

key	Type	Description
phone_number	`string` in this format: "+98xxxxxxxxxx"	The mobile number of the parcel picker.
external_id	`string`	A unique ID in the store's system, which could be the package number, order number, or any other identifier that distinguishes this order.

Request Body

{
  "phone_number": "+989111111111",
  "external_id": "external_id"
}

🛠 Response Params

key	Type	Description
order_link	`string`	The link that the user should be redirected to in order to complete the rest of the order registration process in Ganje.

Response

{
  "order_link": "Ganje reserve plugin url"
}

Scripts Used on the Front-End

After receiving the order_link key, simply use it through the Ganje reservation plugin to guide the user into the process of selecting a locker and reserving a specific time slot.

All web applications that use JavaScript for their development can utilize this service. The usage and setup of this service have been designed in a way that requires minimal development, with all user processes implemented by the Ganje service.

How to Use:

To install the required scripts and styles for the Ganje reservation service, simply add them to the plugin's usage location via the following CDN:

<script src="https://cdn.jsdelivr.net/gh/GanjeCo/reserve-plugin/index.js"></script>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/gh/GanjeCo/reserve-plugin/style.css"
/>

To use and invoke the plugin, simply execute the following function. For example, you can call this function on the desired onClick event as follows:

<script>
  openGanjeDelivery(url, returnSelectedGanje);
</script>

Input Parameters:

The openGanjeDelivery function has two input parameters, which are as follows:

Parameter	Type	Description
url	`string`	The order_link URL, which has been provided to the developer through the previously mentioned web service.
returnSelectedGanje	`object`	A callback function that returns the locker information, capacity, and the time selected by the user.

The output parameters of the `returnSelectedGanje` function are as follows:

The returnSelectedGanje function, after the locker and time reservation is completed by the user, returns the following value as a JSON:

{
  "selectedStation": {
    "uuid": "station uuid",
    "nickname": "station name",
    "address": "station string address",
    "location": "station location in lat-lng format"
  },
  "selectedTimeScope": {
    "expected_check_in": "reserve time selected by user",
    "expected_duration": "duration to pickup parcel"
  }
}