Sinyal API'siyle çalışmak.

Temel kavramlar

Kimlik doğrulama

Makine-makine istekleri API anahtarıyla yetkilendirilir. Anahtarı Authorization başlığında Bearer şeması ile gönderin. Canlı anahtarlar sk_live_, test anahtarları sk_test_ önekiyle başlar.

Authorization: Bearer sk_live_8a2f7c...

Anahtarlar sunucuda yalnız SHA-256 hash'iyle saklanır; düz metin yalnız oluşturma anında bir kez gösterilir. Sızan bir anahtarı DELETE /v1/api-keys/{id} ile anında iptal edebilirsiniz. Her anahtarın kapsamları (scope) vardır:

Anahtarları sunucu tarafında tutun; tarayıcı veya mobil koda gömmeyin. Üretim sunucunuz için yalnız events:write kapsamı yeterlidir; en az yetki ilkesini uygulayın.

Hızlı başlangıç

Bir satın alma eventini Sinyal'e göndermek için gereken tek çağrı:

curl -X POST /v1/events \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: order_98213" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "order_98213",
    "event_name": "Purchase",
    "event_time": "2026-07-13T14:32:11Z",
    "user": {
      "email": "musteri@example.com",
      "phone": "+905551234567",
      "ip": "85.105.12.7",
      "user_agent": "Mozilla/5.0 ..."
    },
    "properties": {
      "currency": "TRY",
      "value": 1899.90,
      "order_id": "98213",
      "content_ids": ["SKU-123", "SKU-456"]
    }
  }'

Başarılı istekte 202 Accepted döner: event kalıcı kaydedilmiş, aktif her hedef için bir teslimat işi kuyruğa alınmıştır. Teslimat sonucunu GET /v1/events/{id}/deliveries ile veya panelden izlersiniz.

Event gönderme

POST /v1/events tek bir dönüşüm eventini kabul eder (scope: events:write). İstek başlıkları:

Gövde alanları:

Eventin hangi platformlara gideceği gövdede belirtilmez: event, tenant'ınızda tanımlı ve aktif olan tüm hedeflere fan-out edilir. Hedefleri Hedefler bölümündeki uçlarla yönetirsiniz.

Event nesnesi

Tam bir event gövdesi:

{
  "event_id": "order_98213",
  "event_name": "Purchase",
  "event_time": "2026-07-13T14:32:11Z",
  "source": "backend-api",
  "user": {
    "email": "musteri@example.com",
    "phone": "+905551234567",
    "first_name": "Ali",
    "last_name": "Yilmaz",
    "city": "Istanbul",
    "zip": "34000",
    "country": "TR",
    "external_id": "cust_1029",
    "ip": "85.105.12.7",
    "user_agent": "Mozilla/5.0 ...",
    "fbp": "fb.1.1751530000.998877",
    "fbc": "fb.1.1751536000.AbCd",
    "ttclid": "E.C.P.v1..."
  },
  "properties": {
    "currency": "TRY",
    "value": 1899.90,
    "order_id": "98213",
    "content_type": "product",
    "content_ids": ["SKU-123", "SKU-456"],
    "contents": [
      { "id": "SKU-123", "quantity": 1, "item_price": 1499.90 },
      { "id": "SKU-456", "quantity": 1, "item_price": 400.00 }
    ],
    "num_items": 2
  },
  "context": {
    "page": {
      "url": "https://magaza.example.com/tesekkurler",
      "referrer": "https://magaza.example.com/sepet"
    },
    "session_id": "sess_8f31"
  }
}

properties altında ayrıca search_string (arama eventleri) ve predicted_ltv (tahmini yaşam boyu değer) alanları desteklenir. value ondalık gönderilir (ör. 1899.90); tam sayı isteyen platformlar için dönüşümü Sinyal yapar.

Kullanıcı kimliği (eşleştirme)

Platformlar dönüşümü bir kullanıcıya bağlamak için kimlik sinyallerini kullanır. Ne kadar çok sinyal gönderirseniz eşleşme kalitesi (ör. Meta EMQ) o kadar yükselir. Kurallar: en az bir güçlü tanımlayıcı (email, phone veya external_id) zorunludur; ip ve user_agent her event'te zorunludur.

Ham PII'yi düz gönderebilirsiniz; normalizasyon ve SHA-256 hash'lemeyi Sinyal alım anında yapar. Kendi tarafınızda hash'lemek isterseniz 64 karakterlik küçük-harf hex değer gönderin; zaten hash'lenmiş görünen değerler ikinci kez hash'lenmez.

Doğrulama kuralları

Alım anında uygulanan kuralların özeti:

Kurallara uymayan istek 422 ile reddedilir; yanıtta hangi alanın hangi kuralı ihlal ettiği alan bazında listelenir (bkz. Hata modeli).

Tekilleştirme

Ağ yeniden denemeleri ve çift tetiklemeler aynı eventi birden çok kez gönderebilir. Sinyal iki bağımsız katmanda korur:

1. Idempotency-Key (HTTP katmanı)

