Fiş Yazıcısı Kurulumu: Bağlantı ve Sipariş Yazdırma

RestaurantManage Print Agent, buluttan yazdırma komutları alarak bunları termal fiş yazıcınıza ileten hafif bir Windows hizmetidir. Siparişler ödendiğinde veya mutfak biletlerinin yazdırılması gerektiğinde otomatik fiş yazdırmayı mümkün kılar. Agent; ağ yazıcılarını (TCP port 9100), USB yazıcıları ve Windows spooler bağlantılarını destekler. Bu kılavuz kurulum, yapılandırma, yazıcı bağlantısı ve sorun giderme konularını kapsar.

Fiş Yazdırma Nasıl Çalışır?

Yazdırma iş akışı tamamen otomatiktir. Kasiyer ödemeyi onayladığında veya bir mutfak bileti tetiklendiğinde, RestaurantManage arka ucu tüm fişi ESC/POS bayt komutları olarak oluşturur. Bu baytlar güvenli bir WebSocket bağlantısı (PrintHub) üzerinden restoranınızdaki bir Windows PC'de çalışan Print Agent'a gönderilir. Agent verileri çözer ve doğrudan bağlı termal yazıcıya iletir. Tüm süreç ödeme onayından yazdırılmış fişe kadar iki saniyenin altında sürer.

Tam Yazdırma Hattı

Tam hattı anlamak sorun gidermeye yardımcı olur. Her fiş veya mutfak bileti yazdırıldığında gerçekleşen olayların sırası şöyledir:

1. Ödeme onaylandı: Kasiyer bir siparişi ödenmiş olarak işaretler veya bir mutfak bileti manuel olarak tetiklenir.
2. Arka uç fişi biçimlendirir: RestaurantManage sunucusu ReceiptFormattingService'i çalıştırır; ReceiptBuilder ile fiş düzenini oluşturur ve EscPosCommands ile EscPosRasterEncoder aracılığıyla ESC/POS bayt komutlarına dönüştürür.
3. PrintHub üzerinden veri gönderilir: Biçimlendirilmiş fiş baytları (Base64 olarak kodlanmış) güvenli bir WebSocket kanalı (SignalR PrintHub) üzerinden doğru Print Agent'a — restoran kimliğinizle tanımlanan — yayınlanır.
4. Print Agent işi alır: Yerel PC'nizde çalışan Windows hizmeti Base64 yükünü alır, ham ESC/POS baytlarına geri çözer ve hangi yazıcının kullanılacağını belirler.
5. Yazıcı çıktısı: Çözülen baytlar ağ TCP, Windows spooler veya USB üzerinden doğrudan termal yazıcıya gönderilir ve fiş saniyeler içinde yazdırılır.

Yazdırılan Fişte Neler Bulunur

RestaurantManage tarafından oluşturulan her fiş eksiksiz işlem ayrıntılarını içerir. Başlık bölümünde restoran adı, adresi ve logosu (yapılandırılmışsa) gösterilir. İçerik bölümünde masa numarası, miktar ve birim fiyatlarıyla birlikte sipariş edilen tüm ürünlerin numaralı listesi, varsa indirimler ve vergi kategorisine göre ayrıntılı vergi dökümü yer alır. Alt bilgide sipariş toplamı, ödeme yöntemi (nakit, kart vb.), ödeme tarihi ve saati ile isteğe bağlı bir teşekkür mesajı gösterilir. Mutfak biletleri yalnızca masa numarasını, ürün adlarını, miktarları ve varsa ürün düzeyindeki notları gösteren basitleştirilmiş bir formatta sunulur.

Fişler Ne Zaman Tetiklenir

Müşteri fişleri, kasiyer bir sipariş için tam veya kısmi ödemeyi onayladığında otomatik olarak yazdırılır. Mutfak biletleri, kasiyer panelinden veya garson mobil uygulamasından yeni bir sipariş gönderildiğinde yazdırılır. Her iki durumda da yazdırma işi tamamen arka uç tarafından işlenir ve Print Agent'a otomatik olarak yönlendirilir. Yetkili personel, orijinal yazdırma kaçırıldıysa veya bozuksa admin panelinden yeniden yazdırma işlemi de başlatabilir.

