Rezervasyonlar

Rezervasyon al

Sitenizin aldığı rezervasyonu mekana gönderin. Mekanın rezervasyon listesine düşer; hemen onaylanıp onaylanmayacağı mekanın ayarına bağlıdır.

POST/public/v1/venues/{venueId}/reservations

Kimlik doğrulama: X-Api-Key başlığında API anahtarı
Gereken izin: Rezervasyon alabilir
Hız sınırı: Anahtar başına dakikada yaklaşık 30 istek

Uyarı: Deneme ortamı yoktur. Gerçek bir anahtarla alınan rezervasyon, gerçek bir mekanın listesinde gerçek bir rezervasyondur ve çalışanlarına bildirilir. Geliştirirken yönettiğiniz bir mekanı kullanın ve oluşturduğunuz rezervasyonları iptal edin.

Sitenizin aldığı rezervasyonu gönderin. Yanıt, GET /reservations/{reservationId} adresini gösteren bir Location başlığıyla 201 Created olur. Rezervasyon diğer bütün rezervasyonların düştüğü yere düşer: mekanın kasadaki ve çalışan uygulamasındaki rezervasyon listesine, misafirin kendi yaptığı bir rezervasyonla aynı bildirimle. Ayrıntılar: Rezervasyon almak.

Saati müsaitlik çağrısından alın. startsAt UTC bir andır; müsait saatler yanıtındaki bir saatin startsAt değerini gönderin. guests 1 ile 20 arasındadır; misafirin adı en fazla 100, telefonu en fazla 30, not en fazla 250 karakterdir.

Onay mekanın ayarıdır. Rezervasyonları alındığı anda onaylayan bir mekanda yanıt Confirmed olur; diğerlerinde mekandan biri kabul ya da reddedene kadar Pending kalır. Mekanın saatine kadar yanıtlamadığı istek System tarafından iptal edilir. Hangisini bekleyeceğinizi müsaitlik yanıtındaki confirmsAutomatically söyler.

Misafire siz haber verirsiniz. Cibusy, API üzerinden alınan bir rezervasyon için misafire SMS göndermez: rezervasyonu siteniz aldı ve misafir haberi sitenizden bekler. Misafire yanıttaki pageUrl adresini ya da code değerini verin; mekan misafiri kapıda bununla karşılar.

İki kez göndermek güvenlidir ve Idempotency-Key gerekmez. Bir misafir aynı anda iki masada oturamaz; bu yüzden aynı telefon numarası için, aynı mekanda, aynı an için gönderilen ikinci istek, ilki hala geçerliyken aynı rezervasyondur. İlk çağrının aldığı rezervasyonu mekandaki güncel haliyle 200 OK olarak alırsınız ve mekana ikinci kez bildirilmez. İstek zaman aşımına uğrarsa değiştirmeden yeniden gönderin. Tekrar, mekanın kurallarına yeniden bakılmadan yanıtlanır, çünkü rezervasyon zaten vardır.

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: mekan rezervasyon alıyor olmalı (RESERVATIONS_DISABLED), en fazla 20 kişi (TOO_MANY_GUESTS), gelecekte bir saat (INVALID_RESERVATION_DATE), en az 30 dakika sonrası (RESERVATION_TOO_SOON), en çok 60 gün sonrası (RESERVATION_TOO_FAR) ve mekanın misafir aldığı bir saat (RESERVATION_TIME_UNAVAILABLE). Müsaitlik yanıtından alınan bir saat hepsinden geçer. Mekanın ayrıca etkin bir aboneliği olmalıdır (PUBLIC_API_RESERVATIONS_UNAVAILABLE). Bir hata isteğin bir kısmını adlandırıyorsa validationErrors hangisi olduğunu yoluyla söyler (customer.phone).

Rehber: Rezervasyon almak

Parametreler

venueIdstring · uuidYol parametresizorunlu

Mekan; GET /venues listesindeki kimliklerden biri.

Accept-LanguagestringBaşlık

Hata yanıtlarındaki userMessage metninin dili: tr (varsayılan), en, de, fr, it, es, ar ya da ru. Başlıktaki ilk dil belirler, bölgesi olmadan (en-US, en okunur) ve q ağırlıklarına bakılmadan; Cibusy'nin sunmadığı bir dil Türkçe yanıtlanır. Menünün dilini seçmez; o, menü çağrısındaki lang parametresidir.

İstek gövdesi

Mekanın sitesinin alıp gönderdiği rezervasyon. Alınıp alınamayacağına mekanın kendi rezervasyon kuralları karar verir; kabul edilecek saatleri GET /venues/{venueId}/reservation-availability listeler.

startsAtstring · date-timenull olabilir

Masanın ne zaman için olduğu, UTC bir an olarak. Müsaitlik yanıtındaki bir saatin startsAt değerinden alın. Zorunlu.

guestsintegernull olabilir

Kaç kişi geleceği: 1 ile 20 arası. Daha kalabalık bir grup mekanı arayarak yer ayırtır. Zorunlu.

customerobjectnull olabilir

Masanın kimin için olduğu. Zorunlu.

Misafir bilgisi alanları

namestringnull olabilir

Misafirin adı, en fazla 100 karakter. Zorunlu.

phonestringnull olabilir

Misafirin telefon numarası, uluslararası biçimde ya da yerelde yazıldığı gibi (+905321112233, 0532 111 22 33). En fazla 30 karakter. Zorunlu: mekan misafire bununla ulaşır ve tekrarlanan bir isteği ikinci bir rezervasyondan ayıran da budur.

notestringnull olabilir

Mekan için not, en fazla 250 karakter.

Yanıtlar

200

Tekrar: aynı telefon, mekan ve saat için zaten alınmış rezervasyon, mekandaki güncel haliyle.

