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.
====== 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:

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

Get request:

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

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.

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

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

<code>
Client code: ‘HungerStation’

Hash: 285c148c9374923c3024d6ec76b7f85d6519293949f7340afe1470079de9adzz
</code>

**JSON EXAMPLE POST DATA:**

<code>
http://s01.pav-online.com/PAV_RESTFUL/GetBranches

[data]={"BranchCode":"0","ClientCode":"HungerStation","Timestamp":"1432562038"}

[hash]="7b4f034c2abf901682fabc0b74e7ef992c8a38bc97c9760f29cbad32794091ff"}
</code>

====== Get Example ======

<code>
http://s01.pav-online.com/PAV_RESTFUL/GetBranches?data={%22BranchCode%22:%22%22,%22ClientCode%22:%HungerStation%22,%22Timestamp%22:%221432562038%22}&hash=7b4f034c2abf901682fabc0b74e7ef992c8a38bc97c9760f29cbad32794091ff
</code>

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

<code>
[data]={"ClientCode":"897f9408a5d64fda","Timestamp":"1432562038"}
</code>

PHP sample code:

<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/getbranches';
$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));

 
?>
</code>

====== 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**

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

**SAMPLE ERROR**

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

====== 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.

===== getBranchesInfo: =====

This function retrieves the information for all available branches. If data[BranchCode] is specified, retrieves only the information for the requested branch.

**REQUIRED PARAMS:**

<code>
[data][ClientCode]  => Your Pizzagest client code (string 20).
[data][Timestamp]  => Current timestamp (string).
</code>

**OPTIONAL PARAMS:**

<code>
[data][BranchCode]  => Branch code for retrieving the information. If not informed all branches are returned.
</code>

The object returned by the function is as follows:

<code>
[Array]
[AreaCode]: indicating branch area code.
[AreaName]: indicating branch area name.
[BranchActive]: indicating the branch state.
- Active: Full activity.
- Inactive: No activity. ( No service )
- Only-Pickup: Only Pickup Orders allowed.
- Only-Delivery: Only Delivery Orders allowed.
[BranchAddress]: indicating the branch street name.
[BranchCode]: indicating the branch code that identifies the branch on our system.
[BranchLastActivity]: indicates the date/time for the last activity into the middleware database of the Branch Server. If during opening hours the last activity is more than 5 minutes ago, is very possible that there is a problem with the branch connection to the Internet. In this case we recommend to disable the web ordering for the branch until the connection will be restored.
[BranchName]: indicating the branch name.
[BranchNumber]: indicating the branch house number.
[BranchPhone]: indicating the branch phone number.
[BranchTimeTable]: Array object listed by day name of the week. Each day contains an array.
-Opening1: indicates the first opening hour (morning).
-Closing1: indicates the first closing hour (morning).
-Opening2: indicates the second opening hour (afternoon).
-Closing2: indicates the second closing hour (afternoon).
[CityName]: indicating branch city name.
[DeliveryFeeAmount]: indicates the total amount for the delivery fee in the order.
[DeliveryFeeCode]: indicates the sale item code for adding a fee to the delivery orders. This item code must be specified in the order object.
[DeliveryFeeMaxAmount]: indicates the maximum order amount for adding the delivery fee. 
[DeliveryTime]: indicates the estimated delivery time. (00:30:00)
[Latitude]: indicating branch latitude.
[Longitude]: indicating branch longitude.
[MaxUserNoRegisteredAmount]: indicates the maximum order amount for unregistered users.
[MaxUserRegisteredAmount]: indicates the maximum order amount for registered users.
[OfferTime]: indicates the last time to apply a promotion. 24h format .  ( 18 ).
[OrderDeliveryMin]: indicates the minimum amount for delivery orders.
[OrderPickUpMin]: indicates the minimum amount for pickup orders.
[PickupTime]: indicates the estimated pickup time. (00:15:00)
[Province]: indicating branch province name.
[StreetDirectory]: indicating the branch street directory code.
[ZipCode]: indicating the branch ZIP code.
[ZoneCode]: Indicating the zone code.
[PaymentMethods]: Array object, contains two different arrays one for Delivery and the other for Pickup. 
Delivery: Array object list with all available payment methods for delivery orders.
PickUp: Array object list with all available payment methods for pickup orders.
[PrayTimes]: Array containing the prayer times schedule for current day.
</code>

