Restomenum Geliştirici
Giriş yapKayıt ol

Ödeme Cihazları — /plugin-api/connectors/* ✓ Canlı

Kendi terminal POS markanı Restomenum'a bağlamak için cihaz yönetimi: kayıt kodu üret, cihazlarını listele, devre dışı bırak. Platform yalnız eklentinin bulutu ile restorandaki terminal programı arasında hızlı ve güvenli iletişimi sağlar; cihazın sahibi eklentidir. Her eklenti YALNIZ kendi cihazlarını yönetir.

← API Uçları · Tahsilat sonucu: payments/status · Cihaz agent'ı sözleşmesi: kimlik tazeleme + imza.

Sahiplik — zincir kayıt kodundan geçer

Kayıt kodunu üreten eklenti, o kodla kaydolan cihazın sahibi olur. Sahiplik bütün uçlarda sınırdır: listeleme kendi cihazlarını döner, devre dışı bırakma yalnız kendi cihazında çalışır. Aynı restoranda birden çok terminal sağlayıcısı olabilir ve birbirlerinin cihazlarını göremezler.

Sürpriz olabilecek iki davranış — ikisi de bilinçli:

1️⃣ Başka bir sağlayıcının cihazı 404 "bulunamadı" döner, "senin değil" DEĞİL. Sebebi: "senin değil" yanıtı, aynı restorandaki diğer sağlayıcının cihaz kimliklerini taramaya izin verirdi (var/yok ayrımı sızdırırdı). Bu yüzden yetkisiz erişim ile var olmayan kayıt aynı görünür — kendi kodunda "404 = silinmiş" varsayma.

2️⃣ Sahipsiz cihaz kimse tarafından yönetilemez. Sahiplik modelinden önce kaydedilmiş cihazların sahibi null'dır ve hiçbir eklenti onlara dokunamaz. "Sahipsizi herkes yönetebilir" saymak, açıkça kimseye verilmemiş bir yetkiyi herkese vermek olurdu.

Kayıt kodu üret

POST {RESTOMENUM_BASE}/plugin-api/connectors/code
Authorization: Bearer <apiKey>          // scope: terminals:write (ELEVATED)

{}                                       // gövde GEREKMİYOR

// 200
{ "success": true, "data": { "code": "D29Z3XM3VE", "expiresAt": 1788612904453 } }

Yeni bir cihazı restorana bağlamak için kod üretirsin; cihaz bu kodla kaydolur ve senin cihazın olur. İstek gövde istemez.

  • code — 10 karakter (A-Z2-9, ~50 bit).
  • TTL 10 dakika ve tek kullanımlık — kullanıcıya göstermeden hemen önce üret, önden yığıp saklama.
  • expiresAt epoch milisaniye.
terminals:write YÜKSEK YETKİDİR (ELEVATED). Kayıt kodu üretmek, restorana gerçek tahsilat yapacak yeni bir cihazın bağlanmasına izin vermektir. payments:write ve capability:payment.terminal:provide ile aynı ailededir; kiracı kurulum ekranında ne onayladığını açıkça görür.

Cihazlarını listele

GET {RESTOMENUM_BASE}/plugin-api/connectors/list
Authorization: Bearer <apiKey>          // scope: terminals:read

// 200 — data DÜZ DİZİ (sarmalayıcı nesne değil)
{ "success": true, "data": [
  { "id": "conn_4c81bac2a106548e9a", "status": "active", "platform": "windows",
    "version": "1.0.3", "lastSeen": null, "enrolledAt": 1788612303497 }
] }

// hiç cihaz yoksa
{ "success": true, "data": [] }
lastSeen = son oturum token'ı verilme zamanı — telemetri, canlılık DEĞİL. Alan kayıtta null başlar ve yalnız cihaz oturum token'ı aldığında güncellenir (kod yolu doğrulandı).

⚠️ lastSeen !== null yalnız "bir zaman token almış" demektir; "şu an bağlı" DEMEK DEĞİLDİR. Bu çıkarım sahada bir kez yapıldı ve hata ayıklamayı yanlış yere yönlendirdi: alan "bağlı" derken cihaz gerçekte hata alıyordu.

⚠️ null da ispat değil: güncelleme telemetri olarak yapılır ve hatası yutulur → token verilmiş olsa bile alan null kalabilir. Yani null "muhtemelen hiç bağlanmadı" için güçlü bir ipucudur, kesinlik değil. Cihazın çalıştığını ödemenin kendi sonucundan öğren.

Yalnız senin sahip olduğun cihazlar döner — terminals:read. Aynı restorandaki başka sağlayıcıların cihazları listende yer almaz; bu bir filtre değil, sahiplik sınırıdır.

Cihazı devre dışı bırak

POST {RESTOMENUM_BASE}/plugin-api/connectors/revoke
Authorization: Bearer <apiKey>          // scope: terminals:write (ELEVATED)

{ "connectorId": "conn_4c81bac2a106548e9a" }

// 200 — SİLMEZ, disabled yapar
{ "success": true, "data": { "connectorId": "conn_4c81bac2a106548e9a", "status": "disabled" } }

// hatalar
{ "success": false, "message": "plugin.connector.notFound",   "status": 404 }
{ "success": false, "message": "plugin.connector.idRequired", "status": 400 }
{ "success": false, "message": "plugin.scope.denied",         "status": 403 }

Çalışan bir terminali durdurur — bu yüzden terminals:write (ELEVATED) ister. Yalnız kendi cihazında çalışır; başkasının cihazı için 404 alırsın (yukarıdaki sahiplik notu).

İptal SİLMEZ — disabled yapar. Cihaz list çıktısında görünmeye devam eder, yalnız status alanı "disabled" olur (denetim izi). Listeyi "aktif cihazlar" sanıp doğrudan kullanma — status'a bak.