DEV Community: Koray Yalçın

B2B portalından ERP'ye sipariş göndermek: Idempotency, outbox ve kredi limiti kontrolü üzerine geliştirici notları

Koray Yalçın — Thu, 22 Oct 2026 15:23:06 +0000

Bayilerin ve kurumsal müşterilerin kendi özel fiyatlarıyla sipariş verdiği bir B2B portalı dışarıdan bakınca basit bir e-ticaret sitesine benzer: ürün listesi, sepet, onay butonu. Ama arka tarafta durum çok farklıdır. Stok, fatura, cari hesap ve risk limiti ERP'dedir; iletişim geçmişi, fırsatlar ve upsell planı CRM'dedir; portal ise ikisinin arasında, her iki sistemin de doğru kabul ettiği tek bir gerçeği müşteriye göstermeye çalışır. Ben, Koray Yalçın olarak CRM mimarisi, lead yönetimi ve pazarlama otomasyonu üzerine çalışırken en çok zaman kaybettiren hataların arayüzde değil, tam bu entegrasyon katmanında ortaya çıktığını gördüm.

Bu yazıda B2B portal projesini iş tarafından değil, siparişi ERP'ye ulaştıracak kodu yazan geliştiricinin gözünden ele alıyorum: neden portalın ERP veritabanına doğrudan bağlanmaması gerektiği, çift sipariş nasıl önlenir, outbox deseni ne işe yarar, kredi limiti kontrolü nerede yapılmalı ve fiyat listeleri nasıl önbelleğe alınır. Belirli bir ERP'yi (SAP, Logo, Mikro) ya da belirli bir mesaj kuyruğunu savunmuyorum; ilkeler hepsinde aynı.

1. İlk kural: Portal ERP veritabanına SQL atmaz

Küçük ekiplerde en hızlı çözüm gibi görünen şey, portal uygulamasının ERP'nin veritabanına bir okuma-yazma kullanıcısıyla bağlanmasıdır. İlk hafta çalışır. Sonra şu sorunlar birer birer gelir:

Şema bağımlılığı: ERP güncellemesi bir tablo adını ya da alan tipini değiştirdiğinde portal sessizce bozulur.
İş kurallarının atlanması: ERP'nin kendi arayüzünden girilen siparişte çalışan doğrulamalar, tetikleyiciler ve numaralandırma mantığı doğrudan INSERT ile tamamen devre dışı kalır.
Performans: Yoğun saatte portaldan gelen fiyat sorguları, muhasebe ekibinin gün sonu raporlarıyla aynı veritabanı kaynaklarını paylaşır.
Güvenlik: İnternete açık bir uygulamanın, şirketin finansal çekirdeğine geniş yetkili bir bağlantısı olur.

Doğru yapı, portal ile ERP arasına bir entegrasyon katmanı koymaktır. Bu katman ERP'nin resmi API'sini, web servisini ya da onaylı içe aktarma mekanizmasını kullanır; portal ise yalnızca bu katmanla konuşur. Arada bir mesaj kuyruğu (RabbitMQ, Kafka ya da bulut sağlayıcınızın yönetilen kuyruğu) bulunması, ERP yavaşladığında veya bakımdayken siparişlerin kaybolmadan beklemesini sağlar.

2. Siparişin yaşam döngüsünü baştan tanımlayın

Kod yazmadan önce bir siparişin hangi durumlardan geçebileceğini netleştirmek, sonraki bütün tartışmaları kısaltır. Tipik bir durum makinesi şöyle görünür:

TASLAK -> GONDERILDI -> ERP_KUYRUGUNDA -> ERP_ONAYLADI -> SEVK_EDILDI -> FATURALANDI
                     \-> FINANS_ONAYI_BEKLIYOR -> (ONAY) -> ERP_KUYRUGUNDA
                     \-> REDDEDILDI
ERP_KUYRUGUNDA -> ERP_HATASI -> (yeniden deneme) -> ERP_KUYRUGUNDA

Burada önemli olan iki şey var. Birincisi, portal siparişi "gönderildi" diye işaretlediği anda ERP'de sipariş oluşmuş değildir; müşteriye gösterilen ifade de buna uygun olmalıdır ("Siparişiniz alındı, onay bekleniyor" gibi). İkincisi, her durum geçişi kaydedilmelidir. Bir bayi "siparişim nerede?" diye aradığında müşteri temsilcisinin bakacağı yer bu geçmiştir.

3. Çift siparişi önlemek: Idempotency anahtarı

B2B'de çift sipariş, B2C'deki kadar masum değildir. Tek bir sipariş satırı birkaç palet hammadde olabilir. Çift kaydın en yaygın sebepleri bellidir: kullanıcı butona iki kez basar, mobil ağ yanıtı yarıda keser ve uygulama isteği tekrarlar, kuyruk tüketicisi mesajı işledikten sonra onay vermeden çöker ve mesaj yeniden teslim edilir.

Çözüm, her sipariş için istemci tarafında üretilen bir idempotency anahtarıdır. Sepet onay ekranı açıldığında bir UUID üretilir ve sipariş isteğiyle birlikte gönderilir. Sunucu tarafında bu anahtar benzersiz kısıtla saklanır:

