Nasıl çalışır ve günlük kullanım

Köprü eşleştirildikten ve senkronizasyon etkinleştirildikten sonra kendi kendine çalışır. Bu sayfa köprünün gerçekte ne yaptığını açıklar; böylece bir şey tuhaf göründüğünde tahmin yürütmek yerine nereye bakacağınızı bilirsiniz.

Senkronizasyon motoru sade bir dille

1. Bir değişiklik olay oluşturur

WHMCS'deki ilgili her değişiklik bir WHMCS kancasını tetikler: bir müşteri eklenir veya düzenlenir, bir kişi oluşturulur, bir fatura kesinleşir, bir ödeme gelir, bir sipariş verilir, bir hizmet sağlanır veya askıya alınır, bir destek talebi açılır ya da yanıtlanır.

Kanca bir HTTP çağrısı yapmaz. Bir outbox tablosuna (mod_perfexbridge_outbox) küçük bir olay yazar ve anında geri döner.

Outbox neden var

Bir WHMCS kancası Perfex'i doğrudan çağırsaydı, yavaş ya da erişilemeyen bir Perfex sunucusu bir WHMCS yönetim sayfasını veya bir müşterinin ödeme adımını kilitlerdi. Yerel bir tabloya yazmak bir milisaniye sürer ve başkasının ağı yüzünden asla başarısız olamaz. Bundan sonraki her şey arka planda gerçekleşir.

2. Cron kuyruğu boşaltır

Her WHMCS sistem cron turunda dağıtıcı, outbox'tan zamanı gelmiş bir grup olayı alır ve her birini HTTPS üzerinden Perfex kurulumunuza POST eder.

Her istek, JSON gövdesinin yanında iki başlık taşır: bir zaman damgası ve paylaşılan gizli anahtarınız kullanılarak bu zaman damgası ile isteğin tam gövdesi üzerinden hesaplanan bir HMAC-SHA256 imzası. Perfex imzayı kendi gizli anahtar kopyasıyla yeniden hesaplar ve eşleşmeyen ya da zaman damgası 300 saniyeden eski olan her isteği reddeder.

WHMCS modül sayfasındaki Run Sync Now düğmesiyle dilediğiniz an kuyruğu anında boşaltabilirsiniz.

3. Başarısız denemeler yeniden denenir, sonra ölü mektuba düşer

Başarısız bir gönderim kaybolmaz ve sıkı bir döngüde yeniden denenmez. Üstel geri çekilme ile yeniden zamanlanır: ilk başarısızlıktan yaklaşık 60 saniye sonra, ardından 2 dakika, 4, 8 ve böyle devam eder; denemeler arasındaki süre en fazla 6 saat olur.

Kabaca 40 saati kapsayan 15 denemeden sonra satır dead olarak işaretlenir. Ölü satırlar asla otomatik olarak yeniden denenmez ve asla temizlenmez. Bunlar sizin ölü mektup çekmecenizdir: WHMCS modül sayfasının üst kısmındaki Dead events sayacı kaç tane olduğunu, kayıt satırı ise nedenini söyler.

Ölü bir olay bir sinyaldir, felaket değil

Ölü mektuba düşmek, aynı olayın neredeyse iki gün boyunca aynı nedenle başarısız olduğu anlamına gelir. Neden neredeyse her zaman şu dört şeyden biridir: Perfex'te eksik bir para birimi, gizli anahtar uyuşmazlığı, bir Pro olayını engelleyen Ücretsiz plan ya da Perfex'in çevrimdışı olması. Nedeni giderin ve işi yeniden kuyruğa alın. Sorun giderme sayfasına bakın.

4. Duraklatmak hiçbir şey kaybettirmez

Enable Sync işaretini kaldırmak yalnızca teslimatı duraklatır. Kancalar outbox'a olay yazmaya devam eder, bu nedenle duraklatma sırasında hiçbir şey kaybolmaz. Yeniden etkinleştirin; birikmiş iş bir sonraki turda ya da Run Sync Now ile hemen boşalır.

