Conversions API ile Sunucu Taraflı Dönüşüm Gönderme: OpenAI Ads Rehberi

OpenAI Ads Conversions API, dönüşüm olaylarını tarayıcıdan değil sunucudan gönderir. Pixel’in ateşleyemediği, reklam engelleyiciyle kesilen ya da offline gerçekleşen dönüşümleri doğrudan OpenAI’ye iletir¹. Bu rehber sunucu tarafını çalışır hale getirir: istek yapısı, event alanları, batch davranışı, validate_only ile test ve pixel ile dedup.

Pixel’in tarayıcı tarafındaki kurulumu ve iki katmanın neden birlikte kullanıldığı ayrı yazıların konusu; burada odak sunucu tarafı.

API Key

Pixel ID ve Conversions API anahtarı Ads Manager’ın conversions sekmesinden edinilir¹. API anahtarı sunucuda kalır; istemci koduna ya da tarayıcıya asla sızdırılmaz. Conversions API yalnızca sunucu tarafında çalışır.

İstek Yapısı

Olaylar, Pixel ID’yi pid sorgu parametresiyle taşıyan uç noktaya POST edilir. Kimlik doğrulama Authorization: Bearer başlığıyla yapılır. İstek gövdesi iki alan taşır: validate_only ve events¹.

curl -X POST "https://bzr.openai.com/v1/events?pid=<PIXEL-ID>" \
  -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "validate_only": false,
    "events": []
  }'

validate_only: true gönderildiğinde olaylar kaydedilmeden doğrulanır; gerçek gönderim için false kullanılır¹.

Event Alanları

Her event birkaç zorunlu, birkaç koşullu ve birkaç opsiyonel alan taşır. data nesnesi tipe uygun şekli kullanır: contents, customer_action ya da plan_enrollment².

Alan	Zorunluluk	Açıklama
id	Zorunlu	Tekil event kimliği; type ile dedup için kullanılır
type	Zorunlu	Standart event adı ya da custom
timestamp_ms	Zorunlu	Milisaniye; son 7 gün içinde, en fazla 10 dakika ileride
data	Zorunlu	Tipe uygun event verisi
custom_event_name	Koşullu	type custom ise zorunlu
source_url	Koşullu	action_source web ise zorunlu
action_source	Opsiyonel	web, mobile_app, offline, physical_store, phone_call, email, other
oppref	Opsiyonel	OpenAI gizlilik koruyan kimliği; otomatik gelmez, elle taşınır
user	Opsiyonel	Kimlik eşleştirme alanları
opt_out	Opsiyonel	true ise event kişiselleştirme dışı; varsayılan false

timestamp_ms penceresi sessiz bir tuzak: son 7 günü aşan ya da 10 dakikadan fazla ileri tarihli event’ler kabul edilmez. Offline ve CRM dönüşümlerini geç gönderirken bu sınıra dikkat etmek gerekir.

Tam Örnek Event

Bir siparişin tam event gövdesi şöyle görünür¹:

{
  "id": "order_12345",
  "type": "order_created",
  "timestamp_ms": 1773892800000,
  "oppref": "oppref_abc",
  "source_url": "https://magaza.example.com/odeme/onay",
  "action_source": "web",
  "user": {
    "email_sha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
    "external_id_sha256": "73d83a078369bb4f0971b317aa7797a91cf5c0df1b62161c2e47d75c33ab5b6e",
    "country": "US",
    "city": "San Francisco",
    "zip_code": "94107",
    "ip_address": "203.0.113.1",
    "user_agent": "Mozilla/5.0"
  },
  "data": {
    "type": "contents",
    "amount": 2599,
    "currency": "USD",
    "contents": [
      {
        "id": "sku_123",
        "name": "Starter bundle",
        "content_type": "product",
        "quantity": 1
      }
    ]
  }
}

Kimlik Eşleştirme

user nesnesindeki tüm alanlar opsiyoneldir; yalnızca elde olan gönderilir. E-posta ve dış kimlik SHA-256 ile hash’lenir ve küçük harf, 64 karakter onaltılık dize olarak iletilir. Coğrafi bilgi, IP ve user-agent ham gönderilebilir; ham e-posta, ham dış kimlik, telefon numarası ve telefon hash’i asla gönderilmez¹. Hash’leme yöntemi ve KVKK çerçevesi gizlilik tarafının konusu ve ayrı bir yazıda ele alınacak.

Batch ve Hata Davranışı