CREATE TABLE portal_orders (
  id               BIGSERIAL PRIMARY KEY,
  idempotency_key  UUID NOT NULL UNIQUE,
  customer_code    TEXT NOT NULL,
  status           TEXT NOT NULL,
  erp_order_no     TEXT,
  created_at       TIMESTAMPTZ NOT NULL DEFAULT now()
);

Aynı anahtarla ikinci istek geldiğinde yeni sipariş oluşturulmaz; ilk siparişin durumu döndürülür. Aynı mantık entegrasyon katmanının ERP'ye yazdığı noktada da gerekir. ERP'nin sipariş kaydında harici referans alanı varsa (çoğunda "belge no", "harici referans" ya da benzeri bir alan bulunur) portal sipariş kimliği oraya yazılır ve ERP'ye göndermeden önce bu referansla kayıt olup olmadığı kontrol edilir. Böylece kuyruk mesajı iki kez işlense bile ERP'de tek sipariş oluşur.

4. Outbox deseni: Veritabanı ile kuyruk arasındaki boşluk

Klasik hata şudur: uygulama siparişi kendi veritabanına yazar, ardından kuyruğa bir mesaj atar. Veritabanı işlemi başarılı olur ama kuyruk çağrısı ağ hatası verirse sipariş portalda görünür, ERP'ye hiç gitmez. Ters sırada yaparsanız bu kez ERP'ye giden ama portalda olmayan bir sipariş oluşabilir.

Transactional outbox deseni bu boşluğu kapatır. Sipariş kaydı ile "gönderilecek mesaj" kaydı aynı veritabanı işlemi içinde yazılır:

def submit_order(conn, order, idempotency_key):
    with conn.transaction():
        order_id = insert_order(conn, order, idempotency_key, status="GONDERILDI")
        conn.execute(
            "INSERT INTO outbox (aggregate_id, event_type, payload) VALUES (%s, %s, %s)",
            (order_id, "OrderSubmitted", to_json(order)),
        )
    return order_id

Ayrı bir yayıncı süreç outbox tablosunu düzenli okur, mesajları kuyruğa iletir ve başarıyla iletilenleri işaretler. Yayıncı çökerse mesaj tabloda bekler; tekrar ayağa kalktığında kaldığı yerden devam eder. Bu yöntem "en az bir kez teslim" garantisi verir; bu yüzden bir önceki bölümdeki idempotency kontrolü zorunlu bir eştir. İkisi birlikte, pratikte "tam bir kez etki" sonucunu üretir.

5. Kredi limiti kontrolü nerede yapılmalı?

B2B portalının perakende e-ticaretten en belirgin farkı, ödemenin çoğu zaman sipariş anında değil vadeli olarak yapılmasıdır. Bu da her siparişte müşterinin açık hesap riskini, vadesi geçmiş borcunu ve tanımlı kredi limitini kontrol etmeyi gerektirir.

Bu kontrolün iki katmanda yapılması sağlıklıdır:

Portal tarafında ön kontrol: Sepet onay ekranında entegrasyon katmanı üzerinden ERP'den güncel risk bilgisi alınır. Limit aşılıyorsa kullanıcıya baştan söylenir; sipariş "Finans Onayı Bekliyor" durumuna gideceği açıkça belirtilir.
ERP tarafında kesin kontrol: Asıl karar ERP'ye yazılırken verilir, çünkü ön kontrol ile yazma arasında başka bir sipariş ya da tahsilat bakiyeyi değiştirmiş olabilir.

Ön kontrol için ERP'ye her sepet güncellemesinde sorgu atmak gerekmez. Risk bilgisini kısa süreli (örneğin birkaç dakikalık) önbellekte tutmak ve yalnızca onay adımında taze veri çekmek hem ERP'yi korur hem kullanıcı deneyimini hızlandırır. Finans onayına düşen siparişler için CRM'de ilgili müşteri temsilcisine otomatik görev açmak da iyi bir pratiktir; temsilci müşteriyi arayıp tahsilatı konuşabilir ve sipariş beklemede çürümez.

6. Kademeli fiyat listeleri ve önbellek

Her bayinin kendi iskonto grubu, hacim kademeleri ve bazen ürün bazlı özel fiyatları vardır. Portal her ürün listesinde bu fiyatları ERP'den anlık hesaplatırsa sayfa yavaşlar; tamamen önbellekten gösterirse yanlış fiyatla sipariş alma riski doğar.

İşe yarayan yaklaşım şudur:

Fiyat listeleri (price book) ve iskonto kuralları entegrasyon katmanı tarafından ERP'den periyodik olarak çekilip portalın okuma modeline yazılır. Değişiklik olayı yayınlayabilen bir ERP'de bu, olay tabanlı da yapılabilir.
Listeleme ve arama ekranları bu okuma modelinden beslenir.
Sepet onayı sırasında son fiyat ERP'den doğrulanır. Fark varsa kullanıcıya gösterilir ve onay yeniden istenir.
Her fiyat kaydında "geçerlilik başlangıcı" ve "son senkron zamanı" tutulur. Senkron belirli bir süreden uzun gecikirse sistem uyarı üretir.

Bu yapı, kampanya dönemlerinde fiyatların toplu değiştiği günlerde özellikle önem kazanır. Kullanıcı eski fiyatı görüp siparişi verdiğinde yaşanacak tartışma, birkaç saniyelik ek doğrulamadan çok daha pahalıdır.

