Pizzagest Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<html>

<h1>Introduction</h1>

<p>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. </p>

<p>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.</p>

<p>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.</p>

<h1>Get Started</h1>

<p>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:</p>

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

<p>Get request:</p>

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

<p>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.</p>


<p>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.</p>

<p>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.</p>
 
<p><b>[POST][data] :</b> Contains all the information necessary for the request parsed in a JSON string.
ClientCode, Timestamp, Function Params.</p>

<p><b>[POST][hash] :</b> 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.</p>

<pre>hash_hmac ('SHA256',  $data_string.strlen($data_string ), $HASH)</pre>

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

<pre>Client code: ‘KoutFood’

Hash: 285c148c9374923c3024d6ec76b7f85d6519293949f7340afe1470079de9adzz
</pre>


<b>JSON EXAMPLE POST DATA:</b>

<pre>
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"}
</pre>

<h1>Get Example</h1>

<pre>
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
</pre>

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

<pre>
[data]={"ClientCode":"KoutFood","Timestamp":"1432562038"}</pre>

<p>PHP sample code:</p>

<pre><?php

$client= "demo";
$pass = "demo";
$date = new DateTime();

$data = array(
    "ClientCode"=>$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));

 
?>
</pre>

<h1>Managing Responses</h1>

<p>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.</p>

<p>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.</p>

<p><b>SAMPLE RESPONSE</b></p>

<pre>{"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…..
</pre>

<p><b>SAMPLE ERROR</b></p>

<pre>{"error":{"Error":"Unknown client code","Code":1000}}</pre>	

<h1>About pizzagest software</h1>

<p>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.</p>
	

<h1>Available Functions</h1>


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

<h2>addNewTicket:</h2>

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

<p><b>REQUIRED PARAMS:</b></p>

<pre>
[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 
</pre>	
	<p><b>RETURNED PARAMS:</b></p>
<pre>
[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.

</pre>

<h1>Errors</h1>

<p>There are two error types:</p>     
<p><b>Server:</b> 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:
</p>

<table>
<tr><td>Error Number</td><td>Error Description</td></tr>
<tr><td>100 <td>Continue</td></tr>
<tr><td>101</td><td>Switching Protocols</td></tr>
<tr><td>200</td><td>OK</td></tr>
<tr><td>201</td><td>Created</td></tr>
<tr><td>202</td><td>Accepted</td></tr>
<tr><td>203</td><td>Non-Authoritative Information</td></tr>
<tr><td>204</td><td>No Content</td></tr>
<tr><td>205</td><td>Reset Content</td></tr>
<tr><td>206</td><td>Partial Content</td></tr>
<tr><td>300</td><td>Multiple Choices</td></tr>
<tr><td>301</td><td>Moved Permanently</td></tr>
<tr><td>302</td><td>Found</td></tr>
<tr><td>303</td><td>See Other</td></tr>
<tr><td>304</td><td>Not Modified</td></tr>
<tr><td>305</td><td>Use Proxy</td></tr>
<tr><td>306</td><td>Unused</td></tr>
<tr><td>307</td><td>Temporary Redirect</td></tr>
<tr><td>400</td><td>Bad Request</td></tr>
<tr><td>401</td><td>Unauthorized</td></tr>
<tr><td>402</td><td>Payment Required</td></tr>
<tr><td>403</td><td>Forbidden</td></tr>
<tr><td>404</td><td>Not Found</td></tr>
<tr><td>405</td><td>Method Not Allowed</td></tr>
<tr><td>406</td><td>Not Acceptable</td></tr>
<tr><td>407</td><td>Proxy Authentication Required</td></tr>
<tr><td>408</td><td>Request Timeout</td></tr>
<tr><td>409</td><td>Conflict</td></tr>
<tr><td>410</td><td>Gone</td></tr>
<tr><td>411</td><td>Length Required</td></tr>
<tr><td>412</td><td>Precondition Failed</td></tr>
<tr><td>413</td><td>Request Entity Too Large</td></tr>
<tr><td>414</td><td>Request-URI Too Long</td></tr>
<tr><td>415</td><td>Unsupported Media Type</td></tr>
<tr><td>416</td><td>Requested Range Not Satisfiable</td></tr>
<tr><td>417</td><td>Expectation Failed</td></tr>
<tr><td>500</td><td>Internal Server Error</td></tr>
<tr><td>501</td><td>Not Implemented</td></tr>
<tr><td>502</td><td>Bad Gateway</td></tr>
<tr><td>503</td><td>Service Unavailable</td></tr>
<tr><td>504</td><td>Gateway Timeout</td></tr>
<tr><td>505</td><td>HTTP Version Not Supported</td></tr>
</table>
	
<p><b>Request:</b> Server response JSON object named error, with code and descriptive message. The available error list is shown below:</p>

<table>
<tr><td>Error Number</td><td>Error Description</td></tr>
<tr><td>1000</td><td>Unknown client code</td></tr>
<tr><td>1001</td><td>Bad request (token)</td></tr>
<tr><td>1002</td><td>No results found</td></tr>
<tr><td>1003</td><td>The user is already registered</td></tr>
<tr><td>1004</td><td>Required parameter missing ( Param Name)</td></tr>
<tr><td>1005</td><td>Required parameter empty (Param Name)</td></tr>
<tr><td>1007</td><td>Required parameter type incorrect</td></tr>
<tr><td>1008</td><td>Internal Web Server Error</td></tr>
<tr><td>1009</td><td>User registered not validated</td></tr>
<tr><td>1010</td><td>Wrong password</td></tr>
<tr><td>1011</td><td>Wrong validate code</td></tr>
<tr><td>1012</td><td>User validated </td></tr>
<tr><td>1013</td><td>Order empty</td></tr>
<tr><td>1014</td><td>User Not Registered</td></tr>
<tr><td>1016</td><td>Email missing</td></tr>
<tr><td>1017</td><td>Branch code missing</td></tr>
<tr><td>1018</td><td>Order save fail</td></tr>
</table>


</html>