Pizzagest Documentation

User Tools

Site Tools

Trace:
manuals:api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

manuals:api [2018/03/02 10:12] – created - external edit 127.0.0.1manuals:api [2024/11/18 18:54] (current) – dmarti
Line 1: Line 1:
-<html>+====== Introduction ======
  
-<h1>Introduction</h1>+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>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>+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>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>+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>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>+====== Get Started ======
  
-<h1>Get Started</h1>+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>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> +<code>
- +
-<pre>+
 http://s01.pav-online.com/PAV_RESTFUL/{FunctionName} http://s01.pav-online.com/PAV_RESTFUL/{FunctionName}
 POST[data]-> JSON STRING POST[data]-> JSON STRING
 POST[hash]-> HASH SIGN POST[hash]-> HASH SIGN
-</pre>+</code>
  
-<p>Get request:</p>+Get request:
  
-<pre>+<code>
 http://s01.pav-online.com/PAV_RESTFUL/{FunctionName}?data=JSON_STRING&hash=HASH_SIGN http://s01.pav-online.com/PAV_RESTFUL/{FunctionName}?data=JSON_STRING&hash=HASH_SIGN
-</pre>+</code>
  
-<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>+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.
  
-<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>+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>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> +**[POST][data] :** Contains all the information necessary for the request parsed in a JSON string. ClientCode, Timestamp, Function Params.
-  +
-<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>+**[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.
  
-<pre>hash_hmac ('SHA256',  $data_string.strlen($data_string ), $HASH)</pre>+<code> 
 +hash_hmac ('SHA256',  $data_string.strlen($data_string ), $HASH) 
 +</code>
  
-<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>+**SANDBOX_DATA:** For the preproduction stage you must use the following code and hash. For the production stage we will provide new different values.
  
-<pre>Client code: ‘HungerStation’+<code> 
 +Client code: ‘HungerStation’
  
 Hash: 285c148c9374923c3024d6ec76b7f85d6519293949f7340afe1470079de9adzz Hash: 285c148c9374923c3024d6ec76b7f85d6519293949f7340afe1470079de9adzz
-</pre>+</code>
  
 +**JSON EXAMPLE POST DATA:**
  
-<b>JSON EXAMPLE POST DATA:</b> +<code>
- +
-<pre>+
 http://s01.pav-online.com/PAV_RESTFUL/GetBranches http://s01.pav-online.com/PAV_RESTFUL/GetBranches
  
Line 55: Line 53:
  
 [hash]="7b4f034c2abf901682fabc0b74e7ef992c8a38bc97c9760f29cbad32794091ff"} [hash]="7b4f034c2abf901682fabc0b74e7ef992c8a38bc97c9760f29cbad32794091ff"}
-</pre>+</code>
  
-<h1>Get Example</h1>+====== Get Example ======
  
-<pre>+<code>
 http://s01.pav-online.com/PAV_RESTFUL/GetBranches?data={%22BranchCode%22:%22%22,%22ClientCode%22:%HungerStation%22,%22Timestamp%22:%221432562038%22}&hash=7b4f034c2abf901682fabc0b74e7ef992c8a38bc97c9760f29cbad32794091ff http://s01.pav-online.com/PAV_RESTFUL/GetBranches?data={%22BranchCode%22:%22%22,%22ClientCode%22:%HungerStation%22,%22Timestamp%22:%221432562038%22}&hash=7b4f034c2abf901682fabc0b74e7ef992c8a38bc97c9760f29cbad32794091ff
-</pre> +</code>
- +
-<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> +IMPORTANT NOTE: All requests may have “Client Code” and “Timestamp” included in the JSON String. Both parameters must be converted to string.
-[data]={"ClientCode":"897f9408a5d64fda","Timestamp":"1432562038"}</pre>+
  
-<p>PHP sample code:</p>+<code> 
 +[data]={"ClientCode":"897f9408a5d64fda","Timestamp":"1432562038"} 
 +</code>
  
-<pre><?php+PHP sample code:
  
