Panel — QR & Terminaller

Bu uçları kim çağırır?Merchant panel

Taban yol: /api/panel/v1/wallet
Kimlik: Panel oturumu (JWT) — Authorization: Bearer <panel access token>. Token panel girişinden gelir; s2s imza anahtarı bu uçları AÇMAZ.
Yetki: RBAC izin kodu: wallet:qr:read · wallet:qr:manage · wallet:terminal:read · wallet:terminal:manage · wallet:sponsor-policy:manage · wallet:sponsor-policy:approveDört-göz: isteği yapan ile onaylayan aynı kişi olamaz — rol kapısıyla değil, kimlik karşılaştırmasıyla zorlanır.
Çapraz yüzey: Yalnız QR'ın dört ucu ortaktır (POST qr, GET qr, GET qr/:id, POST qr/:id/revoke); s2s ayrıca GET qr/:id/image ve POST qr/parse taşır. Terminal yönetimi ve QR üretici kodu yüzeyinin tamamı (18 uç) panele özeldir — cihaz kurulumu (provisioning), kimlik bilgisi üretme/döndürme/iptal, askıya alma, toplu işlem ve üretici kodu onayı imza anahtarıyla çağrılamaz.

Fiziksel tahsilat noktalarınızı ve QR kodlarınızı yönettiğiniz bölüm.

QR yönetimi

GET  qr                     # kodlar (programId, qrType, status, targetEndUserId filtresi)
POST qr                     # kod üret
GET  qr/:id
POST qr/:id/revoke          # iptal

Kod üretimi ve ödeme akışı: QR.

Aktif kodları buradan izleyin; kendi tarafınızda kod defteri tutmayın. Şüpheli bir kodu revoke ile anında geçersiz kılabilirsiniz.

Üretici kodu

GET  qr/producer-codes
POST qr/producer-codes
POST qr/producer-codes/:id/approve
POST qr/producer-codes/:id/retire

Üretici kodu, standart bir QR şemasında kurumu tanımlayan kimliktir. Onay ve emekliye ayırma adımlarıyla yönetilir.

Yakında — ortak standart QR şeması

Üretici kodu yönetimi, standart bir QR şemasıyla anlam kazanır. Bugünkü QR formatı kapalı devredir ve bir kurum kimliği taşımaz. Standart şema desteklendiğinde bu bölüm etkinleşir. Durum: Yol Haritası · QR — Karşılıklı çalışabilirlik.

Terminaller

GET   terminals                        # q, storeCode, status filtresi; cursor sayfalama
POST  terminals                        # terminal oluştur
GET   terminals/:id
PATCH terminals/:id
GET   terminals/:id/events             # terminal olay geçmişi

Terminal alanları: bağlı işletme hesabı, etiket, form faktörü, mağaza ve kasa kodu, işlem başı tavan (perTxnCap + perTxnCapCurrency), credential kimliği.

İşlem başı tavanın para birimi

⚠️

perTxnCap birimsiz bir sayı değildir: yanında her zaman perTxnCapCurrency gelir. Bu alan çağırandan kabul edilmez, türetilir — terminalin bağlı olduğu işletme hesabının para biriminden alınır.

Sebebi doğrudan güvenliktir: tavanın birimini istek gövdesi belirleyebilseydi, "cap = 10000 USD" yazmak TRY tavanını genişletmenin yolu olurdu ve tavan anlamını yitirirdi.

İkisi birlikte var olur veya birlikte yok olur: denominasyonsuz bir tavan ya da tavansız bir denominasyon yazılamaz. Tavanı kaldırdığınızda para birimi de temizlenir.

Çok para birimli bir programda aynı "10.000" sayısı TRY ve USD terminallerinde çok farklı bir gerçek tavan demektir. Terminalin işletme hesabını seçerken tavanın hangi para biriminde uygulanacağını da seçmiş olursunuz.

Tavanın para birimi işlem para biriminden farklı olursa işlem reddedilir — kur çevirisi yapılmaz.

storeCode ve laneCode alanlarını baştan doldurun. Terminal sayısı büyüdüğünde raporlama ve toplu işlemler bu alanlara dayanır; sonradan doldurmak elle temizlik işi çıkarır.

Aktivasyon ve credential

POST terminals/:id/activation           # aktivasyon kodu üret ({ ttlMinutes })
POST terminals/:id/credential           # credential bağla
POST terminals/:id/rotate-credential    # credential rotasyonu
POST terminals/:id/revoke-credential    # credential iptali

Terminal sahada bir aktivasyon kodu ile devreye alınır; kod kısa ömürlüdür.

⚠️

Bir terminal kaybolduğunda ya da çalındığında credential'ı iptal edin (revoke-credential), yalnız askıya almak yeterli değildir. İptal edilen credential ile gelen istekler reddedilir.

Yaşam döngüsü

POST terminals/:id/suspend      # { reason }
POST terminals/:id/resume
POST terminals/:id/retire

İşlem	Etkisi
Askıya al	Terminal işlem yapamaz; geri alınabilir
Devam ettir	Askıyı kaldırır
Emekliye ayır	Kalıcı olarak kullanım dışı bırakır

Toplu işlemler

POST terminals/bulk             # toplu terminal oluşturma (satır listesi + aktivasyon TTL)
POST terminals/bulk-suspend     # toplu askıya alma

Toplu askıya alma; terminal id listesi, mağaza kodu veya tüm tenant kapsamıyla çalışır.

⚠️

allInTenant: true tüm terminalleri askıya alır — tahsilat tamamen durur. Bunu yalnız güvenlik olayı gibi bilinçli durumlarda kullanın ve gerekçeyi yazın.

Raporlama

GET reports/terminals

Terminal bazlı işlem raporu; mağaza kodu, durum ve tarih aralığıyla filtrelenir.

Kontrol listesi

Terminal etiketleri, mağaza ve kasa kodları tutarlı doldurulmuş
İşlem başı tavan (perTxnCap) tanımlı ve perTxnCapCurrency beklediğiniz para birimi
Aktivasyon kodları sahaya güvenli kanaldan iletiliyor
Kayıp/çalıntı terminallerde credential iptal ediliyor
Emekliye ayrılan terminaller listeden temizleniyor

Toplu Ödeme Kartlar