Rezervasyon almak

Rezervasyon çağrıları mekanın müsait saatlerini okur, sitenizin aldığı rezervasyonu mekana gönderir, onu takip etmenizi ve misafir vazgeçtiğinde iptal etmenizi sağlar. Bu rehberdeki her çağrı için anahtarın Rezervasyon alabilir izni olmalıdır.

Akış#

1. Sunucunuz GET /venues/{venueId}/reservation-availability ile mekanın müsait saatlerini okur; siteniz misafire bu saatleri gösterir.
2. Misafir saatini seçip adını ve telefonunu yazınca sunucunuz rezervasyonu POST /venues/{venueId}/reservations ile gönderir.
3. Rezervasyon mekanın rezervasyon listesine düşer. Mekanın ayarına göre hemen onaylanır ya da mekanın yanıtını bekler.
4. Misafire haberi siteniz verir; Cibusy bu rezervasyonlar için SMS göndermez.
5. Siteniz rezervasyonu webhook'larla ya da GET /reservations/{reservationId} ile izler; misafir vazgeçerse POST /reservations/{reservationId}/cancel ile iptal eder.

Müsait saatler#

Misafire kendi uydurduğunuz saatleri değil, mekanın saatlerini sunun. GET /venues/{venueId}/reservation-availability mekanın rezervasyon takvimini gün gün döndürür: from ilk gündür (verilmezse mekanın bugünü), days kaç gün istediğinizdir (verilmezse 7, en fazla 14).

curl "https://api.cibusy.com/public/v1/venues/3fa85f64-5717-4562-b3fc-2c963f66afa6/reservation-availability?from=2026-10-09&days=3" \
  -H "X-Api-Key: $CIBUSY_API_KEY"

Yanıtın data alanı, iki günüyle:

{
  "venueId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reservationsEnabled": true,
  "confirmsAutomatically": false,
  "timeZone": "Europe/Istanbul",
  "maxGuests": 20,
  "minNoticeMinutes": 30,
  "lastBookableDate": "2026-11-30",
  "days": [
    {
      "date": "2026-10-09",
      "state": "Open",
      "slots": [
        { "startsAt": "2026-10-09T16:00:00.000Z", "time": "19:00" },
        { "startsAt": "2026-10-09T16:30:00.000Z", "time": "19:30" },
        { "startsAt": "2026-10-09T17:00:00.000Z", "time": "20:00" },
        { "startsAt": "2026-10-09T17:30:00.000Z", "time": "20:30" }
      ]
    },
    { "date": "2026-10-11", "state": "Closed", "slots": [] }
  ]
}

• Gösterdiğiniz ile gönderdiğiniz ayrıdır. Misafire saatin time değerini gösterin: mekanın kendi saatiyle yazılıdır. Rezervasyonu gönderirken aynı saatin startsAt değerini kullanın: UTC bir andır.
• Bu, mekanın kendi rezervasyon sayfasının takvimidir. Bir rezervasyonun uyması gereken kurallarla hesaplanır; burada listelenen bir saati rezervasyon çağrısı kabul eder. Saatler yarım saat arayladır.
• Günün durumu. Open günlerde slots hala alınabilen saatleri taşır. Mekanın kapalı olduğu gün Closed, o hafta günü için çalışma saati girilmemiş gün HoursUnknown okunur; ikisinde de saat yoktur. Gece yarısından sonra da misafir alan bir mekanda o geç saatler, ait oldukları akşamın günü altında listelenir.
• Mekan rezervasyon almıyorsa reservationsEnabled değeri false, days boş olur. Rezervasyon düğmesini bu durumda göstermeyin.
• Takvim doluluğu bilmez. Mekanın ne zaman misafir aldığını söyler, kaç masasının boş olduğunu değil: Cibusy masa saymaz ve yer olmayan bir isteği mekan reddeder.

Rezervasyonu göndermek#

Rezervasyon POST /venues/{venueId}/reservations ile gönderilir:

curl -X POST "https://api.cibusy.com/public/v1/venues/3fa85f64-5717-4562-b3fc-2c963f66afa6/reservations" \
  -H "X-Api-Key: $CIBUSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startsAt": "2026-10-09T17:00:00.000Z",
    "guests": 4,
    "customer": {
      "name": "Ayşe Yılmaz",
      "phone": "+905321112233"
    },
    "note": "Mümkünse cam kenarı bir masa."
  }'

Başarılı ilk yanıt 201 Created olur ve data rezervasyonun kendisidir:

{
  "id": "9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
  "venueId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "Pending",
  "startsAt": "2026-10-09T17:00:00.000Z",
  "guests": 4,
  "customer": { "name": "Ayşe Yılmaz", "phone": "+905321112233" },
  "note": "Mümkünse cam kenarı bir masa.",
  "code": "K7M2Q9XA",
  "pageUrl": "https://cibusy.com/modakofte/reservation/K7M2Q9XA",
  "canCancel": true,
  "checkedInAt": null,
  "cancelledAt": null,
  "cancelledBy": null,
  "cancellationReason": null,
  "createdAt": "2026-10-01T09:30:00.000Z"
}

• Diğer rezervasyonlarla aynı yere düşer. Mekanın kasadaki ve çalışan uygulamasındaki rezervasyon listesinde görünür ve çalışanlarına, misafirin kendi yaptığı bir rezervasyon gibi bildirilir.
• Onay mekanın ayarıdır. Rezervasyonları alındığı anda onaylayan bir mekanda status değeri Confirmed gelir. Diğerlerinde mekandan biri kabul ya da reddedene kadar Pending kalır; mekanın saatine kadar yanıtlamadığı istek iptal edilir ve cancelledBy değeri System olur. Hangisini bekleyeceğinizi müsaitlik yanıtındaki confirmsAutomatically söyler: misafire "rezervasyonunuz onaylandı" mı, "isteğiniz mekana iletildi" mi diyeceğinizi buna göre seçin.