7. CRM'e ne gider, ne gitmez?

Portal, ERP ve CRM aynı anda konuştuğunda en sık yapılan hata, her şeyi her yere kopyalamaktır. Pratikte iyi işleyen ayrım şöyledir:

ERP'de kalır: stok, fatura satırları, cari hareketler, risk hesaplaması. Bunların ana kaynağı ERP'dir.
CRM'e özet olarak gider: sipariş toplamı, sipariş sıklığı, son sipariş tarihi, ürün kategorisi dağılımı, finans onayına düşen siparişler.
CRM'de doğar: iletişim geçmişi, fırsatlar, upsell ve çapraz satış planları, müşteri memnuniyeti notları.

Bu özet veriler CRM'de çok değerli tetikleyicilere dönüşür. Örneğin düzenli olarak ayda bir sipariş veren bir bayi kırk beş gündür sipariş vermediyse temsilciye görev açılabilir. Bu, müşteri kaybını erken yakalamanın en ucuz yollarından biridir ve verinin tamamını değil yalnızca doğru özeti taşımayı gerektirir.

8. Gözlemlenebilirlik: Kaybolan siparişi beş dakikada bulmak

Entegrasyon katmanı kara kutu olursa her sorun bir suçlama oyununa döner: portal ekibi ERP'yi, ERP ekibi ağı, ağ ekibi kuyruğu suçlar. Bunu önlemek için baştan şunları koyun:

Her siparişe portal tarafında üretilen bir korelasyon kimliği atayın ve bu kimliği portal logundan kuyruk mesajına, oradan ERP isteğine kadar taşıyın.
Kuyrukta belirli sayıda başarısız denemeden sonra mesajı bir hata kuyruğuna (dead letter queue) alın ve bunun için alarm kurun. Sessizce bekleyen bir hata kuyruğu, en tehlikeli kuyruktur.
"Gönderildi ama belirli süredir ERP onayı yok" durumundaki siparişleri listeleyen basit bir panel hazırlayın. Operasyon ekibi sabah ilk iş bu listeye bakmalıdır.
ERP hata mesajlarını ham haliyle değil, sınıflandırarak saklayın: geçici hata (zaman aşımı, kilit), veri hatası (tanımsız ürün kodu, birim uyumsuzluğu), iş kuralı hatası (limit, bloke cari). Yeniden deneme yalnızca geçici hatalar için anlamlıdır.

9. Canlıya geçişten önce veri hijyeni

Entegrasyonun kalitesi, ERP'deki ana verinin kalitesini geçemez. Portal açılmadan önce ürün kodlarının, barkodların, birim çevrimlerinin (koli, adet, paket) ve cari kodlarının standartlaştırılması gerekir. Aynı ürünün iki farklı kodla tutulduğu ya da birim tanımının eksik olduğu bir katalogda, en iyi tasarlanmış idempotency ve outbox yapısı bile yanlış siparişi hatasız şekilde ERP'ye taşır.

Geçişi de kademeli yapmak mantıklıdır: önce teknolojiye yatkın, sadık küçük bir bayi grubuyla pilot yapılır, durum geçişleri ve hata kuyruğu birkaç hafta izlenir, sonra tüm ağa açılır. Pilot dönemde toplanan hata sınıfları, entegrasyonun gerçekte nerede zorlandığını gösteren en dürüst veridir.

Sık Sorulan Sorular (SSS)

Mesaj kuyruğu küçük bir portal için gereksiz karmaşıklık değil mi?
Günde birkaç sipariş alan bir yapıda kuyruk yerine outbox tablosunu doğrudan okuyan bir arka plan işi yeterli olabilir. Önemli olan kuyruğun kendisi değil, siparişin ERP geçici olarak erişilemezken kaybolmamasıdır.

Idempotency anahtarını sunucu mu üretmeli, istemci mi?
İstemci üretmelidir; çünkü amaç, aynı kullanıcı eyleminin tekrarlanan isteklerini tanımaktır. Sunucu yalnızca anahtarı benzersiz kısıtla saklar ve tekrar eden istekte ilk sonucu döndürür.

ERP harici referans alanı desteklemiyorsa ne yapılır?
Entegrasyon katmanı kendi eşleme tablosunu tutar: portal sipariş kimliği ile ERP belge numarası. ERP'ye yazmadan önce bu tabloya bakılır, yazdıktan hemen sonra tablo güncellenir. Bu durumda yazma ile eşleme arasındaki kısa boşluk için ERP tarafında periyodik bir mutabakat kontrolü eklemek iyi olur.

Fiyatları tamamen gerçek zamanlı göstermek mümkün değil mi?
Mümkün, ama ERP'nin hesaplama yükünü ve yanıt süresini portalın her sayfa açılışına bağlar. Okuma modeli ile listeleme, onayda kesin doğrulama yaklaşımı çoğu durumda hız ve doğruluk arasındaki en sağlıklı dengedir.

Kredi limiti aşıldığında sipariş tamamen reddedilmeli mi?
Çoğu B2B ilişkisinde hayır. Siparişi "Finans Onayı Bekliyor" durumuna almak ve ilgili temsilciye görev açmak, hem satışı kaybetmez hem riski kontrol altında tutar.

