İçeriğe geç

Entegrasyon

Açık masalar

Hesabı açık masaları ve tutarlarını okumak, tutara göre süzmek ve masalar arasında bir çekiliş yapmak.

GET /venues/{venueId}/active-tables, mekanda şu an hesabı açık olan masaları ve her birinin hesabının ne tuttuğunu listeler; hesabı kim açmış olursa olsun: kasadaki çalışan, garson, masanın QR menüsünden sipariş veren misafir ya da sizin yazılımınız. Mekanın kendi ekranları ve çekilişleri için yapılmıştır: mekanda oturan masalar arasında yapılan bir çekiliş gibi. Bu çağrı için anahtarın Açık masaları görebilir izni olmalıdır.

Uyarı: Bu çağrı mekanın o anki cirosunu gösterir. İzni yalnız mekanın kendi ekranlarına ve güvendiği yazılımlara verin; menüyü gösteren ya da sipariş alan bir sitenin anahtarında açmayın.

İstek#

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

minTotal isteğe bağlıdır. Verilmezse hesabı açık her masa listelenir; verilirse yalnız hesabı en az bu tutarı tutan masalar. Bir merkezin anahtarı, mekanla ilgili her çağrıda olduğu gibi şubelerinin açık masalarını da okuyabilir.

Yanıt#

Yanıtın data alanı, minTotal=500 ile, iki masayla:

JSON
{
  "venueId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "asOf": "2026-10-02T17:05:00.000Z",
  "currency": "TRY",
  "minTotal": 500,
  "tables": [
    {
      "table": { "id": "2f4e6a8c-0b1d-4c3e-9f5a-7b9d1e3c5a70", "name": "M1", "code": "K7PX2A", "capacity": 4 },
      "area": { "id": "1e3a5c7d-9f0b-4d2e-8a4c-6b8d0f2a4c61", "name": "Salon" },
      "mergedTables": [
        { "id": "4a6c8e0f-2b3d-4f5a-8c7e-9d1f3a5b7c92", "name": "M2", "code": "Q4ZT9B", "capacity": 2 }
      ],
      "openedAt": "2026-10-02T15:40:00.000Z",
      "total": 1240,
      "paid": 400,
      "remaining": 840,
      "paymentStatus": "PartiallyPaid",
      "bills": [
        {
          "id": "5e7a9c1b-3d5f-4a7c-9e1b-3d5f7a9c1e42",
          "number": 61,
          "openedAt": "2026-10-02T15:40:00.000Z",
          "total": 1240,
          "paid": 400,
          "remaining": 840,
          "paymentStatus": "PartiallyPaid"
        }
      ]
    },
    {
      "table": { "id": "6c8e0a2b-4d5f-4b7c-9e1a-3f5b7d9a1c34", "name": "B1", "code": null, "capacity": 6 },
      "area": { "id": "8d0f2b4a-6c8e-4a1b-9d3f-5e7a9c1b3d85", "name": "Bahçe" },
      "mergedTables": [],
      "openedAt": "2026-10-02T16:10:00.000Z",
      "total": 545,
      "paid": 545,
      "remaining": 0,
      "paymentStatus": "Paid",
      "bills": [
        {
          "id": "7a9c1e3b-5d7f-4b9a-8c1e-5f7b9d1a3c64",
          "number": 63,
          "openedAt": "2026-10-02T16:10:00.000Z",
          "total": 545,
          "paid": 545,
          "remaining": 0,
          "paymentStatus": "Paid"
        }
      ]
    }
  ]
}
  • table, masayı masa listesindeki haliyle verir; area masanın bulunduğu salon, bahçe ya da kattır.
  • asOf tutarların doğru olduğu andır (UTC). Hesaplar her çağrıda yeniden okunur.
  • minTotal isteğin sorduğu alt sınırdır; bütün açık masalar istendiyse null olur.
  • bills masanın açık hesaplarıdır, en eskisi önce. Genellikle bir tanedir; mekan aynı masa için ayrı hesaplar tutuyorsa birden fazla olur.

Bütün alanlar ve anlamları Açık masaları listele referansında.

