Siparişler ve iadeler · Belgeler

Siparişleri ve iadeleri sunucudan göndermek

Reklam platformları satışı çerezle sayar; ziyaretçilerin çoğu çerezi reddettiğinde Google Analytics ve Google Ads reklamdan gelen satışın küçük bir kısmını görür. Siparişleri kendi sunucunuzdan adall'a gönderdiğinizde adall her satışı sayar, reklam kararlarını gerçek ciro ve kârla verir ve rızası olan satışları Google'a kendisi yükler. Bu sayfa yazılımcınızın kurulumu baştan sona yapması içindir; yaklaşık yarım gün sürer.

1. Anahtarı alın

Panelde Ayarlar › Bağlantılar › Siparişleri doğrudan adall'a gönder › Yazılımcın için kurulum bilgileri bölümünde Anahtar oluştur'a basın. Bir anahtar (X-Adall-Key) ve bir gizli değer görürsünüz; gizli değer yalnız bir kez gösterilir.

İkisini de sunucunuzun ortam değişkenlerine yazın (ör. ADALL_KEY, ADALL_SECRET). Koda, depoya ya da bir yönetim paneli ayarına yazmayın.
Anahtar sızarsa aynı yerden iptal edip yenisini oluşturun; eskisiyle gelen istekler hemen reddedilir.

2. Ne zaman, ne gönderilir

