Kimlik doğrulama

Üç anahtar ailesi var. Hangisini taşıdığınız hangi uçlara erişebildiğinizi belirler.

Aile	Nerede kullanılır	Nasıl taşınır	Kim üretir
Oturum anahtarı (JWT)	`/api/v1/restaurants/me/*`	`Authorization: Bearer <JWT>`	Restoran, panele girerek
`vnrs_live_…`	`/api/v1/pos/*`	`Authorization: Bearer vnrs_live_…`	Restoran, panelden
`vnps_live_…`	`/api/v1/b2b/*`	`Authorization: Bearer vnps_live_…`	Veni, anlaşma sonrası

Test ortamının anahtarı vnrs_test_ ön ekiyle gelir ve yalnız POS uçlarında kullanılır — Test ortamı.

Ortak kurallar:

Düz metin anahtar yalnız oluşturma yanıtında bir kez döner. Veritabanında yalnız özeti durur; kaybederseniz geri okutamayız, yenisini üretirsiniz.
Ön eki koda sabitlemeyin. Kimlik doğrulama ön eke değil anahtarın kendisine bakar; ön ek yalnız okuma kolaylığı içindir.

Ortam anahtarın içinde taşınır ve eşleşme ÇİFT yönlüdür

Anahtarın ortamı (_live_ / _test_) gövdesinde durur ve her istekte denetlenir:

_test_ anahtar yalnız test restoranına çözülür
_live_ anahtar yalnız aktif restoranlara çözülür

Diğer her bileşim 401 döner. Böylece test anahtarı gerçek müşteri verisine ulaşamaz ve "testte çalıştı, canlıda çalışmıyor" sınıfı hatalar ortam karışmasından doğmaz.

POS anahtarı

Restoran panelinde Ayarlar → Entegrasyon (POS/API) altından üretilir; aynı işlem uçlardan da yapılabilir.

POST/api/v1/restaurants/me/api-keysRestoran JWT

json

{ "name": "POS entegrasyonu", "role": "pos_push", "integrator_key": "pos.firmaniz" }

Alan	Zorunlu	Kural
`name`	evet	1–60 karakter
`role`	hayır	`read_mirror` (varsayılan) ya da `pos_push`
`integrator_key`	evet	Anahtarın bağlanacağı entegratör. Anlaşması aktif olmalı, yoksa `422`

Yanıtta key alanı düz metin anahtarı taşır — yalnız bu bir kez.

json

{
  "data": {
    "id": "…",
    "name": "POS entegrasyonu",
    "role": "pos_push",
    "integrator_key": "pos.firmaniz",
    "key_prefix": "vnrs_live_xxxxxxxx",
    "is_active": true,
    "created_at": "2026-10-12T09:14:07Z",
    "key": "vnrs_live_… (yalnızca şimdi)"
  },
  "meta": { "request_id": "01JB2K9X7Q" }
}

Listeleme GET /api/v1/restaurants/me/api-keys, iptal DELETE /api/v1/restaurants/me/api-keys/{keyID}. Restoran başına en çok 10 aktif anahtar.

key_prefix anahtarın ilk 18 karakteridir; panelde hangi anahtarın hangisi olduğunu ayırt etmek için. last_used_at anahtarın gerçekten kullanılıp kullanılmadığını gösterir.

Anlaşma kapanırsa anahtar ölür

Bir entegratörün anlaşması sona ererse o entegratöre verilmiş bütün anahtarlar bir sonraki istekte 401 döner ve aynı entegratöre bağlı webhook'lar bir sonraki teslimatta durur. Ayrı bir iptal adımı yoktur; kapı her istekte kontrol edilir.

Yetki: scope

Scope, bir anahtarın neye erişebileceğini sınırlar. POS anahtarında rol scope'lara çevrilir: read_mirror okuma yetkisi alır, pos_push ek olarak menü yazma yetkisi alır. Yetkisi olmayan çağrı 403 döner.

Scope	Ne verir	Kimin anahtarına verilebilir
`analytics:read`	Özet analitik verisini okur.	PartnerPlatform
`customer_marketing_consent:read`	Ticari ileti izni durumunu okur (İYS / 6563).	PartnerRestoran
`customer_pii:read`	Müşterinin kişisel verisini (ad, telefon, adres) okur. Ayrı tutulur; hukuki hazırlık tamamlanmadan hiçbir anahtara verilmez.	Kurye şirketiRestoran
`deliveries:cancel`	Açılmış teslimat talebini iptal eder.	Kurye şirketiPartner
`deliveries:read`	Teslimat taleplerini ve durumlarını okur.	Kurye şirketiPartner
`deliveries:write` kapsar: `deliveries:read`	Kurye ve teslimat talebi açar.	Kurye şirketiPartner
`invoices:read`	Fatura kayıtlarını okur.	PartnerRestoran
`menu:read`	Menüyü ve ürün listesini okur.	PlatformRestoran
`menu:write` kapsar: `menu:read`	Menüyü yazar; ürün stok/erişilebilirlik durumunu değiştirir.	Restoran
`order_accept:write`	Gelen siparişi kabul eder ya da reddeder.	Restoran
`order_status:write`	Siparişin durumunu ilerletir (hazırlanıyor, hazır gibi).	Restoran
`orders:read`	Siparişleri okur.	PartnerPlatformRestoran
`orders:write` kapsar: `orders:read`	Sipariş oluşturur ve günceller.	PartnerPlatformRestoran
`reports:read`	Rapor çıktılarını okur.	PartnerRestoran
`restaurants:read`	Restoran/şube listesini okur.	PartnerPlatform
`store_status:write`	Şubenin siparişe açık/kapalı durumunu değiştirir.	Restoran
`webhooks:manage`	Webhook aboneliklerini oluşturur, günceller ve siler.	PartnerRestoran