===== getMenuInfo: =====

Retrieves the full menu product list grouped by its family and including topping customization options and prices.

**REQUIRED PARAMS:**

<code>
[data][ClientCode]  => Your Pizzagest client code (string 20).
[data][Timestamp]  => Current timestamp (string).
[data][BranchCode] => Branch code (num).
</code>

**EXTRA PARAMS:**

<code>
[data][Language]=> The language in which you want to retrieve the information.
</code>

Note that is required to provide the branch ID for getting the product list as the prices may be different from one branch to another. As the branch with ID “1” is a test branch do not use it in production.

The object returned by the function is as follows:

<code>
[Array]
[Products]: Array object which specifies the available products (sale items) for the family group. Each element of the array has the following attributes:
[Doughs]: Object containing the default dough for the item.
[Sauces]: Object containing the default dough for the item.
[Topping]: Object containing the default toppings for the item.
[ImageURL]: URL for the element image
[Price]: Double indicating the pick-up price for the item
[PriceDelivery]: Double indicating the delivery price for the item
[ProductCode]: Varchar indicating the ID for the item
[ProductDescription]: Varchar indicating the description for the item
[ProductName]: Varchar indicating the name for the element
[Alcohol]: Indicates if the sale items associated to the family group are alcoholic beverages. [Y/N]
[HalfAndHalf]: Indicates if the sales items associated to the family group are allowed to be half and half. The available values are:
Y: The sales items associated to the family group are allowed to be half and half between them.
N: The sales items associated to the family group are not allowed to be half and half.
A, B, C, D: Indicates half and half grouping. The sales items associated to the family group are allowed to be half and half and also with other families with the same grouping letter. In ex.: All sales items associated to any family group with letter “A” can be half and half between them, but not with a sale item associated to a family group with letter “B”.
[Doughs]: Array object which specifies the available dough for all the products included in the family group. Each element of the array has the following attributes:
[Free]: Char with “S” (yes) or “N” (No) value indicating if the dough can be free or must be charged
[Price]: Double indicating the pick-up price for the element
[PriceDelivery]: Double indicating the delivery price for the element
[PriceDelveryWO]: Double indicating the amount to discount for delivery if the element is removed from the sale item
[PriceWO]: Double indicating the amount to discount for pick-up if the element is removed from the sale item
[ToppingCode]: Varchar indicating the ID for the element
[ToppingName]: Varchar indicating the name for the element.
[Allergens] : String base containing 14 binary positions (1/0), for each position.

[Sauces]: Array object which specifies the available sauces for all the products included in the family group. Each element of the array has the following attributes:
[Free]: Char with “S” (yes) or “N” (No) value indicating if the sauce can be free or must be charged
[Price]: Double indicating the pick-up price for the element
[PriceDelivery]: Double indicating the delivery price for the element
[PriceDeliveryWO]: Double indicating the amount to discount for delivery if the element is removed
 from the sale item.
[PriceWO]: Double indicating the amount to discount for pick-up if the element is removed from the
 sale item.
[ToppingCode]: Varchar indicating the ID for the element
[ToppingName]: Varchar indicating the name for the element
[Allergens] : String containing 14 binary positions (1/0), for each position.