Bu yapıyı CRM tarafında nasıl değerlendirmeliyim?
Sipariş özetlerini CRM'e taşıyıp sipariş sıklığındaki düşüşleri, finans onayına düşen siparişleri ve kategori değişimlerini tetikleyici olarak kullanın. Portal yalnızca sipariş kanalı değil, müşteri davranışını ölçen bir veri kaynağı haline gelir.

Koray Yalçın; lead yönetimi, CRM mimarisi, dijital pazarlama ve yapay zekâ entegrasyonları üzerine çalışıyor. B2B ve gayrimenkul satış ekipleri için reklamdan CRM'e, CRM'den operasyon sistemlerine uzanan veri akışları kuruyor.

HubSpot'tan Salesforce'a veri taşırken External ID, upsert ve ilişki sırası: Geliştirici notları

Koray Yalçın — Thu, 22 Oct 2026 07:26:20 +0000

CRM göçü dendiğinde çoğu ekip önce lisans fiyatlarını, sonra arayüzü konuşur. Oysa projeyi gerçekten zorlayan kısım, yıllardır biriken kayıtların ve aralarındaki ilişkilerin bir sistemden ötekine bozulmadan taşınmasıdır. Ben, Koray Yalçın olarak lead yönetimi, CRM mimarisi ve pazarlama otomasyonu üzerine çalışırken bu işin büyük ölçüde bir veri mühendisliği problemi olduğunu defalarca gördüm. Bu yazıda HubSpot'tan Salesforce'a geçişi iş tarafından değil, kodu yazacak geliştiricinin gözünden ele alıyorum: kimlik eşleştirme, upsert mantığı, yükleme sırası, delta aktarımı ve doğrulama.

Yazı belirli bir aracı satmıyor. Data Loader, Bulk API, bir ETL aracı ya da kendi yazdığınız Python betiği; hangisini seçerseniz seçin, aşağıdaki ilkeler değişmiyor.

1. Sorun neden "Excel'i dışa aktar, içe aktar" kadar basit değil?

HubSpot ile Salesforce aynı kavramları farklı modellerle tutar. HubSpot'ta tek bir Contact nesnesi vardır; Salesforce ise ham adayı (Lead) ve nitelikli kişiyi (Contact) ayırır. HubSpot'taki Company, Salesforce'ta Account olur ve Account hiyerarşisi (ana şirket ile alt şirketler) çok daha katı işler. Deal, Opportunity'ye; Ticket, Case'e; özel property'ler ise __c sonekli özel alanlara dönüşür.

Bu farklar yüzünden tablo kopyalamak yetmez. Asıl taşınması gereken şey kayıtlar arasındaki bağlardır: bir fırsatın hangi şirkete ait olduğu, hangi kişiyle konuşulduğu, iki yıllık e-posta ve not geçmişinin kime bağlı olduğu. İlişkiler koparsa veri "taşınmış" görünür ama satış ekibi için işe yaramaz hale gelir.

2. Temel taş: External ID alanı

Göçün omurgası, kaynak sistemdeki benzersiz kimliğin hedef sisteme taşınmasıdır. HubSpot'ta her nesnenin bir hs_object_id değeri vardır. Salesforce tarafında her hedef nesneye, örneğin HubSpot_ID__c adında, External ID ve Unique olarak işaretlenmiş bir metin alanı açarsınız.

Bu alan üç işe yarar:

Upsert: Aynı kaydı ikinci kez gönderdiğinizde yeni kayıt oluşmaz, mevcut kayıt güncellenir. Göçü defalarca tekrar çalıştırabilmenin anahtarı budur.
İlişki kurma: Bir Opportunity yüklerken Salesforce'un kendi AccountId değerini bilmenize gerek kalmaz; ilişkiyi Account üzerindeki External ID ile kurabilirsiniz.
Denetim izi: Göçten aylar sonra bile bir kaydın HubSpot'taki karşılığını bulabilirsiniz.

Pratik bir uyarı: External ID alanını metin tipinde tutun. Kimlikler sayısal görünse bile, sayısal alan baştaki sıfırları ve büyük değerleri sorunlu işleyebilir.

3. Yükleme sırası: Önce ebeveyn, sonra çocuk

İlişkili nesneler bağımlılık sırasıyla yüklenmelidir. Tipik sıra şöyledir:

Kullanıcılar (User) ve sahiplik eşlemesi
Account (önce ana şirketler, sonra alt şirketler)
Contact (ve gerekiyorsa Lead)
Opportunity ve OpportunityContactRole
Case
Aktiviteler: Task, Event, notlar ve e-posta kayıtları

Account hiyerarşisini tek geçişte yüklemeye çalışmak sık yapılan bir hatadır. Alt şirket, henüz oluşmamış bir ana şirkete bağlanamaz. Güvenli yol iki geçiştir: önce tüm Account'ları ParentId boş olarak upsert edin, ardından ikinci bir geçişte yalnızca ebeveyn ilişkisini External ID üzerinden güncelleyin.

Sahiplik (OwnerId) de ayrı bir eşleme tablosu ister. HubSpot'taki owner kimliklerini Salesforce kullanıcılarına bağlayan küçük bir sözlük tutun ve işten ayrılmış kişilerin kayıtlarını kime devredeceğinize göçten önce karar verin.