Yazma yetkisi okumayı kapsar (menu:write olan anahtar menu:read gerektiren ucu da çağırabilir); tersi olmaz.

Partner teslimat uçlarında yetki

Partner anahtarıyla erişilen teslimat uçlarında yetki uç başına kontrol edilir:

Uç	Gereken yetki
`POST /api/v1/b2b/deliveries`	`deliveries:write`
`GET /api/v1/b2b/deliveries`	`deliveries:read`
`GET /api/v1/b2b/deliveries/{id}`	`deliveries:read`
`PATCH /api/v1/b2b/deliveries/{id}/cancel`	`deliveries:cancel`

İptal ayrı bir yetkidir ve deliveries:writetan türemez; deliveries:write yalnız deliveries:readi kapsar. Böylece "teslimat açabilen ama iptal edemeyen" ya da yalnız okuyan bir anahtar üretilebilir.

Anlaşmanızda aksi kararlaştırılmadıysa anahtarınız üç yetkinin tamamını taşır. Daha dar bir anahtar istiyorsanız hangi yetkilere ihtiyacınız olduğunu söyleyin. Yetkisiz çağrı 403 b2b.scope.insufficient döner — bu 401 değildir, anahtarınızı yenilemeniz gerekmez.

Hız sınırı

Yüzey	Sınır	Aşılırsa
POS API	Anahtar başına dakikada 120 istek	`429` + `Retry-After` (saniye)
POS API (test anahtarı)	Ek olarak günlük 5.000 istek	`429 pos.quota.exceeded`, `Retry-After` gün sonuna kadar
Partner API	Partner başına ayarlanır (anlaşmada belirlenir)	`429`
Tüm `/pos` ve `/b2b` trafiği	Kaynak IP başına dakikada ~320 istek	`429 rate_limit.exceeded`

⚠️ IP başına kova anahtar başına kovadan ayrıdır ve /pos ile /b2b trafiğinizin tamamı onu paylaşır: tek sunucudan çok restoranın anahtarıyla çağrı yapıyorsanız hiçbir anahtar 120'yi aşmasa bile 429 alabilirsiniz.

Retry-After başlığını okuyup o kadar bekleyin; sabit aralıklarla yeniden denemek sınırı daha hızlı doldurur.

Hata yanıtları

Durum	Ne oldu
`401`	Anahtar geçersiz, iptal edilmiş, süresi dolmuş, restoran askıda, entegratör anlaşması kapanmış ya da anahtar başka ortama ait. Hepsi aynı yanıtı verir — hangisi olduğunu söylemek anahtar deneyen birine bilgi vermek olurdu.
`403`	Anahtar geçerli ama bu uç için yetkisi yok.
`422`	Anahtar üretilirken entegratör verilmedi ya da entegratörün aktif anlaşması yok.
`429`	Hız sınırı ya da günlük kota aşıldı.
`503`	Yetki kontrolü geçici olarak yapılamıyor. Anahtarınızda sorun yok; bekleyip tekrar deneyin.

Partner anahtarlarında bir durum daha var: allowlist dışındaki bir IP'den gelen istek, anahtar doğru olsa bile reddedilir.

Süre dolumu

Anahtarların son kullanma tarihi olabilir. Dolmasına 30, 7 ve 1 gün kala api_key.expiring olayı gönderilir; aboneliğiniz varsa haberiniz olur ve kesintisiz yenilersiniz. Olay kataloğu: Olaylar.

Anahtarı saklamak

Sunucu tarafında tutun. Tarayıcıya, mobil uygulamaya ya da depoya koymayın.
Ortam değişkeni ya da bir sır yöneticisi kullanın.
Sızdığından şüpheleniyorsanız önce yenisini üretin, geçişi yapın, sonra eskisini iptal edin.

Kimlik doğrulama ​

POS anahtarı ​

Yetki: scope ​

Partner teslimat uçlarında yetki ​

Hız sınırı ​

Hata yanıtları ​

Süre dolumu ​

Anahtarı saklamak ​