Introduction

This document may describe the ways in which particular tasks are performed to place an order to the PizzaGest platform, using various technologies as JavaScript (xmlhttprequest) or JQuery (AJAX), HTML5 or server side platforms like PHP making the request in POST HTTP, and using UTF-8 charset.

Full documentation of each service is contained within the particular developer guides for those services. However, this guide serves to hold some common practices useful for setting up your web service requests and processing your web service responses.

These web services use HTTP requests to specific URLs, passing parameters as request arguments to the services. Generally, these services return data in the HTTP response as JSON string for being processed by your application.

Get Started

A typical Web Service request is generally of the following form on POST method, replacing {Function Name} by the name of the function and parsing JSON string as parameters. The following URL must be used for all the requests:

http://s01.pav-online.com/PAV_RESTFUL/{FunctionName}
POST[data]-> JSON STRING
POST[hash]-> HASH SIGN

Get request:

http://s01.pav-online.com/PAV_RESTFUL/{FunctionName}?data=JSON_STRING&hash=HASH_SIGN

The REST architectural style was developed by W3C Technical Architecture Group (TAG) in parallel with HTTP 1.1, based on the existing design of HTTP 1.0. The World Wide Web represents the largest implementation of a system conforming to the REST architectural style.

To access to the PizzaGest API we will provide you a “Client code” and “Hash” to sign all the REQUESTS. Your client code and timestamp must be specified in all the placed requests, and also all requests should be signed with the hash.

Keep your client code and hash in a safe place and don’t publish it in your source code, because this may turn vulnerable the whole system. All requests must have these two POST parameters included.

[POST][data] : Contains all the information necessary for the request parsed in a JSON string. ClientCode, Timestamp, Function Params.

[POST][hash] : Contains the sign in SHA256 generated for each request as a Json string merged with Json string length, and signed with the hash. The line below is a PHP example to generate the hash.

hash_hmac ('SHA256',  $data_string.strlen($data_string ), $HASH)

SANDBOX_DATA: For the preproduction stage you must use the following code and hash. For the production stage we will provide new different values.

Client code: ‘KoutFood’

Hash: 285c148c9374923c3024d6ec76b7f85d6519293949f7340afe1470079de9adzz

http://s01.pav-online.com/PAV_RESTFUL/addNewTicket

[data]={"ClientCode":"KoutFood","TicketLines":[{ "ProductCode":"FGAPT0001","ProductName":"Cheesy Wedges","Quantity":1},{"ProductCode":"FGAPT2019","ProductName":"Chicken Tenders","Quantity":1}],"Email":"a.alsamman@hungerstation.com","BranchCode":"7","Phone":"0570847718","Language":"en","StreetNumber":0,"Building":" ","Staircase":"","Floor":"111","Door":"456","ExtraIndications":"The green big building","Latitude":24.6895122419451,"Longitude":46.6435074806213,"DeliveryDate":"2017-07-31 10:27:49","PayTypeCode":"1","TotalAmount":"20.0"}

[hash]="6a5ef6f75d2fcb4d67d2368d5d4e9af1810dce6dcf11028c83bf889d5610ed05"}

Get Example

http://s01.pav-online.com/PAV_RESTFUL/GetBranches?data={"ClientCode":"KoutFood","TicketLines":[{ "ProductCode":"FGAPT0001","ProductName":"Cheesy Wedges","Quantity":1},{"ProductCode":"FGAPT2019","ProductName":"Chicken Tenders","Quantity":1}],"Email":"a.alsamman@hungerstation.com","BranchCode":"7","Phone":"0570847718","Language":"en","StreetNumber":0,"Building":" ","Staircase":"","Floor":"111","Door":"456","ExtraIndications":"The green big building","Latitude":24.6895122419451,"Longitude":46.6435074806213,"DeliveryDate":"2017-07-31 10:27:49","PayTypeCode":"1","TotalAmount":"20.0"}
&hash=6a5ef6f75d2fcb4d67d2368d5d4e9af1810dce6dcf11028c83bf889d5610ed05

IMPORTANT NOTE: All requests may have “Client Code” and “Timestamp” included in the JSON String. Both parameters must be converted to string.

[data]={"ClientCode":"KoutFood","Timestamp":"1432562038"}

PHP sample code:

$client,
    "Timestamp"=> (string) $date->getTimestamp(),    
);

$json = json_encode($data);


$hash = hash_hmac('SHA256', $json . strlen($json), $pass);

 //set POST variables
$url = 'http://s01.pav-online.com/pav_restful/addNewTicket';
$fields = array(
	'data' => $json,
	'hash' => $hash,
);

//open connection
$ch = curl_init();

