Rehber

Meta Dönüşüm API'si nedir, neden gerekli?

Pixel tek başına yetmediğinde sunucu bağlantısı devreye girer. Kurulum yolları, tekilleştirme kuralı, olay eşleşme kalitesi ve KVKK açısından dikkat edilecekler.

Fratres Editör · 11 Kasım 2026

Meta Dönüşüm API'si (Conversions API, kısaca CAPI), satın alma veya form gibi dönüşüm olaylarını tarayıcı yerine işletmenin sunucusundan, CRM'inden ya da e-ticaret altyapısından doğrudan Meta'ya gönderen bağlantıdır. Pixel'in yerine geçmez, onun yanında çalışır. Gerekli olmasının nedeni basit: Meta'nın reklam sistemi neyi ölçebiliyorsa onu optimize eder ve satışın gerçekleştiği yer çoğu zaman tarayıcı değildir.

Pixel varken neden ikinci bir bağlantı gerekir?

Pixel ziyaretçinin tarayıcısında çalışan bir koddur. Sayfa yarım yüklenirse, tarayıcı izleme kodunu kısıtlarsa veya kullanıcı engelleyici kullanırsa olay hiç gönderilmeyebilir. Sunucu bağlantısı bu katmana bağlı değildir.

Daha büyük fark, tarayıcının hiç görmediği olaylardadır. Meta'nın geliştirici belgesine göre Dönüşümler API'si web sitesi, uygulama, işletme mesajlaşması ve çevrim dışı olayları taşır. Veri sunucudan, site altyapısından, mobil uygulamadan veya CRM'den gelebilir ve ölçüm, raporlama ve optimizasyonda Pixel olayları gibi işlenir. Telefonla kapanan satış, mağazada tamamlanan alışveriş veya satış ekibinin "nitelikli" diye işaretlediği potansiyel müşteri ancak bu yolla reklam sistemine ulaşır.

B2B tarafında etkisi ölçülmüş bir örnek var. Meta'nın potansiyel müşteri kampanyaları sayfası, CRM'i Dönüşümler API'sine bağlayıp "dönüşüm potansiyel müşterileri" hedefini kullanan reklamverenlerde nitelikli potansiyel müşteri başına maliyetin ortalama %15 düştüğünü, potansiyel müşteriden nitelikli müşteriye geçiş oranının %44 arttığını yazıyor. Bunlar Meta'nın yöntemini göstermediği kendi ortalamaları, ama yön açık: Sistem form doldurana değil, satışa dönüşene göre öğrenince sonuç değişir. Bu, bütçe ve kitle kararını sisteme bırakan Advantage+ kampanyalarında daha da belirleyici olur.

Dönüşümler API'si nasıl çalışır?

Her olay, sunucudan Meta'ya giden bir istekle iletilir. Sunucu olayı parametrelerine göre temel alanlar şunlardır:

event_name: Olayın adı, örneğin Purchase veya Lead.
event_time: Olayın gerçekleştiği an, GMT saatiyle Unix zaman damgası. Olay en fazla 7 gün geriye tarihli gönderilebilir.
action_source: Olayın gerçekleştiği yer. Kabul edilen değerler arasında website, app, phone_call, chat, physical_store ve business_messaging var.
event_id: Olaya verdiğiniz benzersiz kimlik. Belgede isteğe bağlı görünür ama tekilleştirme için önerilir.

Parametre belgesine göre web olaylarında ayrıca tarayıcı bilgisi (client_user_agent) ve olayın gerçekleştiği sayfa adresi (event_source_url) zorunludur. Müşteri bilgileri eşleştirme için gönderilir, ama kurallı biçimde. E-posta, telefon, ad, soyad, cinsiyet, doğum tarihi, şehir, posta kodu ve ülke karma (hash) uygulanmış olarak gider. IP adresi, tarayıcı bilgisi ve Meta'nın çerez kimlikleri olan fbp ile fbc ise karma uygulanmadan gönderilir.

Tekilleştirme: Aynı satış iki kez sayılmasın