Print Agent'ı Nasıl Kurarım?

Kurulum, herhangi bir modern Windows PC'de yaklaşık beş dakika sürer. PC, Print Agent arka plan Windows hizmeti olarak çalıştığından restoran çalışma saatleri boyunca açık kalmalıdır.

1. İndirin: En son Print Agent yükleyicisini admin panelinden edinin veya destek ekibiyle iletişime geçin.
2. Yükleyin: Yükleyiciyi, çalışma saatleri boyunca açık kalacak olan bir Windows PC'de çalıştırın.
3. Yapılandırın: config.json dosyasını açın ve API temel URL'sini, restoran kimliğini ve agent gizli anahtarını (admin tarafından sağlanır) girin.
4. Yazıcıyı bağlayın: Termal yazıcınızı USB ile takın veya PC ile aynı ağa bağlayın.
5. Hizmeti başlatın: Print Agent'ı çalıştırın — PrintHub'a otomatik olarak bağlanır ve yeşil bir durum göstergesi görüntüler.
6. Test baskısı yapın: Kasiyer panelinden bir test ödemesi işleyin ve fişin doğru yazdırıldığını doğrulayın.

Sistem Gereksinimleri

Print Agent minimum donanım gereksinimlerine sahiptir ancak desteklenen bir işletim sistemi ve çalışma zamanına bağımlıdır:

• İşletim sistemi: Windows 10 (sürüm 1909 veya üzeri) veya Windows 11. Print Agent yalnızca Windows'ta çalışır; macOS veya Linux'ta çalışmaz.
• Çalışma zamanı: .NET 8 Runtime yüklü olmalıdır. Yüklü değilse yükleyici sizi indirmeye yönlendirir — Microsoft'tan ücretsiz olarak temin edilebilir.
• İnternet bağlantısı: RestaurantManage bulutuyla iletişim kurmak için kararlı bir internet bağlantısı gereklidir. Agent, kısa kesintilerden sonra otomatik olarak yeniden bağlanır.
• Ağ erişimi: PC'nin yazıcıya erişebilmesi gerekir — USB kablosu veya aynı yerel ağ üzerinden.
• İşlemci ve RAM: En az 512 MB boş RAM'e sahip herhangi bir modern işlemci yeterlidir. Agent çok az kaynak kullanır.

Windows Hizmeti Olarak Çalıştırma

Üretim ortamında Print Agent, PC açıldığında — bir kullanıcı oturum açmadan önce bile — otomatik olarak başlaması için Windows hizmeti olarak kurulmalıdır. Hizmet olarak kaydetmek için install-service.bat dosyasına sağ tıklayın ve Yönetici olarak çalıştır'ı seçin. Bu işlem, agent'ı RestaurantPrintAgent adıyla Windows Hizmet Denetim Yöneticisi'ne kaydeder. Kurulumdan sonra, Services panelinden (services.msc) veya komut satırından sc start RestaurantPrintAgent ve sc stop RestaurantPrintAgent komutlarıyla yönetebilirsiniz. Hizmeti kaldırmak için uninstall-service.bat dosyasını Yönetici olarak çalıştırın.

Restoran Kimliğinizi ve Gizli Anahtarınızı Bulma

Restoran Kimliği, RestaurantManage sistemindeki restoranınızın benzersiz tanımlayıcısıdır. Admin panelinde Ayarlar → Restoran Bilgileri bölümünde bulunabilir. Agent Gizli Anahtarı, Print Agent'ı PrintHub WebSocket uç noktasıyla doğrulayan ayrı bir kimlik bilgisidir — kullanıcı şifrenizle aynı değildir. Bir gizli anahtar oluşturmak veya yeniden oluşturmak için admin panelinde Ayarlar → Print Agent bölümüne gidin ve Yeni Anahtar Oluştur'a tıklayın. Anahtarı hemen kopyalayın ve config.json'a yapıştırın — başka bir sayfaya geçtikten sonra tekrar gösterilmez. Anahtarı kaybederseniz yeni bir tane oluşturmanız yeterlidir; eski anahtar otomatik olarak geçersiz hale gelir.