5. Yankı bastırma sonsuz döngüleri engeller

Çift yönlü senkronizasyon bariz bir tehlike doğurur: WHMCS, Perfex'ten gelen bir değişikliği uygular, bu yazma işlemi WHMCS'nin kendi kancalarını tetikler ve değişiklik doğrudan geri döner. Kendi haline bırakılsa tek bir düzenleme sonsuza dek gidip gelirdi.

Köprü bunu, her iki tarafta da uygulanan katmanlı korumalarla engeller:

• İstek içi köken bayrağı: köprü gelen bir değişikliği uygularken ayarlanır; böylece kendi yaptığı yazmalar taze kullanıcı düzenlemesi sayılmaz.
• Varlık ve yanıt ID eşlemesi araması: böylece köprünün az önce oluşturduğu bir destek talebi yanıtı, yeni bir kayıt gibi tekrar gönderilmek yerine tanınır.
• Sağlama toplamı karşılaştırması: veri zaten son senkronize edilen durumla aynı olduğunda olayı işlemsiz hale getirir.

Her tarafın kendi köken bayrağı vardır ve bir bayrak atlansa bile sağlama toplamı emniyet ağı görevi görür. Korumalar bilinçli olarak açık başarısızlık ilkesiyle çalışır: bir koruma karar veremiyorsa, sessizce düşürülmüş bir güncelleme yerine zararsız bir fazladan gönderim tercih edilir.

6. Bakım işleri

Her iki taraf da kendi kendini sınırlayan günlük bir temizlik yapar, en fazla 24 saatte bir:

• teslim edilmiş, 7 günden eski outbox satırları silinir;
• 90 günden eski kayıt satırları silinir;
• bekleyen ve ölü satırlar asla temizlenmez, çünkü bekleyen teslim edilmemiş iştir, ölü ise sizin ölü mektup çekmecenizdir.

Ne senkronize edilir ve hangi yönde

WHMCS'den Perfex CRM'e

Veri	Ücretsiz	Pro	Perfex'te ne oluşur
👥 Müşteriler	✅	✅	Bir Perfex müşterisi ve müşterinin adı ile e-postasını taşıyan bir birincil kişi
👤 Kişiler	✅	✅	Aynı Perfex müşterisi altında ek kişiler
🗑️ Müşteri silme	✅	✅	Perfex müşterisi silinmez, devre dışı bırakılır
📄 Faturalar	➖	✅	Kalemleri, vergi satırı, eşleşen toplamları, durumu ve yönetici notundaki WHMCS fatura numarasıyla bir Perfex faturası
💳 Ödemeler ve işlemler	➖	✅	Yansıtılan faturaya karşılık gelen bir ödeme kaydı; ödeme ağ geçidi ve işlem ID'siyle birlikte. Yinelenen kayıtlar reddedilir
💸 İadeler	➖	✅	Perfex'teki kopya iptal edilir ve not düşülür
🛒 Siparişler	➖	✅	Order Sync Target ayarına göre sipariş başına bir Perfex potansiyel müşterisi, müşteride bir not ya da hiçbir şey
📦 Hizmetler	➖	✅	Müşterinin WHMCS sekmesindeki satırlar: ürün adı, alan adı, durum, faturalama döngüsü, tutar ve sonraki ödeme tarihi
🌐 Alan adları	➖	✅	Aynı sekmedeki satırlar: kayıt kuruluşu, durum, bitiş tarihi ve sonraki ödeme tarihi
🎫 Destek talepleri ve yanıtlar	➖	✅	Müşteri altında, eşlenen departmanda, yanıtları ve durumuyla birlikte bir Perfex destek talebi

Ücretsiz sürüm ayrıntısı

Ücretsiz planda bir müşterinin durumu ve notları veri paketinde taşınır ama Perfex'e yazılmaz. Perfex kaydı üzerinde işlem yapan tek şey, müşteriyi devre dışı bırakan müşteri silme olayıdır.