4. Upsert ile ilişki kurmanın örneği

Aşağıdaki örnek, simple-salesforce kütüphanesiyle bir Opportunity'yi kendi External ID'si üzerinden upsert ediyor ve Account ilişkisini Account'un External ID'siyle kuruyor. Kimlik bilgileri ortam değişkenlerinden okunuyor; anahtarları koda yazmayın.

import os
from simple_salesforce import Salesforce

sf = Salesforce(
    username=os.environ["SF_USER"],
    password=os.environ["SF_PASS"],
    security_token=os.environ["SF_TOKEN"],
    domain="test",  # önce sandbox
)

def upsert_opportunity(deal: dict) -> None:
    payload = {
        "Name": deal["dealname"],
        "StageName": STAGE_MAP[deal["dealstage"]],
        "CloseDate": deal["closedate"][:10],
        "Amount": deal.get("amount"),
        # İlişkiyi Salesforce Id yerine Account'un External ID'si ile kur
        "Account": {"HubSpot_ID__c": deal["company_id"]},
    }
    sf.Opportunity.upsert(f"HubSpot_ID__c/{deal['hs_object_id']}", payload)

Burada iki şey önemli. Birincisi STAGE_MAP: HubSpot pipeline aşamaları ile Salesforce StageName picklist değerleri birebir eşleştirilmeli ve eşleşmeyen her değer yükleme başlamadan raporlanmalı. İkincisi tarih ve para birimi: çok para birimli bir yapıdaysanız CurrencyIsoCode alanını ve kur tablosunu göçten önce kurun.

Büyük hacimlerde kayıt kayıt çağrı yapmak yerine Bulk API 2.0 kullanın. Mantık aynıdır; CSV içinde ilişki sütununu Account.HubSpot_ID__c gibi bir başlıkla verirsiniz ve Salesforce eşleştirmeyi kendisi yapar.

5. Önce temizlik: Tekrarlı kayıtlar taşınmaz, çözülür

Kirli veriyi yeni sisteme taşımak, sorunu pahalı bir sisteme kopyalamaktır. Göç öncesi temizlik adımında en azından şunları yapın:

E-posta adreslerini küçük harfe çevirip boşlukları temizleyin, telefonları tek bir biçime (örneğin E.164) getirin.
Aynı e-postaya sahip kişileri ve aynı alan adına sahip şirketleri gruplayın, hangisinin "ana kayıt" olacağına kural ile karar verin (en son aktivite, en dolu kayıt gibi).
Uzun süredir hareketsiz kayıtları taşımak yerine arşivlemeyi değerlendirin.
Birleştirilen kayıtların eski kimliklerini bir eşleme tablosunda saklayın; aksi halde bu kimliklere bağlı aktiviteler sahipsiz kalır.

Salesforce tarafında duplicate ve matching kurallarını göç sırasında geçici olarak gevşetmeniz gerekebilir; ama bunu bilinçli yapın ve göç bitince yeniden açın.

6. Kuru çalıştırma (dry run) ve sandbox

Üretime dokunmadan önce tam bir prova yapın. Kaynak sistem rehberinde de önerilen yaklaşım, kayıtların rastgele bir örneklemini sandbox'a aktarıp doğrulamaktır. Geliştirici açısından bu provanın çıktısı bir rapor olmalı:

Her nesne için kaynak kayıt sayısı, başarılı ve başarısız yükleme sayısı
Hata kodlarına göre gruplanmış başarısızlıklar (zorunlu alan eksik, picklist uyuşmazlığı, doğrulama kuralı gibi)
Rastgele seçilmiş kayıtlarda alan alan karşılaştırma

Bu raporu her provada yeniden üretebiliyorsanız, göçünüz tekrarlanabilir demektir. Upsert ve External ID sayesinde aynı betiği ikinci, üçüncü kez çalıştırmak yeni kopya üretmez; sadece farkları günceller.

Bir de otomasyonlara dikkat: Salesforce'ta tetikleyiciler, Flow'lar ve doğrulama kuralları yükleme sırasında devreye girerek binlerce gereksiz e-posta ya da görev üretebilir. Göç kullanıcısı için bunları atlayan bir mekanizma (örneğin özel bir izin ya da ayar ile kontrol edilen bir bayrak) kurmak işinizi çok kolaylaştırır.

7. Kesin geçiş ve delta aktarımı

Tam veri aktarımı saatler sürebilir; bu sırada satış ekibi HubSpot'ta çalışmaya devam eder. Bu yüzden geçiş iki parçalı planlanır:

Ana yükleme: Geçişten günler önce tüm geçmiş veri upsert edilir.
Delta: Geçiş anında HubSpot salt okunur hale getirilir ve ana yüklemeden sonra değişen kayıtlar (son değişiklik tarihine göre filtrelenerek) tekrar gönderilir.

Delta için ana yüklemenin başladığı zaman damgasını kaydedin ve küçük bir güvenlik payı bırakın. Upsert kullandığınız için çakışan kayıtlar sorun çıkarmaz; aynı kayıt iki kez gelirse sadece güncellenir.

