NAV
CURL

Introduction

This document describes the methods and endpoints to integrate third-party systems with Waitry through its REST API.

Data flow

Waitry works as a hub between Users and POS systems, giving them control over the entire ordering process and automating several order steps.

Waitry API receives input from users in Waitry Mobile App, processes it and sends input to Waitry Handy, Waitry Backend and integrated POS systems.

In the same way, Waitry API fetches all the data from POS systems, processes it and delivers it to Waitry Mobile Users, Waitry Handy and Waitry Backend.

Common endpoints needed

In order to integrate third-party solutions,Waitry needs to pull from the POS software the following data:

To automate and complete ordering processes Waitry needs to push the following data to the POS software:

Common endpoint offered

In order to automate notifications to the end-user, Waitry offers the following endpoint to the POS system in order to push order events to Waitry:

Sandbox and production environments

All integration tests must be performed in the sandbox environment offered by Waitry in the following URL:

https://api.waitry.net/dev/

Once the integration is ready, the following production url should be used:

https://api.waitry.net/1/

The authorization of access to the productive environment, should be requested by email to info@waitry.net

Unless otherwise specified, in all methods the standard format of the data is json.

Authorization and Authentication

Waitry API is a private API offered only to partners. To use it, you must first request an access API-Key next to a client_id. The key and id must be requested by email to info@waitry.net.

Once API-Key and client_id are obtained, they will be used to authenticate and obtain the access token that should be sent in all transactions. This token has a validity of two weeks. Once the token expires, you must refresh it with the same API-Key.

Authentication

In addition to the client_id and API-Key that identify the application that is connecting to Waitry API, the client's username and password must be provided. This username and password must be provided by each person responsible for the client who has access to the web system, after creating a new user with an "interface" profile.

To do this, you must enter the webapp (info@waitry.net) and go to User Management.

New user and create a new one with an "interface" profile.

If the application to integrate supports several Waitry clients, coordinate with info@waitry.net the provision and authorization of all the users necessary to integrate.

Authentication method

Endpoint

Response

[
  {
    "ok": [result of transaction, boolean],
    "msg": [transaction reply message, string],
    "msg_key": [key response message transaction, string],
    "status": [transaction status, string],
    "response": {
      "userId": [User ID, integer],
      "language": [ISO language by default, string],
      "username": [username, string],
      "email": [user email, string],
      "emailAlt": [alternative user email, string],
      "cellphone": [user's cellular number, string],
      "profilePicUrl": [url of user’s profile image, string],
      "bannerPicUrl": [url of user’s background image, string],
      "person": [person associated with the user, see type Person],
      "userType": {
        "userTypeId": [Id of user type, integer],
        "description": [description of the type of user, string]
      },
      "access_token": [generated token for transactions, string]
    },
    "places": [venues associated to the user, see type Place],
    "defaultPlace": [default venue of the user, see type Place]
  }
]

POST https://api.waitry.net/dev/user/login/login

Data

Parameter Description
client_id [you_client_id]
client_secret [your_api_key]
grant_type password
user [user_user]
password [customer_password]

Once the response is obtained, the access_token returned by the API must be saved in order to be able to use it in the sub-following transactions.

In all the transactions the access_token should be sent in the header of the http protocol in the following way:

Authorization: bearer access_token

Endpoints

Create layout and tables

Description

Method to create or modify a sector of a local. Accepts a sector and all its tree (tables). It must be invoked once for each sector to be created or modified.

Response

[
  {
    "ok": [result of transaction, boolean],
    "message": [transaction response message, string],
      "response": {
        "layout_id": [id of the created or modified sector, integer],
        "error_key": [error code if there is one, string],
        "error": [error description if there is one, string]
      }
  }
]

Endpoint

POST https://api.waitry.net/dev/place/layout/setLayout

Data

Parameter Description
place_id [Place id, integer]
layout_id [id of the sector to be modified or null if it is a new one, integer]
layout [json with all the composition of the sector, Layout type and subtypes]

Get orders

Description

Method to get all orders of a client.

Response

[
  {
    "ok": [result of transaction, boolean],
    "message": [transaction response message, string],
    "response": {
      "orders": [array of orders],
      "error_key": [error code if there is one, string],
      "error": [error description if there is one, string]
    }
  }
]

Endpoint

POST https://api.waitry.net/dev/live/order/get

Data

Parameter Description
place_id [Place id, integer]
layout_id [id of the sector to filter or null, integer]
only_open [true or false to get only open orders, boolean]
page [page of resultset, in live mode use 0, integer]
rows [rows of the page to be return, in live mode use a number bigger than tables quantity, integer]

Order update with items

Description

Method to modify an order of a local. Accept an order and all its tree (items, variations). It must be invoked once for each order to be modified.

See example of structure of the order in the example of the method "Get active orders".

Response

[
  {
    "ok": [result of transaction, boolean],
    "message": [transaction response message, string],
    "response": {
      "error_key": [error code if there is one, string],
      "error": [error description if there is one, string]
    }
  }
]

Endpoint

POST https://api.waitry.net/dev/visit/order/update

Data

Parameter Description
order_id [Order ID to modify, integer]
order [json with all the composition of the order, type Order and subtypes]

Event notification

Description

Method to notify an event about an order. The possible events are:

Response

[
  {
    "ok": [result of transaction, boolean],
    "message": [transaction response message, string],
    "response": {
      "error_key": [error code if there is one, string],
      "error": [error description if there is one, string]
    }
  }
]

Endpoint

POST https://api.waitry.net/dev/live/order/event

Data

Parameter Description
place_id [Id del local, integer]
order_id [id of the order on which the event is generated, integer]
event [name of the event to be notified]

Create order from booking

Description

Method to create a new order from a booking. This method allow to send the user and the table. The table is referenced with tableId when use the Waitry table’s IDs or by tableExternalId when use an external ID.

Response

[
  {
    "ok": [result of transaction, boolean],
    "message": [transaction response message, string],
    "response": {
      "orderId": [id of the new order created],
      "error_key": [error code if there is one, string],
      "error": [error description if there is one, string]
    }
  }
]

Endpoint

POST https://api.waitry.net/dev/visit/order/createFromBooking

Data

Parameter Description
username [username, string, optional]
email [user email, string, required]
name [user name, string, optional]
last_name [user lastname, string, optional]
age [user age, string, optional]
gender [user gender, string, optional]
city [user city location, string, optional]
cellphone [user cellphone, string, optional]
placeId [Waitry place id, integer, required]
tableId [Waitry table id, integer, optional if use externalId]
tableExternalId [external table id, integer, optional if use Waitry tableId]
tableNumber [table number, string, optional if use tableId or tableName]
tableName [table name, string, optional if use tableId or tableNumber]
event_date [date of the event formatted as yyyy-mm-dd hh:mm:ss, optional]
bookingId [ID in booking system, string, optional]
customerCount [amount of customers sitting at the table, integer, optional]

Cancel order from external ID

Description

Method to cancel an order by differents parameters.

Response

[
  {
    "ok": [result of transaction, boolean],
    "message": [transaction response message, string],
    "response": {
      "orderId": [Waitry id of the order cancelled],
      "error_key": [error code if there is one, string],
      "error": [error description if there is one, string]
    } 
  }
]

Endpoint

POST https://api.waitry.net/dev/live/order/cancelexternal

Data

Parameter Description
placeId [Waitry place id, integer, optional if use placeExternalId]
placeExternalId [Id in external system, string, optional if use placeId]
orderId [Waitry order ID, integer, optional if use orderExternalId]
orderExternalId [external order id, string, optional if use Waitry orderId]

Update order status

Description

Method to update status of an order

Response

[
  {
    "ok": [result of transaction, boolean],
    "msg": [transaction response message, string],
    "id": [Waitry id of the order updated],
    "response": {
      "error_key": [error code if there is one, string],
      "error": [error description if there is one, string]
    }
  }
]

Endpoint

POST https://api.waitry.net/dev/live/order/updateexternal

Data

Parameter Description
placeId [Waitry place id, integer, optional]
placeExternalId [Id in external system, string, optional]
orderId [Waitry order ID, integer, optional if use orderExternalId]
orderExternalId [external order id, string, optional if use Waitry orderId]
event [event to update. ‘accepted’, ‘canceled’, ‘closed’]

Get order analytics

Description

Method to get orders and details from a place

Response

{
    "ok": true,
    "message": "1 orders found!",
    "response": [
        {
            "orderId": 7573693,
            "timestamp": {
                "date": "2022-07-20 12:11:20.000000",
                "timezone_type": 3,
                "timezone": "America/Argentina/Buenos_Aires"
            },
            "pickupTime": {
                "date": "2022-07-20 13:15:00.000000",
                "timezone_type": 3,
                "timezone": "America/Argentina/Buenos_Aires"
            },
            "paid": false,
            "serviceChargeCount": 1,
            "totalAmount": 288,
            "externalClientId": null,
            "notes": null,
            "sequence": null,
            "externalId": null,
            "urgent": 0,
            "priority": null,
            "externalDeliveryId": "W-D53D12",
            "canceled": null,
            "table": {
                "tableId": 45580,
                "name": "Retirar",
                "number": "R",
                "externalId": null,
                "pin": "04C6C",
                "externalType": null,
                "layout": {
                    "layoutId": 15736,
                    "name": "Take Away",
                    "sector": null,
                    "paymentRequired": false,
                    "paymentElectronic": true,
                    "delay": 60
                },
                "place": {
                    "placeId": 1,
                    "name": "Sushi I",
                    "address": "Soldado de la Independencia 890",
                    "geoLatitude": "-34.5668722",
                    "geoLongitude": "-58.4358072"
                }
            },
            "orderActions": [
                {
                    "orderActionId": 38157222,
                    "timestamp": {
                        "date": "2022-07-20 12:11:20.000000",
                        "timezone_type": 3,
                        "timezone": "America/Argentina/Buenos_Aires"
                    },
                    "relatedId": null,
                    "orderActionType": {
                        "orderActionTypeId": 1,
                        "name": "user_checked_in",
                        "description": "Cuando el usuario ingresa a la mesa",
                        "percentaje": 0
                    },
                    "user": {
                        "userId": 876368,
                        "username": "guest16583298789746",
                        "email": "guest16583298789746@waitry.net",
                        "person": {
                            "personId": 876384,
                            "name": "Bárbara",
                            "lastName": "",
                            "doc": null
                        }
                    }
                },
                {
                    "orderActionId": 38157225,
                    "timestamp": {
                        "date": "2022-07-20 12:11:34.000000",
                        "timezone_type": 3,
                        "timezone": "America/Argentina/Buenos_Aires"
                    },
                    "relatedId": null,
                    "orderActionType": {
                        "orderActionTypeId": 3,
                        "name": "user_placed_order",
                        "description": "Cuando el usuario hace el pedido",
                        "percentaje": 10
                    },
                    "user": {
                        "userId": 876368,
                        "username": "guest16583298789746",
                        "email": "guest16583298789746@waitry.net",
                        "person": {
                            "personId": 876384,
                            "name": "Bárbara",
                            "lastName": "",
                            "doc": null
                        }
                    }
                }
            ],
            "orderItems": [
                {
                    "orderItemId": 29118981,
                    "timestamp": {
                        "date": "2022-07-20 12:11:34.000000",
                        "timezone_type": 3,
                        "timezone": "America/Argentina/Buenos_Aires"
                    },
                    "count": 2,
                    "notes": null,
                    "deletedAt": null,
                    "price": 144,
                    "discount": 0,
                    "discountPrice": 144,
                    "subtotal": 288,
                    "paid": false,
                    "sequence": "16583298944248",
                    "interfaceSend": null,
                    "item": {
                        "itemId": 510945,
                        "name": "Criolla",
                        "price": 144,
                        "externalId": null,
                        "externalCode": "1221"
                    },
                    "orderItemVariations": [
                        {
                            "orderItemVariationId": 37583046,
                            "itemVariation": {
                                "itemVariationId": 398365,
                                "name": "Salsa Buenos Aires",
                                "externalId": null,
                                "externalCode": null
                            }
                        }
                    ],
                    "orderItemStatusChanges": [
                        {
                            "orderItemStatusChangeId": 28235535,
                            "timestamp": {
                                "date": "2022-07-20 12:34:13.000000",
                                "timezone_type": 3,
                                "timezone": "America/Argentina/Buenos_Aires"
                            },
                            "orderItemStatus": {
                                "orderItemStatusId": 5,
                                "name": "accepted",
                                "description": "El item de la orden fue aceptado",
                                "percentage": 20
                            },
                            "user": {
                                "userId": 734206,
                                "username": "Baru",
                                "email": "barbara.urcelay@gmail.com",
                                "person": {
                                    "personId": 734221,
                                    "name": "Bárbara",
                                    "lastName": "Urcelay",
                                    "doc": "32269593"
                                }
                            }
                        }
                    ]
                }
            ],
            "orderUsers": [
                {
                    "orderUserId": 8177748,
                    "user": {
                        "userId": 876368,
                        "username": "guest16583298789746",
                        "email": "guest16583298789746@waitry.net",
                        "communicationsConsent": false,
                        "cellphone": "11222222",
                        "person": {
                            "personId": 876384,
                            "name": "Bárbara",
                            "lastName": ""
                        }
                    }
                }
            ]
        }
    ]
}

Endpoint

POST https://api.waitry.net/dev/analytics/analytics/getordersdetails/

Data

Parameter Description
placeId [Place id or null, integer]
from [date from, format yyyy-mm-dd]
to [date to, format yyyy-mm-dd]
layoutId [id of the sector to filter or null, integer]

ANNEX

Entities

The structure of the entities sent in the different responses is described below.

Entity User

[
  {
    "userId": [User ID, integer],
    "language": [ISO language by default, string],
    "username": [username, string],
    "email": [user email, string],
    "emailAlt": [alternative user email, string],
    "cellphone": [user's cellular number, string],
    "profilePicUrl": [url of user’s profile image, string],
    "bannerPicUrl": [url of user’s background image, string],
    "person": [person associated with the user, see type Person],
    "userType": {
      "userTypeId": [Id of user type, integer],
      "description": [description of the type of user, string]
    }
  }
]

Entity Person

[
  {
    "personId": [person id integer],
    "name": [person name, string],
    "middleName": [person middle name, string],
    "lastName": [person last name, string],
    "doc": [identification number, string],
    "createdAt": [creation date, see Date type],
    "modifiedAt": [modification date, see Date type],
    "city": [city, see City type],
    "region": [region, see type Region],
    "country": [country, see Country type]
  }
]

Entity Date

[
  {
    "date": [date formatted as yyyy-mm-dd hh:mm:ss],
    "timezone_type": [timezone, integer],
    "timezone": "UTC"
  }
]

Entity Place

[
  {
    "placeId": [place id, integer],
    "name": [place name, string],
    "address": [place address, string],
    "description": [Description, string],
    "googlePlaceId": [Google location ID, string],
    "createdAt": [creation date, see Date type],
    "modifiedAt": [modification date, see Date type],
    "deletedAt": [deletion date, see date type],
    "geoLatitude": [GPS latitude, string],
    "geoLongitude": [GPS longitude, string],
    "profilePicUrl": [URL of the place’s profile image, string],
    "bannerPicUrl": [URL of the place’s background image, string],
    "phoneNumber": [Local phone number, string],
    "theme": [theme customization, string],
    "wifiName": [wifi network name, string],
    "wifiPassword": [wifi password, string],
    "canCallWaiter": [permission to call the waiter, boolean],
    "canSeeMenus": [permission to see menu, boolean],
    "canMakeOrder": [permission to manage orders, boolean],
    "canSeeOrderProgress": [permission to see order progress, boolean],
    "published": [published, boolean],
    "timezoneOffset": [timezone offset in hours, integer],
    "lang": [ISO language code, string],
    "city": [city, see City type],
    "parentPlace": [parent place id, for franchises, integer]
  }
]

Entity City

[
  {
    "cityId": [City Id, integer],
    "name": [City name, string],
    "geoLatitude": [GPS latitude of the city, string],
    "geoLongitude": [GPS longitude of the city, string],
    "googlePlaceId": [Google location ID, string]
  }
]

Entity Region

[
  {
    "cityId": [Region or province id, integer],
    "name": [Region name, string],
    "geoLatitude": [GPS latitude of the region, string],
    "geoLongitude": [GPS longitude of the region, string],
    "googlePlaceId": [Google location ID, string]
  }
]

Entity Country

[
  {
    "cityId": [Country ID, integer],
    "name": [Country name, string],
    "geoLatitude": [GPS latitude of the country, string],
    "geoLongitude": [GPS longitude of the country, string],
    "googlePlaceId": [Google location ID, string]
  }
]

Entity Item

[
  {
    "itemId": [Item id, integer],
    "name": [Item name, string],
    "description": [Description of the item, string],
    "preparationTime": [preparation time in minutes, see Date type],
    "profilePicUrl": [URL to the item profile image, string],
    "bannerPicUrl": [URL to the background image of the item, string],
    "points": [promotional points that the item adds when ordered, integer],
    "price": [precios del item, float],
    "order": [position of the item in the category, integer],
    "variations": [array of variations, see type VariationType],
    "external_id": [item id in external system, string]
  }
]

Entity VariationType

[
  {
    "typeId": [Id of variation type, integer],
    "typeName": [Name of type of variation, string],
    "variations": [array of variations, see type Variation]
  }
]

Entity Variation

[
  {
    "itemVariationId": [Variation Id, integer],
    "itemItemVariationId": [Specific id of variation, integer],
    "variationPrice": [variation price, float],
    "itemPrice": [original item price, float],
    "points": [points granted by variation, integer],
    "name": [name of variation, string],
    "priceVariation": [calculation type to apply in the price, string],
    "description": [presentation of the price to show, string]
  }
]

Entity Layout

[
  {
    "layoutId": [layout id, integer],
    "name": [layout name, string],
    "description": [layout description, string],
    "floor": [layout floor number, integer],
    "sector": [general location of the layout, string],
    "canCallWaiter": [permission to call the waiter, boolean],
    "canSeeMenus": [permission to see menu, boolean],
    "canMakeOrder": [permission to manage orders, boolean],
    "canSeeOrderProgress": [permission to see order progress, boolean],
    "createdAt": [creation date, see Date type],
    "modifiedAt": [modification date, see Date type],
    "layoutStatus": {
      "layoutStatusId": [sector status id, integer],
      "name": [name of the state of the sector, string]
    },
    "layoutType": [object indicating the type of sector, type LayoutType],
    "tables": [array of tables in the sector, type Table],
    "external_id": [layout id in external system, string]
  }
]

Entity LayoutType

[
  {
    "layoutTypeId": [layout type id, integer],
    "name": [name of layout type, string],
    "description": [description of the layout type, string]
  }
]

Entity Table

[
  {
    "tableId": [Table Id, integer],
    "name": [name of the table, string],
    "number": [table number, string],
    "layoutX": [X position within the layout, integer],
    "layoutY": [position Y within the layout, integer],
    "createdAt": [creation date, see Date type],
    "modifiedAt": [modification date, see Date type],
    "deletedAt": [date of withdrawal, see Date type],
    "external_id": [table id in external system, string]
  }
]

Entity Order

[
  {
    "orderId": [Order ID, integer],
    "timestamp": [date of creation of the order, see date type],
    "status": {
      "orderStatusId": [Order state id, integer],
      "name": [order status name, string],
      "order": [state position, integer]
    },
    "table": [table or access point where the order belongs, type Table],
    "items": [array of items of the order, see type Item]
  }
]
CURL