Mekanın kuralları#

Saatin alınıp alınamayacağına mekanın rezervasyon kuralları karar verir; bunlar mekanın kendi rezervasyon sayfasının misafire uyguladığı kurallardır. Müsaitlik yanıtından alınan bir saat hepsinden geçer.

Misafire haber vermek#

Cibusy, API üzerinden alınan bir rezervasyon için misafire SMS göndermez: ne alındığında, ne onaylandığında, ne de iptal edildiğinde. Rezervasyonu siteniz aldı ve misafir haberi sitenizden bekler. Bunun için gereken her şey her yanıtta ve webhook'ta bulunur.

• Misafire yanıttaki pageUrl adresini ya da code değerini verin. cibusy.com'daki sayfa rezervasyonu ve onaylandıktan sonra mekanın kapıda okuttuğu QR'ı gösterir; gösterecek bir ekranı yoksa misafir kodu söyler.
• İkisinden birini elinde tutan rezervasyonu görebilir ve iptal edebilir; bu yüzden yalnız misafire verin.
• Mekanın yanıtını beklediğiniz bir rezervasyonda (Pending) sonucu reservation.updated olayıyla öğrenir ve misafire siz iletirsiniz.

Güvenle yeniden denemek#

Rezervasyon göndermek için Idempotency-Key gerekmez. Bir misafir aynı anda iki masada oturamaz; bu yüzden aynı telefon numarası, aynı mekan ve aynı saat için gönderilen ikinci istek, ilk rezervasyon hala geçerliyken aynı rezervasyondur.

• Bir istek zaman aşımına uğrarsa ya da bağlantı koparsa aynı isteği değiştirmeden tekrar gönderin. İlk çağrının aldığı rezervasyonu mekandaki şimdiki haliyle alırsınız; ilk yanıt 201 iken bu yanıt 200 olur ve mekana ikinci kez bildirilmez.
• Bir tekrar, mekanın kurallarına yeniden bakılmadan yanıtlanır, çünkü rezervasyon zaten vardır.
• Tekrar yalnız API'nin aldığı rezervasyonlar arasında aranır. Aynı misafirin Cibusy uygulamasından ya da mekanın sayfasından yaptığı bir rezervasyon, sitenizin rezervasyonunun yerine geçmez.
• Rezervasyon çağrıları, sipariş vermekle aynı bütçeyi paylaşır: anahtar başına dakikada yaklaşık 30 istek; tekrarlar da sayılır.

Rezervasyonu takip etmek#

GET /reservations/{reservationId} rezervasyonu mekandaki şimdiki haliyle okur. GET /reservations, API üzerinden alınan rezervasyonları sayfa sayfa listeler; status ile açık (open, varsayılan), sonuçlanmış (closed) ya da bütün (all) rezervasyonları seçersiniz. Açık olanlar en yakın saat önce gelir: ilk gelecek masa en üsttedir. closed ve all en geç saat önce gelir.

Mekanın her anahtarı, mekanın diğer anahtarlarıyla alınmış rezervasyonları da okuyabilir. Mekanın başka bir yoldan aldığı rezervasyonlar (Cibusy uygulamasından, cibusy.com'daki sayfasından ya da telefonla) listede yer almaz ve kimlikleriyle de okunamaz.

Rezervasyonları tekrar tekrar sorgulamak yerine webhook kullanın: rezervasyon değiştikçe sunucunuza reservation.updated olayı gelir. Bu olaylar siparişlerdeki gibi saniyeler içinde değil, yaklaşık bir dakika içinde gelir.

Rezervasyon durumu#

İptal etmek#

POST /reservations/{reservationId}/cancel, sitenizde fikrini değiştiren misafir içindir. İsteğe bağlı reason alanı mekanın okuması içindir:

curl -X POST "https://api.cibusy.com/public/v1/reservations/9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d/cancel" \
  -H "X-Api-Key: $CIBUSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Cuma akşamı gelemiyoruz."
  }'

• Misafirin iptalidir. Rezervasyonun cibusy.com'daki sayfasından yapılan iptalle aynıdır: cancelledBy değeri Customer olur ve mekana, verildiyse nedeniyle birlikte bildirilir.
• Ne zaman iptal edilebilir. Rezervasyon Pending ya da Confirmed iken, misafir kapıda karşılanmamışken ve saati gelmemişken. Rezervasyondaki canCancel bunu önceden söyler; iptal düğmesini ona göre gösterin. Aksi halde yanıt 409 RESERVATION_NOT_CANCELLABLE olur.
• İki kez göndermek güvenlidir. Kim iptal etmiş olursa olsun, zaten iptal edilmiş bir rezervasyonu iptal etmek onu olduğu haliyle 200 ile döndürür.

API'nin yapmadıkları#

• Saati ya da kişi sayısını değiştirmek. API bir rezervasyonu değiştirmez: iptal edip yenisini alın.
• Mekanın diğer rezervasyonlarını okumak. API yalnız kendi aldığı rezervasyonları gösterir; mekanın uygulamadan, kendi sayfasından ya da telefonla aldıkları dışarıda kalır.
• Masa seçmek. Bir rezervasyon bir saat ve kişi sayısı içindir; hangi masaya oturulacağına mekan karar verir.