Mekanlar ve şubeler

Bir API anahtarı, oluşturulduğu mekana bağlıdır. Bu rehber bir anahtarın hangi mekanlara ulaştığını; bir mekanın bilgilerini, çalışma saatlerini ve masalarını; mekanın şu an sipariş alıp almadığını anlatıyor.

Anahtarın ulaştığı mekanlar#

GET /venues anahtarın ulaştığı mekanları listeler; anahtarın kendi mekanı önce gelir. Bir mekanla ilgili bütün çağrılar o mekanın id değerini adresin içinde alır.

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

Anahtarın ulaşamadığı bir mekan, var olmayan bir mekan gibi 404 PUBLIC_API_VENUE_NOT_FOUND ile yanıtlanır. Böylece bir anahtar, kendi mekanları dışında hangi mekanların var olduğunu hiçbir zaman öğrenemez.

Birden çok şube için tek bir entegrasyon kuruyorsanız merkezin anahtarını kullanın ve şubelerin kimliklerini GET /venues yanıtından alın. Her şubenin kendi anahtarı da olabilir; o anahtar yalnız kendi şubesine ulaşır.

Mekanın bilgileri#

GET /venues/{venueId} bir mekanın sitesinin ihtiyaç duyduğu her şeyi verir: adı ve logosu, adresi ve haritadaki yeri, saat dilimi, çalışma saatleri, menüsünün dilleri ve sipariş durumu.

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

• timeZone mekanın saat dilimidir, örneğin Europe/Istanbul. Çalışma saatleri ve ordering içindeki saatler bu dilimdeki saatlerdir.
• workingHours mekanın girdiği günleri pazartesiden başlayarak listeler. opensAt ve closesAt "HH:mm" biçimindedir; bütün gün kapalı bir günde isClosed true olur. Gece yarısından sonra kapanan bir günde closesAt, opensAt değerinden küçüktür: cuma 11:00–01:00 gibi. Mekanın girmediği bir gün listede yer almaz.
• languages menünün sunulduğu dilleri listeler, varsayılan dil önce. Menüyü bu kodlardan biriyle istersiniz.

Bütün alanlar ve anlamları Mekanı oku referansında.

Şu an sipariş alıyor mu?#

Bir sipariş düğmesini göstermeden önce ordering nesnesine bakın. Mekan sipariş almak için üç koşulu birden sağlamalıdır:

1. Etkin bir abonelik. Aboneliği sona ermiş mekan menüsünü göstermeye devam eder ama sipariş almaz.
2. Yoğunluk bildirimi olmaması. Mekanın mutfağı yoğunluk bildirdiğinde busyUntil yoğunluğun bittiği anı (UTC) söyler, busyReason da mekanın misafirlerine yazdığı açıklamayı.
3. Çalışma saatleri içinde olmak. Mekan bu kuralı kapatmadıysa sipariş yalnız çalışma saatleri içinde, mekanın iki yana tanıdığı toleransla kabul edilir. opensAt ve closesAt bugünün saatleridir; mekan kuralı kapattıysa, bugün için saat girmediyse ya da yoğunluk sürerken null olur.

acceptingOrdersNow bu üçünü birlikte değerlendirir ve her çağrıda yeniden hesaplanır.

acceptingOrdersNow yalnız bir ipucudur: durum iki çağrı arasında değişebilir. Siparişin kabul edilip edilmediğini her zaman siparişi gönderdiğinizde aldığınız yanıt söyler. Mekan o an sipariş almıyorsa yanıt 409 olur: PLACE_IS_BUSY, OUTSIDE_WORKING_HOURS ya da PUBLIC_API_ORDERING_UNAVAILABLE.

QR menüde misafir için geçerli iki kural API'de uygulanmaz: misafirin konumu (bir web sitesi bunu veremez) ve QR menüyü yalnızca menü olarak açan ayar.

Masalar#

Masada verilen bir sipariş, masanın kimliğini taşır. GET /venues/{venueId}/tables mekanın masalarını alanlarına (salon, bahçe, kat) göre gruplanmış olarak verir:

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

Alanlar ve içlerindeki masalar, mekanın kasasında göründükleri sırayla gelir. code, masanın QR kartında yazan koddur; kendi QR kartlarınızı basıyorsanız masayı bu koddan tanıyabilirsiniz. capacity masanın kaç kişilik olduğudur ve mekan belirtmediyse null olur.

Masalar sık değişmez: listeyi bir kez okuyup sunucunuzda tutun ve ara sıra yenileyin.