POS API

Adisyon ya da POS yazılımınızı Veni'ye bağlar: menüyü siz yazar, siparişleri siz okur, durumu siz ilerletirsiniz. Restoranın panele girmesi gerekmez.

Önkoşul: Veni ile entegratör anlaşması imzalanır; sonra müşteriniz olan restoran kendi panelinden anahtarı üretip sizi seçer. Anlaşma kapanırsa o entegratöre verilmiş bütün anahtarlar bir sonraki istekte geçersiz olur.

Kimlik

Authorization: Bearer vnrs_live_…

Anahtar tek bir restoranı temsil eder; o restoranın dışındaki hiçbir veriye erişmez. Üretimi ve rolleri: Kimlik doğrulama.

Rol	Okuma	Menü yazma
read_mirror	✔	✘ (403)
pos_push	✔	✔

Uçlar

Uç	Ne yapar
GET /api/v1/pos/menu	Menüyü okur (kategoriler + ürünler)
PUT /api/v1/pos/menu	Tam katalogu yazar
POST /api/v1/pos/menu/items/{externalID}/availability	Tek ürünün stok ve fiyatını günceller
GET /api/v1/pos/orders	Siparişleri listeler
GET /api/v1/pos/orders/{orderID}	Tek siparişi okur
POST /api/v1/pos/orders/{orderID}/status	Sipariş durumunu ilerletir

Ayrıntılar: Menü · Siparişler

Test anahtarıyla bir uç daha açılır: POST /api/v1/pos/sandbox/orders — Test ortamı.

Hız sınırı

Anahtar başına dakikada 120 istek. Aşarsanız 429 pos.rate_limit.exceeded ve Retry-After başlığı (saniye) döner. Toplu menü senkronunu tek PUT ile yapın; ürün ürün döngü kurmayın.

⚠️ İkinci bir katman var: kaynak IP başına dakikada ~320 istek 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 rate_limit.exceeded alabilirsiniz (ayrıntı).

Tipik akış

1. Menüyü bir kez yazın (PUT /pos/menu). İlk yazım taslak olarak düşer ve restoranın panelden onayını bekler; yanıtta mode: "draft" ve import_id gelir. Böylece bir eşleme hatası restoranın menüsünü sessizce bozmaz.
2. Onayı bekleyin. ⚠️ Taslak onaylanmadan menü POS-yönetimli olmaz ve o ana kadar POST …/availability 409 pos.menu_not_pos_managed döner. Onaydan sonra PUT /pos/menu yanıtı mode: "applied" olur — bunu yoklama ölçütü olarak kullanabilirsiniz.
3. Stok ve fiyat değişikliğini anlık geçin (POST …/availability). Tam katalogu yeniden göndermeniz gerekmez. Eşleşmeyen external_id için 404 pos.item_not_mapped alırsınız.
4. Siparişleri alın. İki yol var ve birlikte kullanılabilir: webhook'a abone olun (Başlangıç) ya da GET /pos/orders ile sorun. Webhook daha hızlıdır; sorgulama yedek olarak işe yarar.
5. Durumu ilerletin (POST …/status). Adisyonda onaylanan sipariş Veni'de de kabul edilmiş olur.

Bağlantıyı koparmak

Restoran panelden senkronu durdurabilir; menü kaynağı manuele döner ve panel kilidi kalkar. Bu bir restoran kararıdır, sizin ucunuzdan tetiklenmez.

Hatalar

Durum	Kod	Ne oldu
400	validation.failed · validation.invalid_json · pos.item.invalid	Gövde JSON olarak çözülemedi ya da alan kuralları tutmadı; hangi alan olduğu error.details içinde
401	pos.auth.missing · pos.auth.invalid	Başlık yok; ya da anahtar geçersiz/iptal/süresi dolmuş, restoran askıda, entegratör anlaşması kapanmış, anahtar başka ortama ait — hepsi aynı yanıtı verir
403	pos.scope_missing	Anahtarın rolü bu işlem için yetersiz (tipik olarak read_mirror ile menü yazmak)
404	pos.item_not_mapped	external_id eşleşmiyor
409	pos.menu_not_pos_managed · pos.source_mismatch · order.not_paid	Menü henüz POS-yönetimli değil · source mevcut entegratörle çelişiyor · online ödeme onaylanmadan sipariş kabul edilemez
422	pos.menu_invalid · pos.source_required · invalid_transition	İş kuralı reddi: menü doğrulaması, ilk importta eksik source, izinsiz durum geçişi
429	pos.rate_limit.exceeded · rate_limit.exceeded · pos.quota.exceeded	Anahtar başına, IP başına ya da (test anahtarında) günlük sınır aşıldı; Retry-After kadar bekleyin
503	pos.gate.unavailable	Yetki kontrolü geçici olarak yapılamıyor. Anahtarı yenilemeyin, bekleyip tekrar deneyin

⚠️ 400 ile 422 ayrımı: 400 alan hatasıdır (isteği düzeltin), 422 iş kuralı reddidir (istek değişmeden sonuç değişmez).

Hata gövdesinin şekli ve ortak alanlar: Hatalar.