Geçişten sonra web formları, reklam platformlarının sunucu taraflı dönüşüm entegrasyonları ve diğer uç noktalar Salesforce'a yönlendirilir. Bu adım çoğu zaman unutulur ve ilk gün gelen leadler eski sisteme düşer. Geçiş kontrol listesine her entegrasyonu tek tek yazın.

8. Doğrulama: "Yüklendi" ile "doğru" aynı şey değil

Göçten sonra şu kontrolleri otomatikleştirin:

Sayım eşitliği: Nesne bazında kaynak ve hedef kayıt sayıları (arşivlenenler ve birleştirilenler düşüldükten sonra) tutuyor mu?
İlişki bütünlüğü: Account'u boş kalan Opportunity var mı? Sahipsiz aktivite var mı?
Toplam değerler: Aşama bazında toplam fırsat tutarı iki sistemde aynı mı?
Örneklem karşılaştırması: Rastgele kayıtlarda alan değerleri birebir eşleşiyor mu?

Bu kontroller bir kez değil, ilk haftalarda düzenli çalışmalı. Satış ekibinin "bu müşterinin geçmişi kaybolmuş" şikâyeti geldiğinde External ID sayesinde sorunu dakikalar içinde izleyebilirsiniz.

9. Kod kadar önemli: Kullanıcı benimsemesi

Teknik olarak kusursuz bir göç bile satış temsilcileri yeni sistemi kullanmazsa başarısız sayılır. Geliştirici olarak katkınız burada da büyük: sayfa düzenlerini sadeleştirip temsilcinin günlük işinde gerçekten kullandığı az sayıda alanı öne çıkarmak, e-posta ve takvim kayıtlarının otomatik işlenmesini sağlamak ve rol bazlı (SDR, AE, yönetici) farklı görünümler hazırlamak benimsemeyi doğrudan etkiler.

Kısa kontrol listesi

Her hedef nesnede HubSpot_ID__c External ID ve Unique alanı
Aşama, owner ve picklist eşleme tabloları, eşleşmeyen değer raporu
Temizlik ve birleştirme kuralları, eski kimlik eşleme tablosu
Bağımlılık sırasına göre yükleme, Account hiyerarşisi için iki geçiş
Sandbox provası ve tekrarlanabilir hata raporu
Göç sırasında otomasyonları atlayan bayrak
Ana yükleme, zaman damgası ve delta
Entegrasyon uç noktalarının yeniden yönlendirilmesi
Sayım, ilişki ve toplam değer doğrulamaları

SSS

External ID kullanmadan göç yapılabilir mi?
Yapılabilir ama önerilmez. External ID olmadan her ilişki için Salesforce'un ürettiği kimlikleri bulup eşlemeniz gerekir ve göçü güvenle tekrar çalıştıramazsınız. Her tekrar yeni kopyalar üretir.

Lead mi Contact mı? HubSpot kişilerini nereye taşımalıyım?
Genel yaklaşım, henüz nitelendirilmemiş adayları Lead, bir şirketle ilişkilendirilmiş ve satış sürecine girmiş kişileri Contact olarak taşımaktır. Kuralı yaşam döngüsü aşaması gibi açık bir alana bağlayın ki karar kişiden kişiye değişmesin.

Aktivite geçmişini taşımak şart mı?
Satış ekibi için çoğu zaman en değerli veri budur. Hacim büyükse son belirli bir dönemi tam taşıyıp daha eskisini arşivde erişilebilir tutmak makul bir orta yoldur.

Göç ne kadar sürer?
Bu tamamen veri hacmine, özel nesne sayısına ve entegrasyonlara bağlıdır. Süreyi belirleyen şey genellikle yükleme değil, temizlik ve eşleme kararlarıdır.

Bulk API mi, kayıt kayıt REST çağrısı mı?
Binlerce kaydın üzerindeki her şey için Bulk API daha uygundur. REST çağrıları küçük düzeltmeler ve delta aktarımı için pratiktir.

Göç sırasında satış ekibi çalışmaya devam edebilir mi?
Evet, ana yükleme sırasında edebilir. Yalnızca kesin geçiş penceresinde kaynak sistem salt okunur yapılır; bu yüzden pencereyi hafta sonu gibi düşük yoğunluklu bir zamana planlamak yaygındır.

Koray Yalçın; lead yönetimi, CRM mimarisi, dijital pazarlama ve yapay zekâ entegrasyonları üzerine çalışıyor. Gayrimenkul ve B2B satış ekipleri için reklamdan CRM'e uzanan veri akışları kuruyor.

Pazarlama ekibi için RAG kurarken parçalama ve metadata: Sahada öğrenilen dersler

Koray Yalçın — Wed, 21 Oct 2026 13:09:55 +0000

Pazarlama ekiplerine yapay zekâ asistanı kurma talebi genelde aynı cümleyle gelir: "ChatGPT gibi olsun ama bizim ürünlerimizi bilsin." İlk prototip birkaç saatte çıkar, sonra sorun başlar. Asistan geçen yılın fiyat listesinden teklif yazar, sunulmayan bir özelliği vaat eder ya da iki farklı ürünün şartlarını tek cevapta karıştırır.