Perfex CRM'den WHMCS'ye (yalnızca Pro)

Perfex'te yapılan değişiklik	WHMCS'de ne olur
Müşteri şirket bilgileri düzenlendi	WHMCS müşteri kaydı, çakışma politikasına tabi olarak güncellenir
Birincil kişi düzenlendi	WHMCS müşteri kimlik alanları güncellenir, çünkü birincil kişi müşteri kimliğidir
Birincil olmayan kişi düzenlendi	Eşleşen WHMCS kişisi güncellenir
Personel, yansıtılmış bir destek talebine yanıt verdi	Yanıt WHMCS destek talebinde görünür; ayarlanmışsa Ticket Reply Admin adına, aksi halde Perfex personelinin adına
Destek talebi durumu değişti	WHMCS destek talebi durumu da değişir

Perfex tarafındaki silmeler asla WHMCS'ye gönderilmez

Perfex'te bir müşteriyi veya kaydı silmek WHMCS'de hiçbir şeyi silmez. CRM'de ne olursa olsun faturalama kayıtları korunur. Bu bilinçli bir tercihtir ve yapılandırılamaz.

Güvenmeden önce bilinmesi gereken davranışlar

Bunlar belgelenmiş kararlardır, hata değil:

• Doğrudan Perfex'te oluşturulan destek talepleri Perfex'te kalır. Bunlar WHMCS'de asla oluşturulmaz, çünkü bir WHMCS destek talebi, CRM tarafında oluşturulan bir talebin sahip olmayabileceği bir müşteri hesabı ve bir destek departmanı gerektirir.
• Perfex'in tam destek talebi ayarları formu üzerinden değiştirilen durum bilgisi aktarılmaz. Tek talep durum açılır listesi, yanıtlar, toplu durum değişiklikleri ve otomatik kapatma sorunsuz senkronize edilir.
• Talep başına Perfex görevinde kaydedilen süre WHMCS'ye geri senkronize edilmez. Görev, yerel Perfex zaman çizelgesi raporlaması için vardır.
• Yinelenen fatura döngüsü modellenmez. WHMCS faturaları Perfex'e sade, tek seferlik faturalar olarak yansıtılır.
• İki WHMCS müşterisinin birleştirilmesi ele alınmaz. Birleştirmenin ardından, kapsanan müşteriye ait eşleme satırlarını yeniden eşleyin veya kaldırın.
• Senkronize edilmiş bir destek talebine verilen Perfex personel yanıtı müşteriye iki e-posta gönderilmesine yol açabilir, biri Perfex'ten, biri WHMCS'den. Müşterileriniz WHMCS müşteri portalını kullanıyorsa, Perfex'teki ticket-reply e-posta şablonunu Setup > Email Templates > Tickets altında devre dışı bırakın.

Kayıtlar nerede

En çok zaman kazandıran bölüm burasıdır. İnsanlar alışkanlıkla yanlış yere bakar.

WHMCS tarafı: modülün kendi sayfası

Addons > Perfex CRM Bridge sayfasına gidin ve Recent activity bölümüne inin.

WHMCS Activity Log değil

Köprü, Utilities > Logs altındaki WHMCS Activity Log kaydına yazmaz. Kendi tablosu, modül sayfasındaki Recent activity paneli olarak gösterilir ve WHMCS tarafında bakılacak tek yer orasıdır.

Tablo son 50 olayı şu sütunlarla gösterir:

Sütun	Anlamı
Time	Satırın yazıldığı an
Dir	WHMCS'den Perfex'e için out, Perfex'ten WHMCS'ye için in
Event	Örneğin client.upsert, invoice.upsert, cron.drain
Entity	client, contact, invoice, ticket ve benzeri
WHMCS ID	Kaydın WHMCS ID'si
Status	Yeşil ok veya kırmızı error
Message	Sonuç ya da tam hata metni