-$client= "demo"; +<code> 
-$pass = "demo"; +$client,
-$date = new DateTime(); +
- +
-$data = array( +
-    "ClientCode"=>$client,+
     "Timestamp"=> (string) $date->getTimestamp(),         "Timestamp"=> (string) $date->getTimestamp(),    
 ); );
Line 110: Line 102:
    
 ?> ?>
-</pre>+</code>
  
-<h1>Managing Responses</h1>+====== Managing Responses ======
  
-<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>+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>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>+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><b>SAMPLE RESPONSE</b></p>+**SAMPLE RESPONSE**
  
-<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….. +<code> 
-</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….. 
 +</code>
  
-<p><b>SAMPLE ERROR</b></p>+**SAMPLE ERROR**
  
-<pre>{"error":{"Error":"Unknown client code","Code":1000}}</pre> +<code> 
 +{"error":{"Error":"Unknown client code","Code":1000}} 
 +</code>
  
-<h1>About pizzagest software</h1>+====== About pizzagest software ======
  
-<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> +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.
- +
  
-<h1>Available Functions</h1>+====== 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.
  
-<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>+===== getBranchesInfo: =====
  
 +This function retrieves the information for all available branches. If data[BranchCode] is specified, retrieves only the information for the requested branch.
  
-<h2>getBranchesInfo:</h2>+**REQUIRED PARAMS:**
  
-<p>This function retrieves the information for all available branches. If data[BranchCode] is specified, retrieves only the information for the requested branch. </p> +<code>
- +
-<p><b>REQUIRED PARAMS:</b></p> +
-<pre>+
 [data][ClientCode]  => Your Pizzagest client code (string 20). [data][ClientCode]  => Your Pizzagest client code (string 20).
 [data][Timestamp]  => Current timestamp (string). [data][Timestamp]  => Current timestamp (string).
-</pre>+</code> 
 + 
 +**OPTIONAL PARAMS:** 
 + 
 +<code> 
 +[data][BranchCode]  => Branch code for retrieving the information. If not informed all branches are returned. 
 +</code>
  
-<p><b>OPTIONAL PARAMS:</b></p> +The object returned by the function is as follows:
- <pre>[data][BranchCode]  => Branch code for retrieving the information. If not informed all branches are returned.</pre> +
-  +
-<p>The object returned by the function is as follows:</p>+
  
-<pre>[Array]+<code> 
 +[Array]
 [AreaCode]: indicating branch area code. [AreaCode]: indicating branch area code.
 [AreaName]: indicating branch area name. [AreaName]: indicating branch area name.
Line 193: Line 190:
 PickUp: Array object list with all available payment methods for pickup orders. PickUp: Array object list with all available payment methods for pickup orders.
 [PrayTimes]: Array containing the prayer times schedule for current day. [PrayTimes]: Array containing the prayer times schedule for current day.
-</pre>+</code>
  
 +===== getMenuInfo: =====
  
-<h2>getMenuInfo:</h2+Retrieves the full menu product list grouped by its family and including topping customization options and prices.
  
-<p>Retrieves the full menu product list grouped by its family and including topping customization options and prices.</p>+**REQUIRED PARAMS:**
  
-<p><b>REQUIRED PARAMS:</b></p> +<code> 
-<pre>[data][ClientCode]  => Your Pizzagest client code (string 20).+[data][ClientCode]  => Your Pizzagest client code (string 20).
 [data][Timestamp]  => Current timestamp (string). [data][Timestamp]  => Current timestamp (string).
 [data][BranchCode] => Branch code (num). [data][BranchCode] => Branch code (num).
-</pre>+</code>
  
-<p><b>EXTRA PARAMS:</b></p> +**EXTRA PARAMS:**
-<pre>[data][Language]=> The language in which you want to retrieve the information.</pre>+
  
-<p>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.</p>+<code> 
 +[data][Language]=> The language in which you want to retrieve the information. 
 +</code>
  