Hangi Yazıcı Bağlantı Türleri Desteklenir?

Print Agent aralarında otomatik yedekleme olan üç bağlantı yöntemini destekler: ağ yazıcıları, USB yazıcılar ve Windows spooler bağlantıları. Agent önce spooler'ı dener, ardından doğrudan USB'ye geçer ve son olarak UNC ağ paylaşımlarını dener.

Ağ Yazıcıları (Önerilir)

Ağ yazıcıları çoğu restoran için önerilen bağlantı yöntemidir. Ağa bağlı bir termal yazıcının kendi IP adresi vardır ve TCP port 9100'de ham yazdırma verisi kabul eder. Kurulum için yazıcıyı Ethernet kablosuyla router'a veya switch'e bağlayın, ardından yazıcının dahili yapılandırma sayfasını veya ön panel menüsünü kullanarak statik bir IP adresi atayın (örn. 192.168.1.100). Bu IP adresini ve port 9100'ü Print Agent yapılandırmasına girin. Statik IP önemlidir — yazıcı her yeniden başladığında DHCP'den yeni bir IP alırsa yazdırma işleri başarısız olur. Ağ yazıcıları, PC ve yazıcının fiziksel olarak yanyana olmasına gerek olmadığından tercih edilir.

USB ve Windows Spooler Yazıcıları

USB termal yazıcılar, Print Agent çalıştıran Windows PC'ye doğrudan bağlanır. USB kablosunu bağladıktan sonra gerekirse üreticinin Windows sürücüsünü yükleyin (modern ESC/POS yazıcıların çoğu Windows'ta dahili genel sürücü kullanır). Print Agent, yazıcıyı Windows spooler aracılığıyla algılar. Yazıcı spooler'da görünmüyorsa doğrudan USB adresleme yöntemi denenebilir: agent, \\?\USB001 gibi USB cihaz yollarına veya LPT1 gibi paralel port yollarına doğrudan yazabilir.

Otomatik Yedekleme Sırası

Bir yazdırma işi alındığında Print Agent bağlantı yöntemlerini şu sırayla dener: 1) Windows Spooler — yazıcı Windows'ta kayıtlıysa ve spooler üzerinden erişilebiliyorsa bu yöntem önce kullanılır. 2) Doğrudan USB — spooler başarısız olursa agent, USB001, USB002 gibi USB cihaz yollarına ve LPT portlarına doğrudan yazmayı dener. 3) UNC ağ paylaşımı — son çare olarak agent, yazıcıya bir Windows ağ paylaşım yolu aracılığıyla erişmeyi dener. Her üç yöntem de başarısız olursa hata logs/ klasörüne ayrıntılarıyla kaydedilir.

Print Agent'ı Nasıl Yapılandırırım?

Print Agent, kurulum dizinindeki tek bir config.json dosyası aracılığıyla yapılandırılır. Tüm ayarlar düz metin biçimindedir ve hizmetin bir sonraki başlatılmasında (veya yeniden başlatılmasında) geçerli olur. Yapılandırma için grafik arabirim yoktur — dosyayı herhangi bir metin düzenleyiciyle düzenlemek yeterlidir.

config.json Dosyasının Açıklaması

Yapılandırma dosyasında üç zorunlu alan ve isteğe bağlı yazıcı ayarları bulunur:

• ApiBaseUrl: RestaurantManage sunucunuzun temel URL'si, örneğin <code>https://restaurantmanage.xyz</code>. Sondaki eğik çizgiyi eklemeyin. Print Agent bu URL'yi PrintHub'a bağlanmak ve güncellemeleri kontrol etmek için kullanır.
• RestaurantId: Restoranınızın benzersiz tanımlayıcısı. Admin panelinde Ayarlar → Restoran Bilgileri bölümünde bulunabilir.
• AgentSecretKey: Admin panelinde Ayarlar → Print Agent bölümünde oluşturulan gizli anahtar. Bu anahtar, agent'ın kullanıcı girişi gerektirmeden sunucuyla kimlik doğrulamasını sağlar. Gizli tutun.

Eksiksiz bir config.json örneği şöyle görünür: {"ApiBaseUrl": "https://restaurantmanage.xyz", "RestaurantId": "restoran-kimliginiz", "AgentSecretKey": "gizli-anahtariniz"}. Dosyayı düzenledikten sonra değişikliklerin geçerli olması için Print Agent hizmetini yeniden başlatın.

Yazıcı Adı ve IP Yapılandırması

Ağ yazıcıları için yazıcının IP adresine ihtiyacınız vardır. Bulmak için: çoğu termal yazıcı, güç açılırken besleme düğmesine basılı tutulduğunda bir yapılandırma sayfası yazdırır — IP adresi orada listelenir. Alternatif olarak, router'ınızın DHCP istemci listesinde yazıcının ana bilgisayar adını kontrol edin. IP'yi aldıktan sonra, hiç değişmemesi için yazıcının ağ ayarlarında statik adres olarak atayın. Windows spooler yazıcıları için yazıcı adının Windows Ayarları → Yazıcılar ve Tarayıcılar'da göründüğü şekliyle tam olarak eşleşmesi gerekir. Yazıcı adları büyük/küçük harfe duyarlıdır.

Günlük Dosyaları ve Tanılama

Print Agent, kurulum dizinindeki logs/ alt klasörüne ayrıntılı günlükler yazar. Günlük dosyaları tarihe göre adlandırılır (örn. log-2026-04-06.txt) ve günlük olarak döner. Her günlük girişi zaman damgası, önem düzeyi (BİLGİ, UYARI, HATA) ve ne olduğunun açıklamasını içerir. Bir yazdırma hatasını gideriyorsanız, sorunun yaşandığı tarihin günlük dosyasına bakın — tam hata mesajı sorunun ağla, kimlik doğrulamayla veya yazıcıyla ilgili olup olmadığını gösterir.

Otomatik Güncelleme Nasıl Çalışır?

Print Agent, RestaurantManage sunucusundaki güncelleme uç noktasını yaklaşık her 2,5 saatte bir çağırarak güncellemeleri kontrol eder. Yeni bir sürüm mevcutsa güncelleme paketini bekleyen güncellemeler klasörüne ZIP dosyası olarak indirir, kurulum komut dosyasını çalıştırır ve hizmeti otomatik olarak yeniden başlatır. Bu sayede restoranınız manuel müdahale gerektirmeden her zaman en son sürümü çalıştırır. Güncelleme kontrolleri, tüm agent'ların eş zamanlı güncellenmesini önlemek için restoran başına zamanlama dağılımı içerir.

Yaygın Sorunların Giderilmesi

Çoğu yazdırma sorunu üç kategoriden birine girer: bağlantı sorunları, yazıcı donanım sorunları veya yapılandırma hataları. Herhangi bir sorunu teşhis etmek için en iyi başlangıç noktası logs/ klasöründeki günlük dosyalarıdır.

Bağlantı ve Kimlik Doğrulama Hataları