Hemen üstündeki başlık satırı Queue pending ve Dead events sayılarını gösterir. Bu iki sayı sizin sağlık özetinizdir: bekleyen sayısı bir ya da iki cron döngüsü içinde sıfıra inmeli, ölü sayısı ise sıfırda kalmalıdır.

Perfex tarafı: ayarlar sayfasındaki iki panel

Setup > WHMCS Bridge sayfasına gidin.

Recent inbound events, WHMCS'nin bu Perfex kurulumuna gönderdiklerini olay türü, WHMCS ID'si, eşlendiği Perfex ID'si, bir durum rozeti ve bir mesajla listeler. Reddedilen bir istek burada auth.rejected satırı olarak görünür; bu da bir imza veya zaman damgası sorunu, neredeyse her zaman da bir gizli anahtar uyuşmazlığı anlamına gelir. Reddedilen satırlar, bir istek seli diskinizi doldurmasın diye dakikada 10 ile sınırlıdır.

Outbound queue, WHMCS'ye gönderilmeyi bekleyen Perfex tarafı değişiklikleri şunlarla listeler:

• panel başlığında pending ve dead sayıları;
• kuyruğa alınmış her değişiklik için olayı, varlığı, durumu, deneme sayısını, sonraki deneme zamanını ve son hatayı gösteren bir satır;
• nedeni bilinen durumlarda ham hata yerine sade bir açıklama. Lisanssız bir WHMCS'den gelen 403 yanıtı, bir JSON dökümü yerine yükseltme bağlantısıyla birlikte "Two-way sync requires Pro on the WHMCS side" şeklinde görünür.

Yalnızca en son 20 satır gösterilir. Teslim edilmiş satırlar 7 gün sonra kendiliğinden temizlenir; bekleyen ve ölü satırlar saklanır.

Hangi kayıt hangi soruyu yanıtlar

Soru	Buraya bakın
📤 WHMCS'deki değişikliğim WHMCS'den çıktı mı?	WHMCS: Recent activity, out yönü
📥 Perfex kabul etti mi?	Perfex: Recent inbound events
🔑 Paylaşılan gizli anahtarım yanlış mı?	Perfex: Recent inbound events içindeki auth.rejected satırları
🔁 Perfex'teki düzenlemem WHMCS'ye ulaştı mı?	Perfex: Outbound queue, ardından WHMCS: Recent activity, in yönü
⏰ Cron çalışıyor mu?	WHMCS: Cron delivering kontrol listesi satırı
🔇 Çift yönlü senkronizasyon neden sessiz?	Perfex: WHMCS plan paneli. Free diyorsa yanıtınız budur

Geri doldurma sihirbazı (Pro)

Canlı senkronizasyon yalnızca yeni etkinlikleri işler. Köprüyü halihazırda kullanılan bir WHMCS kurulumuna eklerseniz, mevcut müşterileriniz ve faturalarınız siz geri doldurma yapana kadar Perfex'e gelmez.

Backfill wizard, WHMCS modül sayfasında ayarlar formunun altında yer alır. Mevcut kayıtlarınızı canlı senkronizasyonun kullandığı outbox'a alır; böylece bu kayıtlar da aynı imzalama, yeniden deneme, geri çekilme ve ölü mektup davranışını devralır.

Kapsamlar

Bir veya daha fazlasını işaretleyin:

Kapsam	Neyi kuyruğa alır
Clients + contacts	Kapsamdaki her müşteri. Kişiler otomatik olarak müşterileriyle birlikte gelir
Invoices	Kapsamdaki her fatura
Services + domains	Kapsamdaki her hizmet ve alan adı; Perfex WHMCS sekmesini doldurur

Destek talepleri geri doldurulamaz

Geçmiş destek talepleri senkronize edilmez. Köprü devreye girdikten sonra yalnızca yeni destek talebi etkinliği aktarılır. Bu belgelenmiş bir sınırlamadır, yapılandırma sorunu değil.

