DEV Community: Koray Yalçın

Lead entegrasyonlarında hata yönetimi: Hata sınıflandırma, jitter'lı retry, idempotency, dead-letter ve replay

Koray Yalçın — Wed, 11 Nov 2026 16:23:40 +0000

Reklamdan CRM'e uzanan bir lead akışında en pahalı hata, gürültü çıkaran hata değildir. En pahalı hata, hiç kimsenin fark etmediği hatadır. Bir webhook 500 döner, otomasyon aracı "başarısız" diye küçük bir kırmızı ikon gösterir, kimse bakmaz; üç gün sonra satış ekibi "bu kampanyadan neden hiç lead gelmedi" diye sorar. Formu dolduran kişi o sırada çoktan başka bir projeyle görüşmeye başlamıştır.

Ben Koray Yalçın; lead yönetimi, CRM ve dijital pazarlama altyapıları üzerine, özellikle gayrimenkul ve PropTech tarafında çalışıyorum. Bu yazıda hata yönetimini bir "try/catch alışkanlığı" olarak değil, bir tasarım kararı olarak ele alacağım: hatalar nasıl sınıflandırılır, ne zaman ve nasıl yeniden denenir, aynı lead'in iki kez oluşması nasıl engellenir, kurtarılamayan mesajlar nereye gider ve sonradan nasıl güvenle yeniden oynatılır. Örnekler TypeScript ve PostgreSQL ile, ama fikirler dil bağımsız.

Problemi doğru tanımlamak: "Hata" tek bir şey değil

Bir lead entegrasyonunda tipik zincir şöyledir: reklam platformu (Meta Lead Ads, Google lead form uzantısı) veya landing page formu bir olay üretir, bu olay sizin alıcı servisinize gelir, servis veriyi doğrular ve zenginleştirir, ardından CRM'e yazar ve son olarak bildirim ya da WhatsApp/SMS gibi bir ilk temas adımını tetikler.

Bu zincirin her halkasında farklı türde hatalar çıkar ve hepsine aynı tepkiyi vermek iki kötü sonuçtan birine yol açar: ya her şeyi sonsuza kadar yeniden denersiniz ve kalıcı hatalar kuyruğu tıkar, ya da ilk hatada vazgeçersiniz ve geçici bir ağ kesintisi yüzünden lead kaybedersiniz.

Bu yüzden ilk iş, hataları davranışa göre sınıflandırmaktır. Ben pratikte dört sınıf kullanıyorum:

Geçici (transient): Zaman aşımı, bağlantı kopması, 502/503/504, hız sınırı (429). Aynı istek bir süre sonra büyük ihtimalle başarılı olur.
Kalıcı veri hatası (permanent-data): Zorunlu alan eksik, telefon biçimi çözülemiyor, CRM bir alanı reddediyor (400/422). Aynı veriyle yüz kez denemek sonucu değiştirmez; verinin düzeltilmesi gerekir.
Kalıcı yapılandırma hatası (permanent-config): Süresi dolmuş token (401), yetki eksikliği (403), silinmiş bir pipeline aşaması ya da alan. Veri doğru, ama sistem yanlış ayarlı. Düzeltildiğinde tüm bekleyen mesajlar tekrar oynatılabilir olmalıdır.
Belirsiz (unknown): İstek gitti, ama cevap gelmeden bağlantı koptu. İşlem karşı tarafta gerçekleşmiş olabilir de olmayabilir de. En tehlikeli sınıf budur, çünkü körü körüne yeniden denemek mükerrer kayıt üretebilir.

Bu ayrımın kodda açıkça görünmesi gerekir; HTTP durum kodlarını iş mantığının içine dağıtmak yerine tek bir sınıflandırma fonksiyonu yazmak işi çok kolaylaştırır.

// errors.ts
export type ErrorClass = "transient" | "permanent_data" | "permanent_config" | "unknown";

export class IntegrationError extends Error {
  constructor(
    message: string,
    public readonly cls: ErrorClass,
    public readonly retryAfterMs?: number,
    public readonly detail?: unknown,
  ) {
    super(message);
  }
}

export function classifyHttp(status: number, headers: Headers, body: unknown): IntegrationError {
  const retryAfter = parseRetryAfter(headers.get("retry-after"));
  if (status === 429) return new IntegrationError("rate_limited", "transient", retryAfter, body);
  if (status >= 500) return new IntegrationError(`upstream_${status}`, "transient", retryAfter, body);
  if (status === 401 || status === 403) return new IntegrationError("auth_or_permission", "permanent_config", undefined, body);
  if (status === 404) return new IntegrationError("target_missing", "permanent_config", undefined, body);
  if (status === 400 || status === 422) return new IntegrationError("rejected_payload", "permanent_data", undefined, body);
  return new IntegrationError(`unexpected_${status}`, "unknown", undefined, body);
}

export function classifyNetwork(err: unknown, requestSent: boolean): IntegrationError {
  // İstek hiç gönderilmediyse (DNS, bağlantı reddi) güvenle geçici sayılabilir.
  // Gönderildikten sonra kopma ise sonuç belirsizdir.
  return new IntegrationError(String(err), requestSent ? "unknown" : "transient");
}

function parseRetryAfter(v: string | null): number | undefined {
  if (!v) return undefined;
  const sec = Number(v);
  if (!Number.isNaN(sec)) return sec * 1000;
  const at = Date.parse(v);
  return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now());
}

Burada önemli bir nokta var: 404'ü "veri hatası" değil "yapılandırma hatası" saydım. Lead akışlarında 404 çoğu zaman birisinin CRM'de bir aşamayı, kullanıcıyı ya da özel alanı silmesinden kaynaklanır. Bu durumda tek tek lead'leri düzeltmek yerine eşlemeyi düzeltip hepsini toplu yeniden oynatmak gerekir. Sınıflandırma, sonradan alacağınız operasyonel aksiyonu belirlemelidir.

Önce kalıcı kayıt, sonra işlem: Gelen olayı kaybetmemek

Webhook alıcısında en sık gördüğüm hata, gelen isteği alır almaz CRM'e yazmaya çalışmak ve CRM yavaşsa ya da hata verirse kaynak platforma da hata döndürmektir. Bu durumda yeniden deneme sorumluluğunu tamamen kaynak platforma bırakmış olursunuz; onun yeniden deneme politikası ise sizin kontrolünüzde değildir.

Daha sağlam desen şudur: gelen olayı önce kendi veritabanınıza ham haliyle yazın, hızlıca 200 dönün, işlemi arka planda yapın.

CREATE TABLE inbound_event (
  id            bigserial PRIMARY KEY,
  source        text        NOT NULL,          -- 'meta_lead_ads', 'web_form', ...
  source_ref    text        NOT NULL,          -- kaynağın kendi olay/lead kimliği
  received_at   timestamptz NOT NULL DEFAULT now(),
  payload       jsonb       NOT NULL,
  status        text        NOT NULL DEFAULT 'pending', -- pending|processing|done|dead
  attempts      int         NOT NULL DEFAULT 0,
  next_attempt_at timestamptz NOT NULL DEFAULT now(),
  last_error_class text,
  last_error    text,
  UNIQUE (source, source_ref)
);

CREATE INDEX inbound_event_due ON inbound_event (next_attempt_at)
  WHERE status = 'pending';