//set the url, number of POST vars, POST data
curl_setopt($ch,CURLOPT_RETURNTRANSFER , 1);
curl_setopt($ch,CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POST, count($fields));
curl_setopt($ch,CURLOPT_POSTFIELDS, http_build_query($fields));
curl_setopt($ch,CURLOPT_HTTPHEADER, array('Content-Type:'=> 'application/x-www-form-urlencoded', 'Content-Length:' => strlen($json), 'Charset'=>'UTF-8'));
//execute post
$res = curl_exec($ch);

print_r(json_decode($res));

 
?>

Managing Responses

Once the request is completed, the API will return a POST data as JSON string parsed with all the data you requested, then the data only needs to be parsed to an object or array to be comfortably managed.

The API returns a JSON String [response], if the request is correctly filled with all the information, and JSON String [error] with error code and message, if there was any error during the request or incorrect parameters have been included.

SAMPLE RESPONSE

{"response":[{"StreetCode":"22","StreetDirectory":"1","ZoneCode":"1","AreaCode":"2","StreetName":"GHORNATA","AreaName":"Ghornata","ZipCode":null,"CityName":"Riyadh","Province":"Riyadh","DeliveryFeeCode":"DELIVERY","DeliveryFeeAmount":"5","DeliveryFeeMaxAmount":"0","BranchCode":"2","BranchName":"Maestro Pizza (Ghornata Br)","BranchAddress":"Ghornata","BranchNumber":"271","BranchPhone":"011-2641950","OrderDeliveryMin":"75…..

SAMPLE ERROR

{"error":{"Error":"Unknown client code","Code":1000}}

About pizzagest software

Our software is a complete tool for managing food related business with lots of possible options depending on the customer, and may be necessary to acquire some knowledge about how our software works to understand correctly how to deal with the requests to our servers.

Available Functions

IMPORTANT NOTE:In the list below we describe the parameters that must be included in [data] field parsed JSON to its corresponding function.

addNewTicket:

Saves the order into the middleware database. The order will be automatically imported by its corresponding branch.

REQUIRED PARAMS:

[ClientCode]  => Your Pizzagest client code (string 20). 
[Timestamp]  => Current timestamp (string).
[TicketLines]  => Array containing products to save on the order (Array)
[Email]  => User email (string 50). 
[BranchCode]  => Branch code (num).
[Phone]  => User phone number (string 15).
[Language]=> The language in which you want to retrieve the information (char 2, valid languages ‘EN’,’AR’).
[StreetNumber]  => User street number (num).
[Building]  => User building name (sting 15).
[Staircase]  => User staircase name (string 3).
[Floor]  => User floor (string 3).
[Door]  => User door code (string 3).
[ExtraIndications]  => User extra indications about his address (string 100).
[Latitude]  => User latitude (double).
[Longitude]  => User longitude (double).
[CallbackUrl]=> Url 

RETURNED PARAMS:

[BranchAlive]-> Indicates the time elapsed between the call to the function and the last time the branch
connected to the middleware database. This time can be used for avoiding ordering to a branch with
connectivity issues.
[BranchCode] -> Indicates the branch code for each record.
[BranchDeliveryTime]-> Indicates the estimated delivery time. This parameter can also be changed at any time
by the branch manager.
[BranchState]-> Indicates if the branch is ready for receiving web orders. The branch manager can stop receiving 
	web orders if needed in case of saturation or any other issue. (Active/Inactive).
[BranchTimeTable]-> Array containing the branch timetable.	
[Opening1]-> Indicates the first opening hour, usually in the morning.
		[Closing1]-> Indicates the first closing hour, usually in the morning.
		[Opening2]-> Indicates the second opening hour, usually in the afternoon.
		[Closing2]-> Indicates the second closing hour, usually in the afternoon.
[Change]-> Indicates the change amount needed by customer.
[Delivery]: indicates if it’s a delivery order. (Y/N)
[DeliveryDate]: Indicates the hour for delivery or pick up the order.
[DeliveryIndications]: Indicates extra delivery indications. 
[OrderCode]: indicates the order code. This function returns this field empty until the order is saved.
[OrderDate]: indicates the date when the order was created. 
[OrderIndications]: Indicates extra order indications.
[PayTypeCode]: Indicates the payment method code.
[TicketLines]: Array containing list products by ticket line.
	[ProductCode]: contains the product code for each line.
	[ProductName]: contains the product name for each line.
				[Quantity]: contains the quantity of product placed at the order.
				[Topping]: contains a semi-colon separated string with the toppings.
				[ToppingName]: contains a semi-colon separated string with the toppings names in the same order that [Topping] string.

Errors

There are two error types:

Server: Request failed, bad formed requests, like Internal Server Error (500) or Server Time Error (406). This occurs when some of three required parameters are wrong. The available error list is:

Request: Server response JSON object named error, with code and descriptive message. The available error list is shown below: