Venues and branches

An API key belongs to the venue it was made for. This guide covers which venues a key reaches; a venue's details, hours and tables; and whether a venue is taking orders right now.

The venues a key reaches#

GET /venues lists the venues the key reaches, its own venue first. Every call about one venue takes that venue's id in its path.

curl "https://api.cibusy.com/public/v1/venues" \
  -H "X-Api-Key: $CIBUSY_API_KEY"

A venue the key cannot reach is answered 404 PUBLIC_API_VENUE_NOT_FOUND, exactly as a venue that does not exist is. A key can therefore never find out which venues exist beyond its own.

If you build one integration for several branches, use the headquarter's key and take the branches' ids from GET /venues. Each branch can also have keys of its own; such a key reaches its own branch only.

A venue's details#

GET /venues/{venueId} gives everything a venue's site needs: its name and logo, its address and place on the map, its time zone, its opening hours, the languages of its menu and whether it is taking orders.

curl "https://api.cibusy.com/public/v1/venues/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Api-Key: $CIBUSY_API_KEY"

• timeZone is the venue's time zone, such as Europe/Istanbul. The opening hours and the times in ordering are times in that zone.
• workingHours lists the days the venue has entered, starting on Monday. opensAt and closesAt are "HH:mm"; on a day the venue is shut all day, isClosed is true. On a day that ends after midnight, closesAt is earlier than opensAt: Friday 11:00–01:00, say. A day the venue has not entered is not listed.
• languages lists the languages the menu is offered in, the default first. You ask for the menu with one of these codes.

Every field and what it means is in the Get a venue reference.

Is it taking orders now?#

Look at the ordering object before you show an order button. A venue takes orders when all three of these hold:

1. An active subscription. A venue whose subscription has lapsed still shows its menu, but takes no orders.
2. No rush declared. When the venue's kitchen declares a rush, busyUntil says when it ends (in UTC) and busyReason is what the venue wrote about it for its guests.
3. Inside its opening hours. Unless the venue has switched this rule off, orders are accepted only inside its hours, with the grace the venue allows on either side. opensAt and closesAt are today's times; they are null when the venue has switched the rule off, has entered no hours for today, or while a rush lasts.

acceptingOrdersNow weighs the three together, and is worked out again on every call.

acceptingOrdersNow is only a hint: the state can change between two calls. Whether an order is accepted is always told by the answer to placing it. When the venue is not taking orders at that moment, the answer is a 409: PLACE_IS_BUSY, OUTSIDE_WORKING_HOURS or PUBLIC_API_ORDERING_UNAVAILABLE.

Two rules that apply to a guest using the QR menu do not apply to the API: the guest's location, which a website cannot give, and the setting that opens the QR menu as a menu only.

Tables#

A dine-in order names a table by its id. GET /venues/{venueId}/tables gives the venue's tables grouped by area (a hall, a garden, a floor):

curl "https://api.cibusy.com/public/v1/venues/3fa85f64-5717-4562-b3fc-2c963f66afa6/tables" \
  -H "X-Api-Key: $CIBUSY_API_KEY"

Areas and the tables in them come in the order the venue's till shows them. code is the code printed on the table's QR card; if you print QR cards of your own, you can recognise the table by it. capacity is how many people the table seats, and null when the venue has not said.

Tables seldom change: read the list once, keep it on your server and refresh it now and then.