API’ye genel bakış

Kimin içinBT

CukoZ Suite API’si portallar tarafından sunucu tarafında çağrılır (BFF). İnternete açık olan tek kısım platform webhook’larıdır (https://api.cukoz.com/api/v1/hooks/*). Küme içinde API http://suite-api:8080 adresindedir.

Kimlik doğrulama

API iki yöntemi Authorization başlığına göre seçer:

1. Bearer <JWT> — CukoZ One’ın verdiği erişim belirteci (at+jwt). Yayıncı doğrulanır; client_id talebi cukoz.suite olmalıdır.
2. Terminal <cihaz sırrı> — eşlenmiş POS / mutfak ekranı cihazları için; isteğe bağlı X-Pos-Session başlığı personelin PIN oturumunu taşır. Talepler: device_id, org_id, branch_id, device_mode ve PIN oturumu varsa employee_id. Cihaz yalnızca kendi şubesine erişir; PIN oturumu olmadan yalnızca /terminal uçları yanıt verir.

İstek başlıkları

Başlık	Açıklama
Authorization	Bearer … veya Terminal …
X-Organization-Id	org_… kiracı kimliği
X-Branch-Id	Şube (isteğe bağlı; * = tüm şubeler, salt okunur)
Idempotency-Key	POST isteklerinde tekrar güvenliği için UUID

Açılış sırası: GET /api/v1/me → GET /api/v1/me/organizations → GET /api/v1/me/session (izinler ve menüleriyle birlikte modüller).

Yanıt biçimleri

• Liste: { items, page, pageSize, totalCount } (sayfa başına en fazla 200)
• Hata: { error, message, traceId }

Kod	error	Anlamı
400	tenant_required, branch_not_found	Eksik veya hatalı kiracı / şube
401	—	Kimlik doğrulanmadı
402	module_not_enabled, suite_not_subscribed	Modül veya abonelik yok
403	forbidden	İzin yok
409	alan hatası, concurrency, conflict	İş kuralı veya eşzamanlılık çakışması
429	rate_limited	Hız sınırı (Retry-After başlığıyla)
503	one_unavailable	CukoZ One’a ulaşılamıyor

Denetleyiciler

Tümü /api/v1 altında.

Yol	Modül	Amaç
/adisyon/orders	adisyon	Sipariş / adisyon
/adisyon/menu	adisyon	Menü
/adisyon/tables	adisyon	Masalar, salon planı, bölge ücretleri
/adisyon/kitchen	adisyon	Mutfak ekranı / expo
/adisyon/cash	adisyon	Kasa vardiyaları, kasa hareketleri
/adisyon/delivery	adisyon	Paket bölgeleri, kuryeler
/adisyon/service-requests	adisyon	Garson çağır / hesap iste
/terminal	—	pair, lock, login, session, logout, clock-in, clock-out, break
/terminal-payments	adisyon	Kartla ödemeyi cihaza gönderme (Ödeal)
/devices	adisyon	Cihaz kaydı, eşleme kodu, iptal
/approvals	—	Uzaktan onay kuyruğu (X-Approval-Id)
/reasons	—	Gerekçe listeleri
/employees	—	Personel, PIN, ücret, puantaj
/roles	—	Roller ve atamalar
/branches	core	Şubeler
/settings/business-profile	—	İşletme profili
/management	—	Flash rapor, prime cost, anomaliler, işletme tipi/boyutu, işletme varsayılanları
/contacts	core	Cari kartlar ve cari hareketler
/marketing	core	Sadakat (para-puan), kuponlar
/inventory	inventory	Stok, hareketler, alışlar
/inventory/purchasing	inventory	Satın alma siparişleri, mal kabul, öneriler, tedarikçi performansı
/inventory/counts	inventory	Sayım oturumları
/inventory/recipes	inventory	Reçeteler
/accounting	accounting	Giderler, sabit giderler, hakediş, kâr-zarar, nakit akışı
/reservations	reservation	Rezervasyonlar ve bekleme listesi
/reports	reports	Salt okunur raporlar
/insights	adisyon	Tahmin (hava durumu, özel günler)
/ops, /ops/assets	operations	Kontrol listeleri, görevler, defter, gıda güvenliği, olaylar, otomasyon; demirbaş ve bakım
/integrations	—	Entegrasyon bağlama ve test (sırlar salt yazılır)
/audit	—	Salt okunur denetim kaydı
/modules	—	Tüm modüller ve /enabled
/me	—	Açılış uçları
/public/business	anonim	qr.cukoz.com slug çözümleyici, herkese açık rezervasyon
/public/qr/{orgId}/{tableId}	anonim	QR menü ve sipariş
/public/feedback/{orgId}	anonim	İmzalı misafir değerlendirmesi
/hooks	anonim	Gelen webhook’lar

Geliştirme ortamında (veya Swagger:Enabled açıkken) /swagger kullanılabilir.

Hız sınırları

Sınırlar düğüm başınadır; aşıldığında 429 ve Retry-After döner.

Politika	Sınır	Kullanım
Genel, oturum açık	Kullanıcı veya cihaz başına 600 / dk	Tümü
Genel, anonim	IP başına 300 / dk	Tümü
guest-read	IP başına 120 / dk	QR menü, işletme sayfası, değerlendirme
guest-order	IP başına 5 dakikada 10; ayrıca masa başına 5 dakikada 8	QR sipariş
reservation	IP başına 10 dakikada 5	Online rezervasyon
pairing	IP başına 10 / dk	terminal/pair
heavy	Kullanıcı başına 120 / dk	Raporlar, muhasebe, tahmin
costly	Kullanıcı başına 10 / dk	Maliyetli entegrasyon işlemleri

Sağlık ve tanılama

Hız sınırına tabi değildir:

• /health/live — süreç ayakta
• /health/ready (ve /health) — veritabanı erişilebilir
• /metrics — Prometheus (yalnızca küme içi)
• / — servis, sürüm, düğüm bilgisi (JSON)

Webhook’lar

Entegrasyon kimliği (integrationId) kiracıyı belirler. Webhook’lar adisyon modülünün ve ilgili platform özelliğinin açık olmasını gerektirir.

Uç	Doğrulama	Olay
POST /api/v1/hooks/yemeksepeti/{integrationId}/order/{remoteId}	Mağaza plugin sırrıyla imzalı HS512 JWT	Yeni sipariş
PUT /api/v1/hooks/yemeksepeti/{integrationId}/remoteId/{remoteId}/remoteOrder/{remoteOrderId}/posOrderStatus	Aynı	ORDER_CANCELLED adisyonu iptal eder
POST /api/v1/hooks/odeal/{integrationId}/{outcome}	Geri çağırma URL’sindeki gizli belirteç	Ödeme başarılı / başarısız / iptal

Trendyol Go siparişleri webhook yerine 30 saniyede bir çekilir. Kullanıcı tarafı kurulum: Entegrasyonlar.