Ödeme kesinleştiğinde bir order olayı. Sepet ya da ödeme denemesi değil: para tahsil edildiğinde.
Karta iade yapıldığında bir refund olayı. Kısmi iadede yalnız iade edilen tutar. Ödeme sağlayıcınızın panelinden yapılan iadeleri de gönderin (ör. Stripe charge.refunded webhook'u).
Hediye çeki, bakiye ya da puanla ödenen kısım satış sayılmaz; value müşteriden gerçekten tahsil edilen tutardır.

3. Olayın alanları

event_id (zorunlu, en çok 128): olayın kalıcı kimliği. Aynı kimlik ikinci kez gelirse bir kez sayılır; örneğin order-<sipariş no>, refund-<iade no>.
type (zorunlu): order ya da refund.
occurred_at (zorunlu): ödemenin ya da iadenin zamanı, ISO 8601. Son 400 gün içinde olmalı.
reference (zorunlu): sipariş numaranız. İade, siparişle aynı numarayı taşır.
value.amount_minor ve value.currency (zorunlu): küçük birimle tutar (699,00 TL = 69900) ve üç harfli büyük para birimi (TRY).
profit.amount_minor (isteğe bağlı, önerilir): siparişin kârı, aynı para biriminde (satış − ürün maliyeti). Maliyeti bilmiyorsanız göndermeyin; adall o zaman ciroyla karar verir.
country: siparişin ülkesi (fatura ya da teslimat, iki harf). Ülke kararları bununla verilir.
click_ids: ziyaretçinin geldiği tıklamanın kimlikleri: gclid, gbraid, wbraid (Google), fbclid, fbc, fbp (Meta), msclkid, ttclid. Açılış adresindeki parametrelerden okuyup siparişe kadar saklayın.
utm: source, medium, campaign, term, content. adall'ın kurduğu Google kampanyalarında utm_campaign kampanya numarasıdır; satışı kampanyasına adall bununla yazar. Tıklama kimliği gibi rıza olmasa da siparişle saklayın: kişisel veri değildir. Siparişlerin çoğu kampanyasız gelirse adall kendi sayımıyla karar veremez.
customer.email_sha256: e-postanın küçük harfli ve boşluksuz hâlinin SHA-256 özeti. customer.external_id: müşteri numaranız. Düz e-posta ya da telefon gönderilmez.
consent: aşağıdaki 5. adım.
session.landing_url, session.first_touch_at: ilk ziyaretin adresi ve zamanı (isteğe bağlı).

4. İmza ve istek

POST https://live.adall.io/api/v1/events, gövde {"schema_version":1,"events":[…]}; bir istekte en çok 100 olay.

X-Adall-Key: anahtarınız.
X-Adall-Timestamp: şu anki Unix saniyesi. Beş dakikadan eski ya da ileri istek reddedilir; sunucu saatiniz doğru olmalı.
X-Adall-Signature: sha256= + HMAC-SHA256(gizli değer, "{timestamp}.{gövde}") onaltılık. İmzalanan gövde, gönderdiğiniz baytların aynısı olmalı: önce JSON'u metne çevirin, sonra imzalayın ve o metni gönderin.

Hazır kod: Kod örnekleri.

5. Rıza: bilmiyorsanız göndermeyin

adall bir siparişi Google'a ya da Meta'ya yalnız consent.ad_user_data granted ise yükler. Rıza bloğu hiç gelmezse rıza yok sayılır: sipariş adall'ın kararlarında sayılır ama platforma gitmez ve panelde "rıza yok" diye yazar.

Ödeme anında çerez bannerınızın (rıza yönetim platformunuzun) reklam/pazarlama kararını siparişe kaydedin ve onu gönderin: ad_user_data, ad_personalization, ad_storage için granted ya da denied, source (ör. veribenim), varsa proof_id ve given_at.
Bilmediğiniz rızayı asla granted göndermeyin. Bilinmiyorsa consent'i hiç göndermeyin.
Rıza sonradan geri çekilirse Rıza sayfasındaki uçla bildirin.

6. Kuyruk, yeniden deneme, siparişi asla durdurmamak

Gönderimi ödeme isteğinin içinde değil, bir arka plan işinde (kuyrukta) yapın. adall'a ulaşılamaması siparişi, ödemeyi ya da teslimatı hiçbir zaman etkilememelidir.
Cevap 202'dir ve her olay için accepted, duplicate ya da rejected (+ errors) döner. duplicate başarıdır.
429, 5xx ya da ağ hatası: birkaç dakika sonra aynı event_id ile yeniden deneyin (ör. 3 deneme, 1 ve 10 dakika arayla). Her denemede yeni zaman damgası ve imza üretin.
409 ERR_REPLAYED_REQUEST: aynı imzalı istek zaten işlendi; teslim edilmiş sayın.
401: anahtar ya da imza yanlış, iptal edilmiş ya da saat kaymış. Yeniden denemek düzeltmez; ekibinize alarm verin, çünkü bundan sonraki her sipariş kaybolur.
422 ya da olay başına rejected: alanlardan biri kurala uymuyor; errors'ı loglayın.

7. Geçmişi bir kez gönderin

Kurulumdan sonra son 90 günün ödenmiş siparişlerini aynı biçimle bir kez gönderin (100'lük paketler, dakikada en çok 600 istek). event_id aynı kaldığı için tekrar çalıştırmak güvenlidir.

8. Google'a yüklemeyi açın

Olaylar adall'a geldiği anda adall'ın kararlarında sayılır; Google'a gitmesi için bir kez kurulum gerekir. Panelde Ayarlar › Google'da dönüşüm ayarları › adall dönüşümlerini Google'a kur'a basın ve "Satış"ı seçin. Google Ads'te "Adall · Purchase" dönüşümü açılır ve önce test modunda doğrulanır; doğrulanan yüklemelerden sonra adall onu kendiliğinden canlıya alır (yönetim modu "Tavsiye" ise canlıya almayı siz onaylarsınız).

9. Doğrulama

Canlıda gerçek bir sipariş verin (ya da küçük bir test siparişi).
Panelde Ayarlar › Bağlantılar › Siparişleri doğrudan adall'a gönder bölümünde "son 24 saatte N olay" sayısı artmalı ve "son olay" saati güncellenmeli.
Anahtar listesinde anahtarın "son kullanım" zamanı görünür.
8. adım yapıldıysa, reklam tıklaması ve rızası olan sipariş Google Ads'te "Adall · Purchase" dönüşümüne düşer (önce test olarak; Google'ın raporunda 3 saate kadar gecikebilir). Rızası olmayan sipariş Google'a hiç gitmez, adall'da sayılır.
Sayı artmıyorsa sunucu loglarınızda adall'ın cevabına bakın: 401 anahtar, rejected alan sorunu demektir.