Modlar

Mod	Davranış
All history	Seçilen kapsamlardaki her kayıt
Date range	Yalnızca YYYY-MM-DD biçimindeki başlangıç ve bitiş aralığında oluşturulmuş kayıtlar. Geçersiz bir aralık, örneğin bitişten sonraki bir başlangıç, net bir mesajla reddedilir ve hiçbir şey kuyruğa alınmaz
Only new (not yet synced)	Zaten eşlenmiş kayıtları atlar. Tekrarlanan çalıştırmalarda kullanılacak mod budur

500 varlık sınırı ve nasıl devam edilir

Her çalıştırma en fazla 500 varlığı kuyruğa alır; böylece büyük bir kurulumdaki geri doldurma kuyruğu boğamaz veya cron'unuzu tıkayamaz.

Sınıra ulaşıldığında sihirbaz size bunu bildirir. İzlenecek yol şudur:

1. Queue Backfill düğmesine tıklayın. Bir bilgi bildirimi kaç kaydın planlandığını, kaçının kuyruğa alındığını, kaçının hata verdiğini ve çalıştırmanın kesilip kesilmediğini bildirir.
2. Sayfanın üst kısmındaki Queue pending sayacının, cron ile ya da Run Sync Now ile boşalmasını izleyin.
3. Sihirbazı Only new (not yet synced) modunda yeniden çalıştırın.
4. Bir çalıştırma yeni hiçbir şey planlamayana kadar tekrarlayın.

Yinelenen kayıt riski yoktur. Zaten eşlenmiş kayıtlar atlanır ve verisi Perfex tarafıyla zaten aynı olan bir olay işlemsiz olarak yanıtlanır.

Size zaman kazandıracak iki sıralama kuralı

Müşterileri hizmet ve faturalardan önce ya da onlarla birlikte geri doldurun

Üst kaydı henüz Perfex'te olmayan bir alt kayıt "not mapped, will retry" yanıtını alır ve üst kayıt gelene kadar kuyrukta bekler. Genellikle kuyruğun kendi sıralaması bunu çözer. Ancak müşterileri hiç senkronize edilmemiş bir kurulumda yalnızca hizmetleri veya faturaları geri doldurursanız, bu olaylar yaklaşık 40 saat boyunca yeniden denenir ve ardından ölü mektuba düşer.

Ya aynı çalıştırmada Clients + contacts kutusunu işaretleyin ya da önce müşterileri geri doldurun.

Önce Perfex para birimlerinizi yapılandırın

Perfex'in tanımadığı bir para birimindeki fatura reddedilir, yeniden denenir ve yaklaşık 40 saat sonra ölü mektuba düşer. Faturaları geri doldurmadan önce, WHMCS müşterilerinizin kullandığı her para birimini Perfex'te Setup > Finance > Currencies altında tam ISO koduyla ekleyin.

Geçmişe ait ödenmiş faturalar

WHMCS'de zaten ödenmiş olan geri doldurulmuş faturalar, Perfex'te yapay bir ödeme kaydıyla kapatılır; böylece Gecikmiş değil Ödendi olarak görünürler. Geri doldurmayı yeniden çalıştırmak yinelenen ödemeler oluşturmaz.

Günlük işleyiş

Kurulumu tamamladıktan sonra yapılacak çok az şey kalır. WHMCS modül sayfasına haftada bir kısa bir bakış yeterlidir:

Nereye bakmalı	Sağlıklı durum
Setup checklist	Tamamı yeşil; Ücretsiz plandaysanız lisans satırı gri
Queue pending	Küçük ve cron turları arasında azalıyor
Dead events	0
Recent activity	Çoğunlukla ok satırları
Perfex Outbound queue	Pro çift yönlü kurulumlarda 0 bekleyen, 0 ölü

Bu listede bir şey yolunda değilse, nedeni ve çözümü Sorun giderme sayfasındadır.