201

Rezervasyon alındı. Location rezervasyonu gösterir; status onaylandığını (Confirmed) ya da mekanın yanıtını beklediğini (Pending) söyler.

Location

Rezervasyonun okunabileceği yer: /public/v1/reservations/{reservationId}.

400

PUBLIC_API_RESERVATION_INVALID, TOO_MANY_GUESTS ya da INVALID_RESERVATION_DATE.

401

X-Api-Key başlığı yok (PUBLIC_API_KEY_MISSING) ya da anahtar geçersiz veya iptal edilmiş (PUBLIC_API_KEY_INVALID).

403

PUBLIC_API_SCOPE_MISSING: anahtar "Rezervasyon alabilir" izniyle oluşturulmamış.

404

Mekan yok ya da bu anahtar ona ulaşamıyor (PUBLIC_API_VENUE_NOT_FOUND).

409

PUBLIC_API_RESERVATIONS_UNAVAILABLE, RESERVATIONS_DISABLED, RESERVATION_TOO_SOON, RESERVATION_TOO_FAR ya da RESERVATION_TIME_UNAVAILABLE.

429

Anahtarın siparişler, rezervasyonlar ve testler için dakikada yaklaşık 30 isteklik bütçesi doldu; Retry-After kadar saniye bekleyin.

Retry-After

Beklenecek saniye. Bir sonraki dakikalık pencere bu süre içinde açılır.

Başarılı yanıtın `data` alanı

API üzerinden alınmış bir rezervasyon, mekanda şu an olduğu haliyle. GET /reservations/{reservationId} yanıtının ve webhook'un reservation.updated olayının taşıdığı gövdenin aynısı.

idstring · uuid

Rezervasyonun kimliği. GET /reservations/{reservationId} ile kullanın.

venueIdstring · uuid

Masanın ayırtıldığı mekan.

statusstring

Rezervasyonun geldiği aşama; her okumada yeniden hesaplanır, bu yüzden liste, tek rezervasyon ve webhook olayı aynı rezervasyon için farklı şeyler söyleyemez.

Pending: Mekan henüz yanıtlamadı. Rezervasyonları alındığı anda onaylayan bir mekanda görülmez.
Confirmed: Mekan kabul etti ya da rezervasyonları alındığı anda onaylıyor. Masa bekleniyor.
Declined: Mekan isteği reddetti.
Cancelled: İptal edildi. Kimin iptal ettiğini `cancelledBy` söyler.
Seated: Misafir geldi ve kapıda karşılandı.
Completed: Ziyaret bitti.
NoShow: Mekan kabul etti ama kimse gelmedi.

startsAtstring · date-time

Masanın ne zaman için olduğu, UTC bir an olarak.

guestsinteger

Kaç kişi geleceği.

customerobject

Masanın kimin için olduğu, mekanda kayıtlı haliyle.

Rezervasyon sahibi alanları

namestringnull olabilir

Misafirin adı.

phonestringnull olabilir

Misafirin telefon numarası, uluslararası biçimde.

notestringnull olabilir

Rezervasyonun yapıldığı not. Not yoksa null.

codestringnull olabilir

Mekanın misafiri kapıda karşılarken kullandığı kod: misafirin söyleyebileceği ya da pageUrl sayfasındaki QR olarak gösterebileceği sekiz karakter. Kodu elinde tutan rezervasyonu görebilir ve iptal edebilir; yalnız misafire verin.

pageUrlstringnull olabilir

Rezervasyonun cibusy.com'daki kendi sayfası: rezervasyonu ve onaylandıktan sonra mekanın kapıda okuttuğu QR'ı gösterir. Bağlantısını verin ya da misafire gönderin. Herkese açık adresi olmayan mekanda null.

canCancelboolean

Rezervasyonun API üzerinden hala iptal edilip edilemeyeceği: geçerli, misafir kapıda karşılanmamış ve saati gelmemiş.

checkedInAtstring · date-timenull olabilir

Misafirin kapıda karşılandığı an (UTC). O zamana kadar null.

cancelledAtstring · date-timenull olabilir

Rezervasyonun iptal edildiği an (UTC). status değeri Cancelled değilse null.

cancelledBystringnull olabilir

Kimin iptal ettiği. status değeri Cancelled değilse null.

Customer: Misafir: bu API üzerinden, rezervasyonun kendi sayfasından ya da Cibusy uygulamasından.
Venue: Mekan.
System: Cibusy: mekan isteği, rezervasyonun saatine kadar yanıtlamadı.

cancellationReasonstringnull olabilir

İptal nedeni olarak söylenen, söyleyenin kendi sözleriyle. status değeri Cancelled değilse null.

createdAtstring · date-time

Rezervasyonun yapıldığı an (UTC).

İstek örneği

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."
  }'

Yanıt örneği

201 Created

{
  "success": true,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null,
  "data": {
    "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"
  },
  "message": "Operation completed successfully"
}

Hata örneği

400 Bad Request

{
  "success": false,
  "userMessage": "Rezervasyon isteği geçersiz. Tarihi, kişi sayısını ve müşteri bilgilerini kontrol edin.",
  "developerMessage": "The reservation request is not valid. guests: At least 1. customer.phone: Not a phone number.",
  "errorCode": "PUBLIC_API_RESERVATION_INVALID",
  "validationErrors": [
    {
      "field": "guests",
      "message": "At least 1.",
      "attemptedValue": null
    },
    {
      "field": "customer.phone",
      "message": "Not a phone number.",
      "attemptedValue": null
    }
  ],
  "details": null,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null
}

Rezervasyon al

Parametreler

İstek gövdesi

Yanıtlar

Başarılı yanıtın data alanı

Başarılı yanıtın `data` alanı