-<p>The object returned by the function is as follows:</p> +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. 
-<pre>[Array]+ 
 +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: [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. [Doughs]: Object containing the default dough for the item.
Line 297: Line 300:
  For example: Medium Pizza , prefix [PM]. BBQ medium code PMBB  For example: Medium Pizza , prefix [PM]. BBQ medium code PMBB
           Large Pizza, prefix [PL]. BBQ Large code PLBB           Large Pizza, prefix [PL]. BBQ Large code PLBB
-</pre>+</code>
  
-<h2>addNewTicket:</h2>+===== addNewTicket: =====
  
-<p>Saves the order into the middleware database. The order will be automatically imported by its corresponding branch.</p>+Saves the order into the middleware database. The order will be automatically imported by its corresponding branch.
  
-<p><b>REQUIRED PARAMS:</b></p>+**REQUIRED PARAMS:**
  
-<pre>+<code>
 [ClientCode]  => Your Pizzagest client code (string 20).  [ClientCode]  => Your Pizzagest client code (string 20). 
 [Timestamp]  => Current timestamp (string). [Timestamp]  => Current timestamp (string).
Line 321: Line 324:
 [Latitude]  => User latitude (double). [Latitude]  => User latitude (double).
 [Longitude]  => User longitude (double). [Longitude]  => User longitude (double).
-</pre>  +</code> 
- <p><b>RETURNED PARAMS:</b></p> + 
-<pre>+**RETURNED PARAMS:** 
 + 
 +<code>
 [BranchAlive]-> Indicates the time elapsed between the call to the function and the last time the branch [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 connected to the middleware database. This time can be used for avoiding ordering to a branch with
Line 351: Line 356:
  [Topping]: contains a semi-colon separated string with the toppings.  [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.  [ToppingName]: contains a semi-colon separated string with the toppings names in the same order that [Topping] string.
 +</code>
  
-</pre> +====== Errors ======
- +
-<h1>Errors</h1>+
  
-<p>There are two error types:</p>      +There are two error types:
-<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> +**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:
-<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> +|Error Number|Error Description              | 
-<tr><td>Error Number</td><td>Error Description</td></tr> +|100         |Continue                       | 
-<tr><td>1000</td><td>Unknown client code</td></tr> +|101         |Switching Protocols            | 
-<tr><td>1001</td><td>Bad request (token)</td></tr> +|200         |OK                             | 
-<tr><td>1002</td><td>No results found</td></tr> +|201         |Created                        | 
-<tr><td>1003</td><td>The user is already registered</td></tr> +|202         |Accepted                       | 
-<tr><td>1004</td><td>Required parameter missing ( Param Name)</td></tr> +|203         |Non-Authoritative Information  | 
-<tr><td>1005</td><td>Required parameter empty (Param Name)</td></tr> +|204         |No Content                     | 
-<tr><td>1007</td><td>Required parameter type incorrect</td></tr> +|205         |Reset Content                  | 
-<tr><td>1008</td><td>Internal Web Server Error</td></tr> +|206         |Partial Content                | 
-<tr><td>1009</td><td>User registered not validated</td></tr> +|300         |Multiple Choices               | 
-<tr><td>1010</td><td>Wrong password</td></tr> +|301         |Moved Permanently              | 
-<tr><td>1011</td><td>Wrong validate code</td></tr> +|302         |Found                          | 
-<tr><td>1012</td><td>User validated </td></tr> +|303         |See Other                      | 
-<tr><td>1013</td><td>Order empty</td></tr> +|304         |Not Modified                   | 
-<tr><td>1014</td><td>User Not Registered</td></tr> +|305         |Use Proxy                      | 
-<tr><td>1016</td><td>Email missing</td></tr> +|306         |Unused                         | 
-<tr><td>1017</td><td>Branch code missing</td></tr> +|307         |Temporary Redirect             | 
-<tr><td>1018</td><td>Order save fail</td></tr> +|400         |Bad Request                    | 
-</table>+|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:
  
-</html>+|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                         |
manuals/api.1519981931.txt.gz · Last modified: 2018/03/02 10:12 by 127.0.0.1