• Agent sunucuya bağlanamıyor: config.json'daki ApiBaseUrl'nin doğru olduğunu ve PC'den erişilebilir olduğunu doğrulayın. Aynı PC'de bir tarayıcı açın ve API URL'sine gidin — bir yanıt görmelisiniz. PC'nin aktif bir internet bağlantısı olduğunu kontrol edin.
• Kimlik doğrulama hatası (günlüklerde 401 hatası): AgentSecretKey yanlış veya yeniden oluşturulmuş. Admin panelinde Ayarlar → Print Agent bölümünde yeni bir anahtar oluşturun, config.json'ı güncelleyin ve hizmeti yeniden başlatın.
• Bağlantı sık kesiliyor ve yeniden bağlanıyor: Bu genellikle ağ kararsızlığını gösterir. Wi-Fi yerine kablolu Ethernet kullanın. Güvenlik duvarı veya antivirüsün giden WebSocket bağlantılarını (agent HTTPS port 443 kullanır) engelleyip engellemediğini kontrol edin.
• Agent bağlanıyor ama yazdırma işi gelmiyor: config.json'daki Restoran Kimliğinin admin panelindekiyle tam olarak eşleştiğini doğrulayın (büyük/küçük harf duyarlıdır). Ayrıca Ayarlar → Print Agent bölümünde Print Agent'ın etkin olduğunu doğrulayın.

Yazdırma Kalitesi ve Kodlama Sorunları

• Fişte bozuk karakterler veya semboller: Termal yazıcınız RestaurantManage tarafından kullanılan ESC/POS komut setini tam olarak desteklemiyor olabilir. Uyumluluk için yazıcının belgelerini kontrol edin. 2015 sonrasında üretilen çoğu 58mm ve 80mm termal fiş yazıcısı uyumludur.
• Fiş yazdırılıyor ama metin kesilmiş: Kağıt genişliği ayarı yanlış olabilir. RestaurantManage varsayılan olarak 80mm kağıt için fiş biçimlendirir. 58mm yazıcı kullanıyorsanız dar kağıt modunu etkinleştirmek için destek ekibiyle iletişime geçin.
• Fiş boş veya yalnızca kısmi içerik yazdırılıyor: Bu, düşük kağıt rulosu veya tıkanmış baskı kafasını gösterebilir. Kağıdı değiştirin ve baskı kafasını kuru bezle temizleyin. Sorun devam ederse sorunu yalıtmak amacıyla Windows'tan doğrudan yazıcıyı test edin.
• Özel karakterler veya Arapça/RTL metin doğru yazdırılmıyor: Yazıcınızın karakter setinin UTF-8 veya diliniz için uygun kod sayfasına ayarlandığından emin olun. Bu ayara genellikle yazıcının yapılandırma menüsünden erişilir.

Hizmet Başlatma Hataları

• Agent Windows hizmeti olarak başlamıyor: install-service.bat dosyasını Yönetici olarak çalıştırmanız gerekir (sağ tıklayın → Yönetici olarak çalıştır). Yükseltilmiş izinler olmadan hizmet Windows Hizmet Denetim Yöneticisi'ne kaydedilemez.
• Hizmet başlıyor ama hemen duruyor: Windows Olay Görüntüleyicisi'nde (eventvwr.msc) Windows Günlükleri → Uygulama bölümünde RestaurantPrintAgent'tan gelen hata mesajlarını kontrol edin. Ayrıca logs/ klasörünü başlatma hatalarına karşı inceleyin. Yaygın nedenler arasında eksik veya hatalı biçimlendirilmiş config.json, eksik .NET 8 çalışma zamanı veya port çakışması sayılabilir.
• .NET çalışma zamanı eksik: https://dotnet.microsoft.com adresinden .NET 8 Runtime'ı indirip yükleyin. Kurulumdan sonra Print Agent hizmetini yeniden başlatın.
• Güvenlik duvarı agent'ı engelliyor: Windows Defender veya üçüncü taraf bir güvenlik duvarı agent'ın giden bağlantısını engelliyor olabilir. Güvenlik duvarı ayarlarınızda Print Agent yürütülebilir dosyası için bir istisna ekleyin.

İlgili Kılavuzlar

• Kasiyer paneli: Fiş yazdırmayı tetikleyen ödemelerin nasıl işlendiği
• Mutfak ekranı: Mutfak bileti yazdırmanın sipariş akışıyla nasıl entegre olduğu
• Başlarken: Kayıttan ilk siparişe tam kurulum kılavuzu