Temeller

Kimlik doğrulama

API anahtarının nasıl gönderildiği, anahtarın izinleri ve anahtarı neden yalnız sunucunuzda tutmanız gerektiği.

Cibusy API'ye yapılan her çağrı, mekanınızın API anahtarını X-Api-Key başlığında taşır. Anahtar, hangi mekanlara ulaşabileceğinizi ve neler yapabileceğinizi belirler.

Anahtarı göndermek#

Anahtarı her isteğe X-Api-Key başlığıyla ekleyin. Bütün çağrılar HTTPS üzerinden yapılır.

Shell

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

Anahtarlar cbk_ ile başlar. Panelde her anahtarın yalnız ilk karakterleri görünür; bu kısım anahtarı tanımanıza yeter ama onunla istek yapılamaz.

Anahtar oluşturmak#

Anahtarları mekanın sahibi, Cibusy paneline mekan hesabıyla girerek API Anahtarları sayfasından oluşturur. Çalışan hesapları anahtar oluşturamaz.

Her entegrasyona ayrı bir anahtar. Anahtarın adı, onunla gelen siparişlerde de görünür; mekanınız bir siparişin web sitesinden mi, başka bir yazılımdan mı geldiğini adından anlar. Ayrı anahtarlar, birini diğerlerine dokunmadan iptal etmenizi de sağlar.
Bir kez gösterilir. Anahtar yalnız oluşturulduğu an gösterilir. Cibusy anahtarın kendisini değil, yalnız özetini (hash) saklar; kaybolan bir anahtar geri getirilemez, iptal edilip yerine yenisi oluşturulur.
En fazla 10 anahtar. Bir mekanın aynı anda en fazla 10 çalışan anahtarı olabilir. Yenisine yer açmak için kullanmadığınız birini iptal edin.

İzinler#

Her anahtarda bir izin hep açıktır; diğer ikisini anahtarı oluştururken ya da sonradan, birbirinden bağımsız olarak açarsınız.

İzin	Neye izin verir
Menüyü okuyabilir (her anahtarda)	Anahtarın ulaştığı mekanları listelemek; bir mekanın bilgilerini, menüsünü ve masalarını okumak.
Sipariş gönderebilir (isteğe bağlı)	Sepeti fiyatlandırmak, sipariş vermek, siparişleri okumak ve test webhook'u göndermek.
Rezervasyon alabilir (isteğe bağlı)	Mekanın müsait saatlerini okumak, rezervasyon almak, rezervasyonları okumak ve iptal etmek; test webhook'u göndermek.

Bir anahtarın izinlerini panelde Düzenle ile değiştirebilirsiniz; değişiklik anahtarın bir sonraki isteğinde geçerli olur. İzni olmayan bir çağrı 403 PUBLIC_API_SCOPE_MISSING ile yanıtlanır.

Bir anahtara yalnız gereken izni verin. Yalnız menünüzü gösteren bir site için ikisini de açmayın; yalnız rezervasyon alan bir site için Sipariş gönderebilir iznini açmayın. Anahtar bir gün yanlış ellere geçse bile mutfağınıza sipariş düşüremez.

Anahtarı sunucunuzda tutun#

Anahtar, mekanınızın kimlik bilgisidir. Sunucunuzun yapılandırmasında tutun: bir ortam değişkeninde ya da kullandığınız gizli bilgi yöneticisinde. Bir web sayfasına, mobil uygulamaya ya da kod deposuna koymayın.

Tarayıcıdan yapılan çağrılara izin verilmez. API başka sitelerden gelen çapraz kaynak (CORS) isteklerini kabul etmez; üstelik bir sayfaya konan anahtarı, sayfayı açan herkes kopyalayabilir. Doğru düzen şudur:

Text

Web sayfası ya da uygulama  →  sizin sunucunuz (anahtar burada)  →  api.cibusy.com

Sayfanız ya da uygulamanız kendi sunucunuzu çağırır, sunucunuz da anahtarla Cibusy'yi. Bu düzen menünün bir kopyasını sunucunuzda tutmanızı da kolaylaştırır.

Anahtarı yenilemek#

Bir anahtarı kesinti olmadan değiştirmek için:

Panelde aynı izinlerle yeni bir anahtar oluşturun. Webhook kullanıyorsanız adresi yeni anahtara da girin; imza sırrı her anahtarın kendisinedir.
Yeni anahtarı ve sırrı sunucunuza girin, isteklerin yeni anahtarla gittiğini doğrulayın.
Eski anahtarı İptal Et ile iptal edin.

Mekanın her anahtarı, mekanın diğer anahtarlarıyla verilmiş siparişleri ve alınmış rezervasyonları da okuyabilir; anahtarı değiştirdiğinizde bunları gözden kaybetmezsiniz.

Uyarı: İptal edilen bir anahtarla verilmiş siparişler ve alınmış rezervasyonlar için webhook bildirimi gönderilmez. Eski anahtarla verilmiş açık siparişleriniz ya da bekleyen rezervasyonlarınız varsa bunları GET /orders/{orderId} ve GET /reservations/{reservationId} ile takip edin ya da eski anahtarı onlar sonuçlandıktan sonra iptal edin.

Anahtarı iptal etmek#

İptal edilen anahtar bir sonraki isteğinde çalışmayı bırakır ve yeniden açılamaz. Onunla gelmiş siparişler mekanda olduğu gibi kalır.

Hesabını kapatan bir mekanın bütün anahtarları da hemen durur.
Cibusy ekibi de bir anahtarı iptal edebilir. Böyle bir anahtar panelde iptal edilmiş olarak görünür.
Anahtarın ele geçtiğinden şüpheleniyorsanız beklemeden iptal edin ve yenisini oluşturun.

Abonelik sona erdiğinde#

Aboneliği sona ermiş bir mekanın anahtarı, QR menüde olduğu gibi mekanı, menüyü, masaları ve müsait saatleri okumaya devam eder. Sipariş ise abonelik yeniden etkinleşene kadar 409 PUBLIC_API_ORDERING_UNAVAILABLE, rezervasyon 409 PUBLIC_API_RESERVATIONS_UNAVAILABLE ile reddedilir.

Kimlik doğrulama hataları#

Yanıt	Anlamı
`401` `PUBLIC_API_KEY_MISSING`	İstekte `X-Api-Key` başlığı yok.
`401` `PUBLIC_API_KEY_INVALID`	Anahtar hatalı yazılmış, tanınmıyor ya da iptal edilmiş, ya da mekan hesabını kapatmış. Hangisi olduğunu söylemeyen tek bir yanıttır.
`403` `PUBLIC_API_SCOPE_MISSING`	Anahtar geçerli ama bu çağrının gerektirdiği izin yok: Sipariş gönderebilir ya da Rezervasyon alabilir.

Bir anahtarın ulaşamadığı mekan 404 PUBLIC_API_VENUE_NOT_FOUND ile yanıtlanır; Mekanlar ve şubeler rehberi bunun nedenini anlatıyor.