Creating/Modifying Orders

📘
Changes from V1
If coming from V1 API, stateStarted has been changed to stateChanged in order to clarify when the state has been changed rather than "started" which is also a state.
In addition, an order will now be created even if there isn't a tracker to bind to. From there, the only way to clear this order is by manually invoking DELETE /api/v2/activeorders/{number|uuid} where {number|uuid} is either the order number or unique identifier.

📘
ON_PREMISE vs ON_PREMISES
In v1, ON_PREMISE was used to define the order type; however, the correct term is ON_PREMISES in relation to a place rather than an idea or point. To allow compatibility and because it is easy to look over such difference, ON_PREMISE and ON_PREMISES are both valid values when creating an order.

POST /api/v2/activeorders [SECURED]

Start or locate an active order. POST data should be in JSON.

Body Parameters

Name	Description	Type	Details
name	Order identifier.	string	MUST be a string of digits.
orderType	Order type.	enum	Valid values: ON_PREMISE(S) TO_GO
locationName	Identifier of where the order will be located. (i.e. Usually a table number)	string, optional	MUST be a string of digits.

📘
Located Order vs Started Order
If locationName is set in request, then the resulting state, if successful, will be "located" as the order was created with a table in mind. Otherwise, if the order does not yet have a table assigned, it should be left out of the request. The state will remain as "started" until the customer brings their tracker to a table which would change the state to "located" and assign a location number.

Example Request

// Start Order 66 (POST http://[TT LAN IP]:8000/api/v1/activeorders)
// Using jQuery

$.ajax({
    url: "http://[TT LAN IP]:8000/api/v1/activeorders",
    type: "POST",
    headers:{
        "Authorization":"Bearer 2f1f4339c7b77fa3474bf8ba8852349273e928bb8ad9d186",
        "Content-Type":"application/json",
    },
    contentType:"application/json",
    data:JSON.stringify({
        "name": "66",
        "orderType": "ON_PREMISES"
    })
})
.done(function(data, textStatus, jqXHR) {
    console.log("HTTP Request Succeeded: " + jqXHR.status);
    console.log(data);
})
.fail(function(jqXHR, textStatus, errorThrown) {
    console.log("HTTP Request Failed");
})
.always(function() {
    /* ... */
});