[Topping]: Array object which specifies the available toppings for all the products included in the family
group. Each element of the array has the following attributes:
[Free]: Char with “S” (yes) or “N” (No) value indicating if the topping can be free or must be charged
[Price]: Double indicating the pick-up price for the element
[PriceDelivery]: Double indicating the delivery price for the element
[PriceDeliveryWO]: Double indicating the amount to discount for delivery if the element is removed from the sale item.
[PriceWO]: Double indicating the amount to discount for pick-up if the element is removed from the sale item.
[ToppingCode]: Varchar indicating the ID for the element
[ToppingName]: Varchar indicating the name for the element
[Allergens] : String containing 14 binary positions (1/0), for each position.

[FamilyCode]: Varchar indicating the family group code
[FamilyName]: Varchar indicating the family group name
[FreeTopping]: Integer indicating the number of free toppings for all the products included in the family
group.
[ImageURL]: URL for the family group image
[MaxTopping]: Integer indicating the maximum number of toppings allowed for all the products included in
the family group. If the value is set 0, indicates simple products.
[ShopCode]: Integer indicating the ID for the branch
[BaseProduct]: Indicating which product will be used for product customizations for each family product.
[Allergens] => String containing 14 binary positions (1/0), for each position. 
(‘00000000000000’) -> No allergens.
(‘10000000000000’) -> Lupin
(‘01000000000000’) -> Celery
(‘00100000000000’) -> Peanuts
(‘00010000000000’) -> Crustaceans
(‘00001000000000’) -> Nuts
(‘00000100000000’) -> Gluten
(‘00000010000000’) -> Eggs
(‘00000001000000’) -> Dairy
(‘00000000100000’) -> Molluscs
(‘00000000010000’) -> Mustard
(‘00000000001000’) -> Fish
(‘00000000000100’) -> Sesame 
(‘00000000000010’) -> Soybeans
(‘00000000000001’) -> Sulfites
Example of combined allergens:
	(‘10000000000001’) -> Lupin + Sulfites

[FamilySize]: Indicates the family size in case of different sizes.	
	‘S’: Small Size
	‘M’: Medium Size
	‘L’: Large Size
	‘X’: Extra Large Size
[FamilyPrefix]: Indicates the Family Prefix, this prefix relates items for the same family. All products from the same familiy will have the same prefix followed by its corresponding product code.
	For example: Medium Pizza , prefix [PM]. BBQ medium code PMBB
		         Large Pizza, prefix [PL]. BBQ Large code PLBB
</code>

===== addNewTicket: =====

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

**REQUIRED PARAMS:**

<code>
[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).
</code>

**RETURNED PARAMS:**

<code>
[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.
</code>

====== 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:

|Error Number|Error Description              |
|100         |Continue                       |
|101         |Switching Protocols            |
|200         |OK                             |
|201         |Created                        |
|202         |Accepted                       |
|203         |Non-Authoritative Information  |
|204         |No Content                     |
|205         |Reset Content                  |
|206         |Partial Content                |
|300         |Multiple Choices               |
|301         |Moved Permanently              |
|302         |Found                          |
|303         |See Other                      |
|304         |Not Modified                   |
|305         |Use Proxy                      |
|306         |Unused                         |
|307         |Temporary Redirect             |
|400         |Bad Request                    |
|401         |Unauthorized                   |
|402         |Payment Required               |
|403         |Forbidden                      |
|404         |Not Found                      |
|405         |Method Not Allowed             |
|406         |Not Acceptable                 |
|407         |Proxy Authentication Required  |
|408         |Request Timeout                |
|409         |Conflict                       |
|410         |Gone                           |
|411         |Length Required                |
|412         |Precondition Failed            |
|413         |Request Entity Too Large       |
|414         |Request-URI Too Long           |
|415         |Unsupported Media Type         |
|416         |Requested Range Not Satisfiable|
|417         |Expectation Failed             |
|500         |Internal Server Error          |
|501         |Not Implemented                |
|502         |Bad Gateway                    |
|503         |Service Unavailable            |
|504         |Gateway Timeout                |
|505         |HTTP Version Not Supported     |

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

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