Satış Bildirimi API

Çerez Rehberi üzerinden sitenize gelen ziyaretçiler sipariş verdiğinde bunu bize bildirebilirsiniz. Böylece aylık olarak “bu kanaldan gelen toplam satış” raporunuz oluşur ve reklam yatırımınızın karşılığını somut rakamlarla görürsünüz.

Hızlı özet

• Tek uç nokta: POST /api/donusum
• Kimlik: Authorization: Bearer <anahtar>
• Zorunlu 3 alan: sipariş no, net tutar, tarih
• Aynı sipariş iki kez sayılmaz — güvenle tekrar gönderebilirsiniz

1. API anahtarı

Anahtarınızı biz üretir ve size bir kez iletiriz. Anahtar bizde yalnızca özeti (hash) olarak saklanır; kaybederseniz gösteremeyiz, yenisini üretiriz. Yeni anahtar üretildiğinde eskisi anında geçersiz olur.

Anahtar sunucu tarafında saklanmalıdır. Tarayıcı kodunda, mobil uygulamada veya herkese açık bir depoda bulundurmayın — anahtarı ele geçiren biri sizin adınıza satış bildirebilir.

Anahtarınızın geçerli olduğunu test etmek için:

curl -s https://cerezrehberi.com/api/donusum \
  -H "Authorization: Bearer cr_ANAHTARINIZ"

# Başarılı yanıt:
# {"ok":true,"firma":"firma-slug","mesaj":"API anahtarı geçerli."}

2. İstek modeli

POST https://cerezrehberi.com/api/donusum — gövde JSON olmalıdır.

Zorunlu alanlar

Alan	Tip	Açıklama
`siparisNo`	metin	Sipariş numaranız. En fazla 64 karakter. Tekilliği sağlayan alan budur.
`netTutar`	sayı	Müşterinin fiilen ödediği tutar (indirim sonrası, KDV dahil). Sıfırdan büyük olmalı.
`tarih`	metin	Sipariş tarihi, ISO biçimi: `2026-08-22` veya `2026-08-22T14:30:00Z`

İsteğe bağlı alanlar

Hiçbiri zorunlu değildir; gönderirseniz rapor zenginleşir.

Alan	Tip	Açıklama
`ilkFiyat`	sayı	İndirim öncesi liste tutarı. `netTutar`'dan küçük olamaz.
`indirimTutari`	sayı	Uygulanan indirim tutarı. Verilmezse `ilkFiyat`'tan hesaplanır.
`indirimOrani`	sayı	Yüzde olarak, 0-100 arası. Verilmezse hesaplanır.
`kalemSayisi`	tam sayı	Sepetteki ürün adedi.
`paraBirimi`	metin	3 harfli kod. Varsayılan `TRY`.
`not`	metin	Serbest not, en fazla 300 karakter.

3. Örnek istek

curl -X POST https://cerezrehberi.com/api/donusum \
  -H "Authorization: Bearer cr_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{
    "siparisNo": "SP-1043",
    "netTutar": 1250.50,
    "tarih": "2026-08-22",
    "ilkFiyat": 1490.00,
    "kalemSayisi": 3
  }'

PHP

$veri = [
  "siparisNo" => $siparis->kod,
  "netTutar"  => (float) $siparis->odenenTutar,
  "tarih"     => $siparis->tarih->format("c"),
  "ilkFiyat"  => (float) $siparis->listeTutari,
];

$ch = curl_init("https://cerezrehberi.com/api/donusum");
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    "Authorization: Bearer " . getenv("CEREZ_REHBERI_ANAHTAR"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode($veri),
  CURLOPT_TIMEOUT    => 10,
]);
$yanit = curl_exec($ch);
$kod   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// 200 değilse kuyruğa alıp tekrar deneyin — aynı siparisNo iki kez sayılmaz.

Node.js

const yanit = await fetch("https://cerezrehberi.com/api/donusum", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CEREZ_REHBERI_ANAHTAR}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    siparisNo: siparis.kod,
    netTutar: siparis.odenenTutar,
    tarih: siparis.tarih.toISOString(),
    ilkFiyat: siparis.listeTutari,
    kalemSayisi: siparis.kalemler.length,
  }),
});

if (!yanit.ok) {
  // Kuyruğa al ve tekrar dene. Tekrar göndermek güvenlidir.
  console.error("bildirim başarısız", yanit.status, await yanit.text());
}

4. Yanıt modeli

// 200 — başarılı
{
  "ok": true,
  "durum": "yeni",          // veya "guncellendi"
  "firma": "firma-slug",
  "siparisNo": "SP-1043"
}

// 400 — geçersiz veri
{ "ok": false, "hata": "netTutar sıfırdan büyük olmalı." }

// 401 — anahtar geçersiz
{ "ok": false, "hata": "Geçersiz veya eksik API anahtarı." }

Kod	Anlamı	Ne yapmalı
`200`	Kaydedildi	—
`400`	Veri hatalı	Tekrar denemeyin; gövdeyi düzeltin.
`401`	Anahtar geçersiz	Anahtarı kontrol edin, bizimle iletişime geçin.
`500`	Bizde hata	Kuyruğa alıp tekrar deneyin.

5. Tekrar gönderim güvenlidir

Kayıtlar siparisNo ile tekilleştirilir. Aynı sipariş numarasını tekrar gönderirseniz yeni kayıt açılmaz, mevcut kayıt güncellenir ve yanıtta "durum": "guncellendi" dönülür.

Bu sayede ağ hatalarında çekinmeden tekrar deneyebilirsiniz. Sipariş iptal veya iade olursa aynı numarayı düzeltilmiş tutarla göndermeniz yeterlidir.

6. Ne göndermemelisiniz

Bu uç noktaya müşteri kişisel verisi göndermeyin: ad, soyad, e-posta, telefon, adres, kart bilgisi veya müşteri kimliği istemiyoruz ve saklamıyoruz. Yalnızca sipariş numarası, tutar ve tarih yeterlidir.

Gönderdiğiniz veriler yalnızca size sunulan aylık performans raporunda kullanılır; üçüncü taraflarla paylaşılmaz.

Yardım

Entegrasyon sırasında takılırsanız iletisim@cerezrehberi.com adresine yazın. Reklam paketleri için reklam sayfamıza bakabilirsiniz.