Pixel ile sunucu aynı satışı bildirince Meta'nın bunu tek olay sayması gerekir. Meta'nın önerdiği yöntem olay kimliği ile olay adının iki tarafta aynı olmasıdır: Pixel'deki eventID, sunucudaki event_id ile, Pixel'deki olay adı sunucudaki event_name ile eşleşmelidir. Aynı çift 48 saat içinde gelirse sonraki kopyalar atılır ve sistem genelde ilk geleni tutar. fbp veya external_id ile yapılan alternatif eşleştirme ise yalnız tarayıcı olayı önce gelirse işler. Bu yüzden kimliği satış anında bir kez üretip iki tarafa aynı değeri vermek en sağlam yoldur.

Hangi yöntemle kurulur?

Doğru yöntem, ekibinizin teknik kapasitesine ve hangi olayları göndereceğinize bağlıdır.

Events Manager üzerinden hızlı kurulum: Meta, sitede Pixel varsa Events Manager'dan kod yazmadan ve kurulum ücreti olmadan bağlantı açılabildiğini belirtiyor. Yalnız web olayları için en kısa yoldur.
Platform veya iş ortağı entegrasyonu: E-ticaret altyapınız ya da CRM'iniz hazır bir bağlantı sunuyorsa bakımı sağlayıcı üstlenir. Hangi olayları, hangi müşteri bilgileriyle gönderdiğini mutlaka kontrol edin.
Conversions API Gateway: Meta'nın belgesine göre kendi bulut hesabınızda (AWS EKS, AWS ECS Express veya GCP) çalışan, Pixel olaylarını sunucu olayına çeviren bir sunucudur. Kod gerektirmez, tekilleştirme kimliğini kendisi üretir. Tek maliyeti bulut kaynağı veya iş ortağı ücretidir.
Sunucu taraflı Google Etiket Yöneticisi: Sitenizde GA4 etiketi zaten çalışıyorsa olaylar sunucu kapsayıcısına gelir ve Meta'nın bakımını yaptığı etiket şablonu onları Meta'ya iletir. Mimari için sunucu taraflı etiketleme yazısına bakabilirsiniz.
Doğrudan entegrasyon: Geliştirici, olayları kendi sunucunuzdan gönderir. CRM aşamaları ve çevrim dışı satışlar gibi tarayıcıda hiç oluşmayan olaylar için çoğu zaman tek yol budur.

Adım adım kurulum

Olay listesini çıkarın. Sayfa görüntüleme, sepete ekleme, satın alma, form ve CRM'deki nitelikli aşama gibi olayları ve her birinin değerini yazın.
Yöntemi seçin. Web olayları için hızlı kurulum veya Gateway, CRM olayları için doğrudan entegrasyon ya da iş ortağı.
Olay kimliğini tasarlayın. Sipariş numarası gibi doğal bir kimlik varsa onu kullanın, yoksa satış anında rastgele bir değer üretip Pixel ve sunucuya aynısını verin.
Müşteri bilgilerini hazırlayın. Yalnız aydınlatma ve rıza süreçlerinizin kapsadığı alanları gönderin, karma kuralına uyun.
Test edin. Sunucu taraflı GTM belgesi, Test Events ekranında kimliklerin eşleştiğine bakmayı ve yayına almadan önce test kodunu (test_event_code) kaldırmayı hatırlatıyor.
CRM aşamalarını bağlayın. Nitelikli potansiyel müşteri ve kapanan satış gibi aşamaları, kaydın oluştuğu zamana göre 7 gün içinde gönderin.

Kurulumun doğru çalıştığını nasıl anlarsınız?

Meta'nın doğrulama belgesi, gönderilen olayların Events Manager'da 20 dakika içinde görünmesi gerektiğini yazıyor. Sonra şu göstergelere bakın:

Olay eşleşme kalitesi (Event Match Quality): Dataset Quality API belgesine göre gönderdiğiniz müşteri bilgilerinin olayı bir Meta hesabıyla eşleştirmedeki etkisini 10 üzerinden puanlar ve şimdilik yalnız web olayları için hesaplanır. Doğrulama belgesi 6,0 ve üzerini öneriyor.
Olay kapsamı (event coverage): Pixel olaylarının ne kadarının Dönüşümler API'siyle de geldiğini, 7 günlük ortalama olarak gösterir.
Tekilleştirme oranı: Event Details altındaki Event Deduplication sekmesinde görünür. Oran düşükse kimlik bir tarafta eksiktir ya da iki tarafta farklı üretiliyordur.
Olay tazeliği: Olayın gerçekleşmesiyle Meta'ya ulaşması arasındaki gecikmeyi gerçek zamanlıdan haftalığa kadar bir ölçekte gösterir.
İş verisiyle karşılaştırma: Meta'nın bildirdiği satın alma sayısını aynı haftanın sipariş sistemi kaydıyla yan yana koyun. Fark büyükse sorun ölçümdedir, kampanyada değil.

Dataset Quality API ayrıca "ek raporlanan dönüşümler" (Additional Conversions Reported) metriğini verir. Bu metrik, sunucu bağlantısının Pixel'e kaç ek olay kattığını gösterir. Reklamın yarattığı ek satışı göstermez. Onu ölçmek için kontrol gruplu deney gerekir.

Türkiye'de durum: KVKK ve yurt dışına aktarım

Sunucudan giden olaylar, karma uygulanmış da olsa müşteri bilgisinden türetilir ve yurt dışında yerleşik bir şirkete iletilir. Bu akışın 6698 sayılı Kişisel Verilerin Korunması Kanunu'ndaki yurt dışına aktarım kurallarına göre nasıl dayandırılacağı hukuk ekibinizle netleştirilmelidir.

Kanunun 9. maddesi 7499 sayılı Kanun'la değişti. Kişisel Verileri Koruma Kurumu'nun duyurusuna göre aktarım standart sözleşmeye dayanıyorsa sözleşme, imzadan itibaren beş iş günü içinde Kuruma bildirilmelidir. Kurul, 17.10.2024 tarihli ve 2024/1793 sayılı kararıyla bu bildirimin internetten yapılabildiği bir modül açtı. Sitedeki aydınlatma metni ve çerez tercihleri de aynı kurguya uymalıdır. Bunun için KVKK çerez rehberi yazısına bakabilirsiniz. Bu bölüm genel bilgi verir, hukuki danışmanlık yerine geçmez.

Sık yapılan hatalar

Kimliği tek tarafta göndermek. Pixel'de eventID yoksa tekilleştirme çalışmaz ve satışlar şişer.
Olay adlarını iki tarafta farklı yazmak. Ad eşleşmezse Meta iki ayrı olay görür.
Yanlış alana karma uygulamak. IP, tarayıcı bilgisi, fbp ve fbc düz gönderilir, e-posta ve telefon karma ile.
Geç kalan CRM verisi. 7 günden eski olaylar kabul edilmez. Toplu yüklemeyi haftalık değil günlük yapın.
Test kodunu yayında bırakmak. Olaylar test ekranına düşer, raporlama ve optimizasyon eksik kalır.
"Ek raporlanan dönüşümü" kazanç sanmak. Daha çok olay görmek, daha çok satış yapmak demek değildir.

Yarın Events Manager'da üç ekranı açın

Satın alma veya potansiyel müşteri olayınız için Events Manager'da olay eşleşme kalitesine, Event Deduplication sekmesine ve olay tazeliğine bakın. Son yedi günün Meta satın alma sayısını sipariş sisteminizdeki sayıyla karşılaştırın ve farkı not edin. Eşleşme puanı düşük, tekilleştirme zayıf ya da fark büyükse ilk iş olay kimliğini ve müşteri bilgisi alanlarını düzeltmektir. Ölçüm kurgusunu GA4 ve Etiket Yöneticisi ile birlikte ele almak isterseniz GA4 / GTM ve Meta Ads sayfaları kapsamı anlatır.