Aynı Idempotency-Key + aynı gövde 24 saat içinde tekrar gelirse ilk isteğin yanıtı önbellekten döner ve yanıtta Idempotent-Replayed: true başlığı yer alır. Aynı anahtar farklı gövdeyle gelirse 409 döner. Batch isteğinde anahtar, batch'in bütününe uygulanır.

2. event_id (event katmanı)

Aynı event_id 24 saat penceresinde ikinci kez gelirse event bir daha kaydedilmez, yeni teslimat işi açılmaz; yanıtta "deduplicated": true döner. İlk yazım kazanır; sonraki kopyanın alanları asla ilk kaydın üstüne yazılmaz.

Öneri: satın almada event_id = sipariş numarası kullanın. Tarayıcı pikseli ile Sinyal'i birlikte çalıştırıyorsanız iki tarafta da aynı event_id'yi gönderin; platform (ör. Meta) çift saymayı kendi tarafında da engeller.

PII ve hash

API'nin kabul ettiği gövde ham PII taşır; alım işleyicisi bu alanları SHA-256 ile hash'ler ve ham değerleri kalıcılık ya da loglama öncesinde siler. Veritabanında yalnız hash'ler durur; GET /v1/events/{id} da yalnız hash'lenmiş değerleri döndürür, çünkü ham değer sistemde yoktur.

Saklanan kimlik bloğu Meta CAPI kısaltmalarıyla tutulur (em, ph, fn, ln, ct, zp); platform adaptörlerine eşleme bu sayede mekaniktir. IP ve user agent, platformların eşleştirme için ham istediği alanlar olduğundan hash'lenmez.

KVKK açısından mimari veri minimizasyonunu gözetir: dönüşüm eşleştirmesi için gerekli alanlar işlenir, ham kişisel veri kalıcı depolanmaz. Teknik detay için KVKK teknik dokümanını talep edebilirsiniz.

Toplu gönderim

Geçmiş dönüşümleri veya yüksek hacmi tek çağrıda göndermek için POST /v1/events:batch kullanın. En çok 1000 event, toplam gövde en çok 5 MB.

curl -X POST /v1/events:batch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event_id": "order_98213", "event_name": "Purchase",
        "event_time": "2026-07-13T14:32:11Z",
        "user": { "email": "a@example.com", "ip": "85.105.12.7", "user_agent": "..." },
        "properties": { "currency": "TRY", "value": 199.00 } },
      { "event_id": "form_88", "event_name": "Lead",
        "event_time": "2026-07-13T14:40:00Z",
        "user": { "phone": "+905320000000", "ip": "85.105.12.8", "user_agent": "..." } }
    ]
  }'

Her event kendi işleminde koşar: bir satırın reddi diğerlerini düşürmez. Yanıt 200 ile satır bazında sonuç döndürür:

{
  "results": [
    { "index": 0, "status": "accepted", "id": "evt_01HV...", "event_id": "order_98213", "deduplicated": false },
    { "index": 1, "status": "rejected", "event_id": "form_88",
      "error": {
        "type": ".../errors/validation",
        "detail": "One or more fields failed validation.",
        "errors": [ { "field": "user.user_agent", "detail": "is required", "code": "required" } ]
      } }
  ],
  "summary": { "accepted": 1, "duplicated": 0, "rejected": 1, "total": 2 }
}

Hedefler

Hedef (destination), eventlerin fan-out edileceği bir platform bağlantısıdır. Hedefler event gövdesinde değil, kaynak olarak tanımlanır: bir kez oluşturursunuz, sonrasında her event aktif hedeflerin tümüne dağıtılır.

curl -X POST /v1/destinations \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "type": "meta_capi",
    "name": "Ana Pixel (production)",
    "config": { "pixel_id": "123456", "api_version": "v19.0" },
    "credentials": { "access_token": "EAA..." }
  }'

Hedef yönetiminin önemli davranışları:

API anahtarları

İlk anahtar onboarding'de verilir (* kapsamlı). Sonrasında anahtarları API'den yönetebilirsiniz:

curl -X POST /v1/api-keys \
  -H "Authorization: Bearer sk_live_OWNER..." \
  -d '{ "name": "shopify entegrasyonu", "scopes": ["events:write"] }'

# Yanıt — secret yalnız bu yanıtta görünür:
# { "id": "key_01HW...", "key_prefix": "sk_live_3b91",
#   "secret": "sk_live_3b91d8c...", "scopes": ["events:write"], ... }

GET /v1/api-keys anahtarları önek + son kullanım zamanıyla listeler (sır içermez). DELETE /v1/api-keys/{id} anahtarı anında ve geri alınamaz biçimde iptal eder.

Yanıtlar

Başarılı tekil gönderimde 202 Accepted döner: event kalıcıdır, teslimatlar kuyruğa alınmıştır (henüz denenmemiştir).

{
  "id": "evt_01HV2QY9NM...",
  "event_id": "order_98213",
  "received_at": "2026-07-13T14:32:11.842Z",
  "deduplicated": false,
  "deliveries": [
    { "id": "dlv_01HV...", "destination_id": "dst_01HV...",
      "destination_type": "meta_capi", "status": "pending" },
    { "id": "dlv_01HW...", "destination_id": "dst_01HW...",
      "destination_type": "tiktok_events", "status": "pending" }
  ]
}