Koray Yalçın'ın pazarlama ekipleri için RAG mimarisini anlattığı yazısı, bu riskin neden ticari bir risk olduğunu ve RAG'ın (Retrieval-Augmented Generation, yani modelin cevap üretmeden önce şirketin doğrulanmış dokümanlarından ilgili pasajları getirmesi) bunu nasıl azalttığını üst seviyeden anlatıyor. Yazıdaki en önemli tespitlerden biri şu: sistemin başarısı modelin büyüklüğünden çok bilginin nasıl parçalandığına bağlı. Ben bu yazıda o cümleyi geliştirici tarafından açmak istiyorum.

Sabit boyutlu parçalama neden pazarlama dokümanında kırılır

Metni 500 kelimelik bloklara bölmek kolaydır ve teknik dokümantasyonda çoğu zaman yeterlidir. Pazarlama dokümanları ise farklıdır: bir kampanya koşulları sayfasında "geçerlilik tarihi", "kapsam dışı ürünler" ve "fiyat" birbirine bağlı üç küçük bölümdür. Bölme noktası tam ortaya denk gelirse, getirilen pasajda fiyat vardır ama hangi döneme ait olduğu yoktur. Model de boşluğu kendinden emin bir dille doldurur.

Bu yüzden başlıkları, madde listelerini ve tabloları bütün tutan anlamsal parçalamayı varsayılan yapmak daha güvenlidir.

Her parçaya kimliğini taşıtın

Parçalamanın ikinci yarısı metadata'dır. Bir pasajın tek başına anlamlı olması için hangi dokümandan, hangi başlıktan, hangi tarihte geldiğini bilmesi gerekir. Basit bir yapı şöyle olabilir:

from dataclasses import dataclass
from datetime import date

@dataclass
class Chunk:
    text: str
    doc_id: str
    section_path: list[str]   # ["Fiyatlandırma", "Kurumsal Paket"]
    doc_type: str             # "fiyat_listesi", "vaka_analizi", "marka_kilavuzu"
    valid_from: date
    valid_until: date | None
    owner: str                # dokümandan sorumlu ekip

def embed_input(c: Chunk) -> str:
    # Başlık yolunu metnin başına eklemek, kısa pasajların
    # bağlamını embedding'e de taşır.
    return " > ".join(c.section_path) + "\n\n" + c.text

Burada iki küçük karar büyük fark yaratıyor. Birincisi, başlık yolunu embedding girdisine eklemek: "Kurumsal Paket" altındaki iki cümlelik bir pasaj, bağlamı olmadan aranınca neredeyse hiçbir soruya eşleşmez. İkincisi, geçerlilik tarihleri: eski fiyat listesini silmek yerine valid_until ile işaretleyip sorgu anında filtrelemek hem geçmişe dönük soruları cevaplamayı sağlar hem de güncel cevaplarda eski bilgiyi dışarıda bırakır.

Getirmeden önce filtreleyin

Vektör araması "en benzer" olanı bulur, "en doğru" olanı değil. Fiyat sorulan bir soruda vaka analizinden gelen bir pasaj semantik olarak çok benzer olabilir. Pratikte iyi çalışan yaklaşım, soruyu önce basit bir sınıflandırmadan geçirip doc_type ve tarih filtresini aramaya eklemek, sonra kalan adaylar içinde benzerlik sıralaması yapmaktır. Pinecone, Qdrant ve Milvus gibi vektör veritabanlarının hepsi metadata filtresini destekliyor; bu özelliği kullanmamak en sık gördüğüm hatalardan biri.

Kaynak göstermeyen cevabı reddedin

Son katman üretim adımı. Modele "yalnızca verilen pasajlardan cevap ver, her iddianın yanına doc_id yaz, pasajlarda yoksa bilmediğini söyle" talimatını vermek yetmez; bunu kodda da doğrulamak gerekir. Cevapta geçen kaynak kimlikleri getirilen parçalar arasında değilse ya da hiç kaynak yoksa cevap kullanıcıya gitmeden işaretlenmeli. Satış ekibinin müşteri karşısında kullandığı bir asistanda "bilmiyorum" demek, yanlış bir taahhütten her zaman ucuzdur.

Küçük bir kontrol listesi

Parçalama başlık ve tablo sınırlarına saygı duyuyor mu?
Her parçada doküman türü, başlık yolu ve geçerlilik tarihi var mı?
Arama öncesi metadata filtresi uygulanıyor mu?
Cevaptaki her iddia getirilen bir parçaya bağlanabiliyor mu?
Dokümanın sahibi belli mi, güncellenince yeniden indeksleniyor mu?

Mimarinin bütününü, doküman havuzundan üretim adımına kadar akışı ve pazarlama tarafındaki kullanım alanlarını (teklif şartnamesi yanıtlama, marka dili kontrolü, satış temsilcisi asistanı) merak edenler için kaynak yazı: Pazarlama Ekipleri İçin RAG ve Kurumsal Bilgi Tabanı Mimarisi

Pazarlama olaylarını sunucuda toplamak: Bir geliştiricinin kontrol listesi

Koray Yalçın — Wed, 21 Oct 2026 11:02:12 +0000

Pazarlama ekibi "dönüşümler panelde düşük görünüyor" dediğinde, sorun çoğu zaman kampanyada değil, verinin yolculuğundadır. Tarayıcıda çalışan izleme kodları reklam engelleyicilere, Safari'nin çerez kısıtlamalarına ve onay bannerlarına takılır. Sonuçta reklam panelindeki sayı ile CRM'deki gerçek satış birbirinden uzaklaşır.

