{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"PUC Logical Hierarchy","type":"text"}]},{"type":"paragraph","content":[{"text":"The PUC hierarchy starts with ","type":"text"},{"text":"organizations","type":"text","marks":[{"type":"em"}]},{"text":", which are equivalent to a business like a restaurant chain. The next level is a ","type":"text"},{"text":"store","type":"text","marks":[{"type":"em"}]},{"text":", and an organization can have many stores. A store can in turn have multiple associated ","type":"text"},{"text":"PUC cabinets","type":"text","marks":[{"type":"em"}]},{"text":", which are the physical hardware of the PUC system.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":743,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":743,"id":"84fdbde7-846b-4f89-9f0b-9b33ad89cb5d","collection":"contentId-450527234","type":"file","height":482}}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Prerequisites","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to use the PUC API, you will need a valid API key for your organization. This can be requested from Powerhouse Dynamics. You can have multiple API keys per organization. You can use the GET / keys endpoint to retrieve a list of all of the keys in your organization.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Creating a new PUC order: ","type":"text"}]},{"type":"paragraph","content":[{"text":"To create a new PUC order, you use the POST /orders endpoint. The syntax is (using curl as an example):","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"marks":[{"type":"breakout","attrs":{"mode":"wide"}}],"content":[{"text":"curl -X POST \"https://.sitesage.net/api/v1/orders\"\n-H \"accept: application/json\"\n-H \"Authorization: Basic \"\n-H \"Content-Type: application/json\"\n-d \"{\\\"\\\":\\\"\\\",\n \\\"reference\\\":\\\"\\\",\n \\\"display_name\\\":\\\"\\\",\n \\\"sms_phone_number\\\":\\\"\\\",\n \\\"accessible\\\":,\n \\\"queue_hold_minutes\\\":,\n \\\"cabinet_hold_minutes\\\":,\n \\\"code\\\":,\n \\”order_source\\”:,\n \\\"code_load\\\":\\\"\\\",\n \\\"code_pickup\\\":\\\"\\\",\n \\\"estimated_size\\\":{\\\"ambient\\\":,\\\"heated\\\":},\n \\\"extended_info\\\":{}}\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Explanation of parameters:","type":"text"}]},{"type":"paragraph","content":[{"text":"","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": An API key valid for your organization.","type":"text"}]},{"type":"paragraph","content":[{"text":" cabinet_alias","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":", ","type":"text"},{"text":"cabinet_ID","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":", ","type":"text"},{"text":"or store_ID","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": You may enter a cabinet alias or a cabinet ID to designate the PUC cabinet to send the order to. If you specify a store ID instead, the order will be sent to a store and the PUC server will decide what cabinet at that store to send the order to, allowing for load balancing between multiple cabinets at one store site.","type":"text"}]},{"type":"paragraph","content":[{"text":"reference","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": a reference string for the order.","type":"text"}]},{"type":"paragraph","content":[{"text":"display_name","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": The name of the customer that will display on screen or on an (optional) printed ticket.","type":"text"}]},{"type":"paragraph","content":[{"text":"sms_phone_number","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": the mobile number of the customer to send order status texts to.","type":"text"}]},{"type":"paragraph","content":[{"text":"accessible","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": a true/false value denoting if the order should be placed in an ADA accessible locker. Any locker can be configured to be ADA accessible for the purposes of this function.","type":"text"}]},{"type":"paragraph","content":[{"text":"queue_hold_minutes","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": how long in minutes the order can be in the queue before being marked as expired. If this is not provided in the order POST, the cabinet default will be used.","type":"text"}]},{"type":"paragraph","content":[{"text":"cabinet_hold_minutes","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": how long in minutes the order can stay in a locker before being marked as expired. If not provided the cabinet default will be used.","type":"text"}]},{"type":"paragraph","content":[{"text":"code","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": the numeric code a customer can use to pick up the order. The valid number of digits can be configured on a per cabinet basis but are usually 3 digits.","type":"text"}]},{"type":"paragraph","content":[{"text":"order_source","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": The source of the order, such as Grubhub, etc.","type":"text"}]},{"type":"paragraph","content":[{"text":"code_load","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": A string to be encoded into a QR code that will be used for an employee to load this order into its cabinet. Will be generated automatically if not provided. This value must be unique per cabinet. We suggest you derive this from your reference.","type":"text"}]},{"type":"paragraph","content":[{"text":"code_pickup","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": A string to be encoded into a QR code that will be used for a customer to pick up this order. Will be generated automatically if not provided. This value must be unique per cabinet. We suggest you derive this from your reference.","type":"text"}]},{"type":"paragraph","content":[{"text":"estimated_size","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": a JSON block containing the number of ","type":"text"},{"text":"ambient ","type":"text","marks":[{"type":"em"}]},{"text":"and ","type":"text"},{"text":"heated ","type":"text","marks":[{"type":"em"}]},{"text":"lockers the order needs. If only one type of locker is needed do not include the other type. For example, if an order needs 1 ambient locker you do not have to include ","type":"text"},{"text":"heated: 0 ","type":"text","marks":[{"type":"em"}]},{"text":"in the JSON block.","type":"text"}]},{"type":"paragraph","content":[{"text":"extended_info","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": An optional JSON block used to send complete order information if needed to print a kitchen ticket. A ticket is printed automatically if the store’s cabinets are configured to do so. Most PUC installations do not have kitchen ticket printing enabled.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Successful Return","type":"text"}]},{"type":"paragraph","content":[{"text":"On successfully sending an order to the PUC server, you will receive a 201 message and a JSON block containing the order data. An example of the returned JSON block is shown below:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"id\": \"TMURoP5aSQi-KySvKdVzkg\",\n \"cabinet_id\": \"TMURoP5aSQi-KySvKdVzkg\",\n \"cabinet_alias\": \"bestchinese\",\n \"reference\": 123456,\n \"display_name\": \"John\",\n \"sms_phone_number\": \"503-555-1212\",\n \"accessible\": false,\n \"queue_hold_minutes\": 60,\n \"cabinet_hold_minutes\": 20,\n \"code\": 376,\n \"order_source\": \"grubhub\",\n \"code_load\": \"load:123456\",\n \"code_pickup\": \"pickup:123456\",\n \"estimated_size\": {\n \"ambient\": 0,\n \"heated\": 0\n },\n \"created_at\": \"2021-03-26T06:03:36.086Z\",\n \"updated_at\": \"2021-03-26T06:03:36.086Z\",\n \"status\": \"new\",\n \"event_id\": 234,\n \"queued_at\": \"2021-03-26T06:03:36.086Z\",\n \"loaded_at\": \"2021-03-26T06:03:36.086Z\",\n \"canceled_at\": \"2021-03-26T06:03:36.086Z\",\n \"pickedup_at\": \"2021-03-26T06:03:36.086Z\",\n \"disposed_at\": \"2021-03-26T06:03:36.086Z\",\n \"queue_expires_at\": \"2021-03-26T06:03:36.086Z\",\n \"pickup_expires_at\": \"2021-03-26T06:03:36.086Z\",\n \"lockers\": [\n {\n \"id\": \"TMURoP5aSQi-KySvKdVzkg\",\n \"created_at\": \"2021-03-26T06:03:36.086Z\",\n \"updated_at\": \"2021-03-26T06:03:36.086Z\",\n \"label\": \"1\",\n \"type\": \"heated\",\n \"accessible\": false,\n \"status\": \"loaded\"\n }\n ]\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Detailed API Syntax","type":"text"}]},{"type":"paragraph","content":[{"text":"The example above for creating an order is the same basic syntax used with all the PUC API endpoints. Detailed syntax for the API, including endpoints not listed in this document, is available at ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://puc.sitesage.net/api-docs/#/"}},{"text":". For each endpoint listed in the api-docs URL, you can see example values and a schema for both the request and response. For example, the POST /order endpoint used for creating an order looks like this:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":906,"id":"82e4a344-2ff6-47a3-89d1-70924903d7df","collection":"contentId-450527234","type":"file","height":524}}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Other Common Endpoints For The Ordering Workflow","type":"text"}]},{"type":"paragraph","content":[{"text":"Cancelling an order","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The DELETE /orders/{ID} endpoint allows you to cancel an order (this can also be done from the touch screen on the PUC cabinet).","type":"text"}]},{"type":"paragraph","content":[{"text":"Get the data for a specific order","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The GET /orders/{ID} endpoint retrieves all the order data for a specific order, including all its event timestamps. This can be used to determine when an order was loaded, cancelled, etc. if not using a web hook for automatic event notifications.","type":"text"}]},{"type":"paragraph","content":[{"text":"Getting a list of orders in the system","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The GET /orders endpoint returns a list of orders for your organization. You can get a list of the orders in one cabinet by specifying a cabinet ID. Future enhancements to this endpoint include being able to specify a cabinet alias, store ID, or store alias.","type":"text"}]},{"type":"paragraph","content":[{"text":"Getting order statistics for a cabinet","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The GET /orders/stats endpoint returns the statistics for a cabinet ID. If you omit the cabinet ID it will return order stats for your entire organization but getting order stats for a specific cabinet is the most common and practical use of the endpoint. Examples of the data returned include order counts for queued, loaded, and expired orders, among others. Checking the number of orders currently associated with a cabinet could be useful in deciding what cabinet to send an order to or when to release an order from a POS system to manage load, for example.","type":"text"}]},{"type":"paragraph","content":[{"text":"Changing/updating an order","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"There is currently no endpoint for changing/updating an order (changing the SMS phone number for example). The only way to achieve this is to first ","type":"text"},{"text":"delete ","type":"text","marks":[{"type":"em"}]},{"text":"the order and then ","type":"text"},{"text":"create a new order ","type":"text","marks":[{"type":"em"}]},{"text":"with the new data. Future enhancements to the API might allow for changing order data in place.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Useful Endpoints for Configuration and Administration","type":"text"}]},{"type":"paragraph","content":[{"text":"Create a child API key for your organization","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"You can create a ","type":"text"},{"text":"child ","type":"text","marks":[{"type":"em"}]},{"text":"API key for your organization that allows for using the API using the POST /keys endpoint. Note that you MUST have an initial parent API key for your organization in order to create a child API key.","type":"text"}]},{"type":"paragraph","content":[{"text":"Create a custom SMS template","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The POST /orders/sms/templates endpoint lets you create a custom SMS text message for your organization that overrides the default message. You can also create a custom SMS message for a specific ","type":"text"},{"text":"cabinet. ","type":"text","marks":[{"type":"em"}]},{"text":"The hierarchy of text messages is cabinet SMS templates are used before organization SMS templates, which are used before the default templates. You can have a custom SMS template for each of the events that would trigger a text to the customer: ","type":"text"},{"text":"loaded, pickup_expiring, ","type":"text","marks":[{"type":"em"}]},{"text":"and ","type":"text"},{"text":"pickup_expired. ","type":"text","marks":[{"type":"em"}]},{"text":"Future enhancements will include the addition of ","type":"text"},{"text":"store ","type":"text","marks":[{"type":"em"}]},{"text":"SMS templates which would fit into the hierarchy between cabinet and organization templates.","type":"text"}]},{"type":"paragraph","content":[{"text":"There are variables from the order data that can be used in the SMS templates. These fields are delimited by surrounding them with double curly braces in the template text. For example, you can insert the customer’s name into the SMS text by using ","type":"text"},{"text":"{{order.display_name}}. ","type":"text","marks":[{"type":"em"}]},{"text":"See the web API documentation for specific details.","type":"text"}]},{"type":"paragraph","content":[{"text":"After creating a custom SMS template, you must activate it by using the PATCH /orders/sms/templates/{ID} endpoint and sending the JSON data block ","type":"text"},{"text":"{“activate”: true}","type":"text","marks":[{"type":"em"}]},{"text":". Conversely you can deactivate a template using the same endpoint by sending ","type":"text"},{"text":"{“activate”: false}. ","type":"text","marks":[{"type":"em"}]},{"text":"You can get a list of all of the custom templates for your organization by using the GET /orders/sms/templates, or just a specific template with GET /orders/sms/ templates/{ID}.","type":"text"}]},{"type":"paragraph","content":[{"text":"Adding an alias to a cabinet","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"You can add a text alias to a cabinet that you can use in lieu of a cabinet ID to send orders to a cabinet by using the PUT /cabinets/{ID}/aliases/{alias} endpoint. Cabinet aliases must be unique to the organization the cabinet is associated with. In addition to adding a custom alias to a cabinet, you can optionally include a ","type":"text"},{"text":"business_name, business_phone, ","type":"text","marks":[{"type":"em"}]},{"text":"and ","type":"text"},{"text":"business_address ","type":"text","marks":[{"type":"em"}]},{"text":"when creating the alias and these values will override the store values when using them as fields in an SMS template. Future enhancements will include adding all of the above alias functionality to stores, so you could create a store alias that matches the store number in your own system, for example.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Webhooks For Automatic Event Notifications","type":"text"}]},{"type":"paragraph","content":[{"text":"The PUC server supports webhooks for sending event notifications to a third-party system. To create a webhook you must use the POST /webhooks endpoint and supply both the URL of your endpoint (this must use HTTPS) and the shared secret used by your endpoint to validate communication from the PUC server.","type":"text"}]},{"type":"paragraph","content":[{"text":"Once you register your webhook, it will receive data whenever the status (queued, loaded, picked up, etc.) of any order in your organization changes. Future enhancements to the API may allow for filtering events sent to an endpoint by store or cabinet, but currently an endpoint will receive ALL order status events for an entire organization.","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is an example of a JSON block sent to a custom endpoint via a webhook when an order was queued:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"marks":[{"type":"breakout","attrs":{"mode":"wide"}}],"content":[{"text":"{\n \"id\": \"KIqXbb4XQ_SpWp0FxqJPGU2Q\",\n \"sequence\": 1178,\n \"cabinet_id\": \"IXPw65ibZTJuq4w98K_q8pg\",\n \"reference\": \"KIqXbb4XQ_SpWp0FxqJPGU2Q\",\n \"order_source\": \"grubhub\",\n \"code\": \"7530\",\n \"sms_phone_number\": null,\n \"display_name\": \"7530\",\n \"accessible\": true,\n \"queue_hold_minutes\": 20,\n \"cabinet_hold_minutes\": 20,\n \"created_at\": \"2021-02-12T21:58:57.434Z\",\n \"extended_info\": null,\n \"event_id\": 3793,\n \"updated_at\": \"2021-02-12T21:58:57.434Z\",\n \"status\": \"queued\",\n \"queued_at\": \"2021-02-12T21:58:57.434Z\",\n \"loaded_at\": null,\n \"canceled_at\": null,\n \"pickedup_at\": null,\n \"disposed_at\": null,\n \"locker_conflicted_at\": null,\n \"queue_expires_at\": \"2021-02-12T22:18:57.434Z\",\n \"pickup_expires_at\": null,\n \"cancel_initiated_at\": null,\n \"cancel_invalidated_at\": null,\n \"code_load\": \"U2FsdGVkX19XLHqUY34kP3LjMkcRfAPLrQUmiiUEm8gaJmbleJ/8HaWfsK6qu28A\",\n \"code_pickup\": \"U2FsdGVkX1+mG1iPqN3tZtj8GY+rhHRcfUhcdbEH2ONKD7IiljQGXI40Q2+Vuzh8\",\n \"cabinet_alias_id\": null,\n \"cabinet_alias\": null,\n \"lockers\": [],\n \"estimated_size\": {\"ambient\": 1},\n \"text\": \"order: 'KIqXbb4XQ_SpWp0FxqJPGU2Q', status: 'queued', at: '2021-02-12T21:58:57.434Z'\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Any event in the JSON with a ","type":"text"},{"text":"null ","type":"text","marks":[{"type":"em"}]},{"text":"value has not occurred for the order. The specific event that triggered the webhook is in the ","type":"text"},{"text":"status ","type":"text","marks":[{"type":"em"}]},{"text":"portion of the ","type":"text"},{"text":"text ","type":"text","marks":[{"type":"em"}]},{"text":"field, in addition to having a valid datetime stamp in the corresponding preceding field in the JSON.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Future Enhancements","type":"text"}]},{"type":"paragraph","content":[{"text":"As stated throughout this document, one of the major enhancements to the API will be to more fully support the ","type":"text"},{"text":"store ","type":"text","marks":[{"type":"em"}]},{"text":"object in the hierarchy. Filtering GET requests with a store ID or alias would be one example of more fully supporting store objects.","type":"text"}]},{"type":"paragraph"}],"version":1}

Browser not supported