import java.io.IOException;
import org.apache.http.client.fluent.*;
import org.apache.http.entity.ContentType;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }
  
  private static void sendRequest() {
    
    // Start Order 66 (POST )
    
    try {
      
      // Create request
      Content content = Request.Post("http://[TT LAN IP]:8000/api/v1/activeorders")
      
      // Add headers
      .addHeader("Authorization", "Bearer 2f1f4339c7b77fa3474bf8ba8852349273e928bb8ad9d186")
      .addHeader("Content-Type", "application/json")
      
      // Add body
      .bodyString("{\"name\": \"66\",\"orderType\": \"ON_PREMISES\"}", ContentType.APPLICATION_JSON)
      
      // Fetch request and return content
      .execute().returnContent();
      
      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

// Start Order 66 (POST http://[TT LAN IP]:8000/api/v1/activeorders)

NSURL* URL = [NSURL URLWithString:@"http://[TT LAN IP]:8000/api/v1/activeorders"];
NSMutableURLRequest* request = [NSMutableURLRequest requestWithURL:URL];
request.HTTPMethod = @"POST";

// Headers

[request addValue:@"Bearer 2f1f4339c7b77fa3474bf8ba8852349273e928bb8ad9d186" forHTTPHeaderField:@"Authorization"];
[request addValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

// JSON Body

NSDictionary* bodyObject = @{
	@"name": @"66",
	@"orderType": @"ON_PREMISES"
};
request.HTTPBody = [NSJSONSerialization dataWithJSONObject:bodyObject options:kNilOptions error:NULL];

// Connection

NSURLConnection* connection = [NSURLConnection connectionWithRequest:request delegate:nil];
[connection start];

curl -X "POST" "http://[TT LAN IP]:8000/api/v1/activeorders" \
	-H "Authorization: Bearer 2f1f4339c7b77fa3474bf8ba8852349273e928bb8ad9d186" \
	-H "Content-Type: application/json" \
	-d "{ \"name\":\"66\", \"orderType\":\"ON_PREMISES\"}"

# Install the Python Requests library:
# `pip install requests`

import requests
import json

def send_request():
    # Start Order 66 (POST http://[TT LAN IP]:8000/api/v1/activeorders)

    try:
        r = requests.post(
            url="http://[TT LAN IP]:8000/api/v1/activeorders",
            headers = {
                "Authorization":"Bearer 2f1f4339c7b77fa3474bf8ba8852349273e928bb8ad9d186",
                "Content-Type":"application/json",
            },
            data = json.dumps({
                "name": "66",
                "orderType": "ON_PREMISES"
            })
        )
        print('Response HTTP Status Code : {status_code}'.format(status_code=r.status_code))
        print('Response HTTP Response Body : {content}'.format(content=r.content))
    except requests.exceptions.RequestException as e:
        print('HTTP Request failed')

Responses

201 Created

A newly created order that hasn't existed before can be distinguished from a modified order by it's 201 HTTP status. A Websocket notification will also be sent out with "type": "NEW_ORDER".

{
  "status": 201,
  "returnCode": 5,
  "warning": "Tracker not assigned with order.",
  "activeorder": {
    "uuid": "54ed91e6-286b-4912-b44c-7a7a3001d715",
    "created": "2014-08-25T08:09:42",
    "orderType": "ON_PREMISE",
    "locationName": "",
    "state": "started",
    "stateChanged": "2014-08-25T06:57:45",
    "name": "66",
    "paged": false,
    "elapsedTime": 0
  }
}

📘
"Tracker not assigned with order."
The warning property will appear if an order is created but a tracker is not found to bind to. This can occur if a tracker is not cleared and started before creation of order. As a result, the order may not be able to be paged. It is best to notify user in client application if this happens.

200 OK (Order modified)

If a order is modified, then the HTTP status will be 200. How to respond to this will depend on the application. In a Websocket connection, the same order will be sent with "type": "ORDER_MODIFIED"

In this example, we make the same request, but this time change the "orderType". Since the order already exists (i.e. active), the same payload will return except with the requested modifications.

In order to differentiate between a modified and newly created order, use the HTTP status code and look for the returnCode to distinguish from the following informational status messages.

{
  "status": 200,
  "returnCode": 5,
  "activeorder": {
    "uuid": "54ed91e6-286b-4912-b44c-7a7a3001d715",
    "created": "2014-08-25T08:09:42",
    "orderType": "TO_GO",
    "locationName": "",
    "state": "started",
    "stateChanged": "2014-08-25T06:57:45",
    "name": "66",
    "paged": false,
    "elapsedTime": 0
  }
}

200 OK (Order Already Started)

Returns if order has already been started.

{
  "status": 200,
  "returnCode": 1009,
  "message": "Order already started."
}

200 OK (Order Already Located)

Returns if order has already been located.

{
  "status": 200,
  "returnCode": 1010,
  "message": "Order already located."
}

400 Bad Request (Missing Order Name)

Returns if required order name is missing.

{
  "status": 400,
  "message": "Missing order name. Must be a positive integer.",
  "returnCode": -8
}

400 Bad Request (Invalid Order Name)

Returns if order name exists but not a valid positive integer.

{
  "status": 400,
  "message": "Invalid order name. Must be a positive integer.",
  "returnCode": -9
}

400 Bad Request (Invalid Location Name)

Returns in optional location name is not a valid integer.

{
  "status": 400,
  "message": "Invalid location name. Must be a positive integer.",
  "returnCode": -10
}

400 Bad Request (Order Type Missing)

Returns if order type is missing from request.

{
  "status": 400,
  "message": "Order type missing from request. Must be either TO_GO or ON_PREMISES.",
  "returnCode": -11
}

400 Bad Request (Invalid Order Type)

Returns if order type is invalid.

{
  "status": 400,
  "message": "Order type invalid. Must be either TO_GO or ON_PREMISES.",
  "returnCode": -12
}

Note:

To facilitate testing the API, a special query parameter named dummy_tracker_address can be included. Trackers have an address and it is captured when a tracker is started via a "starter" unit. Tracker addresses are saved by the gateway, so this only needs to be done once.

Example:

http://10.0.1.2:8000/api/v1/activeorders?dummy_tracker_address=true

In production, this parameter would NEVER be used.

Creating/Modifying Orders

📘
Changes from V1

📘
ON_PREMISE vs ON_PREMISES

POST /api/v2/activeorders [SECURED]

Body Parameters

📘
Located Order vs Started Order

Example Request

Responses

201 Created

📘
"Tracker not assigned with order."

200 OK (Order modified)

200 OK (Order Already Started)

200 OK (Order Already Located)

400 Bad Request (Missing Order Name)

400 Bad Request (Invalid Order Name)

400 Bad Request (Invalid Location Name)

400 Bad Request (Order Type Missing)

400 Bad Request (Invalid Order Type)

Note:

Example:

📘Changes from V1

📘ON_PREMISE vs ON_PREMISES

POST /api/v2/activeorders [SECURED]

Body Parameters

📘Located Order vs Started Order

Example Request

Responses

201 Created

📘"Tracker not assigned with order."

200 OK (Order modified)

200 OK (Order Already Started)

200 OK (Order Already Located)

400 Bad Request (Missing Order Name)

400 Bad Request (Invalid Order Name)

400 Bad Request (Invalid Location Name)

400 Bad Request (Order Type Missing)

400 Bad Request (Invalid Order Type)

Note:

Example:

📘
Changes from V1

📘
ON_PREMISE vs ON_PREMISES

📘
Located Order vs Started Order

📘
"Tracker not assigned with order."