UNIQUE (source, source_ref) kısıtı burada sessiz bir kahramandır. Kaynak platform aynı olayı iki kez gönderirse (ki webhook'lar "en az bir kez" teslim garantisiyle çalışır) ikinci kayıt veritabanı seviyesinde reddedilir:

// webhook handler
await db.query(
  `INSERT INTO inbound_event (source, source_ref, payload)
   VALUES ($1, $2, $3)
   ON CONFLICT (source, source_ref) DO NOTHING`,
  ["meta_lead_ads", body.leadgen_id, body],
);
return new Response("ok", { status: 200 });

İmza doğrulaması (örneğin Meta webhook'larında gelen imza başlığının uygulama gizli anahtarıyla doğrulanması) bu adımdan önce yapılmalıdır. İmzası tutmayan istek kalıcı bir hata değildir, saldırı ya da yanlış yapılandırmadır; kaydetmeden reddedin ve ayrıca loglayın.

Jitter'lı exponential backoff: Yeniden denemeyi düzgün yapmak

Geçici hatalarda yeniden deneme şarttır, ama sabit aralıklı ya da anında yeniden deneme iki sorun çıkarır. Birincisi, karşı sistem zaten zorlanıyorsa onu daha da boğarsınız. İkincisi, bir kesintiden sonra biriken bütün mesajlar aynı saniyede tekrar denenir ve "thundering herd" dediğimiz ani yük oluşur.

Çözüm, katlanarak büyüyen bekleme süresine rastgelelik (jitter) eklemektir. Ben genellikle "full jitter" yaklaşımını kullanıyorum: bekleme süresi sıfır ile o denemenin üst sınırı arasında rastgele seçilir.

// backoff.ts
const BASE_MS = 2_000;
const CAP_MS = 30 * 60_000; // tek bekleme en fazla 30 dk
export const MAX_ATTEMPTS = 12;

export function nextDelayMs(attempt: number, retryAfterMs?: number): number {
  const ceiling = Math.min(CAP_MS, BASE_MS * 2 ** attempt);
  const jittered = Math.random() * ceiling;
  // Karşı taraf Retry-After verdiyse ondan erken deneme
  return Math.max(jittered, retryAfterMs ?? 0);
}

Buradaki sayılar örnek değerlerdir; doğru değerler sizin iş gereksiniminize bağlıdır. Lead akışında belirleyici soru şudur: bir lead en geç ne kadar sürede satış ekibinin önüne düşmeli? Gayrimenkulde ilk temas hızı satış sonucunu doğrudan etkilediği için, ben yeniden deneme penceresini saatlerle değil dakikalarla düşünmeyi ve pencere dolmadan önce bir insanı uyarmayı tercih ediyorum. Yeniden deneme sistemi lead'i "sonunda" teslim ederse ama bu altı saat sürerse, teknik olarak başarılı, ticari olarak başarısız olmuşsunuzdur.

Worker: Sınıfa göre karar veren tek döngü

Arka plan işçisi, vadesi gelen olayları alır, işler ve sonucu hata sınıfına göre kaydeder. Birden fazla işçi aynı anda çalışabileceği için satırları FOR UPDATE SKIP LOCKED ile kilitlemek, aynı olayın iki işçi tarafından aynı anda işlenmesini engeller.

// worker.ts
async function tick() {
  const { rows } = await db.query(
    `UPDATE inbound_event SET status = 'processing'
     WHERE id IN (
       SELECT id FROM inbound_event
       WHERE status = 'pending' AND next_attempt_at <= now()
       ORDER BY next_attempt_at
       LIMIT 20
       FOR UPDATE SKIP LOCKED
     )
     RETURNING *`,
  );

  for (const ev of rows) {
    try {
      await processLead(ev);            // doğrula, normalize et, CRM'e yaz
      await markDone(ev.id);
    } catch (e) {
      const err = e instanceof IntegrationError ? e : new IntegrationError(String(e), "unknown");
      await handleFailure(ev, err);
    }
  }
}

async function handleFailure(ev: InboundEvent, err: IntegrationError) {
  const attempts = ev.attempts + 1;
  const retryable = err.cls === "transient" || err.cls === "unknown";

  if (retryable && attempts < MAX_ATTEMPTS) {
    const delay = nextDelayMs(attempts, err.retryAfterMs);
    await db.query(
      `UPDATE inbound_event
       SET status='pending', attempts=$2, next_attempt_at=now() + ($3 || ' milliseconds')::interval,
           last_error_class=$4, last_error=$5
       WHERE id=$1`,
      [ev.id, attempts, delay, err.cls, err.message],
    );
    return;
  }
  await moveToDeadLetter(ev, err, attempts);
}

"Belirsiz" sınıfını yeniden denenebilir saydığıma dikkat edin. Bunu güvenle yapabilmemin tek sebebi, bir sonraki bölümdeki idempotency katmanı. O katman yoksa belirsiz hataları otomatik yeniden denemek yerine insan incelemesine göndermek daha doğrudur.

Idempotency: Aynı lead'i iki kez yaratmamak

Belirsiz hata senaryosunu düşünün: CRM'e "lead oluştur" isteğini gönderdiniz, CRM kaydı oluşturdu, ama cevap size ulaşmadan bağlantı koptu. Yeniden denerseniz CRM'de aynı kişi iki kez görünür; iki farklı danışmana atanabilir, iki kez aranabilir. Bu, müşterinin gözünde kurumun düzensiz görünmesinin en hızlı yoludur.

Bunu engellemenin üç yolu var ve genellikle en az ikisini birlikte kullanıyorum:

Karşı sistemin idempotency desteği: Bazı API'ler bir idempotency anahtarı başlığı kabul eder; aynı anahtarla gelen ikinci istek yeni kayıt oluşturmaz, ilk sonucu döner. Varsa mutlaka kullanın ve anahtarı source + source_ref gibi deterministik bir değerden türetin, rastgele üretmeyin.
Harici kimlik ile upsert: CRM'de "harici kaynak kimliği" gibi benzersiz bir özel alan tanımlayın ve "oluştur" yerine "bu harici kimlikle varsa güncelle, yoksa oluştur" mantığıyla yazın.
Yerel eşleme tablosu: Hangi olayın hangi CRM kaydına dönüştüğünü kendi tarafınızda tutun.

CREATE TABLE crm_link (
  source      text NOT NULL,
  source_ref  text NOT NULL,
  crm_object  text NOT NULL,      -- 'lead', 'contact', 'deal'
  crm_id      text NOT NULL,
  created_at  timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (source, source_ref, crm_object)
);

async function upsertLeadInCrm(ev: InboundEvent, lead: NormalizedLead) {
  const existing = await findCrmLink(ev.source, ev.source_ref, "lead");
  if (existing) return existing.crm_id;

  // Belirsiz bir önceki denemeden kalmış olabilir: önce CRM'de harici kimlikle ara
  const found = await crm.searchByExternalId(`${ev.source}:${ev.source_ref}`);
  const crmId = found ?? (await crm.createLead({
    ...lead,
    external_id: `${ev.source}:${ev.source_ref}`,
  }, { idempotencyKey: `${ev.source}:${ev.source_ref}` }));

  await saveCrmLink(ev.source, ev.source_ref, "lead", crmId);
  return crmId;
}

Bu katman, kişi düzeyindeki tekilleştirmenin (aynı kişinin farklı formlardan iki kez gelmesi) yerine geçmez. O ayrı bir problemdir ve eşleşme kuralları gerektirir. Buradaki amaç daha dardır: aynı olayın iki kez işlenmesini engellemek.

Zincirin sonraki adımları için de aynı ilke geçerlidir. Lead CRM'e yazıldıktan sonra tetiklenen WhatsApp ilk mesajı, danışman bildirimi ya da görev oluşturma adımlarının her biri kendi idempotency anahtarına sahip olmalıdır. Aksi halde CRM adımı başarılı olup bildirim adımı başarısız olduğunda tüm akışı yeniden denemek, müşteriye ikinci kez "merhaba" mesajı gitmesine yol açar. Bu yüzden ben her yan etkiyi ayrı bir adım olarak kaydediyor ve yalnızca tamamlanmamış adımları yeniden deniyorum.

Dead-letter tablosu: Kurtarılamayanı kaybetmeden ayırmak

Kalıcı hatalar ve deneme hakkı biten olaylar silinmemeli, ayrı bir yere taşınmalıdır. Bu "dead-letter" alanı bir çöp kutusu değil, bir iş kuyruğudur: her satırın bir sahibi, bir sebebi ve bir çözüm durumu olmalıdır.

CREATE TABLE dead_letter (
  id              bigserial PRIMARY KEY,
  inbound_event_id bigint NOT NULL REFERENCES inbound_event(id),
  error_class     text NOT NULL,
  error_message   text NOT NULL,
  error_detail    jsonb,
  attempts        int  NOT NULL,
  dead_at         timestamptz NOT NULL DEFAULT now(),
  resolution      text,            -- NULL | 'replayed' | 'fixed_manually' | 'discarded'
  resolved_by     text,
  resolved_at     timestamptz,
  note            text
);

async function moveToDeadLetter(ev: InboundEvent, err: IntegrationError, attempts: number) {
  await db.tx(async (t) => {
    await t.query(`UPDATE inbound_event SET status='dead', attempts=$2,
                   last_error_class=$3, last_error=$4 WHERE id=$1`,
      [ev.id, attempts, err.cls, err.message]);
    await t.query(`INSERT INTO dead_letter (inbound_event_id, error_class, error_message, error_detail, attempts)
                   VALUES ($1,$2,$3,$4,$5)`,
      [ev.id, err.cls, err.message, JSON.stringify(err.detail ?? null), attempts]);
  });
  await alert(err.cls, ev);
}

Uyarı politikası sınıfa göre değişmelidir. Tek bir permanent_data hatası için bütün ekibi uyandırmaya gerek yoktur; günlük bir özet yeterlidir. Ama tek bir permanent_config hatası, muhtemelen o andan sonra gelen bütün lead'lerin aynı yere düşeceği anlamına gelir; bu hemen bir insana ulaşmalıdır.

Kalıcı veri hatalarında bile lead'in kendisini tamamen kaybetmemek mümkündür. Telefon numarası çözülemeyen bir kayıt, e-postası geçerliyse "eksik veri" etiketiyle CRM'e yine de yazılabilir ve bir danışmana manuel kontrol görevi açılabilir. Teknik olarak hatalı olan veri, ticari olarak hâlâ değerli bir taleptir. Hangi alanların gerçekten zorunlu olduğuna, satış ekibiyle birlikte karar vermek gerekir.

Replay: Düzelttikten sonra güvenle yeniden oynatmak

Yapılandırma hatasını düzelttiniz, diyelim ki süresi dolan CRM token'ını yenilediniz. Şimdi dead-letter'daki yüzlerce olayı geri almanız gerekiyor. Bunu güvenli yapmak için birkaç kural:

Replay, normal işleme yolunu kullanmalı. Ayrı bir "toplu import" scripti yazmak yerine olayları tekrar pending durumuna alın. Böylece aynı doğrulama, aynı idempotency ve aynı izleme devreye girer.
Filtrelenebilir olmalı. Sınıfa, kaynağa ve zaman aralığına göre seçim yapabilmelisiniz.
Kademeli olmalı. Önce küçük bir parti, sonuçları kontrol, sonra geri kalanı.
İz bırakmalı. Kim, ne zaman, hangi gerekçeyle yeniden oynattı.

-- Örnek: belirli bir zaman aralığındaki yapılandırma hatalarını ilk 50 kayıtla yeniden kuyruğa al
WITH picked AS (
  SELECT d.id AS dl_id, d.inbound_event_id
  FROM dead_letter d
  JOIN inbound_event e ON e.id = d.inbound_event_id
  WHERE d.resolution IS NULL
    AND d.error_class = 'permanent_config'
    AND e.source = 'meta_lead_ads'
    AND d.dead_at BETWEEN $1 AND $2
  ORDER BY d.dead_at
  LIMIT 50
),
requeue AS (
  UPDATE inbound_event e
  SET status='pending', attempts=0, next_attempt_at=now()
  FROM picked p WHERE e.id = p.inbound_event_id
  RETURNING e.id
)
UPDATE dead_letter d
SET resolution='replayed', resolved_by=$3, resolved_at=now(), note=$4
FROM picked p WHERE d.id = p.dl_id;

Replay sırasında unutulmaması gereken bir ayrıntı daha var: bazı adımlar zamana duyarlıdır. Üç gün önce gelmiş bir lead'e otomatik "Formunuzu aldık, hemen arıyoruz" mesajı göndermek yanlış bir beklenti yaratır. Bu yüzden ilk temas adımı, olayın orijinal alınma zamanına bakmalı ve belli bir süreyi aşan kayıtlarda otomatik mesaj yerine danışmana öncelikli bir arama görevi açmalıdır. Reklam platformlarına geri dönüşüm gönderen adımlarda da platformların olay zamanı için kabul ettiği geriye dönük sınırlar vardır; sınırı aşan olayları göndermeye çalışmak yerine raporlamak gerekir.

İzleme: Hatanın değil, sessizliğin alarmı

Bütün bu yapı kurulduğunda bile bir tür hata hiçbir tabloya düşmez: hiç gelmeyen olay. Reklam platformundaki webhook aboneliği düşmüşse, form sayfasında bir JavaScript hatası gönderimi engelliyorsa ya da bir DNS değişikliği endpoint'inizi erişilmez kılmışsa, sisteminiz kusursuz biçimde "hata yok" raporlar.

Bu yüzden ben izlemeyi üç katmanda kuruyorum:

Hacim sapması: Her kaynak için beklenen saatlik lead aralığını geçmiş verilerden çıkarıp, belirgin bir düşüşte uyarı. Kampanya bütçesi açıkken bir kaynaktan uzun süre hiç olay gelmemesi başlı başına bir alarmdır.
Mutabakat: Belirli aralıklarla reklam platformunun kendi API'sinden o dönemde oluşan lead kimliklerini çekip inbound_event tablosundaki source_ref değerleriyle karşılaştırmak. Fark varsa eksik olanları çekip normal yoldan işlemek.
Kuyruk sağlığı: pending durumunda en eski olayın yaşı, dead-letter'daki çözülmemiş kayıt sayısı ve sınıflara göre dağılımı.

-- Kuyruk sağlığı için tek sorgu
SELECT
  (SELECT max(now() - received_at) FROM inbound_event WHERE status='pending')        AS oldest_pending_age,
  (SELECT count(*) FROM dead_letter WHERE resolution IS NULL)                         AS open_dead_letters,
  (SELECT jsonb_object_agg(error_class, c) FROM (
      SELECT error_class, count(*) c FROM dead_letter
      WHERE resolution IS NULL GROUP BY error_class) s)                               AS open_by_class;

Mutabakat adımı, bütün tasarımın sigortasıdır. Webhook'lar, kuyruklar ve yeniden denemeler ne kadar iyi kurulursa kurulsun, "kaynakta var, bizde yok" sorusunu düzenli soran bir süreç olmadan sistemin güvenilir olduğunu iddia edemezsiniz.

Otomasyon araçlarıyla çalışıyorsanız

Her ekip bu altyapıyı sıfırdan kod olarak yazmaz; çoğu akış Make, n8n ya da Zapier gibi araçlarda kuruludur. Aynı ilkeler orada da uygulanabilir: hata yolu (error route) olmayan bir senaryo bırakmayın, hata yolunda olayı ham haliyle bir tabloya ya da sayfaya yazın, kalıcı ve geçici hataları farklı dallara ayırın, CRM adımında "oluştur" yerine harici kimlikle arama + güncelleme kullanın ve haftalık bir mutabakat kontrolü planlayın. Aracın kendi yeniden deneme ayarlarına güvenmek yerine, en azından kurtarılamayan olayların görünür bir yerde biriktiğinden emin olun.

Sık sorulan sorular (SSS)

Her hatayı yeniden denemek neden kötü bir fikir?
Çünkü kalıcı hatalar yeniden denemeyle düzelmez. Eksik zorunlu alanı olan bir kaydı on iki kez denemek yalnızca kuyruğu meşgul eder, gerçek geçici hataların işlenmesini geciktirir ve insanın sorunu fark etmesini erteler. Kalıcı hatayı hemen dead-letter'a alıp sahibine bildirmek daha hızlı çözüm getirir.

Jitter gerçekten gerekli mi, sabit bekleme yetmez mi?
Az trafikte fark hissedilmez. Ama bir CRM ya da API kesintisi sonrası yüzlerce mesaj aynı anda beklemeye girer; sabit aralıkla hepsi aynı anda tekrar denenir ve sistem toparlanırken yeniden boğulur. Rastgelelik bu yükü zamana yayar.

Kaynak platform zaten yeniden deniyorsa benim ayrıca retry yazmama gerek var mı?
Evet. Kaynağın yeniden denemesi yalnızca sizin endpoint'inize ulaşma sorununu çözer; sizin CRM'e, mesajlaşma servisine ya da reklam platformuna yaptığınız çağrıların başarısızlığını çözmez. Ayrıca kaynağın politikası değişebilir ve sizin kontrolünüzde değildir. Olayı önce kendi tablonuza yazmak, sorumluluğu sizin tarafınıza alır.

Idempotency anahtarını nasıl seçmeliyim?
Deterministik olmalı ve olayın kendisinden türetilmelidir: kaynak adı ve kaynağın verdiği benzersiz kimlik iyi bir başlangıçtır. Her denemede rastgele bir anahtar üretirseniz, anahtarın hiçbir koruma sağlamaz.

Dead-letter'daki kayıtları ne kadar tutmalıyım?
Çözülene kadar mutlaka; çözüldükten sonra ise kişisel veri içerdikleri için şirketinizin veri saklama politikasına tabi olmalıdırlar. Çözülmüş kayıtların ham yükünü belirli bir süre sonra silip yalnızca istatistiksel özeti tutmak iyi bir dengedir.

Bu tasarım küçük bir ekip için fazla mı?
Tamamını ilk günden kurmak gerekmez. Benim önerdiğim öncelik sırası şöyle: önce gelen olayı ham haliyle kalıcı yazmak, sonra harici kimlikle upsert, ardından dead-letter ve uyarı, en son mutabakat. İlk iki adım bile sessiz lead kaybının en yaygın kaynaklarını kapatır.

Kapanış

Lead entegrasyonlarında hata yönetimi, bir altyapı detayı gibi görünse de doğrudan satışa dokunan bir konudur. Kaybolan her olay, bir insanın "bilgi almak istiyorum" demesinin cevapsız kalması anlamına gelir. Hataları sınıflandırmak, yeniden denemeyi ölçülü yapmak, idempotency ile mükerrer kaydı engellemek, kurtarılamayanı görünür bir kuyrukta toplamak ve düzenli mutabakatla sessizliği yakalamak; bu beş adım birlikte, "çalışıyor gibi görünen" bir akışı gerçekten güvenilir bir akışa dönüştürür.

Lead yönetimi ve CRM altyapısı üzerine bu tür uygulama notlarını paylaşmaya devam edeceğim. Kendi akışınızda en çok hangi hata sınıfıyla uğraştığınızı yorumlarda yazarsanız, bir sonraki yazılarda o senaryoları daha ayrıntılı ele alabilirim.

— Koray Yalçın

Çerez izni (cookie consent) koda dökmek: İzin durumu modeli, script kapısı, Consent Mode v2 ve sunucu tarafına taşıma

Koray Yalçın — Wed, 11 Nov 2026 08:20:11 +0000

Konut projeleri için landing page ve CRM altyapısı kurarken en sık karşılaştığım teknik borçlardan biri çerez izni katmanıdır. Çoğu sitede bir banner vardır, "Kabul et" ve "Reddet" düğmeleri vardır; ama arka planda pikseller banner'dan önce yüklenmiş, reddetme seçeneği yalnızca banner'ı kapatıyor, izin durumu hiçbir yerde kayıt altına alınmıyor ve sunucu tarafı olaylar (Meta CAPI, Google offline dönüşüm) izinden tamamen habersiz çalışıyor olur.

Ben Koray Yalçın; lead yönetimi, CRM ve dijital pazarlama altyapıları üzerine çalışıyorum. Bu yazıda çerez iznini bir "banner tasarımı" meselesi olarak değil, bir veri akışı ve durum yönetimi problemi olarak ele alacağım: izin durumu nasıl modellenir, scriptler nasıl kapı arkasında tutulur, Google Consent Mode v2 nereye oturur, izin bilgisi sunucu tarafına ve CRM'e nasıl taşınır ve tüm bunlar nasıl test edilir.

Not: Bu yazı teknik bir uygulama rehberidir, hukuki görüş değildir. KVKK, GDPR ve ePrivacy kapsamındaki yükümlülükleriniz için hukuk danışmanınızla çalışın.

Problemi doğru tanımlamak

Çerez izni üç ayrı soruya cevap vermelidir:

Ne zaman? Hangi script, hangi izin verilmeden önce çalışabilir?
Ne kadar? Kullanıcı hangi kategorilere, hangi metin sürümüne, ne zaman izin verdi?
Nereye kadar? Bu izin bilgisi tarayıcıda mı kalıyor, yoksa sunucu tarafı olaylara ve CRM kaydına da ulaşıyor mu?

Çoğu hazır CMP (Consent Management Platform) ilk soruyu kısmen çözer. İkinci ve üçüncü soru ise neredeyse her zaman sizin kodunuza kalır. Özellikle form doldurup lead'e dönüşen bir ziyaretçi için, çerez izni ile pazarlama iletişim izninin (ETK/İYS kapsamındaki ticari ileti izni) farklı şeyler olduğunu baştan netleştirmek gerekir. Çerez izni tarayıcıdaki ölçüm ve reklam teknolojileriyle ilgilidir; ticari ileti izni ise kişiye mesaj gönderip gönderemeyeceğinizle. İkisini tek bir onay kutusunda birleştirmek hem hukuken hem teknik olarak sorun çıkarır.

İzin durumu modeli: Kategoriler ve sürüm

İlk adım, izin durumunu tek bir boolean olarak değil, kategorilere ayrılmış ve sürümlenmiş bir nesne olarak tutmaktır.

// consent-state.js
export const CONSENT_VERSION = "2026-11-01"; // çerez metninin sürümü

export const CATEGORIES = {
  necessary:   { required: true  }, // oturum, güvenlik, yük dengeleme
  analytics:   { required: false }, // GA4, PostHog vb.
  marketing:   { required: false }, // Meta Pixel, Google Ads, retargeting
  functional:  { required: false }, // canlı sohbet, harita, video gömme
};

export function defaultState() {
  return {
    version: CONSENT_VERSION,
    decidedAt: null,           // kullanıcı karar vermediyse null
    choices: {
      necessary: true,
      analytics: false,
      marketing: false,
      functional: false,
    },
    consentId: crypto.randomUUID(), // kanıt kaydını bağlamak için
  };
}

Burada üç kritik nokta var:

Varsayılan reddettir. Karar verilmemiş durum ile reddedilmiş durum farklı alanlarla ayırt edilir (decidedAt: null), ama ikisinde de opsiyonel kategoriler kapalıdır.
Sürüm alanı zorunludur. Çerez politikası değiştiğinde, örneğin yeni bir reklam ortağı eklediğinizde, eski sürümle verilmiş izin yeni durumu kapsamaz. Kayıtlı sürüm güncel sürümden farklıysa banner yeniden gösterilir.
consentId tarayıcıdaki kararı sunucudaki kanıt kaydına bağlayan anahtardır. Kişisel veri değildir; rastgele bir kimliktir.

Durumu saklarken birinci taraf bir çerez tercih ediyorum (ör. cc_state), çünkü sunucu da ilk istekte bu değeri okuyabilmeli. localStorage yalnızca tarayıcıdan erişilebilir; sunucu tarafı render ve edge mantığı için yetersiz kalır.

export function readState() {
  const raw = document.cookie
    .split("; ")
    .find((c) => c.startsWith("cc_state="));
  if (!raw) return defaultState();
  try {
    const s = JSON.parse(decodeURIComponent(raw.split("=")[1]));
    if (s.version !== CONSENT_VERSION) {
      // politika değişti: kimliği koru, kararı sıfırla
      return { ...defaultState(), consentId: s.consentId };
    }
    return s;
  } catch {
    return defaultState();
  }
}

export function writeState(state) {
  const value = encodeURIComponent(JSON.stringify(state));
  const maxAge = 60 * 60 * 24 * 180; // saklama süresini politikanıza göre belirleyin
  document.cookie =
    `cc_state=${value}; Max-Age=${maxAge}; Path=/; SameSite=Lax; Secure`;
}

Saklama süresi burada bir örnektir; kaç gün tutacağınız sizin politika kararınızdır ve politika metninde yazanla birebir aynı olmalıdır.

Script kapısı: İzin gelmeden hiçbir şey çalışmasın

Sahada gördüğüm en yaygın hata, banner'ın doğru çalışması ama piksellerin <head> içinde doğrudan yüklenmesidir. Ağ sekmesini açtığınızda, kullanıcı daha hiçbir şeye tıklamadan facebook.com/tr ve googleads isteklerinin gittiğini görürsünüz.

Çözüm, opsiyonel scriptleri tarayıcının çalıştırmayacağı bir türle işaretlemek ve izin geldiğinde etkinleştirmektir:

<!-- Çalışmaz: type text/plain olduğu için tarayıcı yürütmez -->
<script type="text/plain" data-consent="marketing"
        data-src="https://connect.facebook.net/tr_TR/fbevents.js"></script>

<script type="text/plain" data-consent="analytics">
  // analitik başlatma kodu
</script>

// consent-gate.js
export function activateScripts(choices) {
  document
    .querySelectorAll('script[type="text/plain"][data-consent]')
    .forEach((el) => {
      const cat = el.dataset.consent;
      if (!choices[cat] || el.dataset.activated) return;

      const s = document.createElement("script");
      if (el.dataset.src) s.src = el.dataset.src;
      else s.textContent = el.textContent;
      s.async = true;
      el.dataset.activated = "1";
      el.after(s);
    });
}

Bu yaklaşımın önemli bir sınırı var: izin geri çekildiğinde zaten yüklenmiş bir scripti "geri yükleyemezsiniz". Bu yüzden geri çekmede iki şey yapıyorum: ilgili birinci taraf çerezleri siliyorum ve sayfayı yeniliyorum. Yenilenen sayfada kapı yeni duruma göre yeniden değerlendirilir. Zarif değil ama doğru davranış budur.

Gömülü içerikler (YouTube videosu, harita, canlı sohbet widget'ı) için de aynı mantık geçerli: izin yoksa iframe yerine bir yer tutucu ve "Bu içeriği görmek için işlevsel çerezlere izin verin" düğmesi gösterilir.

Google Consent Mode v2 nereye oturur?

Google etiketleri kullanıyorsanız, kendi kapınızın yanında Consent Mode sinyallerini de doğru vermelisiniz. Consent Mode v2'de reklam tarafı için ad_storage, ad_user_data ve ad_personalization, analitik için analytics_storage parametreleri kullanılır.

Sıralama kritiktir: varsayılan durum, herhangi bir Google etiketi yüklenmeden önce tanımlanmalıdır.

<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){ dataLayer.push(arguments); }

  gtag("consent", "default", {
    ad_storage: "denied",
    ad_user_data: "denied",
    ad_personalization: "denied",
    analytics_storage: "denied",
    functionality_storage: "denied",
    personalization_storage: "denied",
    security_storage: "granted",
    wait_for_update: 500
  });
</script>

Kullanıcı karar verdiğinde kendi durum nesnenizi Consent Mode diline çeviren tek bir fonksiyon yazın:

export function toGoogleConsent(choices) {
  const g = (v) => (v ? "granted" : "denied");
  return {
    ad_storage: g(choices.marketing),
    ad_user_data: g(choices.marketing),
    ad_personalization: g(choices.marketing),
    analytics_storage: g(choices.analytics),
    functionality_storage: g(choices.functional),
    personalization_storage: g(choices.functional),
  };
}

export function applyConsent(state) {
  window.gtag?.("consent", "update", toGoogleConsent(state.choices));
  activateScripts(state.choices);
}

Burada bir mimari karar vermeniz gerekiyor: Google etiketlerini "Consent Mode'un temel uygulaması" ile mi (izin yoksa etiket hiç yüklenmez), yoksa "gelişmiş uygulama" ile mi (etiket yüklenir, izin yoksa çerezsiz sinyal gönderir) kullanacaksınız? Bu teknik bir tercih gibi görünse de aslında bir uyum kararıdır. Ben bu kararı kod değil, ayar olarak tutuyor ve hukuk ekibiyle birlikte veriyorum.

Kararı kanıtlamak: Sunucu tarafı izin kaydı

Tarayıcıdaki çerez, kullanıcının neye izin verdiğinin kanıtı değildir; kullanıcı onu silebilir, değiştirebilir. Bu yüzden her kararı sunucuya bir olay olarak yazıyorum. Kişisel veri tutmadan, yalnızca kararı ve bağlamını saklayan, ekleme yapılan (append-only) bir tablo:

CREATE TABLE cookie_consent_event (
  id            BIGSERIAL PRIMARY KEY,
  consent_id    UUID        NOT NULL,
  version       TEXT        NOT NULL,        -- çerez metni sürümü
  choices       JSONB       NOT NULL,        -- {"analytics":true,...}
  action        TEXT        NOT NULL         -- accept_all | reject_all | custom | withdraw
                CHECK (action IN ('accept_all','reject_all','custom','withdraw')),
  ui_variant    TEXT,                        -- hangi banner tasarımı gösterildi
  page_path     TEXT,
  ua_hash       TEXT,                        -- tam user-agent yerine hash
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX ON cookie_consent_event (consent_id, created_at DESC);

IP adresini ham haliyle saklamıyorum. İhtiyaç varsa kısaltılmış ya da tuzlu hash'lenmiş bir türev yeterlidir. ui_variant alanı ise ileride "Reddet düğmesi eşit görünürlükte miydi?" sorusu geldiğinde hangi tasarımın gösterildiğini kanıtlamak için var.

Tarayıcı tarafında kayıt çağrısı basit tutulur ve başarısız olsa bile kullanıcı deneyimini bozmaz:

export async function recordDecision(state, action) {
  try {
    await fetch("/api/consent", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      keepalive: true,
      body: JSON.stringify({
        consentId: state.consentId,
        version: state.version,
        choices: state.choices,
        action,
        uiVariant: document.documentElement.dataset.ccVariant ?? null,
        pagePath: location.pathname,
      }),
    });
  } catch {
    // ağ hatası kararı geçersiz kılmaz; bir sonraki sayfa yüklemesinde yeniden dene
  }
}

İzni sunucu tarafı olaylara taşımak

Asıl kör nokta burasıdır. Bir ziyaretçi pazarlama çerezlerini reddedip formu doldurduğunda, CRM'iniz o lead'i "nitelikli" aşamasına aldığında Meta Conversions API'ye veya Google Ads'e offline dönüşüm göndermeye devam ediyorsa, tarayıcıda kurduğunuz bütün kapı anlamını yitirir.

Bunu çözmek için form gönderiminde çerez izni anlık görüntüsünü lead kaydına ekliyorum:

// form gönderiminde
const state = readState();
payload.cookieConsent = {
  consentId: state.consentId,
  version: state.version,
  marketing: state.choices.marketing,
  analytics: state.choices.analytics,
  capturedAt: new Date().toISOString(),
};

CRM tarafında dışa giden her reklam olayı, tek bir kontrol fonksiyonundan geçer:

def can_send_ad_event(lead) -> bool:
    cc = lead.cookie_consent or {}
    if not cc.get("marketing"):
        return False
    latest = consent_repo.latest(cc.get("consent_id"))
    # sonradan geri çekildiyse eski anlık görüntüye güvenme
    if latest and latest.action == "withdraw":
        return False
    return True

Bu fonksiyonu outbox işleyicisinin içinde, gönderimden hemen önce çağırmak önemli. Lead oluştuğu anda izin vardı ama üç gün sonra satış aşaması değiştiğinde kullanıcı izni geri çekmiş olabilir. Kontrolü olayın üretildiği anda değil, gönderildiği anda yapmak bu açığı kapatır.

Bir de şu ayrımı not edeyim: çerez izni, tarayıcı tarafı takip teknolojileri içindir; sunucu tarafı reklam olaylarında kişisel verinin işlenmesi ayrıca bir hukuki dayanak gerektirebilir. Teknik olarak yapabileceğiniz en temiz şey, iki izni de ayrı alanlarda tutmak ve gönderim kontrolünde ikisini birlikte değerlendirmektir.

Banner'ın kendisi: Teknik açıdan dikkat edilecekler

Tasarım bu yazının konusu değil, ama koda yansıyan birkaç kural var:

Eşit seçenekler. "Tümünü kabul et" ile "Tümünü reddet" aynı katmanda, benzer görünürlükte olmalı. Reddetmeyi ikinci bir ekrana saklamak hem güven hem uyum sorunudur.
Erişilebilirlik. Banner klavyeyle gezilebilir olmalı, odak ilk açılışta banner'a taşınmalı, role="dialog" ve aria-labelledby kullanılmalı.
Kararı değiştirebilme. Sayfa altında her zaman erişilebilen bir "Çerez tercihleri" bağlantısı olmalı ve aynı modalı açmalı.
Performans. Banner scripti küçük ve senkron olmalı; ama sayfanın ilk boyamasını engellemeyecek şekilde. Ağır bir CMP yüklüyorsanız varsayılan Consent Mode bloğunu yine de satır içi ve en üstte tutun.

Test etmek: "Bana güven" yerine kanıt

İzin katmanı, otomatik testi en çok ihmal edilen bileşenlerden biridir. Ben üç senaryoyu sürekli entegrasyon hattında çalıştırıyorum:

// playwright test örneği
test("karar öncesi pazarlama isteği gitmez", async ({ page }) => {
  const blocked = [];
  page.on("request", (r) => {
    if (/facebook\.com\/tr|googleadservices|doubleclick/.test(r.url())) {
      blocked.push(r.url());
    }
  });
  await page.goto("/proje/ornek-landing");
  await page.waitForTimeout(2000);
  expect(blocked).toEqual([]);
});

test("reddet sonrası da gitmez", async ({ page }) => {
  // banner'da reddet, sonra formu doldur, aynı kontrol
});

test("politika sürümü değişince banner yeniden açılır", async ({ page, context }) => {
  // eski sürümle cc_state çerezi yaz, sayfayı aç, banner görünür mü?
});

Bunlara ek olarak haftalık bir mutabakat sorgusu çalıştırıyorum: son yedi günde reklam platformlarına gönderilen sunucu tarafı olayların kaç tanesi marketing=false olan lead'lere aitti? Doğru kurulmuş bir sistemde bu sayı sıfır olmalıdır; sıfır değilse bir yerde kapı sızdırıyor demektir.

Sık yapılan hatalar

Pikselleri <head>'e doğrudan koyup banner'ı yalnızca görsel bir katman olarak eklemek.
Consent Mode varsayılanını Google etiketinden sonra tanımlamak.
Politika değişince eski izinleri geçerli saymak; sürüm alanı tutmamak.
Çerez iznini ticari ileti izniyle tek onay kutusunda birleştirmek.
Sunucu tarafı reklam olaylarını izin durumundan bağımsız göndermek.
Kararı yalnızca tarayıcıda tutup sunucuda kanıt kaydı oluşturmamak.
Geri çekmede sayfayı yenilemeden, yüklenmiş scriptlerin "kendiliğinden duracağını" varsaymak.

Sık Sorulan Sorular (SSS)

Hazır bir CMP kullanıyorsam bu yazıdakileri yine de yapmam gerekir mi?
CMP genellikle banner'ı, kategori seçimini ve Consent Mode sinyallerini çözer. Ancak izin anlık görüntüsünü lead kaydına eklemek, sunucu tarafı olayları izinle kapılamak ve mutabakat sorgusu çalıştırmak çoğu zaman sizin backend'inize kalır. CMP'nin olay geri çağırmalarını (callback) kendi applyConsent ve recordDecision fonksiyonlarınıza bağlamanız yeterli.

Kullanıcı reddederse analitik verim tamamen kaybolur mu?
Kurduğunuz uygulamaya bağlıdır. Consent Mode'un gelişmiş uygulamasında Google etiketleri çerezsiz sinyaller gönderebilir ve modelleme yapılabilir; temel uygulamada izin yoksa etiket hiç yüklenmez. Hangisinin size uygun olduğu bir uyum kararıdır, teknik ekip tek başına vermemelidir.

İzin durumunu localStorage'da mı, çerezde mi tutmalıyım?
Sunucunun da okuyabilmesi için birinci taraf bir çerez daha pratiktir. Sunucu tarafı render, edge kuralları ve form gönderiminde izin anlık görüntüsü almak için bu önemli bir avantaj.

Çerez izni ile KVKK açık rızası aynı şey mi?
Hayır, teknik olarak ayrı tutulmalıdır. Çerez izni tarayıcıdaki takip teknolojileriyle, ticari ileti izni kişiye mesaj gönderimiyle, aydınlatma metni ise bilgilendirmeyle ilgilidir. Her biri ayrı alan, ayrı kayıt ve ayrı geri çekme akışı ister.

Politika metnini her güncellediğimde herkese banner'ı yeniden mi göstermeliyim?
Kapsamı değiştiren güncellemelerde (yeni kategori, yeni reklam ortağı, yeni amaç) evet; bunun için sürüm alanını artırırsınız. Yazım hatası düzeltmesi gibi kapsamı etkilemeyen değişikliklerde sürüm artırmak gerekmeyebilir; bu ayrımı politika sahibiyle birlikte yapın.

Sunucu tarafı takip (server-side tagging) kurarsam çerez iznine gerek kalmaz mı?
Kalır. Sunucu tarafı takip verinin nereden gönderildiğini değiştirir, izin yükümlülüğünü ortadan kaldırmaz. Aksine, tarayıcıdaki kapıyı atlayan bir kanal olduğu için izin kontrolünü sunucu tarafında da açıkça uygulamanız gerekir.

Kapanış

Çerez izni doğru kurulduğunda bir "uyum maliyeti" değil, ölçüm altyapınızın güvenilirlik katmanı olur. Hangi verinin hangi izinle toplandığını bilen bir sistemde reklam platformlarına giden sinyaller daha temiz, CRM'deki lead kaydı daha açıklanabilir ve denetim sorularına verilecek cevap hazırdır. Benim önerim basit: izin durumunu sürümlü bir nesne olarak modelleyin, scriptleri kapı arkasında tutun, kararı sunucuda kayıt altına alın ve reklam olaylarını gönderildikleri anda izinle kontrol edin.

— Koray Yalçın

CRM'de activity modelini kurmak: Tek aktivite tablosu, durum geçişleri, kaynak tekilleştirme ve son temas

Koray Yalçın — Tue, 10 Nov 2026 16:23:48 +0000

Bir CRM'in en çok okunan ekranı genelde lead kartının altındaki zaman çizelgesidir: kim aradı, hangi mesaj gitti, toplantı ne zaman yapıldı, sıradaki adım ne. Satış müdürü bir fırsatı incelerken ilk oraya bakar, danışman bir müşteriyi devraldığında ilk oraya bakar. Buna rağmen birçok CRM'de bu ekranın arkasındaki veri modeli aceleyle kurulur: her kanal için ayrı bir tablo, birbirini tutmayan tarih alanları, elle girilmiş ve sonradan düzeltilmiş kayıtlar. Sonuç, "bu lead'i en son kim aradı?" gibi basit bir sorunun bile güvenilir cevabının olmamasıdır.

Ben Koray Yalçın; uzun süredir lead yönetimi, CRM kurulumu ve gayrimenkul satış operasyonları üzerine çalışıyorum. Bu yazıda CRM'deki activity kavramını, yani temsilcilerin ve sistemlerin bir kayıt üzerinde yaptığı arama, mesaj, toplantı, e-posta ve görev gibi aksiyonların bütününü, bir geliştiricinin gözünden ele alıyorum: tek bir aktivite tablosu nasıl tasarlanır, telefon santrali ve WhatsApp gibi dış kaynaklardan gelen kayıtlar nasıl tekilleştirilir, planlanmış ve gerçekleşmiş aktivite nasıl ayrılır, "son temas" ve "sıradaki adım" gibi türetilmiş alanlar nasıl tutarlı tutulur ve tüm bunlar nasıl raporlanır.

Aktivite neden ayrı bir kavram olarak modellenmeli?

Aktiviteyi hafife almanın tipik görüntüsü şudur: leads tablosunda last_call_at, last_whatsapp_at, notes gibi kolonlar vardır; arama kayıtları santral panelinde, mesajlar WhatsApp sağlayıcısında, toplantılar takvimde durur. Her yeni kanal, ana tabloya yeni bir kolon ve yeni bir entegrasyon kodu demektir.

Bu yaklaşımın üç somut sorunu var. Birincisi, geçmiş kaybolur: last_call_at sadece en son aramayı tutar, önceki beş aramanın sonucunu değil. İkincisi, kanallar arası sıralama yapılamaz: "önce mesaj mı gitti, arama mı yapıldı?" sorusu üç ayrı sisteme bakmadan cevaplanamaz. Üçüncüsü, ölçüm imkânsızlaşır: bir danışmanın günlük iş yükünü veya bir lead'e ilk dokunuşun ne kadar sürdüğünü hesaplamak için önce veriyi bir araya getirmeniz gerekir.

Çözüm, aktiviteyi kendi başına bir varlık olarak modellemek ve her kanalı bu ortak modele eşlemektir. Lead, kişi, fırsat (deal) ve şirket kayıtları aktivitelerin "üzerinde gerçekleştiği" şeylerdir; aktivitenin kendisi ise ayrı bir olay kaydıdır.

Tek tablo, ortak çekirdek, türe özel ek alanlar

Benim tercih ettiğim yapı, tüm aktivite türleri için ortak bir çekirdek tablo ve türe özel ayrıntılar için yapılandırılmış bir ek alandır.

CREATE TABLE activity (
  id              BIGSERIAL PRIMARY KEY,
  type            TEXT NOT NULL CHECK (type IN ('call','message','email','meeting','task','note','site_visit')),
  direction       TEXT CHECK (direction IN ('inbound','outbound','internal')),
  status          TEXT NOT NULL CHECK (status IN ('planned','done','cancelled','missed')),
  owner_id        INTEGER REFERENCES app_user(id),
  occurred_at     TIMESTAMPTZ,          -- gerçekleştiği an (done/missed için)
  due_at          TIMESTAMPTZ,          -- planlandığı an (planned için)
  duration_sec    INTEGER,
  outcome         TEXT,                 -- 'reached','no_answer','busy','interested','not_interested'...
  source          TEXT NOT NULL,        -- 'manual','pbx','whatsapp','calendar','email_sync','automation'
  source_ref      TEXT,                 -- dış sistemdeki kimlik
  details         JSONB NOT NULL DEFAULT '{}',
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (source, source_ref)
);

CREATE TABLE activity_link (
  activity_id  BIGINT REFERENCES activity(id) ON DELETE CASCADE,
  entity       TEXT NOT NULL CHECK (entity IN ('lead','contact','deal','company','unit')),
  entity_id    BIGINT NOT NULL,
  is_primary   BOOLEAN NOT NULL DEFAULT false,
  PRIMARY KEY (activity_id, entity, entity_id)
);
CREATE INDEX ON activity_link (entity, entity_id);

Bu şemada üç karar bilinçli.

İlki, occurred_at ile created_at ayrımı. Bir danışman akşam saatinde, öğleden sonra yaptığı üç görüşmeyi CRM'e girebilir. Zaman çizelgesi ve raporlar occurred_at'e göre, denetim ise created_at'e göre çalışmalıdır. İkisini tek alanda birleştirirseniz ya sıralama bozulur ya da "kayıt ne zaman girildi?" bilgisi kaybolur.

İkincisi, ilişkinin ayrı bir activity_link tablosunda tutulması. Gayrimenkulde bir site ziyareti aynı anda bir kişiye, o kişinin fırsatına ve gezilen daireye (unit) bağlıdır. Tek bir lead_id kolonu bu gerçeği taşıyamaz. Çoklu bağlantı sayesinde aynı aktivite hem kişinin hem fırsatın zaman çizelgesinde görünür; is_primary ise raporlamada aktivitenin hangi kayda "sayılacağını" belirler.

Üçüncüsü, details alanının JSONB olması ama serbest bırakılmaması. Arama için kayıt dosyası kimliği ve santral dahilisi, mesaj için şablon adı ve teslim durumu, toplantı için katılımcılar gibi alanlar türe göre değişir. Bunları ana tabloya kolon olarak eklemek tabloyu şişirir; tamamen serbest bırakmak ise her geliştiricinin farklı anahtar kullanmasına yol açar. Uygulama katmanında tür başına bir şema (JSON Schema veya Pydantic modeli) tanımlayıp yazmadan önce doğrulamak, iki dünyanın iyi tarafını birleştirir.

Planlanmış ve gerçekleşmiş aktivite: aynı kayıt, iki hal

Satış ekiplerinin en sık karıştırdığı şey, görevle yapılan işin farkıdır. "Yarın 14:00'te ara" bir plandır; ertesi gün yapılan arama ise bir olaydır. Bunları iki ayrı tabloda tutmak cazip görünür ama planın gerçekleşmeye dönüştüğü anı izlemeyi zorlaştırır.

Ben aynı kaydın durum değiştirmesini tercih ediyorum: planned olarak oluşturulan aktivite, yapıldığında done, ulaşılamadığında missed, vazgeçildiğinde cancelled olur. Geçişleri uygulama katmanında açıkça tanımlamak gerekir:

ALLOWED = {
    "planned":   {"done", "missed", "cancelled"},
    "missed":    {"done"},          # geç de olsa ulaşıldıysa
    "done":      set(),             # gerçekleşmiş olay değiştirilmez
    "cancelled": set(),
}

def transition(activity, new_status, occurred_at=None, outcome=None):
    if new_status not in ALLOWED[activity.status]:
        raise InvalidTransition(activity.status, new_status)
    if new_status in ("done", "missed") and occurred_at is None:
        raise ValueError("gerçekleşen aktivite için occurred_at zorunlu")
    activity.status = new_status
    activity.occurred_at = occurred_at
    activity.outcome = outcome
    record_audit(activity, new_status)

done durumundaki bir kaydın değiştirilememesi önemli bir kural. Gerçekleşmiş bir aramanın sonucu yanlış girildiyse, kaydı sessizce düzeltmek yerine bir düzeltme notu veya denetim satırı eklenmelidir. Aksi halde "bu fırsat neden kaybedildi?" sorusunu sorduğunuzda geçmiş, olduğu gibi değil, sonradan düzenlendiği haliyle karşınıza çıkar.

Gecikmiş görevler de bu modelde doğal olarak hesaplanır: status = 'planned' AND due_at < now() olan her kayıt gecikmiştir. Ayrı bir "overdue" bayrağı tutmaya gerek yoktur; tutarsanız mutlaka bir gün gerçeklikten kopar.

Dış kaynaklardan gelen aktiviteler: tekilleştirme ve eşleme

Aktivitelerin çoğu artık elle girilmez. Bulut santral her aramayı webhook ile bildirir, WhatsApp Cloud API mesaj durumlarını gönderir, takvim entegrasyonu toplantıları senkronlar. Bu kaynakların ortak özelliği, aynı olayı birden fazla kez gönderebilmeleridir: yeniden deneme, durum güncellemesi veya sıra dışı teslim.

Şemadaki UNIQUE (source, source_ref) kısıtı bu yüzden var. Her kaynak kendi olay kimliğini taşır ve kayıt "ekle ya da güncelle" mantığıyla yazılır:

INSERT INTO activity (type, direction, status, occurred_at, duration_sec, outcome, source, source_ref, details)
VALUES ('call', 'outbound', 'done', $1, $2, $3, 'pbx', $4, $5)
ON CONFLICT (source, source_ref) DO UPDATE
SET duration_sec = EXCLUDED.duration_sec,
    outcome      = COALESCE(EXCLUDED.outcome, activity.outcome),
    details      = activity.details || EXCLUDED.details
WHERE activity.status <> 'cancelled';

Asıl zor kısım tekilleştirme değil, eşlemedir: santralden gelen bir arama hangi lead'e aittir? Elinizde genelde yalnızca bir telefon numarası vardır. Burada daha önce lead deduplication için kullandığımız normalizasyonun aynısını kullanmak şart. Santral numarayı 05xx... biçiminde, form +90 5xx... biçiminde, WhatsApp ise 905xx... biçiminde gönderebilir. Hepsini E.164 biçimine çevirip normalize edilmiş numara üzerinden arama yapmazsanız, aynı müşterinin aramaları üç farklı "bilinmeyen numara" kaydına dağılır.

Eşleme belirsiz olduğunda (aynı numara iki farklı kişide kayıtlıysa veya hiç eşleşme yoksa) aktiviteyi atmamak, activity_link olmadan bir "eşleşmemiş aktiviteler" kuyruğunda tutmak gerekir. Bu kuyruk hem veri kalitesi sorunlarını görünür kılar hem de yeni bir lead'in ilk temasının kaybolmasını önler.

Türetilmiş alanlar: son temas, sıradaki adım, ilk dokunuş

Zaman çizelgesi her açıldığında tüm aktiviteleri taramak küçük veriyle sorun değildir, ama liste ekranlarında yüzlerce lead için "son temas" ve "sıradaki adım" göstermek gerekir. Bu yüzden türetilmiş alanları bir özet tablosunda tutmak mantıklıdır:

CREATE TABLE entity_activity_summary (
  entity             TEXT NOT NULL,
  entity_id          BIGINT NOT NULL,
  first_touch_at     TIMESTAMPTZ,
  last_touch_at      TIMESTAMPTZ,
  last_touch_type    TEXT,
  next_due_at        TIMESTAMPTZ,
  next_activity_id   BIGINT,
  done_count         INTEGER NOT NULL DEFAULT 0,
  PRIMARY KEY (entity, entity_id)
);

Kritik nokta, "temas"ın tanımını tek bir yerde yazmaktır. Bir not eklemek temas mıdır? Teslim edilmemiş bir WhatsApp mesajı temas mıdır? Cevapsız bir arama? Benim kullandığım tanım şu: müşteriye yönelik, gerçekleşmiş (done) ve direction değeri inbound ya da outbound olan aktiviteler temastır; iç notlar ve iptal edilmiş görevler değildir. Cevapsız arama "deneme" olarak ayrıca sayılır ama son temas tarihini güncellemez. Bu tanımı bir SQL görünümü veya tek bir fonksiyon olarak yazar, özet tablosunu yalnızca oradan güncellersiniz.

Özet tablosunu tetikleyiciyle (trigger) güncellemek mümkün ama dış kaynaklardan yoğun olay geldiğinde kilitlenme yaratabilir. Ben genelde aktivite yazıldığında etkilenen kayıtları bir kuyruğa atıp kısa aralıklarla yeniden hesaplayan bir iş kullanıyorum. Yeniden hesaplama her zaman ham aktivite tablosundan yapıldığı için özet tablo bozulsa bile silip baştan üretilebilir. Bu, özet tablonun bir "gerçek kaynağı" değil, bir önbellek olduğunu hatırlatan iyi bir disiplin.

Otomasyonların ürettiği aktiviteler

Otomatik karşılama mesajı, hatırlatma e-postası veya randevu teyidi gibi sistem tarafından yapılan işler de aktivitedir ve zaman çizelgesinde görünmelidir. Aksi halde danışman, müşterinin zaten üç mesaj aldığını bilmeden dördüncüyü gönderir.

Ancak otomasyon aktivitelerini insan aktiviteleriyle aynı şekilde saymak raporları yanıltır. "Danışman başına günlük temas" metriğine otomatik mesajlar girerse, en çok otomasyonu tetikleyen danışman en çalışkan görünür. Bu yüzden source = 'automation' olan kayıtları ve owner_id değeri boş olan kayıtları performans raporlarından ayırmak, ama müşteri zaman çizelgesinde göstermek gerekir. İlk dokunuş süresi gibi ölçümlerde de hangi tanımı kullandığınızı açıkça belirtin: otomatik karşılama mesajı ilk dokunuş sayılıyorsa bu süre her zaman çok kısa çıkar ve gerçek insan yanıt süresini gizler.

Raporlama: aktivite verisinden anlamlı soru üretmek

İyi modellenmiş aktivite verisi, satış yönetiminin sorduğu birçok soruya doğrudan cevap verir. Örneğin her lead için ilk insan temasına kadar geçen süreyi şöyle hesaplayabilirsiniz:

SELECT l.id,
       l.created_at,
       MIN(a.occurred_at) AS first_human_touch,
       MIN(a.occurred_at) - l.created_at AS time_to_first_touch
FROM lead l
JOIN activity_link al ON al.entity = 'lead' AND al.entity_id = l.id
JOIN activity a ON a.id = al.activity_id
WHERE a.status = 'done'
  AND a.direction = 'outbound'
  AND a.source <> 'automation'
GROUP BY l.id, l.created_at;

Aynı yapı üzerinden aşamalar arası aktivite yoğunluğu (bir fırsat kapanana kadar kaç temas gerekti), danışman başına gecikmiş görev sayısı veya kanal bazında ulaşılabilirlik oranı da hesaplanabilir. Burada rakamın kendisinden önce tanımın tutarlılığı önemlidir. Aynı metriği iki farklı ekranda iki farklı sorguyla hesaplarsanız, toplantıda rakamları değil sorguları tartışırsınız. Metrik tanımlarını görünüm olarak veritabanında tutmak bu tartışmayı baştan bitirir.

Kişisel veri ve saklama

Aktivite tablosu bir CRM'deki en yoğun kişisel veri kaynaklarından biridir: arama kayıtları, mesaj içerikleri, serbest metin notlar. Bu yüzden saklama ve maskeleme kurallarının aktivite tablosunu da kapsaması gerekir. details alanındaki mesaj gövdesi veya kayıt dosyası bağlantısı, lead anonimleştirildiğinde ayrıca temizlenmelidir; aktivitenin türü, tarihi, süresi ve sonucu ise istatistik için kalabilir. Hangi alanın ne kadar tutulacağı hukuk ekibinizin kararıdır, bu yazı hukuki görüş değildir; ama şemayı baştan bu ayrıma uygun kurmak, o karar geldiğinde uygulamayı kolaylaştırır.

Sık yapılan hatalar

Sahada en sık gördüğüm hataları kısaca toplarsam:

Her kanal için ayrı tablo açmak ve zaman çizelgesini uygulama katmanında birleştirmeye çalışmak.
occurred_at yerine created_at ile sıralamak; sonradan girilen kayıtların çizelgeyi karıştırması.
Gerçekleşmiş aktiviteleri sessizce düzenlemeye izin vermek.
Telefon numarasını normalize etmeden eşleme yapmak.
Otomasyon aktivitelerini insan performansına saymak.
"Son temas" tanımını her raporda farklı yazmak.

SSS

CRM'de activity ile task arasındaki fark nedir?
Task, planlanmış bir aktivitedir. Aynı kayıt planned olarak oluşturulur ve yapıldığında done, ulaşılamadığında missed olur. İkisini aynı tabloda tutmak planla gerçekleşme arasındaki geçişi izlemeyi kolaylaştırır.

Her kanal için ayrı tablo tutmak hiç mantıklı değil mi?
Kanala özel büyük veriler (örneğin mesaj gövdeleri veya kayıt dosyası meta verisi) ayrı tablolarda durabilir. Ama zaman çizelgesi, sıralama ve raporlama için ortak bir çekirdek aktivite kaydı olmalı; kanal tabloları bu kayda bağlanmalı.

Aynı arama santralden iki kez gelirse ne olur?
source ve source_ref üzerindeki tekil kısıt sayesinde ikinci olay yeni kayıt açmaz, mevcut kaydı günceller. Güncellemenin hangi alanlara izin verdiğini açıkça yazmak gerekir.

Eşleşmeyen aktiviteler ne yapılmalı?
Atılmamalı. Bağlantısız olarak saklanıp bir kuyrukta gösterilmeli; yeni bir müşterinin ilk teması çoğu zaman tam da böyle bir kayıttır.

Son temas tarihini tetikleyiciyle mi güncellemeliyim?
Düşük hacimde tetikleyici yeterlidir. Dış kaynaklardan yoğun olay geliyorsa, etkilenen kayıtları kuyruğa atıp ham tablodan yeniden hesaplayan bir iş daha güvenlidir ve özet tablo bozulduğunda baştan üretilebilir.

Otomatik mesajlar zaman çizelgesinde görünmeli mi?
Evet, müşterinin ne aldığını danışmanın görmesi gerekir. Ancak performans ve ilk yanıt süresi gibi metriklerde insan aktivitelerinden ayrı tutulmalıdır.

Son söz

Aktivite modeli, bir CRM'in "ne oldu?" sorusuna verdiği cevaptır. Lead, fırsat ve aşama tabloları bir kaydın şu anki halini anlatır; aktivite tablosu ise oraya nasıl gelindiğini. Bu tabloyu ortak bir çekirdekle, açık durum geçişleriyle, kaynak bazında tekilleştirmeyle ve tek yerde tanımlanmış türetilmiş alanlarla kurduğunuzda, satış ekibinin güvendiği bir zaman çizelgesi ve yönetimin tartışmadan kullanabildiği raporlar elde edersiniz. Benim lead yönetimi ve CRM projelerinde gördüğüm, sorunların büyük kısmının bu tabloyu baştan doğru kurmamaktan kaynaklandığı.

CRM'de data retention'ı koda dökmek: Kural tablosu, güvenli saklama işi, legal hold ve kripto-parçalama

Koray Yalçın — Tue, 10 Nov 2026 08:21:39 +0000

Bir CRM'de "veriyi ne kadar saklıyoruz?" sorusu genelde bir politika belgesiyle cevaplanır ve orada kalır. Belgede "pasif lead kayıtları iki yıl sonra anonimleştirilir" yazar, ama veritabanında bu cümleyi uygulayan tek satır kod yoktur. Üç yıl sonra biri yedekten eski bir tabloyu geri yüklediğinde, silindiği sanılan telefon numaraları da geri gelir.

Ben Koray Yalçın; yıllardır lead yönetimi, CRM kurulumu ve gayrimenkul satış operasyonları üzerine çalışıyorum. Bu yazıda data retention'ı, yani veri saklama süresini, bir geliştiricinin gözünden ele alıyorum: politikayı koda nasıl çevirirsiniz, saklama işini nasıl güvenli çalıştırırsınız, yasal tutma (legal hold) istisnasını nasıl modellersiniz, yedeklerdeki kopyalarla ne yaparsınız ve tüm bunların gerçekten çalıştığını nasıl kanıtlarsınız. Politikanın içeriği, yani hangi verinin kaç yıl tutulacağı, hukuk ekibinizin işidir; bu yazı hukuki görüş değildir. Benim derdim, karar verildikten sonra o kararın sistemde gerçekten uygulanması.

Politika belgesi neden yetmez?

Saklama politikalarının sahada çökmesinin üç tipik nedeni var.

Birincisi, kural insan hafızasına bırakılır. "Ayda bir eski kayıtları temizleriz" diye başlanır, iki ay sonra unutulur. İkincisi, kural tek bir tabloya uygulanır ama veri on yere kopyalanmıştır: ana leads tablosu temizlenir, fakat arama kayıtları, WhatsApp mesaj geçmişi, dışa aktarılmış CSV'ler, analitik ambarı ve hata loglarında aynı kişinin bilgisi durmaya devam eder. Üçüncüsü, silme işi bir kez yanlış çalışır ve fazla veri siler; ekip korkup işi tamamen kapatır.

Bu üç sorunun çözümü aynı yere çıkıyor: saklama kuralını veri olarak tutmak, tek bir iş tarafından uygulamak ve her çalıştırmayı kayda geçirmek.

Kuralı kod değil veri olarak tutun

Saklama süresini if bloklarına gömmek yerine bir tabloda tutmak, hem değişikliği kolaylaştırır hem de denetimde "kural neydi?" sorusuna net cevap verir.

CREATE TABLE retention_rule (
  id              SERIAL PRIMARY KEY,
  entity          TEXT NOT NULL,        -- 'lead', 'call_recording', 'message', 'export_file'
  condition_key   TEXT NOT NULL,        -- 'stage=lost', 'stage=won', 'no_activity'
  anchor_field    TEXT NOT NULL,        -- süre hangi tarihten sayılır: 'last_activity_at', 'closed_at'
  keep_days       INTEGER NOT NULL,
  action          TEXT NOT NULL CHECK (action IN ('anonymize','delete','archive')),
  version         INTEGER NOT NULL,
  approved_by     TEXT NOT NULL,
  effective_from  DATE NOT NULL,
  UNIQUE (entity, condition_key, version)
);

Burada iki ayrıntı önemli. İlki anchor_field: sürenin neye göre sayıldığı. Kaybedilmiş bir lead için çoğu zaman oluşturulma tarihi değil son temas tarihi anlamlıdır; satılmış bir konutun müşteri kaydı için ise satışın kapandığı tarih. Bu çapayı açıkça yazmazsanız, her geliştirici farklı bir tarih kullanır. İkincisi version: kural değiştiğinde eski satırı güncellemezsiniz, yeni sürüm eklersiniz. Böylece bir kaydın neden o tarihte anonimleştirildiğini geriye dönük açıklayabilirsiniz.

action alanındaki üç seçenek de bilinçli bir ayrım. Gayrimenkul CRM'inde satılmış dairenin sözleşme bağlantılı müşteri kaydını silemezsiniz; ama ilgilenip almamış bir adayın telefonunu iki yıl sonra tutmanın çoğu zaman bir gerekçesi kalmaz. Anonimleştirme, kişiyi tanımlayan alanları kaldırıp istatistik için gerekli olanları (kanal, proje, aşama, tarih) bırakır. Böylece "geçen yıl hangi kampanyadan kaç lead geldi?" raporu bozulmaz.

Hangi alan kişisel, hangisi değil: alan sınıflandırması

Anonimleştirmenin doğru çalışması, hangi kolonun kişisel veri olduğunu bilmeye bağlı. Bunu da yine bir kayıt defterinde tutmanızı öneririm:

CREATE TABLE field_classification (
  entity      TEXT NOT NULL,
  field       TEXT NOT NULL,
  category    TEXT NOT NULL CHECK (category IN ('identifier','contact','free_text','business','technical')),
  on_anonymize TEXT NOT NULL CHECK (on_anonymize IN ('null','hash','redact','keep')),
  PRIMARY KEY (entity, field)
);

free_text kategorisini özellikle vurgulamak istiyorum. Satış danışmanlarının not alanına "Ahmet Bey'in eşi Ayşe Hanım 0533... numarasından aradı" gibi cümleler yazdığını hepimiz biliyoruz. Ad ve telefon kolonlarını boşaltıp not alanını bırakırsanız, anonimleştirme kâğıt üzerinde kalır. Serbest metin alanlarında ya tamamını kaldırmak ya da desen tabanlı bir temizleme (telefon, e-posta, TC kimlik deseni) uygulamak gerekir; ben genelde tamamen kaldırmayı ve notun yalnızca uzunluğunu ve tarihini bırakmayı tercih ediyorum.

Yeni bir kolon eklendiğinde bu tabloda karşılığı yoksa CI'ın hata vermesi de iyi bir alışkanlık. Basit bir test, şemadaki her kolonun sınıflandırıldığını kontrol edebilir. Böylece altı ay sonra eklenen secondary_phone alanı sessizce saklama kuralının dışında kalmaz.

Saklama işini güvenli çalıştırmak

Kural ve sınıflandırma hazır olduğunda geriye bunları uygulayan iş kalır. Burada hız değil güvenlik önceliklidir. Benim kullandığım iskelet şöyle:

def run_retention(entity, rule, dry_run=True, batch_size=500, max_total=20000):
    run_id = start_run(entity, rule.id, rule.version, dry_run)
    cutoff = today() - timedelta(days=rule.keep_days)
    processed = 0

    while processed < max_total:
        ids = select_candidates(entity, rule, cutoff, limit=batch_size)
        ids = [i for i in ids if not under_legal_hold(entity, i)]
        if not ids:
            break
        if dry_run:
            log_candidates(run_id, ids)
        else:
            with transaction():
                apply_action(entity, rule.action, ids)   # anonymize / delete / archive
                write_tombstones(run_id, entity, ids)
                enqueue_downstream(entity, ids)          # outbox: diğer sistemlere yay
        processed += len(ids)

    finish_run(run_id, processed, hit_limit=(processed >= max_total))

Bu iskeletteki her parça bir hatadan ders alınarak eklenmiş durumda.

Kuru çalıştırma (dry run) varsayılan olmalı. Yeni bir kural ya da yeni bir sürüm devreye girdiğinde iş önce sadece "şu kayıtlar etkilenecekti" listesini üretir. Bu listeyi bir insan gözden geçirdikten sonra gerçek mod açılır.

Toplu işleme ve üst sınır (max_total) şart. Bir kuralda keep_days yanlışlıkla 730 yerine 73 girildiğinde, üst sınır olmayan bir iş bütün tabloyu bir gecede anonimleştirebilir. Üst sınıra takılan bir çalıştırma alarm üretmeli ve otomatik devam etmemeli.

Mezar taşı (tombstone) kaydı, silinen veya anonimleştirilen kaydın kimliğini, hangi kural sürümüyle ve hangi çalıştırmada işlendiğini tutar; kişisel veri içermez. Bu kayıt iki işe yarar: denetimde kanıt olur ve yedekten geri yükleme sonrası temizliğin tekrar uygulanmasını sağlar.

Aşağı akış kuyruğu (outbox) ise asıl unutulan kısım. Ana veritabanında anonimleştirdiğiniz kişi, reklam kitlelerinde, e-posta aracında, analitik ambarında ve WhatsApp sağlayıcısında yaşamaya devam ediyorsa iş yarım kalmıştır. Aynı işlem içinde outbox'a yazılan olaylar, her hedef sistem için ayrı bir tüketici tarafından işlenir ve başarısız olanlar yeniden denenir.

Yasal tutma (legal hold) istisnası

Bazen saklama süresi dolmuş bir kaydı silmemeniz gerekir: devam eden bir uyuşmazlık, bir şikâyet incelemesi, bir resmi talep. Bu durumu her geliştiricinin kendi koduna if customer_id == 4812 diye yazması felakettir. Ayrı bir tablo kullanın:

CREATE TABLE legal_hold (
  id          SERIAL PRIMARY KEY,
  entity      TEXT NOT NULL,
  entity_id   BIGINT NOT NULL,
  reason      TEXT NOT NULL,
  opened_by   TEXT NOT NULL,
  opened_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  review_at   DATE NOT NULL,
  closed_at   TIMESTAMPTZ
);
CREATE INDEX ON legal_hold (entity, entity_id) WHERE closed_at IS NULL;

review_at alanı zorunlu olmalı. Açılıp unutulan tutmalar, saklama politikasının sessizce delinmesinin en yaygın yoludur. Gözden geçirme tarihi geçmiş açık tutmalar için haftalık bir rapor üretin. Tutma kapandığında kayıt bir sonraki saklama çalıştırmasında normal kurala döner; ayrıca bir işlem yapmanız gerekmez.

Yedekler ve kopyalar: kripto-parçalama (crypto-shredding)

En zor soru yedeklerdir. Günlük yedekleri otuz gün, aylık yedekleri bir yıl tutuyorsanız, bugün anonimleştirdiğiniz kişi yedeklerin içinde bir yıl daha durur. Yedekleri tek tek açıp düzenlemek pratik değildir.

İki yaklaşım var ve çoğu zaman ikisini birlikte kullanıyorum.

Birincisi, geri yükleme sonrası yeniden uygulama. Yedekten geri dönüldüğünde, mezar taşı tablosu (ki ayrı ve daha uzun süre saklanır) okunur ve oradaki tüm kayıtlara anonimleştirme tekrar uygulanır. Bunu geri yükleme prosedürünün zorunlu bir adımı yapın; elle hatırlanmasını beklemeyin.

İkincisi, kişi başına anahtarla şifreleme. Telefon, e-posta ve ad gibi alanlar kişiye özel bir veri anahtarıyla şifrelenir; anahtarlar ayrı bir anahtar deposunda durur. Saklama süresi dolduğunda anahtarı silersiniz. Yedeklerde şifreli veri kalsa bile artık okunamaz.

def shred_subject(subject_id):
    key_ref = key_store.get_ref(subject_id)
    key_store.destroy(key_ref)                  # geri dönüşsüz
    db.execute("UPDATE subject SET key_ref = NULL, shredded_at = now() WHERE id = %s", [subject_id])
    audit("subject_shredded", subject_id=subject_id, key_ref=key_ref)

Kripto-parçalamanın bir bedeli var: şifreli alanlarda arama ve tekilleştirme zorlaşır. Bu yüzden arama için normalleştirilmiş değerin karma (hash) hâlini ayrı bir kolonda tutmak ve onu da saklama kuralına dahil etmek gerekir. Küçük bir CRM için bu mimari ağır gelebilir; o durumda kısa yedek süresi ve geri yükleme sonrası yeniden uygulama çoğu ihtiyacı karşılar.

Unutulan kopyalar listesi

Saklama işinin kapsamını belirlerken her ekipte şu listeyi tek tek kontrol ediyorum:

Dışa aktarılmış CSV ve Excel dosyaları (ortak sürücüler, e-posta ekleri).
Uygulama ve hata logları; özellikle istek gövdesini loglayan ara katmanlar.
Arama kayıtları ve çağrı merkezi transkriptleri.
WhatsApp ve SMS sağlayıcılarındaki mesaj geçmişi.
Analitik ambarı ve oradan türetilen tablolar.
Reklam platformlarına yüklenmiş özel kitleler.
Test ve geliştirme ortamlarına kopyalanmış üretim verisi.
Kuyruklardaki ölü mektup (DLQ) mesajları.

Bu listedeki her kalem için "sahibi kim, saklama süresi ne, silme nasıl tetikleniyor" sorularının cevabı yazılı olmalı. Cevabı olmayan kalem, politikanın deliğidir.

Gerçekten çalıştığını kanıtlamak

Saklama işi sessiz çalışan bir iştir; çalışmadığını genelde bir denetimde ya da bir şikâyette öğrenirsiniz. Bunu önlemek için üç kontrol kuruyorum.

İlki, çalıştırma kaydı ve sapma alarmı. Her çalıştırma retention_run tablosuna başlangıç, bitiş, işlenen kayıt sayısı ve üst sınıra takılıp takılmadığı bilgisiyle yazılır. Bir kural için beklenen hacim birden sıfıra düşerse ya da birden on katına çıkarsa alarm üretilir.

İkincisi, bağımsız doğrulama sorgusu. Saklama işinden ayrı yazılmış basit bir sorgu, "süresi dolmuş, tutmada olmayan ama hâlâ kişisel verisi duran kayıt var mı?" diye bakar:

SELECT count(*)
FROM lead l
JOIN retention_rule r ON r.entity = 'lead' AND r.condition_key = 'stage=lost'
WHERE l.stage = 'lost'
  AND l.last_activity_at < now() - (r.keep_days || ' days')::interval
  AND l.phone IS NOT NULL
  AND NOT EXISTS (SELECT 1 FROM legal_hold h
                  WHERE h.entity = 'lead' AND h.entity_id = l.id AND h.closed_at IS NULL);

Bu sayı sıfır değilse iş ya çalışmıyor ya da bir koşulu kaçırıyor demektir.

Üçüncüsü, aylık örneklem. Rastgele birkaç anonimleştirilmiş kaydı açıp serbest metin alanlarında, ilişkili tablolarda ve aşağı akış sistemlerinde iz kalıp kalmadığına bakmak. Otomasyonun yakalayamadığı şeyleri genelde bu elle kontrol gösterir.

Gayrimenkul CRM'inden bir senaryo

Kıbrıs'ta konut projesi satan bir firmayı düşünün. Lansman döneminde Meta ve Google reklamlarından binlerce lead gelir; bunların küçük bir kısmı satışa döner. Kaybedilen adaylar için kural "son temastan 730 gün sonra anonimleştir" olsun, satılmış müşteriler için ise sözleşme kaydı ayrı tutulur ve anonimleştirilmez.

Bir aday, satıştan vazgeçtikten sonra şikâyet başvurusu yapmış olsun. Hukuk ekibi bu kayıt için yasal tutma açar, gözden geçirme tarihini altı ay sonrasına koyar. Saklama işi her gece çalışır, bu adayı atlar; diğer süresi dolmuş adayları anonimleştirir, mezar taşı yazar ve outbox üzerinden reklam kitlelerinden ve WhatsApp sağlayıcısından çıkarma olaylarını gönderir. Kampanya raporları bozulmaz, çünkü kanal, proje ve aşama bilgisi duruyor. Altı ay sonra tutma kapanınca kayıt bir sonraki çalıştırmada normal kurala döner.

Bu senaryodaki hiçbir adım bir insanın bir şeyi hatırlamasına bağlı değil. Saklama politikasının sahada yaşamasının tek yolu bu.

Saklama süresinin kavramsal tanımı ve KVKK bağlamı için sitemdeki data retention nedir sözlük maddesine bakabilirsiniz; bu yazı onun uygulama tarafını anlatıyor.

Sık Sorulan Sorular

Silmek mi, anonimleştirmek mi daha doğru?
Kişisel veriye artık ihtiyaç yoksa ama kaydın istatistiksel değeri varsa anonimleştirme çoğu zaman daha iyi bir denge sunar. Hangisinin hukuken yeterli olduğu ise sizin politikanıza ve hukuk ekibinizin değerlendirmesine bağlıdır. Teknik olarak önemli olan, anonimleştirmenin gerçekten geri döndürülemez olması: karma değerler tuzsuz ve tahmin edilebilir girdilerden üretiliyorsa, telefon numarası gibi alanlar kolayca geri bulunabilir.

Saklama işi ne sıklıkla çalışmalı?
Günlük çalıştırma çoğu CRM için yeterli. Önemli olan sıklıktan çok her çalıştırmanın kayda geçmesi ve bir gece çalışmadığında bunun fark edilmesi.

Kural değiştiğinde geçmiş kayıtlar ne olacak?
Yeni sürüm eklendiğinde ilk çalıştırmayı kuru modda yapın. Süre kısalıyorsa birden çok kaydı etkileyebilir; üst sınır ve gözden geçirme bu noktada sizi korur. Süre uzuyorsa, zaten anonimleştirilmiş kayıtlar geri gelmez; bunu ekibe açıkça söyleyin.

Yasal tutmadaki bir kayıt diğer sistemlerde de korunmalı mı?
Evet. Tutma bilgisi yalnızca ana veritabanında kalırsa, aşağı akış sistemlerindeki kendi saklama kuralları veriyi silebilir. Tutma açıldığında outbox üzerinden ilgili sistemlere de bildirim gitmesi gerekir.

Küçük bir ekip için en az ne yapılmalı?
Kural tablosu, alan sınıflandırması, kuru modla başlayan günlük bir iş, mezar taşı kaydı ve bağımsız doğrulama sorgusu. Kripto-parçalama ve gelişmiş aşağı akış yayılımı sonraki adım olabilir; ama dışa aktarılmış dosyalar ve loglar listesi ilk günden kapsama girmeli.

Koray Yalçın; lead yönetimi, CRM mimarisi, dijital pazarlama ve gayrimenkul teknolojileri (PropTech) üzerine çalışıyor ve yazıyor.

fbclid'i formdan Meta Conversions API'ye taşımak: _fbc, hash'leme, event_id ve CRM aşama eşlemesi

Koray Yalçın — Mon, 09 Nov 2026 16:28:12 +0000

Bir konut projesinin Instagram reklamına tıklayan kişi formu doldurur, satış danışmanı onu arar, hafta sonu örnek daireyi gezer ve belki bir buçuk ay sonra satış ofisinde sözleşme imzalar. Meta tarafında ise genellikle hikâye form gönderiminde biter: Pixel bir Lead olayı görür, sonrasını hiç öğrenmez. Reklam algoritması da "form dolduran" kişiye benzeyenleri bulmaya devam eder. Lead yönetimi ve CRM kurulumlarında en sık gördüğüm kopukluk budur: reklam paneli hacmi optimize eder, satış ekibi ise kaliteden şikâyet eder.

Bu yazıda o kopukluğu kapatan teknik hattı anlatacağım: tarayıcıda fbclid değerini rızaya bağlı olarak yakalamak, ondan _fbc değerini doğru biçimde üretmek, _fbp ile birlikte sunucuda bir temas (touch) tablosunda saklamak, CRM aşamalarını Meta olaylarına eşlemek ve bu olayları Conversions API (CAPI) ile, Pixel'le çakışmadan, hash'lenmiş kullanıcı verisiyle göndermek. Kavramın tanımına değil, geliştiricinin önüne çıkacak kararlara odaklanacağım.

Kısa bir bağlam: fbclid, Meta (Facebook ve Instagram) reklamına tıklanıp harici bir siteye gidildiğinde hedef URL'ye eklenen tıklama kimliğidir. Tek başına bir anlam taşımaz; değeri, sonradan gönderilen sunucu olaylarının hangi reklam tıklamasına ait olduğunu Meta'nın anlayabilmesini sağlamasından gelir.

Pixel neden yetmiyor, CAPI neyi değiştiriyor?

Pixel tarayıcıda çalışır. Reklam engelleyiciler, tarayıcı gizlilik kısıtlamaları, çerez rızasının reddedilmesi ya da sayfanın olay tetiklenmeden kapanması gibi sebeplerle bazı olaylar hiç ulaşmaz. Ama gayrimenkul ve B2B satış gibi uzun döngülü işlerde asıl sorun bu kayıp bile değil: değerli olayların büyük kısmı zaten tarayıcıda olmuyor. "Danışman telefonda nitelikli buldu", "saha ziyareti yapıldı", "kapora alındı", "sözleşme imzalandı" gibi aşamalar CRM'de, satış ofisinde ya da telefonda yaşanır. Bunları Meta'ya bildirmenin tek yolu sunucudan göndermektir.

Conversions API, işletmenin sunucusundan Meta'ya doğrudan olay göndermeyi sağlar. Burada iki ayrı fayda var ve bunları karıştırmamak gerekiyor:

Yedeklilik: Form gönderimi gibi tarayıcıda da yaşanan olayı hem Pixel hem CAPI ile göndermek. Burada amaç kaybı azaltmak; çift sayımı önlemek için tekilleştirme şart.
Derinlik: Sadece CRM'de yaşanan olayları (nitelikli lead, satış) göndermek. Burada Pixel'in karşılığı yok; eşleştirme tamamen sizin gönderdiğiniz fbc, fbp ve hash'lenmiş kişisel verilerle yapılır.

İkinci fayda, fbclid'i formdan CRM'e kadar kaybetmeden taşımanın neden önemli olduğunu açıklıyor. Kırk beş gün sonra imzalanan sözleşmede elinizde sadece bir telefon numarası varsa eşleşme Meta'nın o numarayı tanımasına kalır. Elinizde tıklama anında üretilmiş bir fbc değeri de varsa, olayı doğrudan o tıklamaya bağlamak için çok daha güçlü bir sinyal göndermiş olursunuz.

Yakalama: Rıza, TTL ve doğru _fbc biçimi

Pixel kuruluysa ve rıza verilmişse, Pixel zaten _fbc ve _fbp adlı birinci taraf çerezleri yazar. _fbp tarayıcı kimliğidir (fb.1.<oluşturma zamanı ms>.<rastgele sayı> biçiminde), _fbc ise tıklama kimliğini taşır. Yine de kendi küçük yakalama katmanımı yazmayı tercih ediyorum, çünkü form sayfası her zaman Pixel'in yüklendiği sayfa olmayabiliyor, bazı projelerde Pixel bilinçli olarak geç yükleniyor ve rıza durumuna göre davranışı kendim kontrol etmek istiyorum.

Meta'nın belgelerine göre fbc değerinin biçimi version.subdomainIndex.creationTime.fbclid şeklindedir. version her zaman fb; subdomainIndex çerezin tanımlandığı alan adı düzeyini belirtir ve değer sunucuda üretiliyorsa 1 kullanılması öneriliyor; creationTime milisaniye cinsinden Unix zamanıdır ve fbclid'in ilk görüldüğü anı göstermelidir. Son parça da URL'deki fbclid değerinin kendisidir. Burada sık yapılan iki hata var: zamanı saniye cinsinden yazmak ve fbclid değerini küçük harfe çevirmek ya da kırpmak. Değer büyük-küçük harfe duyarlıdır, olduğu gibi taşınmalıdır.

// fbclid yakalama: rızaya bağlı, TTL'li, _fbc biçiminde
const FBC_KEY = "kc_meta_click";
const TTL_DAYS = 90; // kendi saklama politikanıza göre belirleyin

function readCookie(name) {
  const m = document.cookie.match(new RegExp("(?:^|; )" + name + "=([^;]*)"));
  return m ? decodeURIComponent(m[1]) : null;
}

export function captureMetaClick(hasAdConsent) {
  if (!hasAdConsent) {
    localStorage.removeItem(FBC_KEY); // rıza geri çekildiyse temizle
    return;
  }
  const fbclid = new URLSearchParams(location.search).get("fbclid");
  const existing = JSON.parse(localStorage.getItem(FBC_KEY) || "null");

  if (fbclid) {
    // Aynı fbclid tekrar geldiyse ilk görülme zamanını koru
    const sameClick = existing && existing.fbclid === fbclid;
    const firstSeen = sameClick ? existing.firstSeen : Date.now(); // ms!
    localStorage.setItem(FBC_KEY, JSON.stringify({
      fbclid,
      firstSeen,
      fbc: `fb.1.${firstSeen}.${fbclid}`,
      landing: location.pathname,
      expiresAt: firstSeen + TTL_DAYS * 864e5,
    }));
  } else if (existing && existing.expiresAt < Date.now()) {
    localStorage.removeItem(FBC_KEY);
  }
}

export function getMetaIdentifiers() {
  const stored = JSON.parse(localStorage.getItem(FBC_KEY) || "null");
  return {
    // Pixel'in yazdığı çerez varsa onu tercih et, yoksa kendi ürettiğimiz
    fbc: readCookie("_fbc") || (stored && stored.fbc) || null,
    fbp: readCookie("_fbp") || null,
  };
}

Burada bilinçli bir öncelik sırası var: Pixel'in yazdığı _fbc çerezi varsa onu olduğu gibi kullanıyorum, kendi ürettiğim değeri yalnızca yedek olarak tutuyorum. Böylece tarayıcı ve sunucu olayları aynı fbc değerini taşıyor. _fbp için ise kendi değerimi üretmiyorum; Pixel yoksa bu alanı boş bırakmak, rastgele bir değer uydurmaktan daha dürüst.

TTL meselesine de değinmek istiyorum. Doksan gün bir zorunluluk değil, benim yaygın gördüğüm ve Pixel çerezinin varsayılan ömrüyle uyumlu bir başlangıç noktası. Asıl kural şu: saklama süresini aydınlatma metninizde yazdığınız süreyle tutarlı tutun ve süre dolunca değeri gerçekten silin.

Taşıma: Form gönderimi ve aynı olay kimliği

Form gönderiminde iki şey olur: tarayıcı Pixel'e Lead olayı atar, sunucu da aynı başvuruyu CRM'e yazar ve CAPI'ye Lead gönderir. İkisinin aynı olay olduğunu Meta'ya söylemenin yolu event_id'dir. Pixel tarafında eventID olarak, sunucu tarafında event_id olarak aynı değeri ve aynı olay adını gönderirseniz Meta bunları tekilleştirir. Belgelere göre eşleşme kırk sekiz saatlik pencere içinde aranır ve iki olay birkaç dakika arayla gelirse tarayıcı olayı tercih edilir.

Pratikte event_id'yi tarayıcıda üretip form gövdesine ekliyorum, sunucuda da aynı değeri lead kaydına yazıyorum. Gizli alanların yanında event_source_url için sayfa adresini ve kullanıcı aracısını sunucuya taşımayı unutmamak gerekiyor; website kaynaklı olaylarda client_user_agent ve event_source_url alanları bekleniyor. IP adresini ise tarayıcının söylediğine değil, sunucunun gördüğü bağlantıya (ve güvendiğiniz proxy başlığına) göre alın.

Formsuz kanallar ayrı bir dert. Proje sayfasındaki "WhatsApp'tan yaz" düğmesine basan kişinin fbc değeri, mesaj CRM'e düştüğünde ortada yoktur. Bu durumda düğmeye tıklanırken kısa ömürlü bir referans kodu üretip mesaj şablonuna eklemek ve sunucuda bu kodu fbc ile eşlemek işe yarıyor. Kusursuz değil, kullanıcı kodu silebilir; ama hiç bağlantı kurmamaktan iyidir.

Saklama: fbc kişiye değil, temasa aittir

Aynı kişi önce Meta reklamından, iki hafta sonra arama motorundan, bir ay sonra da yönlendirmeyle gelebilir. fbc değerini kişi kartındaki tek bir alana yazarsanız ya ilkini ezersiniz ya da sonrakileri kaybedersiniz. Bu yüzden tıklama kimliklerini başvuru düzeyindeki bir temas tablosunda tutuyorum; kişi kartı yalnızca bu temaslara referans veriyor. Gönderimleri de doğrudan değil, bir giden kutusu (outbox) tablosu üzerinden yapıyorum.

-- Her form/WhatsApp/çağrı başvurusu bir temas satırıdır
CREATE TABLE lead_touch (
  id              BIGSERIAL PRIMARY KEY,
  lead_id         BIGINT NOT NULL REFERENCES lead(id),
  channel         TEXT NOT NULL,            -- 'form', 'whatsapp', 'call'
  project_code    TEXT NOT NULL,            -- ör. 'LANSMAN-A'
  fbc             TEXT,                     -- fb.1.<ms>.<fbclid>, hash'lenmez
  fbp             TEXT,
  client_ip       INET,
  user_agent      TEXT,
  source_url      TEXT,
  form_event_id   UUID,                     -- Pixel ile ortak event_id
  consent_ads     BOOLEAN NOT NULL DEFAULT FALSE,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
  purge_after     TIMESTAMPTZ               -- saklama süresi sonu
);
CREATE INDEX ON lead_touch (lead_id, created_at DESC);

-- CAPI'ye gidecek her olay önce buraya yazılır
CREATE TABLE capi_outbox (
  id            BIGSERIAL PRIMARY KEY,
  lead_id       BIGINT NOT NULL,
  touch_id      BIGINT REFERENCES lead_touch(id),
  event_name    TEXT NOT NULL,              -- 'Lead', 'QualifiedLead', 'Purchase'
  event_id      TEXT NOT NULL,
  event_time    TIMESTAMPTZ NOT NULL,       -- olayın gerçekten olduğu an
  action_source TEXT NOT NULL,
  payload       JSONB NOT NULL,
  status        TEXT NOT NULL DEFAULT 'pending', -- pending/sent/failed/dead
  attempts      INT NOT NULL DEFAULT 0,
  next_try_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  last_error    TEXT,
  UNIQUE (event_name, event_id)
);

UNIQUE (event_name, event_id) kısıtı küçük ama önemli: CRM'de bir danışman aşamayı yanlışlıkla iki kez "Sözleşme" yapıp geri alırsa, ikinci kayıt kuyruğa hiç girmez. Satış olayının hangi temasa bağlanacağı da bir iş kuralıdır. Ben genellikle satıştan önceki, reklam rızası verilmiş en son Meta temasını seçiyorum; ama bu bir atıf modeli kararıdır ve pazarlama ekibiyle birlikte yazılı hâle getirilmelidir.

Aşama eşlemesi: Her CRM aşaması Meta olayı değildir

Bir gayrimenkul CRM'inde on, on iki aşama olabilir: yeni, ulaşılamadı, arandı, nitelikli, randevu verildi, ziyaret yapıldı, teklif, kapora, sözleşme, iptal. Bunların hepsini Meta'ya göndermek algoritmaya sinyal değil gürültü verir. Benim yaklaşımım üç, en fazla dört olay seçmek: form anında standart Lead, danışmanın elemesinden geçen kişi için bir özel olay (ör. QualifiedLead), ziyaret için standart Schedule ya da özel bir olay, satış için de değerli bir Purchase.

Özel olay adı kullanmak serbesttir ama adın sabit kalması gerekir; bugün QualifiedLead, yarın Nitelikli_Lead gönderirseniz Events Manager'da iki ayrı olay görürsünüz. Ayrıca negatif aşamaları (ulaşılamadı, iptal) olay olarak göndermiyorum. İptal edilen bir satışın değerini geri almak için CAPI'de doğrudan bir "geri alma" mekanizması aramak yerine, satış olayını kapora değil sözleşme gibi daha geç ve daha kesin bir aşamaya bağlamayı tercih ediyorum.

// CRM aşaması -> Meta olayı eşlemesi (tek yerde, sürüm kontrolünde)
export const STAGE_EVENT_MAP = {
  new:        { event: "Lead",          actionSource: "website",        sendFromServer: true },
  qualified:  { event: "QualifiedLead", actionSource: "system_generated" },
  site_visit: { event: "Schedule",      actionSource: "physical_store" },
  contract:   { event: "Purchase",      actionSource: "physical_store", withValue: true },
  // unreachable, lost, cancelled: bilinçli olarak gönderilmiyor
};

export function buildEventId(leadId, event) {
  // Deterministik: aynı lead + aynı olay her zaman aynı kimliği üretir
  return `${leadId}:${event}`;
}

action_source alanını burada dürüstçe doldurmak önemli. Form website olayıdır. Danışmanın CRM'de işaretlediği "nitelikli" aşaması bir sistem kararıdır; sözleşme ise satış ofisinde, yüz yüze imzalanır. Meta'nın kabul ettiği değerler arasında website, phone_call, chat, physical_store, system_generated, business_messaging ve other gibi seçenekler var. Değeri gönderim penceresini uzatmak için değil, olayın gerçekte nerede olduğuna göre seçin.

Form olayı için deterministik kimliği kullanmıyorum; orada Pixel ile ortak olan, tarayıcıda üretilmiş form_event_id geçerli. Sunucunun ürettiği deterministik kimlikler ise sadece CRM kaynaklı olaylar için.

event_time: Kırk beş gün sonraki satış nasıl gönderilir?

En sık karıştırılan nokta burası. event_time, olayın gerçekten gerçekleştiği anın saniye cinsinden Unix zamanıdır. Meta belgelerine göre bu zaman, gönderim anından en fazla yedi gün öncesi olabilir; isteğin içindeki tek bir olay bile bu sınırı aşarsa isteğin tamamı reddedilir. physical_store kaynaklı olaylar için bu pencere altmış iki gündür.

Bu sınır tıklamayla değil, olayla ilgilidir. Kırk beş gün önce reklama tıklamış birinin sözleşmesini, sözleşme imzalandığı gün gönderirseniz event_time bugündür ve sorun yoktur; fbc içindeki zaman damgası ise tıklama anını taşımaya devam eder. Sorun, ekibin satışları ay sonunda toplu girdiği yapılarda çıkar: imza tarihi event_time olarak doğru girilir ama gönderim penceresi kaçmış olur. Bu yüzden iki kural koyuyorum: CRM'de aşama değişikliği anında kuyruğa yazılsın ve kuyruk işçisi pencereyi aşmış olayları göndermeye çalışmak yerine dead olarak işaretleyip raporlasın. Bir de toplu gönderimde (data dizisi) eski bir olayın tüm partiyi düşürmemesi için yaşlı olayları partiye hiç almıyorum.

Hash'leme ve Türkiye'ye özgü telefon normalizasyonu

E-posta, telefon, ad, soyad, şehir gibi alanlar SHA-256 ile hash'lenerek gönderilir. fbc, fbp, client_ip_address ve client_user_agent ise hash'lenmez. Hash'lemenin değeri tamamen normalizasyona bağlıdır: aynı e-postayı farklı biçimde hash'lerseniz Meta'nın tarafındaki değerle hiçbir zaman eşleşmez ve hata da almazsınız. Sessiz bir başarısızlıktır.

Türkiye'deki CRM verisinde telefon numarası en dağınık alandır: 0532 123 45 67, +90 (532) 123-45-67, 5321234567, 0090532... aynı veritabanında yan yana durur. Meta'nın beklediği biçim, sembolleri ve baştaki sıfırları atılmış, ülke koduyla başlayan rakam dizisidir; yani +90 önekinin artı işareti olmadan 90 ile başlayan biçim. Türk harfleriyle ilgili ince bir tuzak da var: JavaScript'te toLocaleLowerCase("tr") büyük I harfini ı yapar ve AHMET.IŞIK@... gibi bir adresin hash'i bozulur. E-postada yerel ayardan bağımsız küçültme kullanın.

import { createHash } from "node:crypto";

const sha256 = (v) => createHash("sha256").update(v, "utf8").digest("hex");

export function normalizeEmail(raw) {
  if (!raw) return null;
  const v = raw.trim().toLowerCase(); // toLocaleLowerCase('tr') KULLANMA
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) ? v : null;
}

export function normalizeTrPhone(raw) {
  if (!raw) return null;
  let d = String(raw).replace(/\D/g, "");   // sadece rakamlar
  if (d.startsWith("00")) d = d.slice(2);   // 0090... -> 90...
  if (d.startsWith("0")) d = d.slice(1);    // 0532... -> 532...
  if (d.length === 10 && d.startsWith("5")) d = "90" + d; // yerel cep
  // Yalnızca ülke kodlu, makul uzunlukta numaraları kabul et
  return /^\d{11,15}$/.test(d) ? d : null;
}

export function buildUserData(lead, touch) {
  const em = normalizeEmail(lead.email);
  const ph = normalizeTrPhone(lead.phone);
  return {
    em: em ? [sha256(em)] : undefined,
    ph: ph ? [sha256(ph)] : undefined,
    external_id: [sha256(String(lead.id))],
    country: [sha256("tr")],
    fbc: touch?.fbc || undefined,          // hash'lenmez
    fbp: touch?.fbp || undefined,          // hash'lenmez
    client_ip_address: touch?.client_ip || undefined,
    client_user_agent: touch?.user_agent || undefined,
  };
}

normalizeTrPhone bilerek tutucu yazıldı: emin olamadığı numarayı null döndürür. Yanlış normalize edilmiş bir telefonu göndermek, hiç göndermemekten daha kötü değildir ama hata ayıklamayı zorlaştırır; reddedilen numaraları ayrı bir sayaçta tutmak veri kalitesi sorununu görünür kılar. Yurt dışından gelen alıcılar için ülke kodunu tahmin etmek yerine formda ayrı bir ülke kodu seçici kullanmak daha sağlıklı. Ad ve soyad için de Meta küçük harf ve noktalama içermeyen biçim istiyor; Türkçe karakterler UTF-8 olarak kodlanmalı.

Gönderim: Outbox işçisi, yeniden deneme ve test kodu

CAPI çağrısını CRM'in aşama değiştirme isteğinin içinde yapmak cazip gelir ama Meta tarafındaki kısa bir kesinti ya da token sorunu, danışmanın "kaydet" düğmesini hataya düşürmemelidir. Aşama değişikliği aynı veritabanı işleminde capi_outbox'a satır yazar, ayrı bir işçi de kuyruğu boşaltır. Uç nokta POST https://graph.facebook.com/<sürüm>/<PIXEL_ID>/events biçimindedir; sürümü sabit kodlamak yerine yapılandırmadan okuyun ve periyodik olarak güncelleyin.

const GRAPH = `https://graph.facebook.com/${process.env.META_GRAPH_VERSION}`;
const PIXEL_ID = process.env.META_PIXEL_ID;
const TOKEN = process.env.META_CAPI_TOKEN;      // yalnızca sunucuda
const MAX_AGE_S = { default: 7 * 86400, physical_store: 62 * 86400 };

export async function flushOutbox(db) {
  const rows = await db.claimPending({ limit: 200 }); // SELECT ... FOR UPDATE SKIP LOCKED
  const now = Math.floor(Date.now() / 1000);
  const fresh = [];

  for (const r of rows) {
    const t = Math.floor(new Date(r.event_time).getTime() / 1000);
    const limit = MAX_AGE_S[r.action_source] ?? MAX_AGE_S.default;
    if (now - t > limit) {
      await db.mark(r.id, "dead", "event_time penceresi aşıldı");
      continue; // eski olay tüm partiyi düşürmesin
    }
    fresh.push({ row: r, event: { ...r.payload, event_time: t } });
  }
  if (!fresh.length) return;

  const body = { data: fresh.map((f) => f.event) };
  if (process.env.META_TEST_EVENT_CODE) body.test_event_code = process.env.META_TEST_EVENT_CODE;

  const res = await fetch(`${GRAPH}/${PIXEL_ID}/events?access_token=${TOKEN}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const json = await res.json().catch(() => ({}));

  for (const { row } of fresh) {
    if (res.ok) {
      await db.mark(row.id, "sent", json.fbtrace_id || null);
    } else {
      const attempts = row.attempts + 1;
      const backoffMin = Math.min(2 ** attempts, 360);
      const status = res.status >= 500 || res.status === 429 ? "pending" : "failed";
      await db.retry(row.id, { status, attempts, backoffMin, error: JSON.stringify(json.error || {}) });
    }
  }
}

Birkaç ayrıntı: 5xx ve hız sınırı yanıtlarında üstel geri çekilmeyle tekrar deniyorum, 4xx yanıtlarında ise (biçim hatası, geçersiz token, eski event_time) tekrar denemek anlamsız olduğu için satırı failed yapıp insana bırakıyorum. Yeniden denemelerde event_id değişmediği için aynı olayın iki kez gönderilmesi Meta tarafında tekilleştirilir; outbox'ın güvenli olmasını sağlayan şey de bu. Geliştirme ve test ortamında test_event_code ile Events Manager'daki test ekranını kullanmak, canlı veriyi kirletmeden payload'u doğrulamanın en pratik yolu. Erişim token'ını tarayıcıya, mobil uygulamaya ya da istemci tarafı etiket yöneticisine koymayın.

Satış olayının payload kısmında custom_data içine value ve currency (ör. TRY) eklenir. Gayrimenkulde burada bir iş kararı gerekir: sözleşme bedelinin tamamını mı, şirket için anlamlı bir marj ya da komisyonu mu göndereceksiniz? Tutarlı olduğunuz sürece ikisi de savunulabilir; önemli olan değerin her olayda aynı mantıkla hesaplanmasıdır.

İzleme: Event Match Quality ve kendi metrikleriniz

Meta, Events Manager'da her olay için Event Match Quality (EMQ) adında bir eşleşme kalitesi puanı gösterir. Bu puan, gönderdiğiniz müşteri bilgisi parametrelerinin olayları Meta hesaplarıyla ne kadar iyi eşleştirebildiğine dair bir göstergedir. Kesin bir formülü yok, kendi sisteminizden ölçemezsiniz; ama yön gösterir. Puan düşükse genellikle sebep normalizasyon hatası, eksik fbc/fbp ya da sunucu olaylarına IP ve kullanıcı aracısının eklenmemesidir.

EMQ'ya ek olarak kendi tarafımda üç şeyi izliyorum: Meta kaynaklı başvurularda fbc doluluk oranı, outbox'ta failed/dead satır sayısı ve form olaylarında Pixel ile sunucu sayılarının birbirine yakınlığı.

-- Son 7 gün: kanal bazında fbc doluluğu ve kuyruk sağlığı
SELECT t.channel,
       COUNT(*)                                        AS touches,
       ROUND(100.0 * COUNT(t.fbc) / COUNT(*), 1)       AS fbc_fill_pct,
       COUNT(*) FILTER (WHERE o.status = 'failed')     AS failed_events,
       COUNT(*) FILTER (WHERE o.status = 'dead')       AS expired_events
FROM lead_touch t
LEFT JOIN capi_outbox o ON o.touch_id = t.id
WHERE t.created_at > now() - interval '7 days'
  AND t.consent_ads
GROUP BY t.channel
ORDER BY touches DESC;

Bu sorgudaki oranlar için size hedef bir sayı vermeyeceğim; her projenin trafik yapısı farklı. Değerli olan mutlak değer değil, değişimdir. Bir sabah form kanalındaki fbc doluluğunun dibe vurduğunu görürseniz, büyük ihtimalle biri açılış sayfasını yeniden tasarlarken yakalama betiğini kaldırmıştır ya da bir yönlendirme URL parametrelerini düşürüyordur. Bu hat sessizce bozulur; alarm kurmazsanız haftalar sonra fark edersiniz.

KVKK ve rıza üzerine kısa not

Bu bölüm hukuki görüş değildir; kendi projeniz için mutlaka hukuk danışmanınızla çalışın. Teknik açıdan dikkat ettiğim noktalar şunlar: reklam ve ölçüm amaçlı yakalamayı açık rızaya bağlamak ve rıza durumunu temas satırında (consent_ads) saklamak, rıza yoksa fbc/fbp yakalamamak ve CRM olaylarını Meta'ya göndermemek, aydınlatma metninde Meta'ya veri aktarımını ve saklama süresini açıkça belirtmek, purge_after süresi dolan tıklama kimliklerini gerçekten silmek. Hash'leme veriyi anonim hâle getirmez; hash'lenmiş e-posta hâlâ kişisel veri olarak değerlendirilmelidir. Yurt dışına aktarım boyutu da hukuki değerlendirme gerektiren ayrı bir konudur.

Sık yapılan hatalar

fbc içindeki zamanı saniye cinsinden yazmak ya da fbclid değerini küçük harfe çevirmek.
fbc ve fbp değerlerini de hash'lemek.
Pixel ve sunucuda farklı event_id ya da farklı olay adı kullanıp form olaylarını çift saymak.
Telefonu 0532... ya da +90... biçiminde hash'lemek.
Satışları ay sonunda toplu girip event_time penceresini kaçırmak.
Her CRM aşamasını ayrı olay olarak gönderip sinyali gürültüye boğmak.
fbc değerini kişi kartında tek bir alanda tutup sonraki temaslarla ezmek.

SSS

fbclid ile _fbc aynı şey mi?
Hayır. fbclid URL'deki ham tıklama kimliğidir; _fbc ise bu kimliği fb.1.<ms zaman damgası>.<fbclid> biçiminde, oluşturulma zamanıyla birlikte taşıyan değerdir. CAPI'ye fbc alanında ham fbclid değil, bu biçimdeki değer gönderilmelidir.

Pixel çerezini kullanamıyorsam _fbc değerini kendim üretebilir miyim?
Evet. Meta, çerez kaydedilmiyorsa fbclid'in ilk görüldüğü zaman damgasıyla değeri sunucuda üretmeyi ve subdomainIndex olarak 1 kullanmayı öneriyor. _fbp için ise rastgele değer uydurmak yerine alanı boş bırakmayı tercih ediyorum.

Lead olayını hem Pixel hem CAPI ile göndermek çift sayım yapmaz mı?
Aynı event_name ve aynı event_id (Pixel tarafında eventID) kullanılırsa Meta iki olayı tekilleştirir. Kimlikler farklıysa iki ayrı olay olarak sayılır; bu yüzden kimliği tarayıcıda üretip form ile sunucuya taşımak en güvenli yoldur.

Reklam tıklamasından iki ay sonra imzalanan satışı gönderebilir miyim?
Gönderim sınırı tıklamayla değil olay zamanıyla ilgilidir. Satış imzalandığı gün gönderilirse event_time güncel olur. Pencere, event_time ile gönderim anı arasındaki farka uygulanır: genel olarak yedi gün, physical_store olayları için altmış iki gün.

Telefon numarasını hangi biçimde hash'lemeliyim?
Sembolleri, boşlukları ve baştaki sıfırları atıp ülke koduyla başlayan rakam dizisine çevirin; Türkiye cep numarası için 905321234567 biçimi. Artı işareti dahil edilmez. Ardından SHA-256 ile küçük harfli onaltılık (hex) çıktı üretin.

fbclid yoksa CAPI göndermeye değer mi?
Değer. Eşleşme bu durumda e-posta, telefon, external_id, IP ve kullanıcı aracısı gibi sinyallere dayanır ve genelde daha zayıf kalır, ama nitelikli lead ve satış olayları yine de algoritmaya ne tür kişilerin gerçekten satışa döndüğünü anlatır.

Son söz

fbclid'i formdan Meta'ya geri taşımak tek bir kod parçası değil, birbirine bağlı küçük kararlardan oluşan bir zincir: doğru biçimde yakalamak, temasa bağlı saklamak, az ama anlamlı olay seçmek, olay kimliğini korumak, dikkatle normalize etmek ve kuyruğu izlemek. Benim deneyimimde en değerli adım, kod yazmadan önce satış ve pazarlama ekibiyle "hangi aşama bizim için gerçekten başarı" sorusunu netleştirmek oluyor. O cevap belli olduktan sonra geri kalanı, burada anlattığım gibi sıkıcı ve güvenilir bir mühendislik işi.

GCLID'yi formdan Google Ads'e geri taşımak: Yakalama, saklama, aşama eşlemesi ve offline dönüşüm yükleme

Koray Yalçın — Mon, 09 Nov 2026 08:26:12 +0000

Gayrimenkul projesinde bir arama reklamı tıklaması ile tapu devri arasında haftalar, bazen aylar geçer. Reklam paneli o tıklamanın form doldurduğunu bilir ama satışa dönüp dönmediğini bilmez. Satış ofisi de sözleşmeyi bilir ama hangi kampanyadan geldiğini bilmez. Ben Koray Yalçın olarak lead yönetimi ve CRM kurulumlarında bu iki dünyayı birbirine bağlayan en ucuz ve en çok ihmal edilen parçanın GCLID olduğunu düşünüyorum. Sorun genellikle "GCLID'yi kaydedelim" kararının alınması değil; o değerin yolda kaybolması, yanlış kayda bağlanması ya da Google Ads'e yanlış zamanda, yanlış biçimde gönderilmesidir.

GCLID (Google Click Identifier), Google Ads hesabında otomatik etiketleme açıkken reklam tıklamasıyla gelen ziyaretçinin hedef URL'sine eklenen benzersiz bir sorgu parametresidir. Bu yazıda kavramın tanımında kalmayacağım; bir geliştiricinin kuracağı uçtan uca hattı anlatacağım: tarayıcıda yakalama, form üzerinden taşıma, CRM'de doğru tabloda saklama, satış aşamalarını dönüşüm eylemlerine eşleme ve Google Ads API ile güvenli, tekrarlanabilir yükleme.

Hattın beş halkası

Bir GCLID'nin değer üretmesi için beş halkanın da sağlam olması gerekir:

Yakalama: URL'deki gclid (ve iOS tarafındaki gbraid / wbraid) değerini ilk sayfa görüntülemesinde okumak.
Kalıcılık: Ziyaretçi formu ilk sayfada değil, üçüncü sayfada ya da ertesi gün doldurabilir; değer oturumlar arasında korunmalı.
Taşıma: Form gönderiminde değer gizli alanla sunucuya gelmeli; WhatsApp ya da telefon gibi formsuz kanallarda da bir köprü kurulmalı.
Saklama: CRM'de değer kişi kartına değil, başvuru (touch) olayına bağlanmalı.
Geri bildirim: Satış aşaması değiştiğinde ilgili dönüşüm eylemi, doğru zaman damgası ve değerle Google Ads'e yüklenmeli.

Ekiplerin çoğu birinci ve beşinci halkayı kurar, aradakileri varsayar. Kayıp tam da aradaki halkalarda yaşanır.

Yakalama ve kalıcılık: İlk sayfada oku, makul süre sakla

Google etiketi (gtag) ve dönüşüm bağlayıcı zaten tıklama bilgisini birinci taraf çerezde tutar. Ama CRM'e gidecek formun bu değere güvenilir biçimde erişmesi için kendi küçük katmanımı yazmayı tercih ediyorum. Bunun iki nedeni var: değeri hangi koşulda sakladığımı kontrol etmek ve rıza durumuna göre davranabilmek.

const CLICK_KEYS = ["gclid", "gbraid", "wbraid"];
const TTL_DAYS = 90;

function captureClickIds(hasAdConsent) {
  if (!hasAdConsent) return;               // rıza yoksa saklama
  const params = new URLSearchParams(window.location.search);
  for (const key of CLICK_KEYS) {
    const value = params.get(key);
    if (value) {
      const record = {
        key,
        value,
        landing: window.location.pathname,
        capturedAt: new Date().toISOString(),
      };
      localStorage.setItem("click_id", JSON.stringify(record));
      return;                               // en yeni tıklama kazanır
    }
  }
}

function readClickId() {
  const raw = localStorage.getItem("click_id");
  if (!raw) return null;
  const record = JSON.parse(raw);
  const ageDays = (Date.now() - Date.parse(record.capturedAt)) / 86400000;
  return ageDays <= TTL_DAYS ? record : null;
}

Burada üç bilinçli karar var. Birincisi, "en yeni tıklama kazanır" kuralı: aynı kişi iki farklı kampanyadan gelirse son tıklamayı tutuyorum, çünkü form gönderimine en yakın niyet odur. İlk tıklamayı da görmek istiyorsanız ikinci bir anahtarda ayrıca saklayın, ama yükleme tarafında yalnızca birini kullanın. İkincisi, süre sınırı: Google Ads çevrimdışı içe aktarmada tıklamanın, dönüşüm eyleminin tıklama sonrası dönüşüm penceresi içinde olması gerekir ve bu pencere en fazla 90 gündür. Pencere dışında kalacak bir değeri taşımak yalnızca hata satırı üretir. Üçüncüsü, rıza kontrolü: reklam ölçümü için rıza alınmamış bir ziyaretçinin tıklama kimliğini saklamıyorum. KVKK ve GDPR açısından nasıl bir rıza metni gerektiği ayrı bir hukuki değerlendirmedir; bu yazı hukuki görüş değildir, ama mimari olarak "rıza yoksa yakalama yok" anahtarının kodda var olması gerekir.

gbraid ve wbraid notu: iOS ortamında bazı tıklamalarda GCLID yerine bu parametreler gelir. Google Ads API'deki tıklama dönüşümü nesnesinde bu üç alandan yalnızca biri doldurulabilir. Bu yüzden değeri key ile birlikte saklıyorum; yükleme sırasında hangi alana yazılacağını bu belirler.

Taşıma: Gizli alan yetmez, sunucu da doğrulamalı

Formda gizli bir alan açıp değeri oraya koymak işin kolay kısmı. Zor kısmı, sunucunun bu değere körü körüne güvenmemesi. Gizli alan istemciden gelir; boş, bozuk ya da başka bir sayfadan kopyalanmış olabilir.

document.querySelector("#lead-form").addEventListener("submit", (e) => {
  const click = readClickId();
  const form = e.target;
  form.elements["click_id_key"].value = click ? click.key : "";
  form.elements["click_id_value"].value = click ? click.value : "";
  form.elements["click_landing"].value = click ? click.landing : "";
});

Sunucuda yaptığım kontroller basit: anahtar izin verilen üç değerden biri mi, değer makul uzunlukta ve yalnızca URL güvenli karakterlerden mi oluşuyor, aynı değer kısa sürede çok sayıda farklı başvuruda görünüyor mu. Sonuncusu önemli: tek bir GCLID'nin bir saat içinde onlarca farklı telefon numarasıyla gelmesi, ya bir bot trafiğine ya da paylaşılan bir linke işaret eder. Böyle bir değeri dönüşüm yüklemesinden hariç tutmak, reklam algoritmasını kirletmekten iyidir.

Formsuz kanallarda durum farklı. Ziyaretçi "WhatsApp'tan yaz" butonuna bastığında URL'de GCLID olsa bile mesaj uygulamasına geçince kaybolur. Burada kullandığım yöntem, butona basıldığında sunucuda kısa ömürlü bir referans kodu üretmek, bu kodu tıklama kimliğiyle eşleyip hazır mesaj metnine eklemektir. İlk mesaj geldiğinde entegrasyon kodu çözer ve başvuruya bağlar. Telefon aramalarında ise çağrı takibi tarafındaki numara havuzu benzer bir köprü görevi görür. Her iki yöntemde de amaç aynıdır: tıklama kimliğini insan kanalına geçerken düşürmemek.

Saklama: GCLID kişiye değil, başvuruya aittir

En sık gördüğüm veri modeli hatası, gclid alanını kişi (contact) tablosuna tek bir sütun olarak eklemektir. Aynı kişi önce Google'dan, sonra Meta'dan, sonra yine Google'dan gelir; tek sütun her seferinde ezilir ve hangi satışın hangi tıklamaya ait olduğu bilgisi kaybolur. Mükerrer kişi birleştirme işlemi de bu değeri sessizce siler.

CREATE TABLE lead_touch (
  id              bigserial PRIMARY KEY,
  contact_id      bigint NOT NULL REFERENCES contact(id),
  deal_id         bigint REFERENCES deal(id),
  channel         text NOT NULL,          -- google_ads, meta, portal, organik
  click_id_key    text CHECK (click_id_key IN ('gclid','gbraid','wbraid')),
  click_id_value  text,
  landing_path    text,
  clicked_at      timestamptz,
  submitted_at    timestamptz NOT NULL,
  ad_consent      boolean NOT NULL DEFAULT false
);

CREATE INDEX ON lead_touch (click_id_value) WHERE click_id_value IS NOT NULL;

Fırsat (deal) açıldığında hangi başvurunun "kaynak başvuru" olduğunu açıkça işaretliyorum. Genellikle fırsatı doğuran son başvurudur, ama satış ekibi manuel olarak değiştirebilir ve bu değişiklik denetim kaydına düşer. Böylece "bu satışı hangi tıklamaya bağladık ve neden" sorusunun cevabı her zaman sorgulanabilir.

Aşama eşlemesi: Her CRM aşaması bir dönüşüm değildir

Google Ads tarafında birden fazla dönüşüm eylemi tanımlamak, satış hunisinin farklı derinliklerini algoritmaya öğretmenin yoludur. Ama her CRM aşamasını dönüşüme çevirmek gürültü üretir. Gayrimenkul satışında anlamlı bulduğum eşleme şöyle:

CRM aşaması	Dönüşüm eylemi	Değer
Nitelikli lead	`qualified_lead`	Sabit küçük değer
Randevu gerçekleşti	`site_visit_done`	Sabit orta değer
Kapora alındı	`deposit_paid`	Kapora tutarı veya sabit değer
Sözleşme imzalandı	`contract_signed`	Sözleşme bedeli

Değerlerin ne olacağı işletmenin kendi ekonomisine bağlıdır; burada rakam vermiyorum, çünkü her projenin bilet büyüklüğü ve dönüşüm zinciri farklıdır. Önemli olan kural: bu eşleme kodda sabit değil, veri olarak tutulmalı. Pazarlama ekibi yeni bir eylem eklediğinde dağıtım yapmak gerekmemeli.

İkinci kural, aşama geri gittiğinde ne olacağıdır. Kapora iade edildiyse ya da sözleşme feshedildiyse, daha önce yüklenen dönüşüm için Google Ads'in dönüşüm düzeltme (adjustment) mekanizmasıyla geri çekme veya değer güncelleme gönderilebilir. Bunu yapabilmek için ilk yüklemede tekil bir order_id kullanmak şarttır; düzeltme o kimlik üzerinden eşleşir.

Yükleme: Kuyruk, tekil kimlik, kısmi hata

Aşama değişikliği bir olay üretir; olay doğrudan API çağrısı yapmaz, bir giden kutusu (outbox) tablosuna yazılır. Ayrı bir işçi bu tabloyu okuyup toplu yükleme yapar. Bu yapı, Google Ads API geçici olarak hata verdiğinde satış ekibinin ekranını kilitlemez ve her yüklemenin izini tutar.

from google.ads.googleads.client import GoogleAdsClient

def build_click_conversion(client, customer_id, row):
    conv = client.get_type("ClickConversion")
    setattr(conv, row.click_id_key, row.click_id_value)   # gclid / gbraid / wbraid
    conv.conversion_action = client.get_service(
        "ConversionActionService"
    ).conversion_action_path(customer_id, row.conversion_action_id)
    # Biçim: "yyyy-mm-dd hh:mm:ss+hh:mm", saat dilimi açık olmalı
    conv.conversion_date_time = row.converted_at.strftime("%Y-%m-%d %H:%M:%S%z")
    conv.conversion_date_time = (
        conv.conversion_date_time[:-2] + ":" + conv.conversion_date_time[-2:]
    )
    conv.conversion_value = float(row.value)
    conv.currency_code = row.currency
    conv.order_id = row.order_id            # tekilleştirme ve sonraki düzeltme için
    return conv

def upload_batch(client, customer_id, rows):
    service = client.get_service("ConversionUploadService")
    request = client.get_type("UploadClickConversionsRequest")
    request.customer_id = customer_id
    request.conversions.extend(
        build_click_conversion(client, customer_id, r) for r in rows
    )
    request.partial_failure = True
    return service.upload_click_conversions(request=request)

Bu kodda dikkat ettiğim ayrıntılar şunlar:

Zaman damgası dönüşüm anıdır, yükleme anı değil. Sözleşmenin imzalandığı zaman yazılır. Saat dilimi açıkça belirtilmezse dönüşüm, tıklamadan önceymiş gibi görünüp reddedilebilir. Kıbrıs veya Türkiye saatinde çalışan bir satış ofisinde bu hata beklenenden sık çıkar.
partial_failure açık. Toplu yüklemede tek bir bozuk satır tüm paketi düşürmemeli. Yanıttaki kısmi hata ayrıntısı satır satır okunur ve outbox kaydına yazılır.
order_id deterministik. Aynı fırsat ve aynı eylem için her zaman aynı kimlik üretilir, örneğin deal_id ile eylem adının birleşimi. İşçi çöküp aynı satırı yeniden gönderse bile çift sayım oluşmaz.
Para birimi açık. Sterlin bazlı satış yapan bir projede değeri liraya çevirip göndermek ya da para birimini boş bırakmak, raporlamada sessiz bir kaymaya yol açar.

Hata sınıflandırması da önemlidir. Tıklamanın bulunamaması, pencerenin geçmiş olması ya da dönüşümün tıklamadan önce görünmesi kalıcı hatalardır; yeniden denenmez, raporlanır. Kota veya geçici sunucu hataları ise geri çekilmeli yeniden deneme ile tekrar kuyruğa alınır. İki sınıfı karıştırmak, ya kalıcı hatalarla kuyruğu tıkar ya da geçici hatalarda veri kaybeder.

GCLID olmadığında: Gelişmiş dönüşümler bir yedek

Her başvuruda tıklama kimliği olmayacak. Rıza verilmemiş olabilir, ziyaretçi başka cihazdan dönmüş olabilir, kanal köprüsü kopmuş olabilir. Google'ın potansiyel müşteriler için gelişmiş dönüşümler (enhanced conversions for leads) özelliği, normalize edilip SHA-256 ile özetlenmiş e-posta veya telefon üzerinden eşleşme yapmaya izin verir. Ben bunu GCLID'nin yerine değil, yanına konmuş bir yedek olarak görüyorum. Normalizasyon kuralları (küçük harf, boşluk temizleme, telefonda uluslararası biçim) burada da kritik; eşleşme oranını en çok etkileyen şey özetlemeden önceki temizliktir. Bu tür kişisel veri işleme için de rıza ve aydınlatma tarafı ayrıca değerlendirilmelidir.

İzleme: Hat sessizce bozulur

Bu hattın en tehlikeli özelliği, bozulduğunda kimsenin fark etmemesidir. Bir tema güncellemesi gizli alanı formdan kaldırır, bir yönlendirme kuralı sorgu parametrelerini düşürür, bir CRM kullanıcısı aşama adını değiştirir ve eşleme tablosu boşa düşer. Bu yüzden haftalık değil günlük baktığım birkaç gösterge var:

Google Ads kanalından gelen başvurularda tıklama kimliği dolu olanların oranı. Ani düşüş genellikle yakalama veya taşıma halkasının koptuğunu gösterir.
Outbox'ta bekleyen, başarılı, kalıcı hatalı ve yeniden denenen satır sayıları.
Kalıcı hataların neden dağılımı. Aynı neden birden artıyorsa kod değişmiş demektir.
Yüklenen dönüşüm sayısı ile CRM'deki aynı aşamadaki fırsat sayısı arasındaki fark.

Son madde bir mutabakat kontrolüdür ve en değerlisidir. Reklam panelindeki sayıyla CRM'deki sayı hiçbir zaman birebir tutmaz, ama farkın nedenlerini (rıza yok, pencere dışı, kimlik yok) açıklayabiliyorsanız hat sağlıklıdır.

Sık yapılan hatalar

GCLID'yi yalnızca açılış sayfasında okuyup formun başka sayfada olduğunu unutmak.
Değeri kişi kartında tek sütunda tutmak ve her yeni başvuruda ezmek.
Yükleme zamanını dönüşüm zamanı olarak göndermek.
Saat dilimi bilgisini atlamak.
Tekil order_id kullanmadan yeniden deneme yapmak.
Her CRM aşamasını ayrı dönüşüm eylemi yapıp algoritmaya gürültü vermek.
İade ve fesihleri geri yansıtmamak.
Rıza durumunu yakalama anında değil, yalnızca yükleme anında kontrol etmek.

Sık Sorulan Sorular (SSS)

GCLID'yi neden kişi tablosunda değil de başvuru tablosunda tutmalıyım?
Çünkü bir kişi birden fazla kampanyadan, farklı zamanlarda gelebilir. Tıklama kimliği bir başvuru olayının özelliğidir. Kişi tablosunda tutulduğunda her yeni başvuru eskisini ezer ve satışın gerçek kaynağı kaybolur.

Satış 90 günden sonra kapanırsa ne olur?
Tıklama, dönüşüm eyleminin tıklama sonrası penceresinin dışında kalıyorsa Google Ads o dönüşümü kabul etmez. Uzun satış döngülerinde bu yüzden randevu veya kapora gibi daha erken, pencere içinde kalan aşamaları da dönüşüm eylemi olarak tanımlamak mantıklıdır.

Aynı dönüşümü yanlışlıkla iki kez yüklersem ne olur?
Her yüklemede aynı fırsat ve eylem için aynı order_id değerini gönderiyorsanız tekrar eden satır tekilleştirilir. order_id göndermiyorsanız çift sayım riski vardır; bu yüzden deterministik kimlik üretimi zorunlu kabul edilmelidir.

Kapora iade edildiğinde dönüşümü nasıl geri alırım?
Google Ads'in dönüşüm düzeltme mekanizmasıyla, ilk yüklemedeki order_id üzerinden geri çekme veya değer güncelleme gönderilebilir. Bunu da outbox üzerinden, ayrı bir olay türü olarak işlemek en temiz yoldur.

gbraid ve wbraid ile ne yapmalıyım?
GCLID ile aynı şekilde yakalayıp hangi anahtarla geldiğini birlikte saklayın. Yükleme sırasında tıklama dönüşümü nesnesinde bu üç alandan yalnızca biri doldurulabilir; hangisinin kullanılacağını saklanan anahtar belirler.

Rıza vermeyen ziyaretçi için ne yapılır?
Tıklama kimliği saklanmaz ve yüklenmez. Bu başvurular CRM'de normal şekilde işlenir, yalnızca reklam geri bildirim hattına girmez. Rıza metninin içeriği ve hukuki dayanağı için uzman görüşü alınmalıdır; bu yazı hukuki tavsiye değildir.

Bu hattı kurmak için mutlaka Google Ads API mi kullanmalıyım?
Küçük hacimlerde panelden dosya ile içe aktarma da mümkündür. Ancak aşama değişiklikleri sürekli olduğunda ve düzeltme, yeniden deneme, mutabakat gerektiğinde API tabanlı bir kuyruk çok daha güvenilir ve izlenebilir bir yapı sunar.

Son söz

GCLID küçük bir sorgu parametresi gibi görünür ama reklam bütçesinin satışa nasıl dönüştüğünü algoritmaya öğreten tek sağlam bağdır. Yakalama, kalıcılık, taşıma, saklama ve geri bildirim halkalarını ayrı ayrı tasarlayıp izlediğinizde, reklam paneli yalnızca form dolduranları değil, gerçekten satın alanları anlamaya başlar. Lead yönetimi ve CRM entegrasyonu üzerine çalışırken en çok önem verdiğim ilke de bu: veri, kaybolduğu yerde değil, doğduğu yerde korunmalıdır.

Koray Yalçın — lead yönetimi, CRM mimarisi, dijital pazarlama ve PropTech üzerine yazıyor.

Lead deduplication'ı kodla kurmak: Blocking key, telefon normalizasyonu, eşik ve kişi grafı

Koray Yalçın — Sun, 08 Nov 2026 19:18:07 +0000

Lansman haftasında aynı kişi üç kanaldan geliyor: sabah Meta anlık formunu dolduruyor, öğleden sonra proje sitesindeki formu gönderiyor, akşam da ilan portalından "bilgi al" butonuna basıyor. CRM'de üç kayıt açılıyor, üç danışman aynı numarayı arıyor, aday kızıyor, pazarlama ekibi de "reklam çalışıyor ama satış kaçırıyoruz" diyor. Ben Koray Yalçın olarak lead yönetimi ve CRM kurulumlarında bu tabloyu defalarca gördüm: mükerrer kayıt, bir temizlik işi gibi düşünülüyor; oysa sorun kayıt geldikten haftalar sonra tabloda satır birleştirmek değil, kaydın sisteme girdiği anda kimliğin çözülmemesidir.

Lead deduplication (mükerrer lead ayıklama), yeni bir talebin mevcut bir kişiye ait olup olmadığına karar veren ve bu kararı tekrarlanabilir kurallarla veren katmandır. Kavramın kısa tanımını lead deduplication nedir sözlük maddesinde tutuyorum; bu yazıda o tanımı bir geliştiricinin kuracağı yapıya çeviriyorum: normalizasyon, blocking key, kural tablosu, üç sonuçlu karar (bağla / incelemeye al / yeni kişi aç) ve geri alınabilir bir kişi grafı.

Önemli bir ayrım var. Her gelen formu silip tek satırda toplamak istemiyoruz. Her başvuru bir niyet sinyalidir: hangi kanal, hangi proje, hangi saat, hangi reklam. Birleştirilmesi gereken şey kişi kimliğidir, başvuru olayı değil.

Telefon tek başına yetmez

Birçok ekip "aynı telefon varsa aynı kişidir" kuralıyla yola çıkar. Gayrimenkul tarafında bu kural üç şekilde bozulur.

Birincisi biçim. 0532 111 22 33, +90 532 111 22 33, 00905321112233 ve 5321112233 aynı numaradır ama metin olarak dört farklı değerdir. İkincisi paylaşım. Bir ofis sabit hattı veya bir ev numarası iki farklı kişi tarafından kullanılabilir; özellikle ailece bakılan bir dairede bu sık görülür. Üçüncüsü değişim. Aynı kişi yeni bir hatla ikinci kez başvurur; telefon eşleşmez, e-posta eşleşir.

Bu yüzden eşleştirmeyi tek bir alana bağlamak yerine, normalize edilmiş birkaç kimlik anahtarı ve bu anahtarların güven düzeyini tutan kurallar kullanıyorum.

Önce normalize et, sonra karşılaştır

Karşılaştırma asla ham metin üzerinde yapılmamalı. Telefon için hedef biçim E.164'tür; Türkiye'de mobil numarada baştaki sıfır ve 0090 / +90 varyantları tek bir +90XXXXXXXXXX değerine indirgenir. E-posta için küçük harf, uç boşluk ve Gmail'deki nokta ile + takıları ayrı ele alınır: ali.veli+proje@gmail.com ile aliveli@gmail.com aynı teslim kutusudur.

import phonenumbers

def normalize_phone(raw: str, default_region: str = "TR") -> str | None:
    if not raw:
        return None
    try:
        num = phonenumbers.parse(raw, default_region)
        if not phonenumbers.is_valid_number(num):
            return None
        return phonenumbers.format_number(
            num, phonenumbers.PhoneNumberFormat.E164
        )
    except phonenumbers.NumberParseException:
        return None

def normalize_email(raw: str) -> str | None:
    if not raw:
        return None
    email = raw.strip().lower()
    if "@" not in email:
        return None
    local, domain = email.split("@", 1)
    if domain in {"gmail.com", "googlemail.com"}:
        local = local.split("+", 1)[0].replace(".", "")
        domain = "gmail.com"
    return f"{local}@{domain}"

İsim için daha temkinliyim. Türkçe karakterleri NFC ile tutmak, fazla boşlukları sıkıştırmak ve unvanları (sn., mr.) atmak yeterlidir. İsmi tek başına eşleşme anahtarı yapmam; "Mehmet Yılmaz" aynı projede onlarca kez geçer. İsim, telefon veya e-posta gibi güçlü bir anahtarla birlikte destekleyici kanıt olur.

Kişi grafı: başvuruyu silme, kişiye bağla

Şemada üç tablo tutuyorum. person kanonik kimliktir. lead_event her başvurudur ve asla güncellenerek yok edilmez. person_identifier o kişiye bağlı, normalize edilmiş anahtarlardır.

CREATE TABLE person (
  id           bigserial PRIMARY KEY,
  created_at   timestamptz NOT NULL DEFAULT now(),
  display_name text
);

CREATE TABLE lead_event (
  id               bigserial PRIMARY KEY,
  person_id        bigint REFERENCES person(id),
  source           text NOT NULL,
  source_record_id text NOT NULL,
  project_key      text,
  payload          jsonb NOT NULL,
  received_at      timestamptz NOT NULL DEFAULT now(),
  match_status     text NOT NULL,
  match_rule       text,
  match_score      numeric,
  UNIQUE (source, source_record_id)
);

CREATE TABLE person_identifier (
  id         bigserial PRIMARY KEY,
  person_id  bigint NOT NULL REFERENCES person(id),
  kind       text NOT NULL,
  value      text NOT NULL,
  first_seen timestamptz NOT NULL DEFAULT now(),
  UNIQUE (kind, value)
);

CREATE TABLE match_review (
  id                  bigserial PRIMARY KEY,
  lead_event_id       bigint NOT NULL REFERENCES lead_event(id),
  candidate_person_id bigint NOT NULL REFERENCES person(id),
  score               numeric NOT NULL,
  reasons             jsonb NOT NULL,
  created_at          timestamptz NOT NULL DEFAULT now(),
  resolved_at         timestamptz,
  resolution          text
);

UNIQUE (kind, value) satırı kritiktir: aynı E.164 numarası iki kişiye bağlanamaz. İki kişi aynı numarayı gerçekten paylaşıyorsa bu bir inceleme kaydıdır, sessizce ikinci kişiye yazılmaz. UNIQUE (source, source_record_id) ise aynı Meta form gönderiminin iki kez işlenmesini engeller; bu, deduplication'ın kardeşi olan idempotent ingest'tir.

Blocking key: tüm tabloyu taramayın

Her yeni lead geldiğinde bütün person tablosunu gezmek hem yavaş hem tehlikelidir; yanlış eşleşme riski hacimle birlikte artar. Blocking, olası adayları ucuz bir anahtarla daraltır, pahalı karşılaştırmayı yalnız o kümeye uygular.

CREATE TABLE person_block (
  person_id bigint NOT NULL REFERENCES person(id),
  block_key text NOT NULL,
  PRIMARY KEY (block_key, person_id)
);

-- örnek anahtarlar:
-- phone:+905321112233
-- email:aliveli@gmail.com
-- phone_last7:5321112233

Yeni kayıt geldiğinde önce kendi blocking key'lerini üretiyorum, person_block üzerinden aday kişi kimliklerini çekiyorum, sonra yalnız bu adaylar üzerinde kural tablosunu çalıştırıyorum. Hacim binlerle ifade edildiğinde bu fark, tam taramayla kıyaslanamayacak kadar belirgindir.

Kuralları koda gömmeyin, tabloya yazın

Eşleşme kurallarının iş birimiyle konuşulabilir olması gerekir. "Aynı normalize telefon kesin eşleşmedir" kuralını bir if dalının içine gömersem, pazarlama ekibi kuralı değiştirmemi istediğinde deploy beklemek zorunda kalır. Ben kuralları veri olarak tutuyorum:

CREATE TABLE match_rule (
  id         text PRIMARY KEY,
  priority   int NOT NULL,
  conditions jsonb NOT NULL,
  decision   text NOT NULL,
  min_score  numeric NOT NULL
);

-- phone_exact:  {"phone": "exact"} -> auto_link
-- email_exact:  {"email": "exact"} -> auto_link
-- phone_name:   {"phone": "exact", "name": "similar"} -> review
-- email_project:{"email_local": "exact", "project": "exact"} -> review

Kesin telefon veya kesin e-posta eşleşmesi otomatik bağlanır. İsim benzerliği, aynı proje, aynı cihaz veya aynı oturum gibi zayıf sinyaller tek başlarına otomatik birleştirme yapmaz; inceleme kuyruğuna düşer. Yapay zekâyı bu katmanda skor üretmek veya kuyruğu sıralamak için kullanabilirsiniz, birleştirme kararını ona bırakmam. Yanlış birleştirmenin maliyeti, yanlış ayrı tutmanın maliyetinden daha yüksektir: iki gerçek kişinin sohbet geçmişi, izni ve satış aşaması birbirine karışır ve geri almak zordur.

İsim benzerliği için Levenshtein ya da Jaro-Winkler yeterli olur; eşik değerini kendi verinize bakarak seçin, ezbere bir sayı yazmayın. Türkçe'de ı/i ve ğ/g dönüşümlerini karşılaştırmadan önce uygulamak, sahte farkları azaltır. Yine de isim skorunu otomatik birleştirme eşiğinin üstüne koymuyorum.

Karar anı ve yarış durumu

İki form aynı saniye içinde gelebilir. İkisi de henüz person tablosunda olmayan aynı telefonu taşırsa, kontrol-sonra-yaz yaklaşımı iki kişi üretir. Bunu önlemenin yolu, identifier üzerine konan benzersiz kısıt ve kısa bir kilit:

def ingest_lead(conn, event):
    phone = normalize_phone(event.get("phone"))
    email = normalize_email(event.get("email"))
    keys = []
    if phone:
        keys.append(("phone_e164", phone))
    if email:
        keys.append(("email_norm", email))

    with conn.cursor() as cur:
        lock = phone or email or event["source_record_id"]
        cur.execute("SELECT pg_advisory_xact_lock(hashtext(%s))", (lock,))
        candidates = find_candidates(cur, keys)
        decision = apply_rules(candidates, event, keys)

        if decision.kind == "auto_link":
            person_id = decision.person_id
        elif decision.kind == "review":
            person_id = None
        else:
            cur.execute(
                "INSERT INTO person (display_name) VALUES (%s) RETURNING id",
                (event.get("name"),),
            )
            person_id = cur.fetchone()[0]

        cur.execute(
            """INSERT INTO lead_event (
                   person_id, source, source_record_id, project_key,
                   payload, match_status, match_rule, match_score
               ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
               ON CONFLICT (source, source_record_id) DO NOTHING""",
            (
                person_id, event["source"], event["source_record_id"],
                event.get("project"), event["payload"], decision.kind,
                decision.rule_id, decision.score,
            ),
        )

        if person_id and decision.kind == "auto_link":
            for kind, value in keys:
                cur.execute(
                    """INSERT INTO person_identifier (person_id, kind, value)
                       VALUES (%s, %s, %s)
                       ON CONFLICT (kind, value) DO NOTHING""",
                    (person_id, kind, value),
                )
        if decision.kind == "review":
            queue_review(cur, event, decision)
        return decision

pg_advisory_xact_lock aynı telefon veya e-posta üzerinde eşzamanlı iki işlemi sıraya koyar. ON CONFLICT DO NOTHING aynı kaynak kaydının yeniden oynatılmasını yutar. Identifier çakışması olursa (başka bir kişi o telefonu zaten taşıyorsa) bunu sessizce geçmek yerine inceleme kuyruğuna yazın; aksi halde veri kaybını fark etmezsiniz.

İnceleme kuyruğundaki kayıt için person_id boş bırakılabilir ya da geçici bir kişi açılıp sonra bağlanabilir. Ben boş bırakmayı tercih ediyorum: satır görünür, danışmana henüz ikinci bir kişi olarak atanmaz, karar verilince bağlanır. Atama ve ilk temas bu kuyruğu bekleyemezse, geçici kişiyi açıp "olası mükerrer" bayrağı koymak daha güvenlidir; aksi halde inceleme bekleyen lead sessizce soğur. İkisinden birini bilinçli seçin.

Otomatik bağlama, kaydın sahibini değiştirmez. Var olan kişinin bir danışmanı varsa yeni başvuru o kişiye eklenir; sahiplik devredilmez, SLA saati sıfırlanmaz, "yeni lead" kuyruğuna ikinci kez düşülmez. Aksi halde aynı aday her formda başka bir danışmana gider ve mükerreri teknik olarak birleştirsek bile operasyonda yine üç kişi arar. İsterseniz bağlama olayına "mevcut sahibe haber ver" gibi bir yan etki ekleyin; haber vermek ile yeniden atamak farklı işlerdir.

Birleştirmeyi geri alınabilir tutun

Otomatik bağlama bile yanlış olabilir. Evli bir çift aynı e-posta kutusunu paylaşıyor olabilir; bir asistan kendi telefonundan işvereni adına form doldurmuş olabilir. Bu yüzden bağlama bir olaydır:

CREATE TABLE person_link_event (
  id            bigserial PRIMARY KEY,
  lead_event_id bigint NOT NULL REFERENCES lead_event(id),
  from_person_id bigint,
  to_person_id  bigint NOT NULL REFERENCES person(id),
  rule_id       text,
  actor         text NOT NULL,
  action        text NOT NULL,
  created_at    timestamptz NOT NULL DEFAULT now()
);

Geri alma (unlink) lead olayını eski haline döndürür, identifier'ı gerekirse koparır ve sonraki otomatik kuralların aynı hatayı hemen tekrarlamaması için bir istisna kaydı bırakır. Denetimde "bu iki kayıt neden birleşti?" sorusunun cevabı bu tablodadır.

İzin birleştirilirken de dikkat gerekir. Bir kayıttaki geri çekme, diğer kayıttaki daha eski bir onayın üzerine yazılmalıdır; aksi halde mükerreri birleştirirken birine tekrar mesaj göndermiş olursunuz. Bu, izni ayrı bir olay defteri olarak tutmanın bir başka nedenidir.

Ne ölçülür?

Panoda dört sayıya bakıyorum. Otomatik bağlanan başvuruların oranı, inceleme kuyruğunun medyan bekleme süresi, incelemede "yeni kişidir" denilen kayıtların oranı ve geri alınan bağlama sayısı. İlki yüzde yüze yaklaşırsa kurallar çok agresiftir. İkincisi saatleri aşarsa lansman gününde kuyruk satışın önüne geçer. Üçüncüsü çok yüksekse blocking key fazla geniş tutulmuş demektir. Dördüncüsü sıfırdan büyükse, hangi kuralın yanlış pozitif ürettiğini person_link_event üzerinden geriye doğru okuyabilirsiniz.

Sahte bir doğruluk yüzdesi uydurmanın alemi yok; bu sayılar sizin verinizde, sizin kurallarınızla anlam kazanır.

Gayrimenkulde sık gördüğüm tuzaklar

İlan portallarından gelen bildirim e-postalarında telefon bazen imzada, bazen konu satırında, bazen de farklı bir biçimde durur. Ayrıştırıcının ürettiği ham metni doğrudan eşleştirmek yerine önce normalizasyondan geçirin; aksi halde aynı kişi her portal için yeni kayıt olur.

İkinci tuzak, "mükerrer = değersiz" varsayımıdır. Aynı kişinin üç gün içinde ikinci kez form doldurması genelde çöp değil, ısınma sinyalidir. Lead olayını silmek bu sinyali yok eder. Kişi aynı kalır, olay ayrıca durur, skorlama ve danışman notu bu ikinci olayı görür.

Üçüncü tuzak, test ve sahte kayıtlardır. 555 ile başlayan numaralar, test@ e-postaları ve kendi çalışanlarınızın tekrarlayan başvuruları eşleştirme istatistiklerini bozar. Bunları deduplication'dan önce ayrı bir doğrulama katmanında ayıklamak, hem kuyruğu hem de kuralların kalibrasyonunu temiz tutar.

Sık sorulan sorular

Yalnızca telefon eşleştirsem olmaz mı?
Küçük bir ofiste ve tek kanallı bir akışta bir süre idare eder. Kanal sayısı artınca biçim farkları, paylaşılan hatlar ve ikinci numaralar boşluk bırakır. Telefonu en güçlü anahtar olarak tutun, ama tek anahtar yapmayın.

Olası eşleşmeyi otomatik birleştirmesem satış gecikir mi?
Gecikme inceleme kuyruğunun tasarımına bağlıdır. Kuyruğu birinin hayır demesini bekleyen bir beklemeye dönüştürmeyin: süre dolunca geçici kişi üzerinden ilk temas kurulsun, bayrak kalsın, sonra insan karar versin. İlk temasın kaçmaması ile yanlış birleştirmenin olmaması aynı anda kurgulanabilir.

İki kişi birleştikten sonra sohbet geçmişi ne olur?
Kişi grafı doğru kurulmuşsa sohbet person_id üzerinden okunur, lead olayları yerinde kalır. Yanlış birleştirmede unlink sohbeti de ayırmalıdır; bu yüzden mesajları kişiye değil, mümkünse lead olayı veya konuşma oturumuna bağlamak daha güvenlidir.

Hacim küçükseniz blocking key gerekir mi?
İlk yüz kayıtta fark etmez. İlk lansmanda binlerce form aynı güne yığılınca fark eder. Blocking key'i baştan koymak ucuzdur, sonradan tam taramayı temizlemek pahalıdır.

Yapay zekâ eşleştirmeyi devralabilir mi?
Adayları sıralayabilir, zayıf sinyalleri gerekçesiyle birlikte incelemeye bırakabilir. Otomatik auto_link kararını kural tablosuna bırakın. Model bir gün değişir, kural tablosu ve olay defteri kalır; denetimde ikincisini göstermek daha kolaydır.

Koray Yalçın — lead yönetimi, CRM mimarisi, dijital pazarlama ve PropTech üzerine çalışıyor.

CRM'de izin yönetimi tasarlamak: Değişmez rıza defteri, kanal ve amaç ayrımı, gönderim anında kontrol ve geri çekme

Koray Yalçın — Wed, 04 Nov 2026 08:17:59 +0000

Bir gayrimenkul projesinin lansman haftasında pazarlama ekibi yeni bir SMS kampanyası hazırlıyor. Liste CRM'den çekiliyor, filtre "izinli = evet" olarak ayarlanıyor ve gönderim başlıyor. İki gün sonra bir müşteri adayı şikâyet ediyor: üç hafta önce "artık mesaj istemiyorum" diye yanıt vermiş, çağrı merkezi temsilcisi de bunu nota yazmış. Ama "izinli" alanı hiç değişmemiş, çünkü o alanı yalnız web formu dolduruyordu. Ben Koray Yalçın olarak lead yönetimi ve CRM kurulumlarında bu tabloyu defalarca gördüm: izin, bir onay kutusunun sonucu olarak tek bir boolean alanda tutulur ve sistemin geri kalanı o alanın doğru olduğunu varsayar.

İzin yönetimi (consent management), bir kişinin hangi kanal üzerinden, hangi amaçla, ne zaman ve hangi metni görerek izin verdiğini ya da geri çektiğini kayıt altına alan ve bu kaydı her gönderimde uygulayan yapıdır. Bu yazıda kavramı bir geliştiricinin gözünden ele alıyorum: izni neden bir alan değil bir olay dizisi olarak tutmalıyız, kanal ve amaç ayrımını şemaya nasıl yansıtırız, kontrolü neden gönderimin son anında yaparız ve "beni listeden çıkarın" talebi tüm sistemlere nasıl yayılır.

Bir not: Bu yazı teknik bir tasarım yazısıdır, hukuki görüş değildir. KVKK, Elektronik Ticaret Kanunu ve İleti Yönetim Sistemi (İYS) yükümlülüklerinin sizin işinize nasıl uygulandığını bir hukukçuyla netleştirin; aşağıdaki yapı o kararları güvenle uygulayabileceğiniz bir altyapı sunar.

İzin neden bir boolean alan olamaz?

marketing_opt_in = true alanı üç soruyu cevapsız bırakır. Birincisi, hangi kanal için? E-posta bülteni almak isteyen biri telefonla aranmak istemeyebilir. İkincisi, hangi amaç için? Satın aldığı daireyle ilgili teslim bilgilendirmesi ile yeni bir projenin kampanyası aynı şey değildir. Üçüncüsü, nasıl kanıtlanır? Bir şikâyet geldiğinde "evet, izin vardı" demek yetmez; ne zaman, hangi formda, hangi metin gösterilerek alındığını gösterebilmeniz gerekir.

Bir de zaman boyutu var. İzin verilir, geri çekilir, yeniden verilir. Tek alanlı yapıda her değişiklik bir öncekini siler. Geçen ay bu kişiye gönderilen mesajın o tarihte izinli olup olmadığını sormak imkânsız hale gelir. Benim önerim şudur: izni bir olay defteri olarak tut, güncel durumu bu defterden türet.

Değişmez rıza defteri

Defterin her satırı tek bir olaydır: verildi, geri çekildi ya da doğrulandı. Satırlar güncellenmez, silinmez; yalnız eklenir.

CREATE TYPE consent_channel AS ENUM ('email', 'sms', 'call', 'whatsapp');
CREATE TYPE consent_action  AS ENUM ('granted', 'withdrawn');

CREATE TABLE consent_event (
  id             bigserial PRIMARY KEY,
  contact_id     bigint NOT NULL REFERENCES contact(id),
  channel        consent_channel NOT NULL,
  purpose        text NOT NULL,          -- 'marketing', 'project_updates', 'surveys'
  action         consent_action NOT NULL,
  occurred_at    timestamptz NOT NULL,   -- olayın gerçekte olduğu an
  recorded_at    timestamptz NOT NULL DEFAULT now(),
  source         text NOT NULL,          -- 'web_form', 'call_center', 'sms_reply', 'iys_sync'
  notice_version text,                   -- gösterilen metnin sürüm anahtarı
  evidence       jsonb NOT NULL DEFAULT '{}'::jsonb,
  actor_id       bigint,                 -- kaydı giren kullanıcı, otomatikse NULL
  idempotency_key text UNIQUE
);

CREATE INDEX consent_event_lookup
  ON consent_event (contact_id, channel, purpose, occurred_at DESC);

REVOKE UPDATE, DELETE ON consent_event FROM app_role;

Birkaç ayrıntı önemli. occurred_at ile recorded_at ayrıdır, çünkü çağrı merkezinden gelen bir geri çekme talebi sisteme birkaç saat sonra girilebilir; hangi olayın önce geçerli olduğuna gerçek zamanla karar verilir. idempotency_key aynı form gönderiminin ya da aynı İYS kaydının iki kez işlenmesini engeller. REVOKE satırı uygulama kullanıcısının bu tabloyu değiştirmesini veritabanı düzeyinde yasaklar; yanlışlıkla yazılmış bir UPDATE sorgusu sessizce geçmez, hata verir.

Kanıtı neyle saklarız?

evidence alanı, izin alınan anın fotoğrafıdır. Web formu için tipik içerik şöyledir:

{
  "form_id": "proje-a-lansman-formu",
  "page_url": "https://ornek-proje.com/basvuru",
  "notice_version": "etk-2026-09",
  "notice_sha256": "9f2c...e1",
  "checkbox_label": "Kampanya ve duyurular için SMS almak istiyorum.",
  "prechecked": false,
  "ip": "203.0.113.24",
  "user_agent": "Mozilla/5.0 ..."
}

notice_version ve notice_sha256 metnin kendisini değil, metnin hangi sürümünün gösterildiğini kaydeder. Metinlerin kendisi ayrı bir consent_notice tablosunda sürümlü olarak durur. Böylece pazarlama ekibi onay kutusu yazısını değiştirdiğinde eski kayıtlar bozulmaz; her olay kendi metnine bağlı kalır. prechecked: false küçük görünür ama önemlidir: önceden işaretlenmiş kutuyla alınmış bir onayın geçerliliği tartışmalıdır ve bunu sonradan kanıtlamak için o anda kaydetmek gerekir.

IP ve tarayıcı bilgisi de kişisel veridir. Bunları saklama sürenizi veri saklama politikanızla uyumlu tutun ve bu alanları önceki yazımda anlattığım maskeleme kurallarına dahil edin; kanıt kaydı herkesin görebileceği bir ekran olmamalı.

Kanal ve amaç ayrımı

Kanal (e-posta, SMS, arama, WhatsApp) ile amaç (pazarlama, proje bilgilendirmesi, anket) iki ayrı eksendir ve izin bu ikisinin kesişiminde verilir. Gayrimenkul tarafında en sık karışan ayrım şudur: satın alma süreci devam eden bir müşteriye ödeme hatırlatması ya da teslim tarihi bilgisi göndermek ile ona yeni bir projenin kampanyasını göndermek farklı hukuki dayanaklara ve farklı izin ihtiyacına sahip olabilir. Bu ayrımı şemada açıkça tutmazsanız, "işlemsel" etiketiyle kampanya gönderilmesi kaçınılmaz olur.

Bunu kod düzeyinde zorlamanın yolu, her mesaj şablonunun bir amaca bağlı olmasıdır:

CREATE TABLE message_template (
  id       bigserial PRIMARY KEY,
  name     text NOT NULL,
  channel  consent_channel NOT NULL,
  purpose  text NOT NULL REFERENCES consent_purpose(key),
  requires_consent boolean NOT NULL DEFAULT true
);

requires_consent = false olan amaçların listesi kısa olmalı ve değiştirilmesi bir kod incelemesi ya da yönetici onayı gerektirmelidir. Kampanya aracında kullanıcıya serbest metin alanı verip amacı seçtirmemek, en sık gördüğüm açıktır.

Güncel durumu defterden türetmek

Her gönderimde tüm defteri taramak pahalıdır. Güncel durumu ayrı bir tabloda tutarız, ama bu tablo yalnız defterden beslenir ve istenirse baştan yeniden hesaplanabilir.

CREATE TABLE consent_state (
  contact_id   bigint NOT NULL,
  channel      consent_channel NOT NULL,
  purpose      text NOT NULL,
  status       consent_action NOT NULL,
  effective_at timestamptz NOT NULL,
  last_event_id bigint NOT NULL,
  PRIMARY KEY (contact_id, channel, purpose)
);

-- Olay eklendikten sonra aynı transaction içinde:
INSERT INTO consent_state AS s
  (contact_id, channel, purpose, status, effective_at, last_event_id)
VALUES ($1, $2, $3, $4, $5, $6)
ON CONFLICT (contact_id, channel, purpose) DO UPDATE
SET status = EXCLUDED.status,
    effective_at = EXCLUDED.effective_at,
    last_event_id = EXCLUDED.last_event_id
WHERE s.effective_at <= EXCLUDED.effective_at;

WHERE koşulu geç gelen eski bir olayın yeni durumu ezmesini önler. Saat dilimi ve sıra sorunlarında bir kural daha koyuyorum: aynı ana denk gelen bir "verildi" ile bir "geri çekildi" olayı varsa geri çekme kazanır. Belirsizlikte kısıtlayıcı taraf seçilir.

Haftalık bir mutabakat işi, consent_state tablosunu defterden sıfırdan hesaplayıp farkları raporlar. Fark çıkıyorsa bir yerde defteri atlayan bir yazma yolu vardır ve o yol bulunmalıdır.

Kontrol gönderimin son anında yapılır

Kampanya listesini oluştururken izin filtrelemek gereklidir ama yeterli değildir. Liste pazartesi hazırlanıp çarşamba gönderiliyorsa aradaki iki günde gelen geri çekmeler kaçar. Bu yüzden izin kontrolünü mesajı sağlayıcıya teslim etmeden hemen önce, tek bir fonksiyonda yaparım:

class ConsentDenied(Exception):
    pass

def assert_can_send(db, contact_id: int, template) -> None:
    if not template.requires_consent:
        return
    row = db.fetchone(
        """
        SELECT status FROM consent_state
        WHERE contact_id = %s AND channel = %s AND purpose = %s
        """,
        (contact_id, template.channel, template.purpose),
    )
    if row is None or row["status"] != "granted":
        raise ConsentDenied(f"{contact_id}/{template.channel}/{template.purpose}")

def deliver(db, outbox_item):
    template = load_template(db, outbox_item.template_id)
    try:
        assert_can_send(db, outbox_item.contact_id, template)
    except ConsentDenied:
        mark_skipped(db, outbox_item.id, reason="no_consent")
        return
    provider_send(outbox_item)

Varsayılan "kayıt yoksa gönderme"dir. Kayıt yoksa izin de yoktur. Atlanan gönderimler sessizce kaybolmaz, no_consent nedeniyle işaretlenir; böylece kampanya raporunda "1.200 kişilik listenin 140'ı gönderim anında izin dışı kaldı" gibi bir satır görürsünüz (sayılar örnek olarak verilmiştir). Bu satır, izin süreçlerinin işlediğinin en iyi kanıtıdır.

Çağrı merkezi için de aynı fonksiyon kullanılır. Otomatik arayıcı (dialer) bir numarayı kuyruğa almadan önce call/marketing iznini kontrol eder; manuel aramada ise temsilcinin ekranında arama düğmesi izin yoksa pasif görünür ve neden pasif olduğu yazar.

Geri çekmenin her yere yayılması

Geri çekme talebi birçok yoldan gelir: e-postadaki abonelikten çık bağlantısı, SMS'e verilen "RET" yanıtı, WhatsApp'ta "mesaj istemiyorum" yazısı, çağrı merkezinde sözlü talep, İYS üzerinden yapılan ret. Hepsinin ortak noktası, sonunda aynı deftere bir withdrawn olayı olarak düşmesidir.

def record_withdrawal(db, contact_id, channel, purpose, source, occurred_at,
                      evidence, actor_id=None, idem=None):
    with db.transaction():
        event_id = insert_consent_event(
            db, contact_id, channel, purpose, "withdrawn",
            occurred_at, source, evidence, actor_id, idem,
        )
        upsert_consent_state(db, contact_id, channel, purpose,
                             "withdrawn", occurred_at, event_id)
        enqueue_outbox(db, "consent.withdrawn", {
            "contact_id": contact_id, "channel": channel,
            "purpose": purpose, "event_id": event_id,
        })

Outbox'a düşen olay, dış sistemlere yayılır: e-posta pazarlama aracındaki abonelik durumu, reklam platformlarına yüklenen özel kitleler, varsa İYS'ye bildirim ve iş ortaklarının listeleri. Reklam kitleleri en sık unutulan noktadır; izni geri çekilen bir kişinin telefon numarasının hash'li hali hâlâ bir yeniden hedefleme kitlesinde duruyor olabilir.

Çağrı merkezindeki sözlü talep için temsilcinin serbest nota yazmasına izin vermiyorum. Görüşme sonucu kodlarına "pazarlama aramasını reddetti" gibi bir sonuç eklenir ve bu sonuç seçildiğinde record_withdrawal doğrudan çağrılır. Notlar okunmaz; yapılandırılmış alanlar işlenir.

İleti Yönetim Sistemi ile eşitleme

Türkiye'de ticari elektronik ileti izinleri İYS üzerinden de yönetilir ve alıcı iznini İYS'den de geri çekebilir. Bu, CRM'in tek doğruluk kaynağı olmadığı anlamına gelir. Benim tasarımımda İYS de bir olay kaynağıdır: oradan gelen değişiklikler source = 'iys_sync' ile deftere eklenir, kendi occurred_at değeriyle sıralanır ve aynı kurala tabi olur.

Eşitlemede dikkat ettiğim iki konu var. Birincisi, CRM'de verilen bir iznin İYS'ye bildirilmesi başarısız olursa, bu durum bir hata kuyruğunda görünür olmalı ve izin "beklemede" sayılmalıdır. İkincisi, İYS'den gelen bir ret, CRM'deki daha eski bir onayı her zaman ezer; ama CRM'deki daha yeni bir onay İYS'ye bildirilmeden gönderimde kullanılmamalıdır. Bu ikinci kural için consent_state tablosuna bir synced_to_iys alanı eklemek ve gönderim kontrolünde bunu da sorgulamak yeterlidir.

Yeniden izin isteme ve form tasarımı

Geliştirici tarafında form da bu yapının parçasıdır. Her kanal ve amaç için ayrı, önceden işaretlenmemiş onay kutusu, aydınlatma metnine bağlantı ve gönderimde notice_version değerinin sunucuya iletilmesi gerekir. İstemcinin gönderdiği sürüm anahtarı sunucuda doğrulanır; tanınmayan bir sürüm gelirse olay kaydedilmez, form hatası döner.

Bir projeden diğerine geçişte de dikkat gerekir. A projesi için izin veren bir kişiye B projesinin kampanyasını göndermek, amaç tanımınız "firmanın tüm projeleri" değilse sorunludur. Bu yüzden purpose anahtarlarını en baştan doğru kapsamla tanımlamak, sonradan veri taşımaktan çok daha ucuzdur.

İzleme ve denetim

Panoda üç sayıya bakıyorum. Gönderim anında izin nedeniyle atlanan mesaj oranı, geri çekme olayının deftere düşmesinden dış sistemlere yayılmasına kadar geçen süre ve haftalık mutabakatta çıkan fark sayısı. İlki sıfır olursa şüphelenirim, çünkü gerçek bir listede her zaman birkaç kişi arada fikrini değiştirir. İkincisi saatlerle ölçülüyorsa kuyrukta bir tıkanıklık vardır. Üçüncüsü sıfırdan büyükse defteri atlayan bir kod yolu vardır.

Denetim için de defter yeterlidir: "Bu kişiye 12 Ekim'de gönderilen SMS için o anda geçerli izin var mıydı?" sorusu, occurred_at <= '2026-10-12' koşuluyla en son olayı bulan tek bir sorguyla yanıtlanır.

Sık sorulan sorular

Eski sistemden gelen, kanıtı olmayan izinleri ne yapmalıyım?
Bunları deftere source = 'legacy_import' ve boş kanıtla aktarın, ama gönderim kontrolünde ayrı bir sınıf olarak ele alın. Hangi gönderimlerde kullanılabileceğine hukuk ekibiyle birlikte karar verin; çoğu durumda yeniden izin isteme kampanyası en güvenli yoldur.

Geri çekme olayını silmek gerekirse ne olur?
Kişinin verilerinin silinmesi talebinde bile "bu kişiye mesaj gönderme" bilgisini tutmak gerekebilir; aksi halde kişi bir sonraki veri aktarımında yeniden listeye girer. Bunun için kimliği hash'lenmiş bir bastırma listesi (suppression list) tutulur. Hangi verinin ne kadar saklanacağına hukukçunuzla karar verin.

İşlemsel mesajlar için de defter gerekir mi?
İzin gerektirmeyen amaçlar için bile gönderim kaydı ve amacı tutulmalıdır. Bir mesajın gerçekten işlemsel olduğunu sonradan gösterebilmek, şablonun hangi amaca bağlı olduğunu kaydetmekle mümkündür.

Küçük bir emlak ofisi için bu yapı fazla değil mi?
Defter tablosu, durum tablosu ve tek bir assert_can_send fonksiyonu birkaç günlük iştir ve en büyük riski kapatır. İYS eşitlemesi, reklam kitlesi temizliği ve mutabakat işi ekip ve hacim büyüdükçe eklenebilir. Önemli olan, ilk günden izni bir alan yerine olay olarak tutmaktır.

WhatsApp için ayrı bir izin gerekir mi?
Kanal olarak ayrı tutmanızı öneririm. WhatsApp Business tarafında platformun kendi kuralları da vardır; bir kişinin SMS iznini WhatsApp için geçerli saymak hem platform hem mevzuat açısından risklidir.

Koray Yalçın — lead yönetimi, CRM mimarisi, dijital pazarlama ve PropTech üzerine çalışıyor.

CRM'de veri maskeleme tasarlamak: Rol bazlı görünüm, sunucu tarafı maskeleme, açma kaydı ve test ortamı için tokenizasyon

Koray Yalçın — Tue, 03 Nov 2026 16:22:58 +0000

Bir gayrimenkul satış ekibinde CRM ekranını açan herkes aynı şeyi görmemeli. Çağrı merkezindeki yeni başlayan bir temsilci, lead'i aramak için telefon numarasına ihtiyaç duyar ama o numarayı listede toplu halde görmesine gerek yoktur. Pazarlama analisti kampanya performansına bakarken kimin telefonu olduğunu hiç bilmemelidir. Bir entegrasyon ortağının destek ekibi hata ayıklarken gerçek e-posta adreslerini görmemelidir. Ben Koray Yalçın olarak lead yönetimi ve CRM kurulumlarında bu ayrımı en sık atlanan güvenlik katmanı olarak görüyorum: herkes "yetki" konuşur, ama yetkili olan kişinin bile neyi, ne kadarını ve ne zaman göreceği konuşulmaz.

Veri maskeleme, kişisel verinin yetkisiz ya da gereğinden fazla göz önüne çıkmasını engellemek için değerin bir kısmının gizlenerek gösterilmesidir. En bilinen örneği 0532***1234 biçiminde gösterilen telefon numarasıdır. Bu yazıda kavramı sözlük tanımından çıkarıp bir geliştiricinin gözünden ele alıyorum: maskelemeyi nerede yapacağız, kurallarını nasıl veri olarak tutacağız, "numarayı göster" düğmesinin arkasında ne olmalı, dışa aktarma ve loglar nasıl korunacak, test ortamına gerçek veri nasıl sızmayacak.

Maskeleme, şifreleme ve yetkilendirme aynı şey değil

Bu üç kavram sık karıştırılır, oysa farklı soruları yanıtlarlar.

Yetkilendirme "bu kullanıcı bu kayda erişebilir mi?" sorusunu yanıtlar. Erişemiyorsa kayıt hiç gelmez.
Şifreleme "veri diskte ya da ağda çalınırsa okunabilir mi?" sorusunu yanıtlar. Uygulama içinde yetkili kullanıcıya çözülmüş haliyle gelir.
Maskeleme "erişimi olan kullanıcı alanın tamamını görmeli mi?" sorusunu yanıtlar. Kayda erişim vardır, ama belirli alanlar kısmen gizlenir.

Yani maskeleme, yetkilendirmenin alan düzeyindeki ince ayarıdır. Bir temsilci kendisine atanmış lead'e erişebilir (yetkilendirme), telefon sütunu veritabanında şifreli durabilir (şifreleme), ama liste ekranında numara maskeli görünür ve yalnız arama anında tam haliyle açılır (maskeleme). Üçü birbirinin yerine geçmez; birlikte çalışır.

Kural 1: Maskeleme sunucuda yapılır, arayüzde değil

En yaygın hata, tam veriyi API'den gönderip arayüzde CSS ya da JavaScript ile gizlemektir. Tarayıcının geliştirici araçlarını açan herkes ağ sekmesinde tam numarayı görür. Mobil uygulamada da aynı şey geçerlidir: yanıt gövdesi cihazda önbelleğe alınır.

Doğru yer, verinin sunucudan çıktığı son katmandır: serileştirme (serializer) ya da yanıt dönüştürücü. Böylece hangi uç noktadan gelirse gelsin aynı kural uygulanır. Kuralı her endpoint'e tek tek yazmak yerine tek bir fonksiyona bağlamak, yeni bir endpoint eklendiğinde maskelemenin unutulmasını engeller.

# Tek giriş noktası: her yanıt bu fonksiyondan geçer
def serialize_lead(lead: dict, viewer: Viewer, context: str) -> dict:
    out = {}
    for field, value in lead.items():
        rule = FIELD_RULES.get(field)
        if rule is None:
            out[field] = value          # kişisel veri olmayan alan
            continue
        level = resolve_level(rule, viewer, context, lead)
        out[field] = apply_mask(value, rule.kind, level)
    return out

Burada context parametresi önemlidir: aynı kullanıcı liste ekranında, kayıt detayında, dışa aktarmada ve raporda farklı görünürlük seviyesine sahip olabilir.

Kural 2: Kuralları kodda değil veride tut

Hangi alanın kimde nasıl görüneceği zamanla değişir. Yeni bir rol eklenir, bir alan kişisel veri olarak işaretlenir, hukuk ekibi e-postanın da maskelenmesini ister. Bunu her seferinde kod değişikliğiyle yapmak hem yavaştır hem de denetlenmesi zordur. Kuralları bir tabloda tutmak, kimin neyi ne zaman değiştirdiğini de kayıt altına almayı kolaylaştırır.

CREATE TABLE field_mask_rule (
  id           bigserial PRIMARY KEY,
  entity       text NOT NULL,          -- 'lead', 'contact', 'deal'
  field        text NOT NULL,          -- 'phone', 'email', 'national_id'
  mask_kind    text NOT NULL,          -- 'phone', 'email', 'full', 'none'
  role         text NOT NULL,          -- 'agent', 'analyst', 'manager', 'partner'
  context      text NOT NULL,          -- 'list', 'detail', 'export', 'report', 'log'
  level        text NOT NULL CHECK (level IN ('hidden','masked','revealable','clear')),
  updated_by   bigint NOT NULL,
  updated_at   timestamptz NOT NULL DEFAULT now(),
  UNIQUE (entity, field, role, context)
);

Dört seviye pratikte yeterli oluyor:

hidden: Alan yanıtta hiç yer almaz.
masked: Alan maskeli gelir, açılamaz.
revealable: Alan maskeli gelir, kullanıcı gerekçeyle açabilir; açma kaydedilir.
clear: Alan tam gelir.

Varsayılan değer her zaman en kısıtlayıcı olandır. Tabloda kuralı olmayan ama kişisel veri olarak işaretlenmiş bir alan hidden sayılmalıdır. Böylece yeni eklenen bir alan için kural yazmayı unutmak veri sızıntısına değil, eksik görünüme yol açar. Eksik görünüm şikayet getirir ve düzeltilir; sızıntı ise çoğu zaman fark edilmez.

Maskeleme biçimleri: ne kadarını göstermeli?

Maskelemenin amacı veriyi tamamen yok etmek değil, işi yapmaya yetecek kadarını bırakmaktır. Temsilci "bu, dün aradığım numara mı?" diye ayırt edebilmeli; analist aynı kişinin iki kez form doldurup doldurmadığını anlayabilmelidir.

import re

def mask_phone(v: str) -> str:
    digits = re.sub(r"\D", "", v or "")
    if len(digits) < 7:
        return "***"
    return f"{digits[:4]}***{digits[-4:]}" if len(digits) >= 10 else f"***{digits[-3:]}"

def mask_email(v: str) -> str:
    if not v or "@" not in v:
        return "***"
    local, domain = v.split("@", 1)
    head = local[:1]
    return f"{head}***@{domain}"

def apply_mask(value, kind, level):
    if level == "clear":
        return value
    if level == "hidden":
        return None
    if kind == "phone":
        return mask_phone(value)
    if kind == "email":
        return mask_email(value)
    return "***"

Birkaç pratik not:

Telefonda ülke kodu ve operatör önekini bırakmak çoğu zaman yeterli bağlam verir; son dört hane ayırt etmeyi sağlar. Kısa numaralarda daha az hane gösterin, aksi halde maskeleme anlamsızlaşır.
E-postada alan adını açık bırakmak, kurumsal lead'leri ayırt etmeye yarar. Ama küçük bir şirketin alan adı tek başına kişiyi belli edebilir; hassas projelerde alan adını da maskeleyin.
Kimlik numarası, pasaport numarası gibi alanlar için kısmi gösterim yerine full maskeyi ve revealable seviyesini tercih edin.

"Numarayı göster" düğmesi: açma kaydı ve gerekçe

revealable seviyesindeki bir alanın açılması, ayrı bir uç noktaya yapılan bilinçli bir istektir. Liste yanıtı hiçbir zaman tam değeri taşımaz; kullanıcı düğmeye bastığında tek bir kaydın tek bir alanı için istek gider, sunucu yetkiyi yeniden kontrol eder, açma olayını kaydeder ve değeri döner.

CREATE TABLE pii_reveal_log (
  id          bigserial PRIMARY KEY,
  viewer_id   bigint NOT NULL,
  entity      text NOT NULL,
  entity_id   bigint NOT NULL,
  field       text NOT NULL,
  reason      text NOT NULL,      -- 'call', 'whatsapp', 'appointment', 'other'
  note        text,
  ip          inet,
  revealed_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ON pii_reveal_log (viewer_id, revealed_at DESC);

Gerekçe alanı ilk başta bürokrasi gibi görünür, ama iki işe yarar. Birincisi, kullanıcıyı bir an durdurur; "neden bu numaraya ihtiyacım var?" sorusunu sordurur. İkincisi, denetimde anlamlı bir iz bırakır. Arama gerekçesiyle açılan bir numaranın ardından gerçekten bir arama kaydı (call log) oluşmuş mu, bunu karşılaştırmak mümkün hale gelir.

Daha da iyisi, birçok durumda numarayı hiç açmadan işi yaptırmaktır. Temsilci "Ara" düğmesine bastığında santral ya da tıkla-ara entegrasyonu numarayı sunucu tarafında çevirir; temsilci numarayı hiç görmez. WhatsApp mesajı da aynı şekilde şablon üzerinden sunucudan gönderilebilir. Benim kurduğum lead yönetimi akışlarında hedef, temsilcinin günlük işinin büyük kısmını tam numarayı görmeden tamamlayabilmesidir. Açma düğmesi istisna için kalmalıdır.

Anormal açma davranışını yakalamak

Açma kaydı tutulduktan sonra basit kurallarla ciddi riskleri yakalamak mümkündür:

-- Son bir saatte olağan dışı sayıda açma yapan kullanıcılar
SELECT viewer_id, count(*) AS reveals
FROM pii_reveal_log
WHERE revealed_at > now() - interval '1 hour'
GROUP BY viewer_id
HAVING count(*) > 40;

Eşik değer ekibin gerçek iş yüküne göre belirlenmelidir; buradaki 40 yalnızca örnek bir değerdir. Eşiği aşan kullanıcı için açma uç noktası geçici olarak yavaşlatılabilir, yöneticiye bildirim gidebilir. İşten ayrılmadan önceki günlerde toplu numara açma, bu tablonun en sık ortaya çıkardığı örüntülerden biridir.

Dışa aktarma: en büyük sızıntı kapısı

Ekranda maskeleme ne kadar iyi olursa olsun, "Excel'e aktar" düğmesi tüm emeği boşa çıkarabilir. Dışa aktarma ayrı bir context olarak ele alınmalı ve kuralları ayrıca tanımlanmalıdır. Benim önerim:

Dışa aktarmada revealable seviyesi yoktur; ya masked ya clear. Toplu açma, tek tek açmanın kaydını anlamsız kılar.
clear dışa aktarma yalnız belirli rollere açıktır ve her dışa aktarma işi kimin, hangi filtreyle, kaç satır aldığıyla birlikte kaydedilir.
Dosya kalıcı bir bağlantıyla değil, kısa süreli imzalı bir bağlantıyla indirilir.
Analiz amaçlı dışa aktarmalarda telefon ve e-posta yerine sabit bir takma kimlik (pseudonym) verilir. Analist aynı kişiyi tekrar eden satırlarda tanıyabilir ama kim olduğunu bilmez.

import hmac, hashlib

def pseudonym(value: str, secret: bytes, scope: str) -> str:
    norm = re.sub(r"\D", "", value) if scope == "phone" else value.strip().lower()
    mac = hmac.new(secret, f"{scope}:{norm}".encode(), hashlib.sha256)
    return mac.hexdigest()[:16]

Sırrı (secret) dışa aktarma işine özel ya da döneme özel tutmak, iki farklı dosyanın birleştirilerek kişilerin eşleştirilmesini zorlaştırır.

Loglar ve hata izleme araçları

Uygulama logları, hata izleme servisleri ve kuyruk mesajları kişisel verinin en sessiz biriktiği yerlerdir. Bir hata yığını (stack trace) tüm istek gövdesini içerebilir; bir webhook hatası gelen lead'in telefonunu loglara yazabilir. Burada context = 'log' için kural genellikle masked ya da hidden olmalıdır ve log kütüphanesine bir filtre eklenmelidir:

import logging

SENSITIVE_KEYS = {"phone", "email", "national_id", "passport_no"}

class PiiFilter(logging.Filter):
    def filter(self, record):
        if isinstance(record.args, dict):
            record.args = {k: ("***" if k in SENSITIVE_KEYS else v)
                           for k, v in record.args.items()}
        return True

Anahtar adına göre filtrelemek tek başına yetmez; serbest metin içinde geçen telefon ve e-posta kalıplarını düzenli ifadeyle temizleyen ikinci bir katman da eklemek gerekir. Hata izleme servislerinin çoğu gönderim öncesi veri temizleme kancası sunar; bu kancayı aynı kural kümesine bağlamak tutarlılığı korur.

Test ve geliştirme ortamı: gerçek veri olmadan gerçekçi veri

Üretim veritabanının bir kopyasını test ortamına almak hızlıdır ama riskli. Test ortamları genellikle daha zayıf korunur, daha çok kişi erişir ve üçüncü taraf araçlara bağlanır. Burada ekranda maskeleme yeterli değildir; verinin kendisi dönüştürülmelidir. Buna statik maskeleme ya da tokenizasyon denir.

İyi bir test verisi dönüşümünün üç özelliği olmalı:

Tutarlılık: Aynı gerçek telefon her tabloda aynı sahte telefona dönüşmeli; böylece tekilleştirme ve eşleştirme mantığı testte de çalışır.
Biçim koruma: Sahte telefon geçerli bir telefon biçiminde olmalı, sahte e-posta geçerli bir e-posta olmalı; doğrulama kuralları kırılmamalı.
Geri döndürülemezlik: Test ortamına erişen biri sahte değerden gerçeğine ulaşamamalı.

def fake_phone(real: str, secret: bytes) -> str:
    h = int(pseudonym(real, secret, "phone"), 16)
    return "0599" + str(h % 10_000_000).zfill(7)   # kullanılmayan bir önek seçin

def fake_email(real: str, secret: bytes) -> str:
    return f"user{pseudonym(real, secret, 'email')[:10]}@example.test"

Sahte numaralar için gerçek bir operatöre ait olmayan bir önek seçmek, testten yanlışlıkla gerçek bir kişiye SMS ya da arama gitmesini engeller. Aynı şekilde sahte e-postalar için example.test gibi teslim edilemeyen bir alan adı kullanılmalıdır. Dönüşüm sırrı test ortamında hiç bulunmamalıdır.

KVKK ve GDPR açısından nereye oturur?

Maskeleme, kişisel verinin işlenme amacıyla sınırlı ve ölçülü tutulması ilkesinin teknik karşılıklarından biridir. KVKK ve GDPR, kişisel verilere erişimin işin gerektirdiği ölçüyle sınırlanmasını ve uygun teknik tedbirlerin alınmasını bekler. Maskeleme tek başına uyumluluk sağlamaz; açık rıza, aydınlatma metni, saklama süresi ve silme süreçleri ayrıca kurulmalıdır. Ama bir veri sızıntısı soruşturmasında "liste ekranında numaralar maskeliydi, açmalar gerekçeyle kaydediliyordu, dışa aktarma rol bazlıydı" diyebilmek, alınan tedbirin somut kanıtıdır. Hukuki yorum için her zaman bir uzmana danışılmalıdır; burada anlattıklarım mühendislik pratiğidir.

Uygulamaya alırken kontrol listesi

Kişisel veri alanlarını bir kayıt defterinde işaretleyin; işaretli ama kuralı olmayan alan varsayılan olarak gizli olsun.
Maskelemeyi tek bir serileştirme katmanına bağlayın; arayüze tam veri göndermeyin.
Liste, detay, dışa aktarma, rapor ve log için ayrı bağlam kuralları tanımlayın.
Açma işlemini ayrı uç noktaya taşıyın; gerekçe ve kayıt zorunlu olsun.
Tıkla-ara ve şablon mesaj ile numarayı göstermeden iletişim kurulmasını sağlayın.
Açma kayıtlarında anormal hacmi izleyin.
Test ortamına yalnız dönüştürülmüş veri aktarın.
Kuralları her çeyrek rol değişiklikleriyle birlikte gözden geçirin.

SSS

Veri maskeleme ile anonimleştirme arasındaki fark nedir?
Maskeleme, yetkili bir kullanıcı için veriyi kısmen gizler; gerçek değer sistemde durur ve gerektiğinde açılabilir. Anonimleştirmede ise veri kişiyle bir daha ilişkilendirilemeyecek şekilde dönüştürülür. Test ortamı için yapılan geri döndürülemez dönüşüm anonimleştirmeye yakındır; ekran maskelemesi değildir.

Maskelemeyi veritabanı düzeyinde yapmak daha güvenli değil mi?
Bazı veritabanları dinamik maskeleme özelliği sunar ve ek bir savunma hattı olarak işe yarar. Ama bağlam (liste mi, dışa aktarma mı, log mu) bilgisi genellikle uygulama katmanındadır. Pratikte en sağlam yapı, uygulama katmanında bağlam duyarlı maskeleme ve veritabanında rol bazlı erişim kısıtlamasının birlikte kullanılmasıdır.

Temsilci numarayı görmeden nasıl arama yapar?
Tıkla-ara entegrasyonu ile CRM, numarayı sunucu tarafında santrale iletir; temsilcinin telefonu çalar ve görüşme bağlanır. Temsilci ekranda yalnız maskeli numarayı görür. WhatsApp ve SMS için de şablonlu gönderim aynı mantıkla çalışır.

Maskeli telefonla tekrar eden lead'ler nasıl tespit edilir?
Tekilleştirme mantığı sunucuda tam değer üzerinde çalışır; kullanıcıya yalnız sonuç gösterilir. Analiz tarafında ise sabit takma kimlik kullanılır; aynı kişi farklı satırlarda aynı kimlikle görünür.

Yönetici rolü her şeyi açık görmeli mi?
Hayır. Yönetici rolü genellikle rapor ve performans ekranlarında çalışır; orada tam numaraya ihtiyaç yoktur. Yöneticinin de revealable seviyesinde olması ve açmalarının kaydedilmesi, hem kötüye kullanımı önler hem de ekibe doğru örnek olur.

Küçük bir ekip için bu yapı fazla değil mi?
Dört kişilik bir ekipte bile liste ekranında maskeleme ve dışa aktarmanın kısıtlanması birkaç saatlik iştir ve en büyük riski kapatır. Açma kaydı, anormallik izleme ve test verisi dönüşümü ekip büyüdükçe eklenebilir. Önemli olan, varsayılanın en baştan kısıtlayıcı olmasıdır.

Koray Yalçın — lead yönetimi, CRM mimarisi, dijital pazarlama ve PropTech üzerine çalışıyor.

CRM ile dış sistemler arasında çift yönlü veri senkronizasyonu: Alan sahipliği, değişiklik imleci, döngü önleme ve çakışma çözümü

Koray Yalçın — Tue, 03 Nov 2026 08:26:48 +0000

Bir CRM'i muhasebe yazılımına, proje stok tablosuna ya da pazarlama aracına bağlarken ilk istek hep aynı cümleyle gelir: "İki taraf da birbirinin aynısı olsun." Kâğıt üzerinde basit görünür. Pratikte ise çift yönlü senkronizasyon, entegrasyon işlerinin en çok sessiz hata üreten parçasıdır. Ben, Koray Yalçın, gayrimenkul satış ekipleri için lead yönetimi ve CRM altyapısı kurarken bu hataların neredeyse hepsini bir kez yaşadım: birbirini sonsuza kadar güncelleyen iki sistem, gece toplu güncellemeden sonra kaybolan telefon numaraları, saat farkı yüzünden "eski" sayılıp ezilen yeni kayıtlar.

Bu yazıda tek yönlü "her gece dışa aktar" yaklaşımının ötesine geçip, iki sistemi güvenle eşitleyen bir senkronizasyon katmanını geliştirici gözüyle adım adım tasarlıyorum. Örnekler PostgreSQL ve TypeScript ile, ama fikirler hangi yığını kullanırsanız kullanın geçerli.

Önce soru: Gerçekten çift yönlü mü olmalı?

En ucuz senkronizasyon, hiç çift yönlü olmayanıdır. Her alan için tek bir "sahip" sistem belirleyebiliyorsanız, sorunun büyük kısmı ortadan kalkar. Bir konut projesi örneği düşünelim:

Lead'in adı, telefonu, kaynağı ve danışman ataması CRM'de doğar ve CRM'e aittir.
Ünitenin fiyatı ve durumu stok sisteminde doğar ve oraya aittir.
Fatura numarası ve tahsilat durumu muhasebe yazılımına aittir.

Bu durumda "çift yönlü" aslında "her alan tek yönlü, ama iki sistem de bazı alanların sahibi" demektir. Gerçek çakışma ancak iki sistemin de aynı alanı yazmasına izin verdiğinizde ortaya çıkar. O yüzden tasarıma kod yazarak değil, bir alan sahipliği tablosu çıkararak başlıyorum.

Alan sahipliğini veri olarak tutmak

Sahiplik kuralını koda gömmek yerine bir tabloda tutmak, ileride "bu alanı artık muhasebe yönetsin" dendiğinde dağıtım yapmadan değişiklik yapmanızı sağlar.

CREATE TABLE sync_field_policy (
  connector     text NOT NULL,          -- 'accounting', 'inventory' ...
  entity        text NOT NULL,          -- 'contact', 'deal', 'unit'
  field         text NOT NULL,
  owner         text NOT NULL CHECK (owner IN ('crm','remote','both')),
  conflict_rule text NOT NULL DEFAULT 'owner_wins'
    CHECK (conflict_rule IN ('owner_wins','latest_wins','manual')),
  PRIMARY KEY (connector, entity, field)
);

INSERT INTO sync_field_policy VALUES
 ('accounting','contact','full_name','crm','owner_wins'),
 ('accounting','contact','tax_number','remote','owner_wins'),
 ('accounting','contact','email','both','latest_wins'),
 ('accounting','contact','phone','both','manual');

both olarak işaretlenen her alan bir uyarı işaretidir. Benim kuralım şu: bir alan both ise, bunun neden gerekli olduğu tabloya yorum olarak yazılmadan canlıya çıkmaz. Telefon gibi kritik bir alanda manual seçmek, yanlış numaraya otomatik mesaj gitmesinden çok daha ucuzdur.

Kimlik eşleme: İki sistemin aynı kaydı bilmesi

Senkronizasyonun ikinci temeli, "CRM'deki 4812 numaralı kişi, muhasebedeki C-00931'dir" bilgisini güvenilir biçimde saklamaktır. Bu bilgiyi kayıtların kendisine bir external_id sütunu olarak eklemek ilk bakışta pratiktir, ama birden fazla bağlayıcı geldiğinde dağılır. Ayrı bir eşleme tablosu daha temizdir:

CREATE TABLE sync_link (
  connector     text NOT NULL,
  entity        text NOT NULL,
  local_id      bigint NOT NULL,
  remote_id     text NOT NULL,
  last_local_hash  text,   -- son gönderdiğimiz içeriğin özeti
  last_remote_hash text,   -- son aldığımız içeriğin özeti
  last_synced_at   timestamptz,
  PRIMARY KEY (connector, entity, local_id),
  UNIQUE (connector, entity, remote_id)
);

İki benzersizlik kısıtı birlikte bire bir eşlemeyi garanti eder. Bir kayıt iki kez oluşturulmaya çalışılırsa veritabanı reddeder; böylece "aynı müşteri muhasebede iki kez açıldı" hatası uygulama mantığına güvenmeden engellenir. Hash alanlarını birazdan döngü önlemede kullanacağız.

Değişiklikleri yakalamak: Zaman damgası değil, imleç

En yaygın hata, "son senkrondan sonra updated_at değeri büyük olan kayıtları al" sorgusudur. İki sorunu var. Birincisi, aynı milisaniyede güncellenen kayıtlar sınırda kaybolabilir. İkincisi, uzun süren bir işlem eski bir zaman damgasıyla commit edildiğinde, siz o anı çoktan geçmiş olursunuz ve kayıt hiç görülmez.

CRM tarafında daha sağlam yol, her değişikliğe artan bir sıra numarası veren bir değişiklik günlüğüdür (outbox). Kayıt güncellenirken aynı işlem içinde bu tabloya da bir satır yazılır:

CREATE TABLE change_log (
  seq        bigserial PRIMARY KEY,
  entity     text NOT NULL,
  local_id   bigint NOT NULL,
  changed_fields text[] NOT NULL,
  origin     text NOT NULL,       -- 'user', 'workflow', 'sync:accounting'
  created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE sync_cursor (
  connector text PRIMARY KEY,
  last_seq  bigint NOT NULL DEFAULT 0
);

Gönderici işçi seq > last_seq olan satırları sırayla okur, işler ve imleci yalnızca başarılı işlemden sonra ilerletir. bigserial değerlerinin commit sırasına göre değil tahsis sırasına göre arttığını unutmayın; çok yoğun sistemlerde kısa bir güvenlik gecikmesi bırakmak (örneğin son 5 saniyenin satırlarını bir sonraki tura bırakmak) boşluk kaçırma riskini azaltır.

Uzak sistem tarafında ise elinizde ne varsa onu kullanırsınız: webhook, "şu tarihten beri değişenler" uç noktası ya da en kötü ihtimalle tam liste. Uzak sistem yalnızca zaman damgası veriyorsa, imleci "son görülen zaman eksi birkaç dakika" olarak tutup örtüşen kayıtları hash karşılaştırmasıyla elemek pratik bir çözümdür.

Döngüyü kırmak: Kendi yankınızı tanıyın

Çift yönlü senkronizasyonun klasik kâbusu şudur: CRM bir alanı günceller, değişikliği muhasebeye gönderir; muhasebe bunu "yeni değişiklik" olarak webhook ile geri yollar; CRM bunu tekrar kaydeder ve yeni bir change_log satırı oluşur. Döngü başlar.

Bunu kırmanın iki katmanı var. İlki köken etiketidir: senkron işçisi CRM'e yazarken origin = 'sync:accounting' kullanır ve muhasebeye giden işçi bu kökenli satırları atlar. İkincisi içerik özetidir: gönderdiğimiz alanların normalize edilmiş bir özetini saklarız; uzaktan gelen değişikliğin özeti bizim gönderdiğimizle aynıysa, bu bir yankıdır.

import { createHash } from "node:crypto";

function fingerprint(fields: Record<string, unknown>): string {
  const keys = Object.keys(fields).sort();
  const canonical = keys.map((k) => [k, normalize(fields[k])]);
  return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
}

function normalize(v: unknown): unknown {
  if (typeof v === "string") return v.trim().normalize("NFC");
  if (v === undefined) return null;
  return v;
}

async function onRemoteChange(link: SyncLink, remote: Record<string, unknown>) {
  const fp = fingerprint(pickSyncedFields(remote));
  if (fp === link.last_local_hash || fp === link.last_remote_hash) {
    return; // kendi yazdığımızın yankısı ya da zaten gördüğümüz içerik
  }
  await applyRemote(link, remote, fp);
}

Türkçe veride normalize("NFC") küçük bir ayrıntı gibi görünse de önemlidir: bazı sistemler "ş" harfini birleşik karakter olarak, bazıları ayrık olarak gönderir. Normalize etmezseniz aynı isim iki farklı özet üretir ve döngü önleme sessizce çalışmaz.

Çakışma çözümü: "Son yazan kazanır" neden yetmez

İki taraf aynı alanı iki senkron turu arasında değiştirdiğinde çakışma vardır. "Son yazan kazanır" kuralı basittir ama iki varsayıma dayanır: iki sistemin saatleri uyumludur ve zaman damgaları gerçekten değişikliğin zamanını gösterir. Muhasebe yazılımlarının çoğu toplu içe aktarmalarda tüm kayıtların modified alanını aynı ana çeker; bu durumda yüzlerce kayıt, aslında eski olduğu halde "en yeni" görünür.

Daha güvenilir yöntem üç yollu karşılaştırmadır. Son başarılı senkronda iki tarafın üzerinde anlaştığı değeri (taban) saklarsınız ve her alanda şunu sorarsınız: hangi taraf tabandan uzaklaştı?

type Side = "crm" | "remote";

function resolveField(
  base: unknown, local: unknown, remote: unknown,
  policy: { owner: Side | "both"; conflict_rule: string }
): { value: unknown; conflict: boolean } {
  const localChanged = !same(base, local);
  const remoteChanged = !same(base, remote);

  if (!localChanged && !remoteChanged) return { value: local, conflict: false };
  if (localChanged && !remoteChanged) return { value: local, conflict: false };
  if (!localChanged && remoteChanged) return { value: remote, conflict: false };
  if (same(local, remote)) return { value: local, conflict: false };

  // Gerçek çakışma: iki taraf da farklı yöne değiştirdi
  if (policy.owner === "crm") return { value: local, conflict: false };
  if (policy.owner === "remote") return { value: remote, conflict: false };
  if (policy.conflict_rule === "manual") return { value: local, conflict: true };
  return { value: local, conflict: true }; // latest_wins ayrıca ele alınır
}

Bu yaklaşımda gerçek çakışmalar beklenenden çok daha az çıkar; çoğu "çakışma" aslında yalnızca bir tarafın değişmesidir. Gerçekten iki tarafın da değiştirdiği manual alanlar ise bir inceleme kuyruğuna düşer ve CRM'de kaydın üzerinde görünür bir uyarı olarak durur. Satış operasyonunda bu kuyruk genelde günde birkaç kayıttan ibarettir; bunu bir insanın görmesi, yanlış telefon numarasıyla kaybedilen bir müşteriden çok daha ucuzdur.

Silme ve birleştirme: En çok unutulan iki olay

Güncellemeleri senkronize etmek kolaydır; silmeler ve birleştirmeler tasarımı zorlar. Bir kayıt CRM'de silindiğinde muhasebede de silinmeli mi? Çoğu zaman hayır: faturası kesilmiş bir müşteri muhasebede kalmak zorundadır. Bu yüzden silmeyi ayrı bir politika olarak ele alıyorum: varsayılan davranış uzak kaydı silmek değil, eşlemeyi "bağlantısız" işaretleyip uzak tarafa bir arşiv etiketi göndermektir.

Mükerrer lead birleştirme ise daha sinsidir. CRM'de iki kayıt birleştiğinde, kaybolan kaydın uzak sistemdeki karşılığı ne olacak? Eşleme tablosunda iki satır aynı hayatta kalan kayda işaret etmeye çalışır ve benzersizlik kısıtı haklı olarak itiraz eder. Çözüm, birleştirmeyi change_log içinde ayrı bir olay türü olarak yaymak ve bağlayıcıya özel bir davranış tanımlamaktır: uzak sistem de birleştirmeyi destekliyorsa orada da birleştirmek, desteklemiyorsa ikinci kaydı arşivleyip eşlemesini hayatta kalan kayda not olarak eklemek.

Gözlemlenebilirlik: Senkron sessizce bozulur

Senkronizasyon katmanı nadiren gürültülü biçimde çöker; genellikle sessizce geride kalır. Bu yüzden her bağlayıcı için şu üç ölçüyü panoda tutuyorum:

Gecikme: change_log içindeki en yüksek seq ile bağlayıcının imleci arasındaki fark ve en eski işlenmemiş satırın yaşı.
Çakışma ve hata oranı: Günlük çakışma kuyruğuna düşen kayıt sayısı ve kalıcı hataya düşen gönderimler.
Mutabakat farkı: Haftada bir, iki taraftaki kayıtların hash'lerini toplu olarak karşılaştıran bir mutabakat işi. Olay tabanlı senkron ne kadar iyi olursa olsun, arada kaçan bir webhook olur; mutabakat işi bu boşlukları kapatan güvenlik ağıdır.

Mutabakat işinin bulduğu farkları otomatik düzeltmeden önce bir süre yalnızca raporlamasını öneririm. İlk haftalarda bulunan farklar genellikle bir normalize etme hatasını ya da yanlış işaretlenmiş bir alan sahipliğini ortaya çıkarır; bunları kuralda düzeltmek, sonuçları tek tek düzeltmekten çok daha kalıcıdır.

Canlıya alma sırası

Yeni bir bağlayıcıyı canlıya alırken izlediğim sıra kabaca şöyle:

Önce alan sahipliği tablosunu ilgili ekiplerle birlikte doldurun; both alanları tek tek gerekçelendirin.
Kimlik eşlemesini tek seferlik bir eşleştirme işiyle kurun (vergi numarası, e-posta, normalize telefon gibi güçlü anahtarlarla) ve emin olunamayan eşleşmeleri insan onayına bırakın.
Senkronu bir süre "yalnızca okuma ve raporlama" kipinde çalıştırın; ne yazacağını kaydetsin ama yazmasın.
Sonra tek yönlü alanları açın, en son both alanları.

Sonuç

İyi bir veri senkronizasyonu, "iki sistem aynı olsun" isteğini birkaç açık karara böler: her alanın sahibi kim, kayıtlar birbirini nasıl tanıyor, değişiklik nasıl kaçırılmadan yakalanıyor, yankı nasıl tanınıyor ve gerçek çakışmada kim karar veriyor. Bu kararları veri olarak tuttuğunuzda, senkron katmanı bir kara kutu olmaktan çıkar ve satış ekibinin güvendiği bir altyapıya dönüşür. Kavramın kısa tanımı ve gayrimenkul satış operasyonlarındaki yeri için Data sync nedir? sayfasına göz atabilirsiniz.

SSS

Çift yönlü senkron için webhook mu, periyodik sorgu mu kullanmalıyım?
İkisini birlikte. Webhook düşük gecikme sağlar ama kaçabilir; periyodik "değişenleri getir" sorgusu ve haftalık mutabakat işi kaçanları yakalar. Yalnızca webhook'a güvenen bir senkron er geç sapar.

updated_at ile imleç tutmak neden riskli?
Aynı zaman damgasına sahip kayıtlar sınırda kaybolabilir ve uzun süren işlemler geçmiş bir zaman damgasıyla commit edilebilir. Artan sıra numaralı bir değişiklik günlüğü bu iki sorunu da ortadan kaldırır.

Sonsuz güncelleme döngüsünü en basit nasıl önlerim?
Senkron işçisinin yazdığı değişiklikleri bir köken etiketiyle işaretleyin ve o kökenli değişiklikleri karşı tarafa geri göndermeyin. Buna ek olarak, gönderdiğiniz içeriğin normalize edilmiş özetini saklayıp geri gelen değişikliği bu özetle karşılaştırın.

"Son yazan kazanır" hiç mi kullanılmamalı?
Saatleri güvenilir, düşük riskli alanlarda (örneğin bir not alanı) kabul edilebilir. Telefon, e-posta, danışman ataması gibi satış akışını etkileyen alanlarda üç yollu karşılaştırma ve gerekirse insan onayı daha güvenlidir.

CRM'de silinen bir lead uzak sistemde de silinmeli mi?
Genellikle hayır. Muhasebe veya sözleşme kayıtları yasal ve operasyonel nedenlerle kalmalıdır. Varsayılan davranış olarak eşlemeyi bağlantısız işaretleyip uzak kaydı arşivlemek daha güvenlidir.

Senkronun sağlıklı çalıştığını nasıl anlarım?
İmleç gecikmesini, çakışma kuyruğunun büyüklüğünü ve periyodik mutabakat farkını izleyin. Bu üç ölçü sıfıra yakın ve kararlıysa senkron sağlıklıdır; biri yavaşça artıyorsa sessiz bir sorun büyüyordur.

UTM parametrelerini CRM'e doğru taşımak: İlk ve son temas, normalize sözlük, kanal eşleme tablosu ve geriye dönük yeniden hesaplama

Koray Yalçın — Mon, 02 Nov 2026 16:25:10 +0000

Pazarlama toplantılarında en sık duyduğum cümlelerden biri şudur: "Reklam paneli 400 lead diyor, CRM 310 diyor, satış ekibi ise kampanyanın hiç satış getirmediğini söylüyor." Bu üç rakam genellikle aynı gerçeği farklı kayıplarla anlatır. Kayıpların büyük kısmı da reklamdaki tıklama ile CRM'deki fırsat kartı arasındaki o kısa yolda, yani UTM parametrelerinin taşınmasında yaşanır. Ben Koray Yalçın; lead yönetimi, CRM mimarisi, dijital pazarlama ve yapay zekâ destekli otomasyon üzerine, çoğunlukla gayrimenkul ve PropTech projelerinde çalışıyorum. Konut projelerinde kampanya başına bütçeler yüksek, satış döngüleri uzun olduğu için "bu satış hangi reklamdan geldi" sorusunun cevabı doğrudan bütçe kararına dönüşüyor.

UTM mapping, en basit tanımıyla, reklam ve kampanya bağlantılarındaki UTM parametrelerinin CRM'deki lead ve fırsat kayıtlarına otomatik ve tutarlı biçimde yazılmasıdır. Bu yazıda konuyu pazarlama tarafından değil, geliştirici tarafından ele alıyorum: parametreleri sayfaya ilk girişte nasıl yakalayacağınız, form ve oturum boyunca nasıl koruyacağınız, ham değeri ve normalize değeri neden ayrı tutmanız gerektiği, kanal eşlemesini neden kod yerine veri olarak saklamanız gerektiği ve eşleme kuralları değiştiğinde geçmişi nasıl yeniden hesaplayacağınız. Örnekler JavaScript ve PostgreSQL üzerinden.

Sorun nerede başlıyor: UTM bir kez görünür, sonra kaybolur

UTM parametreleri (utm_source, utm_medium, utm_campaign, utm_content, utm_term) yalnızca kullanıcının geldiği ilk URL'de bulunur. Kullanıcı sitede ikinci sayfaya geçtiğinde, galeriye baktığında ya da form sayfasına gittiğinde adres çubuğunda artık yoktur. Formu gönderen sayfa çoğu zaman UTM'yi hiç görmemiştir. Bu yüzden "form gönderilirken URL'deki parametreleri okuyalım" yaklaşımı, tek sayfalık kampanya açılış sayfaları dışında neredeyse her zaman veri kaybettirir.

İkinci sorun, aynı ziyaretçinin birden fazla kez gelmesidir. Konut alıcısı bir hafta önce Instagram reklamından gelip bakar, üç gün sonra Google'da proje adını arayıp tekrar gelir, sonunda bir e-posta bülteninden gelip formu doldurur. Hangi kaynağı yazacağınız bir tercih meselesidir ve bu tercihi kodun içine gömülü bir varsayım olarak değil, açık bir veri modeli olarak yapmanız gerekir.

Üçüncü sorun ise dağınıklıktır. Aynı kaynak için facebook, Facebook, fb, meta, ig ve instagram değerlerini aynı hafta içinde görmek olağandır. Ajans değiştiğinde ya da bir ekip arkadaşı kampanya bağlantısını elle yazdığında yeni varyantlar eklenir. Normalize edilmemiş UTM verisiyle kurulan rapor, birkaç ay içinde güvenilmez hale gelir.

Yakalama katmanı: İlk temas ve son temas ayrı saklanır

Benim önerdiğim temel kural şudur: tarayıcı tarafında hem ilk temas hem son temas bilgisi tutulur ve form gönderiminde ikisi birden sunucuya iletilir. İlk temas, ziyaretçinin bu cihazda UTM ile geldiği ilk ziyarettir ve bir kez yazıldıktan sonra değişmez. Son temas, UTM taşıyan en son ziyarettir ve her yeni kampanyalı girişte güncellenir. UTM'siz bir dönüş (doğrudan giriş ya da organik arama) son temas bilgisini silmez; aksi halde kullanıcı yer imine kaydettiği sayfadan döndüğü anda tüm kampanya bilgisi kaybolur.

const KEYS = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"];
const CLICK_IDS = ["gclid", "fbclid", "wbraid", "gbraid", "ttclid"];
const STORE = "kt_attr_v1";
const MAX_AGE_DAYS = 90;

function readTouch() {
  const p = new URLSearchParams(window.location.search);
  const touch = {};
  for (const k of [...KEYS, ...CLICK_IDS]) {
    const v = p.get(k);
    if (v) touch[k] = v.slice(0, 200);
  }
  if (Object.keys(touch).length === 0) return null;
  touch.landing_path = window.location.pathname;
  touch.referrer_host = document.referrer ? new URL(document.referrer).hostname : null;
  touch.ts = new Date().toISOString();
  return touch;
}

function captureAttribution() {
  const now = Date.now();
  let state = {};
  try { state = JSON.parse(localStorage.getItem(STORE)) || {}; } catch (e) { state = {}; }
  if (state.first && now - Date.parse(state.first.ts) > MAX_AGE_DAYS * 864e5) state = {};

  const touch = readTouch();
  if (touch) {
    if (!state.first) state.first = touch;
    state.last = touch;
    state.touch_count = (state.touch_count || 0) + 1;
  }
  localStorage.setItem(STORE, JSON.stringify(state));
  return state;
}

Burada birkaç tasarım kararı var. Değerleri 200 karakterle kısaltıyorum, çünkü bazen reklam platformları ya da hatalı şablonlar çok uzun değerler üretir ve bunlar hem depolamayı hem raporları bozar. Tıklama kimliklerini (gclid, fbclid gibi) UTM ile aynı yerde ama ayrı alanlarda tutuyorum; çünkü daha sonra kapanan satışı reklam platformuna geri bildirmek istediğinizde UTM değil tıklama kimliği işe yarar. Süre sınırı koyuyorum, çünkü bir yıl önceki bir reklam tıklamasını bugünkü forma bağlamak çoğu işletme için anlamlı değildir. Doksan gün bir örnek değerdir; kendi satış döngünüze göre seçmelisiniz.

Çerez onayı konusunu da baştan çözmek gerekir. Bu bilgileri yerel depolamaya yazmak, kullandığınız onay yönetimi yapısına ve hukuki değerlendirmenize göre onay gerektirebilir. Pratikte iki yol görüyorum: onay verilene kadar parametreleri yalnızca oturum boyunca bellekte tutup form gönderiminde iletmek ya da onay sonrasında kalıcı depolamaya yazmak. Hangisini seçerseniz seçin, CRM'e gelen kayıtta "atıf verisi hangi onay durumunda toplandı" bilgisini de saklamanızı öneririm.

Form ve sunucu tarafı: Tarayıcıya güvenmeyin, ama ondan gelen veriyi kaybetmeyin

Form gönderiminde atıf durumu gizli alanlar ya da JSON gövdesinin bir parçası olarak sunucuya gider. Sunucu bu veriyi doğrulamadan CRM'e yazmamalıdır; çünkü sonuçta kullanıcının değiştirebileceği bir veridir. Doğrulamanın amacı sahteciliği tamamen engellemek değil, bozuk ve tehlikeli değerleri ayıklamaktır: izin verilen anahtarlar dışındakileri atmak, uzunluğu sınırlamak, kontrol karakterlerini temizlemek ve zaman damgasının makul bir aralıkta olduğunu kontrol etmek.

Sunucu tarafında ikinci bir güvence katmanı da kurulabilir. Açılış sayfası isteği sunucunuza geldiğinde, URL'deki UTM'leri birinci taraf bir çerezle eşleşen bir ziyaret kaydına yazarsanız, tarayıcı tarafındaki kod bir reklam engelleyiciye takıldığında bile atıf verisini kurtarabilirsiniz. Form gönderiminde tarayıcıdan gelen değer ile sunucudaki ziyaret kaydı karşılaştırılır; ikisi çelişirse sunucu kaydı tercih edilir ve çelişki not edilir.

Veri modeli: Ham değer, normalize değer ve temas tablosu

En sık gördüğüm hata, UTM değerlerini doğrudan lead kartındaki birkaç metin alanına yazmaktır. Bu, hem tek temas varsayımını kalıcı hale getirir hem de normalizasyon kuralları değiştiğinde geçmişi düzeltmeyi imkânsızlaştırır. Benim tercih ettiğim yapı, her teması ayrı bir satır olarak saklamak ve normalize sonucu ayrı alanlarda tutmaktır.

CREATE TABLE attribution_touch (
  id              bigserial PRIMARY KEY,
  lead_id         bigint NOT NULL REFERENCES lead(id),
  touch_role      text NOT NULL CHECK (touch_role IN ('first', 'last', 'conversion')),
  occurred_at     timestamptz NOT NULL,
  -- ham değerler: asla değiştirilmez
  raw_source      text,
  raw_medium      text,
  raw_campaign    text,
  raw_content     text,
  raw_term        text,
  click_id_type   text,
  click_id        text,
  landing_path    text,
  referrer_host   text,
  consent_state   text NOT NULL DEFAULT 'unknown',
  -- normalize sonuç: yeniden hesaplanabilir
  source_norm     text,
  medium_norm     text,
  channel         text,
  campaign_key    text,
  mapping_version int,
  UNIQUE (lead_id, touch_role)
);

Ham alanlar bir kez yazılır ve hiç güncellenmez. Normalize alanlar ise hangi eşleme sürümüyle üretildiklerini mapping_version üzerinden belli eder. Bu ayrım, yazının ilerleyen bölümündeki geriye dönük yeniden hesaplamayı mümkün kılan şeydir. conversion rolü, formun gönderildiği oturumu temsil eder; ilk ve son temas ile aynı olabilir ama ayrı tutmak, "form gönderen ziyaret organikti ama kullanıcıyı ilk getiren reklamdı" gibi durumları görünür kılar.

Normalize sözlük ve kanal eşleme tablosu: Kural veri olarak

Normalizasyonu iki aşamada yapıyorum. Birinci aşama mekanik temizliktir: küçük harfe çevirme, baştaki ve sondaki boşlukları silme, boşluk ve tireleri alt çizgiye dönüştürme. İkinci aşama anlamsal eşlemedir: fb, facebook, meta ve ig değerlerinin hangi kanonik kaynağa karşılık geldiğine karar vermek. Bu ikinci aşamayı kodun içinde if zinciriyle yapmak, pazarlama ekibinin her yeni varyant için geliştiriciye iş açmasına yol açar. Bu yüzden eşlemeyi bir tabloya koyuyorum.

CREATE TABLE utm_alias (
  field        text NOT NULL CHECK (field IN ('source', 'medium')),
  raw_clean    text NOT NULL,
  canonical    text NOT NULL,
  PRIMARY KEY (field, raw_clean)
);

CREATE TABLE channel_rule (
  id           serial PRIMARY KEY,
  priority     int NOT NULL,
  source_norm  text,          -- NULL: herhangi biri
  medium_norm  text,          -- NULL: herhangi biri
  has_click_id text,          -- 'gclid', 'fbclid' ya da NULL
  channel      text NOT NULL, -- 'paid_social', 'paid_search', 'email', 'referral' ...
  version      int NOT NULL
);

CREATE INDEX ON channel_rule (version, priority);

Kanal kuralları öncelik sırasına göre değerlendirilir ve ilk eşleşen kural kazanır. Tıklama kimliğini bir koşul olarak eklemek, UTM'si eksik ama gclid taşıyan ziyaretleri ücretli arama olarak sınıflandırmanızı sağlar; bu durum Google Ads'in otomatik etiketlemesi açıkken ama manuel UTM eklenmemişken sık görülür.

import re

def clean(value):
    if not value:
        return None
    v = value.strip().lower()
    v = re.sub(r"[\s\-]+", "_", v)
    v = re.sub(r"[^a-z0-9_\.]", "", v)
    return v or None

def normalize_touch(touch, aliases, rules):
    src = clean(touch.get("raw_source"))
    med = clean(touch.get("raw_medium"))
    src = aliases.get(("source", src), src)
    med = aliases.get(("medium", med), med)

    channel = "unmapped"
    for r in rules:  # priority sıralı gelir
        if r.source_norm and r.source_norm != src:
            continue
        if r.medium_norm and r.medium_norm != med:
            continue
        if r.has_click_id and r.has_click_id != touch.get("click_id_type"):
            continue
        channel = r.channel
        break

    if channel == "unmapped" and not src and not med:
        channel = "referral" if touch.get("referrer_host") else "direct"

    return {"source_norm": src, "medium_norm": med, "channel": channel}

unmapped değerini bilerek ayrı tutuyorum. Eşleşmeyen bir değeri "diğer" kategorisine gömmek, sorunu gizler. unmapped oranı ise pazarlama ekibi için çok değerli bir sinyaldir: yeni bir ajans ya da yeni bir kampanya şablonu devreye girdiğinde bu oran yükselir ve sözlüğe eklenmesi gereken değerler hemen görünür.

Kampanya anahtarı: İsimlendirme kuralı olmadan eşleme yarım kalır

Kaynak ve ortam normalize edilse bile utm_campaign alanı genellikle en dağınık olanıdır. Konut projelerinde benim önerdiğim yaklaşım, kampanya adına sabit bir yapı vermektir: proje kodu, hedef kitle ya da pazar, teklif türü ve dönem. Örneğin prj12_uk_lansman_2026q4 gibi bir değer, alt çizgiyle ayrılmış dört parçaya bölünebilir. Bu yapıya uyan değerlerden bir campaign_key türetilir ve fırsat kartında projeyle ilişkilendirilir. Uymayan değerler yine ham haliyle saklanır, ama raporda "isimlendirme dışı" olarak işaretlenir.

Bu kuralı bağlantı üretim aşamasında uygulamak, sonradan temizlemekten çok daha ucuzdur. Pazarlama ekibine serbest metin alanı yerine, açılır listelerden kampanya bağlantısı üreten küçük bir iç araç vermek, birkaç hafta içinde veri kalitesini belirgin biçimde değiştirir. Bu aracın ürettiği değerler doğrudan utm_alias ve proje tablosu ile uyumlu olur.

Lead'den fırsata: Atıf kopyalanmaz, bağlanır

Lead bir fırsata dönüştüğünde UTM alanlarının fırsat kartına kopyalanması yaygın bir uygulamadır. Kopyalama, iki kayıt arasında zamanla ayrışan iki gerçek yaratır. Ben fırsat kaydında atıf verisini kopyalamak yerine, kaynak lead'in temas satırlarına bağlanmayı tercih ediyorum. Raporlama tarafında bir görünüm, fırsatı ilk ve son temasla birleştirir.

CREATE VIEW deal_attribution AS
SELECT d.id AS deal_id,
       d.project_id,
       d.stage,
       d.amount_gbp,
       f.channel  AS first_channel,
       f.campaign_key AS first_campaign,
       l.channel  AS last_channel,
       l.campaign_key AS last_campaign
FROM deal d
JOIN lead ld ON ld.id = d.origin_lead_id
LEFT JOIN attribution_touch f ON f.lead_id = ld.id AND f.touch_role = 'first'
LEFT JOIN attribution_touch l ON l.lead_id = ld.id AND l.touch_role = 'last';

Bir kişinin birden fazla lead kaydı olduğunda (farklı formlar, farklı projeler) hangi lead'in fırsatın kaynağı olduğu, tekilleştirme ve birleştirme kurallarıyla belirlenir. Birleştirme sırasında temas satırları silinmemeli, birleşen kayda taşınmalıdır; böylece kişinin gerçek ilk teması korunur.

UTM'siz kanallar: Telefon, WhatsApp ve satış ofisi

Gayrimenkulde lead'lerin önemli bir kısmı forma hiç uğramaz. Kullanıcı reklamı görür, numarayı arar ya da WhatsApp'tan yazar, bazen de doğrudan satış ofisine gelir. Bu kanallarda UTM yoktur, ama atıf ihtiyacı devam eder. Uyguladığım üç yöntem şunlardır. Birincisi, kampanya bazlı takip numaraları kullanmak ve gelen aramanın numarasını bir kampanya anahtarına eşlemektir. İkincisi, WhatsApp'a yönlendiren bağlantılara önceden doldurulmuş bir mesaj içinde kısa bir referans kodu eklemek ve gelen ilk mesajda bu kodu ayrıştırmaktır. Üçüncüsü, satış ofisine gelen ziyaretçiye danışmanın "bizi nereden duydunuz" sorusunu sabit seçeneklerle sormasıdır. Bu üçünün sonucu da attribution_touch tablosuna yazılır; ham değer olarak takip numarası, referans kodu ya da beyan edilen seçenek saklanır ve aynı normalizasyon hattından geçer.

Beyan edilen kaynağın dijital atıfla çeliştiği durumlar sık görülür. Bunları birbirini ezmesine izin vermeden iki ayrı temas olarak saklamak, hem pazarlama hem satış ekibine daha dürüst bir tablo sunar.

Geriye dönük yeniden hesaplama: Eşleme değiştiğinde geçmiş de değişir

Sözlüğe yeni bir takma ad eklendiğinde ya da bir kanal kuralı değiştiğinde, geçmiş kayıtların normalize alanları eski kurallarla kalır. Ham değerleri sakladığınız için bu sorun çözülebilir: yeni kural sürümüyle tüm temasları yeniden hesaplarsınız. Bunu büyük tablolarda tek bir dev güncellemeyle değil, parçalar halinde yapmak gerekir.

def reproject(conn, new_version, batch=5000):
    aliases = load_aliases(conn)
    rules = load_rules(conn, new_version)
    last_id = 0
    while True:
        rows = conn.execute(
            """SELECT id, raw_source, raw_medium, click_id_type, referrer_host
               FROM attribution_touch
               WHERE id > %s AND (mapping_version IS NULL OR mapping_version < %s)
               ORDER BY id LIMIT %s""",
            (last_id, new_version, batch),
        ).fetchall()
        if not rows:
            break
        for r in rows:
            n = normalize_touch(r._asdict(), aliases, rules)
            conn.execute(
                """UPDATE attribution_touch
                   SET source_norm=%s, medium_norm=%s, channel=%s, mapping_version=%s
                   WHERE id=%s""",
                (n["source_norm"], n["medium_norm"], n["channel"], new_version, r.id),
            )
        conn.commit()
        last_id = rows[-1].id

Yeniden hesaplama sonrası en önemli adım, değişen kayıtların özetini çıkarmaktır: kaç temasın kanalı değişti, hangi kanaldan hangisine geçti. Bu özet, "geçen ayın raporu neden değişti" sorusunun cevabıdır ve pazarlama ekibiyle güveni koruyan şey budur. Kapanmış dönem raporlarını dondurmak isteyen ekipler için rapor anlık görüntüsünü ayrıca saklamak da iyi bir pratiktir.

İzleme: Eşlemenin sağlığını haftalık ölçün

Kurulumdan sonra izlenmesi gereken birkaç basit gösterge var. Atıf verisi hiç olmayan dijital lead oranı, yakalama katmanında bir kırılma olduğunu gösterir; örneğin bir site güncellemesi script'i devre dışı bırakmış olabilir. unmapped kanal oranı sözlüğün güncel olup olmadığını gösterir. İsimlendirme dışı kampanya oranı, bağlantı üretim aracının kullanılıp kullanılmadığını gösterir. Reklam panelindeki dönüşüm sayısı ile CRM'deki aynı kampanyaya ait lead sayısı arasındaki fark ise tek başına kesin bir sonuç vermez ama ani sıçramalar çoğu zaman bir entegrasyon sorununa işaret eder.

Bu göstergeleri bir panoya koymak yeterli değildir; bir eşik belirleyip aşıldığında ilgili kişiye bildirim gitmesini sağlamak gerekir. Atıf hatları sessizce bozulur ve fark edildiklerinde genellikle birkaç haftalık veri çoktan kaybolmuştur.

Sık sorulan sorular

İlk temas mı son temas mı kullanmalıyım?
İkisini de saklayın, raporlama sırasında seçin. Lansman dönemindeki bilinirlik kampanyalarının etkisini görmek için ilk temas, kısa vadeli performans kampanyalarını optimize etmek için son temas daha anlamlıdır. Tek bir alan seçip diğerini atmak, sonradan geri dönülemeyen bir karardır.

UTM verisini sadece reklam platformunun panelinden takip etsem yetmez mi?
Panel, tıklama ve form doldurma düzeyinde bilgi verir. Hangi lead'in randevuya geldiği, hangisinin satışa dönüştüğü ve satış tutarı ise CRM'dedir. Bütçe kararını satış verisine göre vermek istiyorsanız atıfın CRM'de doğru yaşaması gerekir.

Ham değerleri saklamak veri tabanını şişirmez mi?
Temas başına birkaç kısa metin alanı, lead kaydının geri kalanıyla karşılaştırıldığında küçük bir yüktür. Karşılığında kural değiştiğinde geçmişi düzeltme imkânı kazanırsınız. Ham değer olmadan bu düzeltme mümkün değildir.

Reklam engelleyiciler UTM yakalamayı bozar mı?
Kendi alan adınızdan sunulan birinci taraf script'ler genellikle daha az etkilenir, ama risk tamamen ortadan kalkmaz. Açılış sayfası isteğini sunucu tarafında kaydetmek, tarayıcı tarafı başarısız olduğunda bir yedek sağlar.

Tıklama kimliklerini (gclid, fbclid) neden ayrıca saklamalıyım?
UTM size kampanyayı söyler, tıklama kimliği ise reklam platformunun kendi kaydına bağlanmanızı sağlar. Kapanan satışları reklam platformuna offline dönüşüm olarak geri bildirmek istediğinizde ihtiyaç duyacağınız bilgi budur.

Kanal eşleme kurallarını kim yönetmeli?
Kuralların kendisi pazarlama operasyonunun sorumluluğunda olmalı, ama değişiklikler sürümlü ve kayıtlı yapılmalı. Geliştirici, sürüm geçişinde yeniden hesaplamanın çalışmasını ve değişiklik özetinin üretilmesini garanti eder.

Kapanış

UTM mapping, ilk bakışta birkaç gizli form alanından ibaret görünür. Gerçekte ise yakalama, saklama, normalizasyon, eşleme ve yeniden hesaplamadan oluşan küçük bir veri hattıdır. İlk ve son teması ayrı tutmak, ham değeri hiç değiştirmemek, eşlemeyi kod yerine sürümlü veri olarak saklamak, UTM'siz kanalları aynı hatta dahil etmek ve hattın sağlığını düzenli ölçmek, "reklam ne kadar satış getirdi" sorusuna savunulabilir bir cevap vermenin temelidir. Benim deneyimimde bütçe toplantılarındaki tartışmaların önemli bir kısmı, rakamların kendisinden değil, bu hattın hiç kurulmamış olmasından kaynaklanır.

Koray Yalçın — lead yönetimi, CRM mimarisi ve PropTech sistemleri

CRM'den dışarıya webhook yayınlamak: Abonelik kaydı, imzalı gövde, teslimat kuyruğu ve endpoint sağlığı

Koray Yalçın — Mon, 02 Nov 2026 08:22:34 +0000

Bir CRM'i başka sistemlere bağlarken genellikle ilk düşünülen yön içeri doğrudur: reklam platformundan gelen lead'i almak, form verisini kaydetmek, ödeme sağlayıcısından gelen bildirimi işlemek. Oysa bir süre sonra soru tersine döner. Satış ekibi "lead kazanıldı olarak işaretlendiğinde muhasebe sistemi haberdar olsun" der, pazarlama ekibi "randevu oluştuğunda reklam aracına bildirim gitsin" ister, bir iş ortağı ise "yeni ilan eklendiğinde bize anında haber verin" diye sorar. Ben Koray Yalçın; lead yönetimi, CRM mimarisi, dijital pazarlama ve yapay zekâ destekli otomasyon üzerine, ağırlıklı olarak gayrimenkul ve PropTech projelerinde çalışıyorum. Bu taleplerin hepsinin ortak cevabı giden webhook'tur ve gördüğüm entegrasyon sorunlarının önemli bir kısmı, webhook'un "olay olunca bir POST atarız" kadar basit sanılmasından çıkar.

Bu yazıda giden webhook'u (outbound webhook) bir geliştirici gözüyle ele alıyorum: abonelik kaydını nasıl tutacağınız, olayı işlemle aynı anda nasıl güvenle kaydedeceğiniz, gövdeyi nasıl imzalayacağınız, teslimatı nasıl kuyruğa alacağınız, sorunlu bir endpoint'i nasıl yöneteceğiniz ve alıcı tarafında neyi garanti edip neyi etmediğinizi nasıl açıkça söyleyeceğiniz. Örnekler PostgreSQL ve Python üzerinden.

Webhook bir bildirim değil, bir sözleşmedir

Webhook'u bir kez yayınladığınızda karşı tarafta biri ona göre kod yazar. Alan adını değiştirdiğinizde, bir olayı iki kez gönderdiğinizde ya da sırayı karıştırdığınızda, sorunu siz değil o kod yaşar. Bu yüzden ilk adım teknik değil, sözleşmeseldir. Hangi olay türlerini yayınladığınızı, her olayın gövdesinde hangi alanların bulunduğunu, teslimatın "en az bir kez" mi olduğunu, sıranın garanti edilip edilmediğini ve imzanın nasıl doğrulanacağını yazılı olarak belirlemeniz gerekir.

Benim önerdiğim temel sözleşme şudur: teslimat en az bir kezdir, yani aynı olay birden fazla gelebilir; her olayın değişmeyen bir kimliği vardır; sıra garanti edilmez ama her olay, ait olduğu kaydın sürüm numarasını taşır; gövde imzalıdır ve imza bir zaman damgası içerir. Bu dört cümleyi dokümantasyonun en üstüne yazmak, sonradan gelecek destek taleplerinin yarısını önler.

Abonelik kaydı: kim, neyi, nereye istiyor

Webhook altyapısının merkezinde abonelik tablosu durur. Her abonelik bir hedef URL, bir olay türü listesi, bir imza sırrı ve bir durum taşır. Burada sık yapılan hata, sırrı düz metin olarak saklamak ya da tek bir sırrı tüm abonelikler için kullanmaktır. Her aboneliğin kendi sırrı olmalı, sır şifreli saklanmalı ve rotasyon için iki sır aynı anda geçerli olabilmelidir.

CREATE TABLE webhook_subscription (
  id             bigserial PRIMARY KEY,
  tenant_id      bigint NOT NULL,
  target_url     text NOT NULL,
  event_types    text[] NOT NULL,
  secret_enc     bytea NOT NULL,
  secret_prev_enc bytea,
  secret_prev_expires_at timestamptz,
  status         text NOT NULL DEFAULT 'active'
                 CHECK (status IN ('active','paused','disabled')),
  disabled_reason text,
  payload_version smallint NOT NULL DEFAULT 1,
  created_at     timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX ON webhook_subscription USING gin (event_types)
  WHERE status = 'active';

payload_version alanı göz ardı edilen ama çok değerli bir alandır. Gövde biçimini değiştirmeniz gerektiğinde, mevcut abonelere eski sürümü göndermeye devam edip yeni abonelikleri yeni sürümle başlatabilirsiniz. Böylece hiç kimsenin entegrasyonu bir gece ansızın bozulmaz.

Hedef URL'yi kaydederken de dikkatli olmak gerekir. Kullanıcının girdiği bir URL'ye sunucunuzdan istek atmak, sunucu taraflı istek sahteciliği (SSRF) için açık bir kapıdır. Kayıt sırasında yalnızca https şemasına izin vermek, gönderim anında ise alan adının çözüldüğü IP adresinin özel ağ aralıklarında (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, bulut metadata adresleri) olmadığını kontrol etmek gerekir. Kontrolü yalnızca kayıt anında yapmak yetmez; alan adı daha sonra başka bir adrese yönlendirilebilir.

Olayı işlemle aynı anda kaydetmek: outbox

Webhook'u doğrudan iş kodunun içinden göndermek cazip gelir: lead kazanıldı olarak güncellendi, hemen ardından HTTP isteği atıldı. Bu yaklaşımın iki ciddi sorunu var. Birincisi, veritabanı işlemi geri alınırsa webhook yine de gitmiş olur ve karşı taraf hiç gerçekleşmemiş bir olayı işler. İkincisi, karşı tarafın yavaşlığı kullanıcının ekranını yavaşlatır.

Çözüm, olayı iş verisiyle aynı veritabanı işlemi içinde bir outbox tablosuna yazmaktır. Gönderim, ayrı bir işçi tarafından yapılır. İşlem başarıyla tamamlanmadıysa olay da yoktur; tamamlandıysa olay kesin olarak kayıtlıdır.

def mark_deal_won(conn, deal_id, actor_id):
    with conn.transaction():
        row = conn.execute(
            """UPDATE deal SET stage = 'won', version = version + 1,
                      updated_at = now()
               WHERE id = %s AND stage <> 'won'
               RETURNING id, tenant_id, version, amount, currency""",
            (deal_id,),
        ).fetchone()
        if row is None:
            return  # zaten kazanılmış, olay üretme
        conn.execute(
            """INSERT INTO event_outbox
                 (event_id, tenant_id, event_type, entity_id,
                  entity_version, payload, occurred_at)
               VALUES (gen_random_uuid(), %s, 'deal.won', %s, %s, %s, now())""",
            (row.tenant_id, row.id, row.version,
             Json({"deal_id": row.id, "amount": str(row.amount),
                   "currency": row.currency, "actor_id": actor_id})),
        )

Dikkat edilecek nokta, olayın entity_version taşımasıdır. Alıcı taraf, elindeki sürümden daha eski bir olay gelirse onu yok sayabilir. Sıra garantisi vermeden tutarlılık sağlamanın en pratik yolu budur.

Olaydan teslimata: yayılım (fan-out)

Bir olay birden fazla aboneliğe gidebilir. Outbox'taki her olay için ilgili aktif abonelikler bulunur ve her biri için ayrı bir teslimat kaydı oluşturulur. Teslimatı abonelik bazında ayırmak önemlidir; çünkü bir endpoint'in çökmesi, diğer abonelerin olayları almasını engellememelidir.

CREATE TABLE webhook_delivery (
  id              bigserial PRIMARY KEY,
  subscription_id bigint NOT NULL REFERENCES webhook_subscription(id),
  event_id        uuid NOT NULL,
  status          text NOT NULL DEFAULT 'pending'
                  CHECK (status IN ('pending','succeeded','failed','dead')),
  attempt_count   int NOT NULL DEFAULT 0,
  next_attempt_at timestamptz NOT NULL DEFAULT now(),
  last_status_code int,
  last_error      text,
  UNIQUE (subscription_id, event_id)
);

CREATE INDEX ON webhook_delivery (next_attempt_at)
  WHERE status IN ('pending','failed');

UNIQUE (subscription_id, event_id) kısıtı, yayılım işçisi iki kez çalışsa bile aynı olay için aynı aboneliğe iki teslimat kaydı açılmasını engeller. Gönderim işçisi ise FOR UPDATE SKIP LOCKED ile zamanı gelmiş kayıtları alır; birden fazla işçi aynı teslimatı aynı anda göndermez.

İmzalı gövde: alıcı neye güvenebilir

Alıcının, gelen isteğin gerçekten sizden geldiğini ve yolda değiştirilmediğini doğrulayabilmesi gerekir. En yaygın ve sağlam yöntem, gövdeyi aboneliğe özel sırla HMAC-SHA256 ile imzalamaktır. İmzaya bir zaman damgası ve olay kimliği eklemek, eski bir isteğin yeniden oynatılmasını da zorlaştırır.

import hmac, hashlib, json, random, time

def build_request(sub, event, secret: bytes):
    body = json.dumps(render_payload(event, sub.payload_version),
                      separators=(",", ":"), ensure_ascii=False).encode()
    ts = str(int(time.time()))
    signed = f"{event.event_id}.{ts}.".encode() + body
    sig = hmac.new(secret, signed, hashlib.sha256).hexdigest()
    headers = {
        "Content-Type": "application/json",
        "Webhook-Id": str(event.event_id),
        "Webhook-Timestamp": ts,
        "Webhook-Signature": f"v1={sig}",
    }
    return headers, body

Sır rotasyonu sırasında, eski sır da geçerliyken iki imza birden gönderilir (v1=...,v1=...). Alıcı ikisinden biri tutarsa isteği kabul eder. Dokümantasyonda alıcıya şunu açıkça söylemek gerekir: imzayı ham gövde üzerinden doğrulayın, JSON'u ayrıştırıp yeniden oluşturduktan sonra değil; karşılaştırmayı sabit zamanlı yapın; zaman damgası beş dakikadan eskiyse reddedin; Webhook-Id değerini kaydedip aynı kimlikle gelen ikinci isteği işlemeden 200 dönün.

Teslimat işçisi: zaman aşımı, yanıt kodları ve yeniden deneme

Gönderim işçisinin en önemli ayarı zaman aşımıdır. Alıcı on saniye içinde yanıt vermiyorsa beklemeyi bırakmak gerekir; aksi halde yavaş bir endpoint tüm işçileri kilitler. Alıcıya da "isteği aldığınızda hemen 2xx dönün, işi arka planda yapın" önerisi verilmelidir.

Yanıt kodlarını sınıflandırmak gerekir. 2xx başarıdır. 410 Gone, alıcının bu aboneliği artık istemediği anlamına gelir; aboneliği devre dışı bırakmak doğrudur. 4xx kodlarının çoğu kalıcı bir sorun işaretidir ama yine de birkaç kez denemek, alıcının geçici bir yapılandırma hatasını düzeltmesine zaman tanır. 429 ve 5xx ile ağ hataları geçicidir; Retry-After başlığı varsa ona uyulur, yoksa üstel bekleme ve rastgele sapma (jitter) ile tekrar denenir.

SCHEDULE = [60, 300, 1800, 7200, 21600, 43200, 86400]  # saniye

def on_result(conn, d, status_code, error):
    if status_code and 200 <= status_code < 300:
        set_status(conn, d.id, "succeeded", status_code)
        return
    if status_code == 410:
        disable_subscription(conn, d.subscription_id, "endpoint 410 döndü")
        set_status(conn, d.id, "dead", status_code)
        return
    n = d.attempt_count + 1
    if n > len(SCHEDULE):
        set_status(conn, d.id, "dead", status_code, error)
        return
    delay = random.uniform(SCHEDULE[n - 1] * 0.5, SCHEDULE[n - 1])
    schedule_retry(conn, d.id, n, delay, status_code, error)

Bu çizelgeyle bir teslimat yaklaşık üç gün boyunca denenir. "Dead" durumuna düşen teslimatlar silinmez; abonelik sahibine bir panelden görünür kılınır ve tek tek ya da toplu olarak yeniden gönderilebilir. Yeniden gönderimde olay kimliği aynı kalır; böylece alıcının tekilleştirme mantığı bozulmaz.

Endpoint sağlığı: ne zaman durdurmalı

Haftalardır yalnızca hata dönen bir endpoint'e her olayı göndermeye devam etmek hem kaynak israfıdır hem de kuyruğu şişirir. Benim uyguladığım kural basittir: bir abonelik son yetmiş iki saat boyunca hiç başarılı teslimat almadıysa ve bu sürede en az belli sayıda deneme yapıldıysa, otomatik olarak disabled durumuna alınır, sahibine e-posta ile bildirilir ve panelde gerekçe gösterilir. Abonelik yeniden etkinleştirildiğinde, bekleyen teslimatlar sırayla tekrar denenir.

Bir de devre kesici (circuit breaker) mantığı vardır. Bir endpoint arka arkaya hata dönüyorsa, o aboneliğin tüm bekleyen teslimatlarını aynı anda denemek yerine yalnızca bir "keşif" teslimatı gönderilir. O başarılı olursa diğerleri serbest bırakılır. Bu, kendini toparlamaya çalışan bir alıcı sistemin üzerine yüzlerce isteğin aynı anda yığılmasını önler.

Gövde tasarımı: ince mi, kalın mı

Gövdeye kaydın tamamını koymak (kalın gövde) alıcının işini kolaylaştırır ama iki risk taşır: kişisel veriyi gereğinden fazla yaymak ve alıcının eski bir anlık görüntüye göre işlem yapması. İnce gövde ise yalnızca olay türünü, kayıt kimliğini ve sürümü taşır; alıcı güncel veriyi API'den çeker.

Benim tercihim ortada bir yerdir. Olayı anlamak için gereken alanlar gövdede bulunur; telefon, e-posta ve kimlik bilgisi gibi kişisel veriler bulunmaz. Alıcı bunlara ihtiyaç duyarsa, kapsamı sınırlandırılmış bir API anahtarıyla çeker. Bu yaklaşım, KVKK açısından da veri minimizasyonu ilkesiyle uyumludur ve hangi verinin hangi sisteme gittiğini denetlemeyi kolaylaştırır.

Gözlemlenebilirlik ve test ortamı

Webhook sorunlarının çoğu "bize hiç gelmedi" cümlesiyle başlar. Bu soruya kanıtla cevap verebilmek için her teslimat denemesinin zamanını, yanıt kodunu, süresini ve yanıt gövdesinin ilk birkaç yüz karakterini saklamak gerekir. Abonelik sahibine bu kayıtları gösteren bir panel, destek ekibinin yükünü belirgin biçimde azaltır.

Ayrıca abonelik sahibine bir "test olayı gönder" düğmesi sunmak, entegrasyonun canlıya almadan doğrulanmasını sağlar. Test olayları gerçek olaylarla aynı imza ve biçimi kullanmalı, ancak türleri açıkça ayrılmalıdır (örneğin test.ping).

Sık Sorulan Sorular

Webhook yerine alıcının düzenli olarak API'yi sorgulaması daha basit değil mi?
Düşük hacimde öyle görünebilir, ancak sorgulama ya gecikme yaratır ya da gereksiz yük üretir. Webhook ile sorgulamayı birleştirmek en sağlam yoldur: webhook anlık bildirim sağlar, alıcı da kaçırdığı olayları yakalamak için arada bir "şu tarihten sonraki olaylar" uç noktasını sorgular.

Olayların sırasını garanti edebilir miyim?
Abonelik başına tek işçi ve tek kuyrukla teorik olarak evet, ama bir teslimat başarısız olduğunda arkasındaki tüm olaylar bekler. Bunun yerine sıra garantisi vermeyip her olaya kayıt sürüm numarası eklemek çok daha pratiktir.

İmza için HMAC yerine imzalı JWT ya da asimetrik anahtar kullanmalı mıyım?
Asimetrik imza, sırrı alıcıyla paylaşmama avantajı sağlar ve çok sayıda alıcı olduğunda yönetimi kolaylaştırır. Çoğu CRM entegrasyonunda ise abonelik başına HMAC sırrı yeterli, basit ve yaygın olarak desteklenen bir çözümdür.

Alıcı aynı olayı iki kez işlerse ne olur?
Teslimat en az bir kez olduğu için bu ihtimal her zaman vardır. Alıcı Webhook-Id değerini benzersiz kısıtlı bir tabloya yazıp, ekleme başarısız olursa işlemi atlamalıdır. Sözleşmede bunu açıkça belirtmek, sorumluluğu doğru yere koyar.

Webhook'larla kişisel veri göndermek KVKK açısından sorun yaratır mı?
Veri gönderilen her sistem, veri işleme envanterinde yer almalı ve aktarımın bir amacı olmalıdır. Gövdede kişisel veri taşımamak, gerektiğinde kapsamlı API erişimiyle çekmek ve aktarımları kayıt altına almak, riski önemli ölçüde azaltır.

Kapanış

Giden webhook, bir CRM'in dış dünyayla konuştuğu en görünür yüzeylerden biridir. Abonelik başına sır ve sürüm, işlemle aynı anda yazılan outbox, abonelik bazında ayrılmış teslimat kayıtları, zaman damgalı imza, sınıflandırılmış yeniden deneme, endpoint sağlığı ve şeffaf teslimat kayıtları; bunların her biri tek başına küçük bir karar gibi görünür. Birlikte ise "bize hiç gelmedi" ile "iki kez geldi" arasında gidip gelen destek konuşmalarını sona erdirir. Benim deneyimimde iş ortakları bir CRM'e, yayınladığı webhook'ların ne kadar öngörülebilir olduğuna bakarak güvenir.

Koray Yalçın — lead yönetimi, CRM mimarisi ve PropTech sistemleri