İstekler ve yanıtlar

Cibusy API, JSON konuşan bir REST API'dir. Bu rehber her istekte ve her yanıtta geçerli olan kuralları anlatıyor: adres, alan adları, zaman ve para biçimleri, yanıtın zarfı, mesajların dili ve sayfalama.

Temel adres#

Her çağrı HTTPS üzerinden şu adrese gider:

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

İstekler ve yanıtlar UTF-8 kodlu JSON'dur. Gövdesi olan bir istekte Content-Type: application/json başlığını gönderin.

Adlar ve değerler#

• Alan adları camelCase yazılır: paymentMethod, tableId, acceptingOrdersNow.
• Sabit değerler adlarıyla gelir ve gider: "DineIn", "Takeaway"; hiçbir zaman 1 gibi bir sayı değil.
• Boş değerler null olur. Bir alan yanıttan hiçbir zaman çıkarılmaz ve hiçbir zaman boş metin ("") olarak gelmez.
• Kimlikler UUID'dir: 3fa85f64-5717-4562-b3fc-2c963f66afa6.

Zaman#

• Anlar, sonunda Z olan ISO 8601 biçiminde ve UTC'dir: 2026-10-01T09:30:00.000Z. Bunları misafirinize gösterirken mekanın saat dilimine çevirin.
• Mekanın saatiyle saatler, örneğin bir açılış saati, "HH:mm" biçiminde metindir: "11:00". Hangi saate göre olduğunu mekanın timeZone alanı söyler, örneğin Europe/Istanbul.

Para#

Tutarlar Türk lirası (TRY) cinsinden, KDV dahil ve iki ondalık basamaklı JSON sayılarıdır: 320, 161.5, 680.4. Para birimi her zaman TRY'dir.

Fiyatları siz hesaplamazsınız: sipariş isteğinde fiyat yoktur, her tutarı sunucu hesaplar ve yanıtta söyler. Tutarları kendi sisteminizde saklarken kayan noktalı sayı yerine ondalık bir tür kullanın.

Yanıt zarfı#

Her yanıt aynı zarfla gelir. Başarılı bir yanıtta sonuç data alanındadır:

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

Bir hata, üzerine karar vereceğiniz bir kod ve iki mesaj taşır:

{
  "success": false,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null,
  "userMessage": "Bu mekanda böyle bir masa bulunamadı.",
  "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
}

Ne yapacağınıza HTTP durum kodu ve errorCode ile karar verin. userMessage sitenizi kullanan kişiye yazılmış bir cümledir ve olduğu gibi gösterilebilir; developerMessage İngilizcedir, kayıtlarınız içindir ve ifadesi değişebilir. Hata yanıtının bütün alanları ve her hata kodu Hatalar rehberinde.

Mesajların dili#

userMessage, isteğin Accept-Language başlığındaki dilde yazılır:

Başlıktaki ilk dil karar verir ve bölgesine bakılmaz: en-US, en olarak okunur. Cibusy'nin sunmadığı bir dil Türkçe yanıtlanır.

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

Bu başlık menünün dilini seçmez. Menü, mekanın sunduğu dillerden birinde gelir ve onu menü çağrısının lang parametresi seçer; ayrıntılar Menüyü okumak rehberinde.

Sayfalama#

Sipariş listesi (GET /orders) sayfa sayfa okunur:

Yanıttaki nextCursor bir sonraki sayfanın numarasıdır ve son sayfada null olur. nextCursor null olana kadar isteği onunla tekrarlayın:

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;
}

Liste en yeni önce sıralanır. Siz sayfalarken yeni bir sipariş gelirse sonraki sayfalar bir kayar: bir sipariş iki sayfada görünebilir ama hiçbir zaman atlanmaz. Siparişleri kimliklerine göre birleştirin.

Bilmediğiniz alanlar ve değerler#

v1 içinde hiçbir alan kaldırılmaz ve yeniden adlandırılmaz, ama yeni alanlar ve yeni sabit değerler eklenebilir. Tanımadığınız alanları yok sayın, tanımadığınız bir değeri de sisteminizi bozmayacak şekilde karşılayın. Neyin değişmeyeceği Sürümler ve destek rehberinde.