Duplike eventte aynı şekil "deduplicated": true ve boş deliveries ile döner. Durum kodları:

Hata modeli

Hatalar RFC 7807 (problem+json) formatındadır. request_id her hata yanıtında bulunur; destek taleplerinde bu değeri iletin.

{
  "type": ".../errors/validation",
  "title": "Invalid event",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "instance": "/v1/events",
  "request_id": "req_01HV2QY9NM...",
  "errors": [
    { "field": "properties.currency", "detail": "is required for Purchase events", "code": "required" },
    { "field": "event_time", "detail": "is more than 7 days in the past", "code": "out_of_range" }
  ]
}

Teslimat durumu

Bir eventin hedef bazında teslimat geçmişi için GET /v1/events/{id}/deliveries kullanın (scope: events:read). Aynı bilgi panelde hedef sağlığı ve son hatalar görünümüyle de sunulur.

{
  "deliveries": [
    {
      "id": "dlv_01HV...",
      "destination_id": "dst_01HV...",
      "destination_type": "meta_capi",
      "status": "sent",
      "attempt_count": 1,
      "finalized_at": "2026-07-13T14:32:13.214Z",
      "response_status": 200,
      "latency_ms": 1372
    },
    {
      "id": "dlv_01HW...",
      "destination_id": "dst_01HW...",
      "destination_type": "tiktok_events",
      "status": "retrying",
      "attempt_count": 2,
      "error_class": "server_error",
      "error_message": "TikTok 503 Service Unavailable"
    }
  ]
}

Her deneme kaydı hata sınıfı, platform yanıt kodu, gecikme ve maskelenmiş istek/yanıt özetleri taşır. Kara kutu yok: hangi deneme neden düştü, hedef bazında görünür.

Retry ve DLQ

Hedef geçici hata (5xx, zaman aşımı, platform oran sınırı) döndürürse teslimat işi üstel backoff ile yeniden denenir. Varsayılan deneme bütçesi hedef başına 6'dır ve hedefin max_attempts ayarıyla değiştirilebilir. Bütçe tükenince kayıt dead_lettered işaretlenir ve ölü mektup kuyruğuna düşer; kaybolmaz.

DLQ'daki teslimatlar panelin son-hatalar görünümünde listelenir ve pilot sürecinde operasyon ekibi tarafından sizinle birlikte yeniden kuyruğa alınır. Doğrulama (validation) hataları yeniden denenmez; bunlar istek anında 422 ile size döner.

Test modu

Üretime event basmadan uçtan uca doğrulamak için üç mekanizma vardır:

Oran sınırları

Sınırlar API anahtarı başına token bucket ile uygulanır ve plana göre belirlenir:

Her yanıtta X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları döner; sınır aşımında 429 ile birlikte Retry-After (saniye) gelir. Yüksek hacimde tekil çağrı yerine batch ucunu tercih edin: 1000 event tek isteğe sığar.

Kod örnekleri

Node.js

const res = await fetch(`${SINYAL_BASE_URL}/v1/events`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SINYAL_KEY}`,
    "Idempotency-Key": `order_${order.id}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event_id: `order_${order.id}`,
    event_name: "Purchase",
    event_time: new Date().toISOString(),
    user: {
      email: customer.email,
      phone: customer.phone,
      ip: req.ip,
      user_agent: req.get("user-agent"),
    },
    properties: {
      currency: "TRY",
      value: order.total,
      order_id: String(order.id),
    },
  }),
});

if (res.status !== 202) {
  const problem = await res.json();
  console.error("Sinyal reddetti:", problem.status, problem.detail, problem.errors);
}

Python

import os, requests
from datetime import datetime, timezone

resp = requests.post(
    f"{os.environ['SINYAL_BASE_URL']}/v1/events",
    headers={
        "Authorization": f"Bearer {os.environ['SINYAL_KEY']}",
        "Idempotency-Key": f"order_{order_id}",
        "Content-Type": "application/json",
    },
    json={
        "event_id": f"order_{order_id}",
        "event_name": "Purchase",
        "event_time": datetime.now(timezone.utc).isoformat(),
        "user": {
            "email": email,
            "phone": phone,
            "ip": client_ip,
            "user_agent": user_agent,
        },
        "properties": {"currency": "TRY", "value": total, "order_id": str(order_id)},
    },
    timeout=5,
)

if resp.status_code != 202:
    problem = resp.json()
    print("Sinyal reddetti:", problem["status"], problem["detail"], problem.get("errors"))

Sürümleme

Sözleşme değişikliklerinde uyguladığımız kurallar:

İstemciler bilmedikleri yanıt alanlarını yok saymalıdır. Kanonik event şeması schema_version ile ayrıca sürümlenir (şu an 1).

Entegrasyon sırasında takıldığınız bir nokta olursa Sinyal sayfasındaki iletişim kanalından ulaşabilirsiniz; hata yanıtındaki request_id'yi eklemeyi unutmayın.