Integrate With GonnaOrder Admin API

The GonnaOrder Admin API is the entry point that allows third-party applications to interact with GonnaOrder stores to fetch order information. Restaurants and developers can use the API to create integrations for their POS systems and develop customized order notification apps.

Restaurant and store managers should ask their developers or POS providers to read and follow these guidelines.

On This Page

• Considerations When Using GonnaOrder Admin API
• How the API Works
• Application Authentication
• Get Order Details
• List All Orders by Status
• Download 80 MM Order Receipt
• Searching Orders
• HTTP Status Codes

Considerations When Using Gonnaorder Admin API

• GonnaOrder continually adds features and settings to stores. Therefore, you may need to revise your application to accommodate functionalities released in the future.
• Developers must request access to the API from GonnaOrder. Every application requires authorization; therefore, you must get an access token before starting your development. You can send your request email to support@gonnaorder.com. Alternatively, you may use your GonnaOrder account to access the API. In that case, you need to log in to GonnaOrder to receive order events.
• You are required to use the API responsibly and uphold the privacy of GonnaOrder store users. You may not access stores you or your client do not operate.

How the API Works

1. A customer places an order via a GonnaOrder website or app
2. The store confirms the order and optionally provides an estimated time, or the store rejects the order and optionally provides a reason for the rejection
3. GonnaOrder sends an order event to your application
4. Your application interprets and processes the event

With the GonnaOrder admin API, there are five key things you can achieve for a selected store:

• Get order details using the uuid
• Download 80mm order receipt: For all orders – except draft orders, you can download the order receipt generated by the store and print it from the API.
• Get the full list of orders in a selected store: Using the store ID, you can fetch all orders in a store.
• List orders by status: you can get orders with a specific status e.g., submitted, closed, or canceled.
• Search orders: choose from 17 search parameters to filter orders.

Application Authentication

Authenticate With a Username and Password

This is a case where the developer is the store owner or has the explicit permission of the owner to log in to the selected store with a username and password.

To log in to a store, you must pass a username and password to the login API. These are the same login credentials that you use for your GonnaOrder account. The GonnaOrder user account must have access to the store you would like to access.

{
	"username":"user",
	"password":"xxxxxx"
}

The login API will send a response in which there will be a JWT token and a refresh token that is accessible as tokens.jwt and tokens.refreshToken respectively. You need to pass tokens.jwt in the authorization header of your application.

Authenticate With a Fixed Access Token

This method allows your application to stay logged into the selected GonnaOrder store the whole time. It is not dependent on sessions but rather on the store. You must contact GonnaOrder to request a fixed token.

Regardless of the authentication method used in the application, the access token is used in the same way in the authorization header.

« Authorization »: « Bearer {ACCESS_TOKEN} »

Get Order Details

As earlier mentioned, you can get the details of an order using the order uuid sent to your application in the order event. You do not need authorization for this functionality, but you must pass the store ID and the order uuid to the order API.

The GonnaOrder API will then respond with a payload including all order details.

Notice that the order items are presented in an array in the payload, and that’s how they should be accessed.

Dealing With Child Order Items

An order item may contain child items. For example, an offer of Black coffee may have different types as child items, while Pizza may have different sizes as the child items. Child items are included in the order as childOrderItems array that contains JSON objects.
The fields of a child item are similar to those of the main product. However, it is easy to differentiate the two using the hierarchyLevel field where a child item has value CHILD and the main item has value PARENT.

Download 80 MM Order Receipt

You can call the orders API to download an order receipt as a pdf or image. For this, you need to pass the store ID and the order UUID. Additionally, this call must include the authorization header.

Again, you do not need to enclose the store ID or the order UUID in curly braces. Further, notice that the API URL has a variable toImage. When set to true, the order receipt is converted to an image before being downloaded. The default value is false, and the receipt is downloaded in PDF format.

List All Orders by Status

GonnaOrder Admin API allows you to fetch the list of orders with a particular status. There are five possible statuses for orders: DRAFT, SUBMITTED, RECEIVED, CLOSED, or CANCELLED. Besides the order status, your API call must also specify a store ID and the page number.
This API call requires the authorization header.

The payload for this call has four elements:

• totalPages: The total number of pages of orders with the selected status at the time of the call.
• totalElements: The total number of orders with the selected status.
• pageNumber: numeric identifier of the current page.
• pageSize: The number of elements included in a single page.
• data: This is an array comprising of multiple dictionaries where each each dictionary represents an order.

Searching Orders

Searching orders is important when you need some of the specific order details. The API call for searching orders must identify the store where the search is conducted and the page number. Note that this API requires an authorization header.

There are various search options you may combine to narrow down your search.

• customerName : String– name of the customer placing the order.
• status : List– the order status. It can be DRAFT, SUBMITTED, RECEIVED, CLOSED, or CANCELLED.
• wishTimeFrom : Instant– the wish time at which order should be fulfilled.
• relativeWishTimeFrom : Integer– relative wish time in minutes from current time in past.
• wishTimeTo : Instant– the wish till which orders are required.
• relativeWishTimeTo : Integer– relative wish time in minutes from current time in future.
• isReady : Boolean– used to search ready or non-ready orders.
• createdAtFrom : Instant– the order creation from which orders are required.
• relativeCreatedAtFrom : Integer– relative order creation time in minutes from current time in past.
• createdAtTo : Instant– The order creation till which orders are required.
• relativeCreatedAtTo : Integer– Relative order creation time in minutes from current time in future.
• estimatedTimeFrom : Instant– The order estimated time from which orders are required.
• relativeEstimatedTimeFrom : Integer– Relative order estimated time in minutes from current time in past.
• estimatedTimeTo : Instant– The order estimated time till which orders are required.
• relativeEstimatedTimeTo : Integer– Relative order estimated time in minutes from current time in future.
• deliveryMethod : List– The delivery method. The in-store, pickup, and address delivery methods will be IN_STORE_LOCATION, NO_LOCATION, and ADDRESS, respectively.
• orderToken : String– The order token.
• storeId : Long– The unique identifier of the store.
• storeIdList : List– A list of store IDs to search orders across multiple stores.
• effectiveTimeFrom : Instant– The effective time from which orders are required..
• relativeEffectiveTimeFrom : Integer – Relative effective time in minutes from current time in past.
• effectiveTimeTo : Integer – Relative effective time in minutes from current time in future.
• locationId : Long – The unique identifier of the location.
• tapId : String – The tap ID associated with the order. This ID consists of exactly 14 digits..
• openTap : Boolean – Used to search for orders with an open tab.
• stationId : String – The unique identifier of the station.

The pattern for instant fields (dates) is as follows:

HTTP Status Codes

GonnaOrder Admin API sends three HTTP status codes for API calls as follows:

• 200 Ok: This is a sign that everything went well. The server received the request and if any response was being expected, it was returned.
• 400 Bad request: This can either happen if the API call has an invalid URL or if you tried creating an endpoint that is already configured.
• 401 Unauthorized: This code is returned if the authorization header has an invalid or wrong access token.