Hangi masalar listelenir#

  • Hesabı açık olan her masa. Masa, hesabı açık olduğu sürece listededir ve mekan hesabı kapattığında listeden düşer.
  • Ödenmiş hesap da listede kalır. Tamamı ödenmiş bir hesap, mekan onu kapatana kadar listelenir: misafirler hala masadadır.
  • Hesabı olmayan masa listelenmez. Oturulmuş ama henüz sipariş verilmemiş bir masanın hesabı yoktur. Her kalemi iptal edilmiş bir hesap da listelenmez.
  • Birleştirilen masalar tek kayıttır. Aynı grup için birleştirilen masalarda table, grubun hesabını taşıyan masadır; diğerleri mergedTables içinde adlandırılır.
  • Sıra kasanın sırasıdır. Masalar alan alan gelir; her alanda önce mekanın düzenledikleri, sonra kalanlar adlarına göre. Mekanın sonradan sildiği bir masanın hesabı açıksa en sonda, Unknown table adıyla ve area değeri null olarak gelir.

Tutarlar#

  • total, masanın açık hesaplarının toplamıdır: kalemler, indirimler düşülmüş ve hizmet bedeli eklenmiş olarak, Türk lirası ve KDV dahil. İptal edilen kalemler sayılmaz.
  • Ödenen kısım da total içindedir. Hesabının yarısını ödemiş bir grup, hesabın tamamını harcamıştır. paid ödenen, remaining hala ödenecek kısmı söyler.
  • Masanın tutarları hesaplarının toplamıdır. total, paid ve remaining her zaman bills içindeki değerlerin toplamına eşittir.
  • paymentStatus hiçbir hesapta ödeme yoksa Unpaid, her hesap tamamen ödendiyse Paid, arada bir durumdaysa PartiallyPaid olur.

Tutara göre süzmek#

minTotal verildiğinde yalnız total değeri bu tutara eşit ya da daha büyük olan masalar listelenir. Sınır dahildir: minTotal=500, 500.00 tutan masayı listeler, 499.99 tutanı listelemez.

YanıtAnlamı
400 PUBLIC_API_MIN_TOTAL_INVALIDminTotal negatif.
400 VALIDATION_ERRORminTotal bir sayı değil.
403 PUBLIC_API_SCOPE_MISSINGAnahtarın Açık masaları görebilir izni yok.

Misafirler hakkında hiçbir şey#

Yanıt, masada oturan kimseyi adlandırmaz; telefon numarası vermez, bir misafirin Cibusy hesabı olup olmadığını söylemez. Siparişlerin kalemleri de yanıtta yoktur. Kazanan bir masayı adıyla duyurun; hesabı kasada number değeriyle, yani hesapta ve mutfak fişinde yazan numarayla bulun.

Bir hesabın id değeri siparişin kimliğidir. GET /orders/{orderId} yalnız API üzerinden verilmiş siparişleri yanıtlar; kasada ya da QR menüden açılmış bir hesap orada okunamaz.

Bir çekiliş örneği#

Aşağıdaki örnek en az 500 TL harcamış masalar arasından birini rastgele seçer:

JavaScript
import { randomInt } from 'node:crypto';

const response = await fetch(
  `https://api.cibusy.com/public/v1/venues/${venueId}/active-tables?minTotal=500`,
  { headers: { 'X-Api-Key': process.env.CIBUSY_API_KEY } }
);
if (!response.ok) throw new Error(`Cibusy: HTTP ${response.status}`);

const { data } = await response.json();
if (data.tables.length === 0) {
  console.log('Çekilişe katılabilecek masa yok.');
} else {
  const winner = data.tables[randomInt(data.tables.length)];
  const bills = winner.bills.map((bill) => bill.number).join(', ');
  console.log(`Kazanan masa: ${winner.table.name} (hesap no: ${bills})`);
}

Canlı okumak#

  • Her çağrı günceldir. Yanıt saklanmaz ve Cache-Control: no-store başlığıyla gelir; aradaki bir önbellekte tutmayın.
  • Bütçe. Çağrı, anahtarın dakikada yaklaşık 120 isteklik okuma bütçesinden sayılır. Bir ekranı beş saniyede bir yenilemek dakikada 12 istektir; aynı anahtarın diğer okumaları da bu bütçeyi paylaşır. Ayrıntılar Hız sınırları rehberinde.
  • Webhook yoktur. Bir masanın açılıp kapandığı bildirilmez; listeyi çekilişi yapacağınız an okuyun.
  • Abonelik. Aboneliği sona ermiş bir mekanın anahtarı açık masaları okumaya devam eder.