Bir istek en fazla 1000 event taşır. Kritik kural: batch içindeki tek bir hatalı event tüm batch’in reddedilmesine yol açar¹. Bu, sunucu tarafı tasarımını doğrudan etkiler:

• Gönderimden önce validate_only: true ile ön doğrula.
• Hatalı event’leri ayıran bir doğrulama katmanı ve retry kuyruğu kur.
• Büyük gönderimleri 1000’lik dilimlere böl.

Tek event yüzünden bütün batch’i kaybetmek, fark edilmeden dönüşüm kaybına yol açar; bu yüzden ön doğrulama opsiyonel değil.

Pixel ile Dedup

Aynı dönüşüm hem pixel hem Conversions API’den gönderiliyorsa, sunucudaki id ile pixel’deki event_id aynı değerde tutulur ve iki tarafta aynı Pixel ID kullanılır. Custom event’lerde eşleşme aynı custom_event_name ile yapılır¹. Tekilleştirmenin nasıl çalıştığı ve sık yapılan hatalar ayrı bir yazının konusu; burada yalnızca sunucu tarafında hangi alanın eşleşmeyi kurduğu önemli.

Sonraki Adımlar

Sunucu tarafı çalışınca sıra, iki katmanı çakışmadan uzlaştırmaya, yani dedup’ı doğru kurmaya gelir. event_id ve id eşleşmesinin ayrıntıları, kararlı kimlik üretimi ve sık yapılan hatalar bir sonraki yazının konusu.

Footnotes

1. Conversions API (OpenAI Developers) — sunucu taraflı uç nokta (bzr.openai.com/v1/events?pid=), istek gövdesi (validate_only, events), event alanları ve zorunlulukları (id/type/timestamp_ms/data zorunlu; timestamp “within the last 7 days and no more than 10 minutes ahead”), action_source değerleri, 1000 event batch (“If one event in the batch fails, the full batch fails.”), user object ve hash kuralları (lowercase 64-char hex; ham e-posta/dış kimlik/telefon asla), tam örnek event, pixel/server dedup (id = event_id + aynı Pixel ID, custom_event_name). ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸
2. Supported events (OpenAI Developers) — standart event taksonomisi ve data şekilleri (contents/customer_action/plan_enrollment), minor units kuralı, amount varsa currency zorunluluğu. ↩

Önemli Noktalar

• 01 Conversions API sunucudan sunucuya çalışır: bzr.openai.com/v1/events?pid=<PIXEL-ID> uç noktasına Bearer API anahtarıyla POST.
• 02 Her event zorunlu olarak id, type, timestamp_ms ve data taşır; timestamp son 7 gün içinde, en fazla 10 dakika ileride olmalı.
• 03 action_source web ise source_url zorunlu; type custom ise custom_event_name zorunlu.
• 04 Bir istek en fazla 1000 event; tek hatalı event tüm batch'i reddeder, bu yüzden validate_only ile ön doğrula ve retry kuyruğu kur.
• 05 Pixel ile dedup: sunucudaki id ile pixel'deki event_id aynı, iki tarafta aynı Pixel ID; custom event'lerde aynı custom_event_name.

Sık Sorulan Sorular (FAQ)

+ OpenAI Ads Conversions API'ye nasıl istek gönderilir?

Olaylar, bzr.openai.com/v1/events?pid=<PIXEL-ID> uç noktasına POST edilir. İstek Authorization: Bearer <API-KEY> başlığı ve Content-Type: application/json taşır; gövde validate_only ve events alanlarını içerir. Pixel ID ve API anahtarı Ads Manager'ın conversions sekmesinden alınır.

+ Bir event'te hangi alanlar zorunlu?

id (tekil event kimliği), type (standart event adı ya da custom), timestamp_ms ve data zorunlu. timestamp_ms son 7 gün içinde ve en fazla 10 dakika ileride olmalı. action_source web ise source_url, type custom ise custom_event_name zorunlu olur.

+ Bir istekte kaç event gönderilebilir?

Bir istek en fazla 1000 event alır. Batch içindeki tek bir hatalı event tüm batch'in reddedilmesine yol açar, bu yüzden gönderimden önce validate_only: true ile doğrulamak ve hatalı event'leri ayıran bir retry kuyruğu kurmak gerekir.

+ Sunucu ve pixel aynı dönüşümü gönderirse ne olur?

Çift sayımı önlemek için sunucudaki id ile pixel'deki event_id aynı tutulur ve iki tarafta aynı Pixel ID kullanılır. Custom event'lerde eşleşme aynı custom_event_name ile yapılır. Bu sayede OpenAI iki kaydı tek dönüşüm olarak sayar.