Requests and responses

The Cibusy API is a REST API that speaks JSON. This guide covers the rules that hold for every request and every answer: the address, names, times and money, the envelope of an answer, the language of messages and paging.

Base URL#

Every call goes over HTTPS to this address:

https://api.cibusy.com/public/v1

Requests and responses are JSON in UTF-8. Send Content-Type: application/json with a request that has a body.

Names and values#

• Property names are camelCase: paymentMethod, tableId, acceptingOrdersNow.
• Enum values travel as their names: "DineIn", "Takeaway"; never a number such as 1.
• Absent values are null. A property is never left out of an answer and is never an empty string ("").
• Ids are UUIDs: 3fa85f64-5717-4562-b3fc-2c963f66afa6.

Times#

• Instants are ISO 8601 in UTC, ending in Z: 2026-10-01T09:30:00.000Z. Convert them to the venue's time zone before you show them to a guest.
• Times on the venue's clock, such as an opening time, are "HH:mm" strings: "11:00". The venue's timeZone, such as Europe/Istanbul, says whose clock that is.

Money#

Amounts are JSON numbers in Turkish lira (TRY), VAT included, to two decimals: 320, 161.5, 680.4. The currency is always TRY.

You do not work prices out: an order request carries none, and the server prices everything and says what it came to. When you store amounts in your own system, use a decimal type rather than floating point.

The envelope#

Every answer comes in the same envelope. A success carries the result in data:

{
  "success": true,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null,
  "data": { },
  "message": "Operation completed successfully"
}

An error carries a code to act on and two messages:

{
  "success": false,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null,
  "userMessage": "Table not found at this venue.",
  "developerMessage": "The table is not one of this venue's tables.",
  "errorCode": "PUBLIC_API_TABLE_NOT_FOUND",
  "validationErrors": [
    { "field": "tableId", "message": "Not one of this venue's tables.", "attemptedValue": null }
  ],
  "details": null
}

Decide what to do from the HTTP status and errorCode. userMessage is a sentence for the person using your site and can be shown as it is; developerMessage is in English, meant for your logs, and its wording may change. Every field of an error, and every error code, is in Errors.

The language of messages#

userMessage is written in the language of the request's Accept-Language header:

The first language in the header decides, without its region: en-US reads as en. A language Cibusy does not offer is answered in Turkish.

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

This header does not choose the language of a menu. A menu comes in one of the venue's languages, chosen with the menu call's lang parameter; see Reading the menu.

Paging#

The list of orders (GET /orders) is read a page at a time:

nextCursor in the answer is the number of the next page, and null on the last one. Ask again with it until it is null:

async function allOpenOrders() {
  const orders = [];
  let cursor = 1;

  while (cursor !== null) {
    const response = await fetch(
      `https://api.cibusy.com/public/v1/orders?status=open&pageSize=100&cursor=${cursor}`,
      { headers: { 'X-Api-Key': process.env.CIBUSY_API_KEY } }
    );
    const body = await response.json();
    if (!body.success) throw new Error(`${body.errorCode}: ${body.developerMessage}`);

    orders.push(...body.data.items);
    cursor = body.data.nextCursor;
  }

  return orders;
}

The list is newest first. An order placed while you are paging moves every later page along by one: an order can then appear on two pages, but never on none. Merge orders by their ids.

Properties and values you do not know#

Nothing is removed or renamed under v1, but new properties and new enum values may be added. Ignore the properties you do not know, and handle a value you do not know in a way that does not break you. What stays fixed is in Versioning and support.