Koray Yalçın'ın GA4, PostHog ve CDP üzerine yazdığı mimari yazısı bu tabloyu üst seviyeden anlatıyor: birinci taraf veri toplama, sunucu taraflı etiketleme, merkezi veri ambarı ve Reverse ETL ile verinin CRM'e ve reklam platformlarına geri yazılması. Ben bu yazıda aynı mimariye geliştirici koltuğundan bakmak ve işi yaparken sık atlanan teknik noktaları bir kontrol listesine dökmek istiyorum.

1. Olayı bir kez tanımla, her yere aynı adla gönder

Sunucu taraflı kurulumda en büyük kazanç, tek bir olay şemasından GA4'e, ürün analitiğine ve reklam platformlarına dağıtım yapabilmektir. Bunun çalışması için olay adlarının ve alanlarının baştan sabitlenmesi gerekir. form_submit, formSubmitted ve lead aynı şeyi anlatıyorsa, üç ayrı rapor ve üç ayrı tartışma doğar.

Pratik öneri: olay sözlüğünü kodla birlikte versiyonlayın. Basit bir JSON şeması ya da TypeScript tipi bile, yeni bir alan eklendiğinde kimin neyi bozduğunu görmenizi sağlar.

2. Kişisel veriyi tarayıcıdan dışarı çıkarmayın

E-posta ve telefon gibi kişisel verileri doğrudan üçüncü taraf betiklere vermek yerine, kendi sunucunuza alın, normalize edin ve hash'leyin. Burada en sık hata normalizasyonu atlamaktır: büyük harf, baştaki boşluk ya da ülke kodu farkı, aynı kişiyi farklı bir hash'e dönüştürür ve eşleşme oranı sessizce düşer.

import hashlib

def normalize_email(email: str) -> str:
    return email.strip().lower()

def normalize_phone(phone: str, default_cc: str = "90") -> str:
    digits = "".join(ch for ch in phone if ch.isdigit())
    if digits.startswith("0"):
        digits = default_cc + digits[1:]
    return digits

def sha256(value: str) -> str:
    return hashlib.sha256(value.encode("utf-8")).hexdigest()

Bu adım aynı zamanda KVKK ve GDPR açısından da savunulabilir bir sınır çizer: ham veri sizin altyapınızda kalır, dışarıya yalnızca gerekli ve dönüştürülmüş alanlar çıkar. Hangi alanın hangi hedefe gittiğini bir tabloda belgelemek, denetim günü işinizi çok kolaylaştırır.

3. Çift sayımı event_id ile önleyin

Geçiş döneminde hem tarayıcı pikseli hem sunucu çağrısı aynı dönüşümü gönderir. Reklam platformlarının çoğu bu ikisini ortak bir olay kimliğiyle eşleştirip tekilleştirir. Kimliği istemcide üretip hem piksele hem sunucu isteğine aynı değeri taşımazsanız, dönüşümler bir anda iki katına çıkar ve kimse bunun bir hata olduğunu hemen fark etmez.

4. Alt alan adını ve gecikmeyi ciddiye alın

Toplayıcıyı data.alanadiniz.com gibi kendi alt alan adınızda çalıştırmak, isteklerin birinci taraf olarak işlenmesine yardım eder. Ama bu sunucu artık sizin üretim altyapınızın parçasıdır: izleme, alarm ve hata günlüğü ister. Toplayıcı çöktüğünde veri sessizce kaybolur; sağlık kontrolü ve kuyruk (retry) mekanizması olmadan kurulan bir sunucu taraflı izleme, tarayıcı tarafındakinden daha kırılgan olabilir.

5. Ürün olaylarını pazarlama verisiyle aynı kimlikte buluşturun

GA4 "ziyaretçi nereden geldi" sorusuna, PostHog gibi ürün analitiği araçları ise "geldikten sonra ne yaptı" sorusuna cevap verir. İkisini anlamlı kılan şey ortak bir kullanıcı ya da hesap kimliğidir. Kayıt anında anonim kimliği gerçek kullanıcı kimliğiyle birleştirmeyi (identify) unutmak, huniyi ortadan ikiye böler.

6. Veri ambarı tek doğruluk kaynağı olsun

BigQuery ya da Snowflake gibi bir ambarda modellenen veri, Reverse ETL araçlarıyla CRM'e ve reklam kitlelerine geri yazılabilir. Geliştirici açısından kritik nokta, bu senkronizasyonların da kod gibi yönetilmesidir: SQL modelleri versiyon kontrolünde, test edilmiş ve sahibi belli olmalı.

Kapanış

Sunucu taraflı izleme bir etiket yöneticisi ayarı değil, küçük bir veri ürünüdür. Olay sözlüğü, hash normalizasyonu, tekilleştirme ve gözlemlenebilirlik doğru kurulduğunda pazarlama ile finansın gördüğü sayılar birbirine yaklaşır.

Mimarinin tamamını, GA4 ve PostHog karşılaştırmasını ve Composable CDP yaklaşımını kaynak yazıda okuyabilirsiniz: Modern Pazarlama ve Büyüme Analitiği: GA4, PostHog ve CDP Veri Mimarisi