Sipariş Ucu

Sipariş ucu, Selwise'in gelir ve atıf ölçümünün tek kaynağıdır: panelde göreceğiniz her satın alma ve ciro rakamı buraya gönderdiğiniz siparişlerden doğar. Tarayıcıda Selwise.trackOrder() bu uca konuşur; sunucudan, mobil uygulamadan ya da arka ofisinizden doğrudan da çağırabilirsiniz. Tarayıcı tarafı için Sipariş Takibi sayfasına bakın.

Uç nokta

POST /api/v1/public/sites/:siteKey/orders
Content-Type: application/json

• Kimlik: Tarayıcıdan doğrulanmış alan adı (Origin). Sunucudan ya da uygulamadan başlıksız istek ve x-selwise-api-key (kapsam mobile_write). Bkz. Kimlik Doğrulama ve Erişim.
• Sınır: IP başına dakikada 600 istek; sunucunuzdan toplu sipariş gönderimine yetecek kadar. Aşılırsa 429 ve Retry-After.

İstek

curl -X POST https://api.selwise.com/api/v1/public/sites/SITE_KEY/orders \
  -H "Content-Type: application/json" \
  -H "x-selwise-api-key: swpk_live_..." \
  -d '{
    "orderId": "ORDER_12345",
    "currency": "TRY",
    "total": 129.90,
    "subtotal": 119.90,
    "shippingTotal": 10.00,
    "status": "paid",
    "placedAt": "2026-10-09T09:12:00Z",
    "visitorId": "VISITOR_ID",
    "sessionId": "SESSION_ID",
    "siteUserId": "MUSTERI-1001",
    "items": [
      { "productItemCode": "SKU-RED-XL", "name": "Tişört Kırmızı XL", "quantity": 1, "unitPrice": 119.90 }
    ],
    "marketingConsent": [
      { "kind": "email", "value": "ayse@example.com", "optIn": true, "note": "Ödeme sayfası: kampanya e-postaları" }
    ]
  }'

Alanlar

Alan	Zorunlu	Açıklama
orderId	Evet	Mağazanızdaki sipariş kimliği; en çok 255 karakter. Aynı kanalda tekilleştirme anahtarıdır. Boşsa 400
currency	Hayır	ISO 4217, 3 harf (TRY). Verilmezse kanalın para birimi, o da yoksa EUR. Geçersiz bir değer sessizce varsayılana düşer
total	Hayır	Toplam tutar. Verilmezse kalem toplamı kullanılır. En çok iki ondalık, en çok 99999999.99
subtotal, discountTotal, shippingTotal, taxTotal	Hayır	Tutar dökümü; iki ondalığa yuvarlanır. Sayı değilse null saklanır
status	Hayır	Serbest metin, küçük harfe çevrilir, en çok 20 karakter. Aşağıdaki durumlar ciroya sayılmaz
placedAt	Hayır	ISO 8601. Geçersizse 400
visitorId, sessionId	Hayır	Tarayıcıdaki Selwise.getVisitorId() ve getSessionId() değerleri; en çok 64 karakter. Sunucudan gönderiyorsanız bunları sipariş sırasında oturumdan taşıyın; atıf bunlara bağlıdır
siteUserId	Hayır	identify ile kullandığınız müşteri kimliği. 64 karakterden uzunsa sipariş saklanır, yalnızca müşteri bağlantısı düşer
pageUrl, referrer, deviceType	Hayır	Bağlam. deviceType en çok 20 karakter
items[]	Hayır	Sipariş kalemleri; aşağıda
metadata	Hayır	Serbest nesne. couponCode (ya da coupon), sdkPlatform, sdkVersion okunur
attribution	Hayır	İstemcinin hesapladığı son temas. Verilmezse sunucu oturum olaylarından çıkarır; aşağıda
experimentAssignments	Hayır	{ "<deneyId>": { "experimentId", "variantId", "variantName" } }. Deney gelirini kollara yazmak için
skipPurchaseEvent	Hayır	true ise sipariş kaydedilir ama ayrıca kanonik purchase olayı üretilmez. Veri katmanı köprüsü bunu kullanır
marketingConsent[]	Hayır	Ödeme sayfasındaki izin kutusu; aşağıda

id adında bir alan göndermek 400 verir (deprecated field is not allowed: id). Sipariş kimliği her zaman orderId'dir. Bu uç gövdeyi sınıfla doğrulamaz; tanımadığı diğer alanlar yok sayılır, ama tarayıcıdaki trackOrder'ın çevirdiği takma adlar (id, kalemde productId, price) burada çevrilmez: sunucudan çağırırken orderId, productItemCode ve unitPrice yazın.

Kalemler

Alan	Açıklama
productItemCode	Beslemedeki item_code ile birebir aynı olmalı; en çok 100 karakter. Eşleşmezse ürün bazlı rapor ve öneri sinyalleri boş kalır
name	En çok 500 karakter
quantity	En az 1; ondalık varsa aşağı yuvarlanır. Verilmezse 1
unitPrice (ya da price)	Birim fiyat. Verilmezse 0
totalPrice	Satır toplamı. Verilmezse unitPrice çarpı quantity
metadata	Serbest nesne

Gelire sayılmayan durumlar

status alanı aşağıdakilerden biriyse (küçük harfle karşılaştırılır) sipariş kaydedilir ama ciro ve dönüşüm rakamlarına girmez: cancelled, canceled, refunded, partially_refunded, partial_refund, failed, failure, voided, void, declined, chargeback, returned, return. Durum hiç verilmezse sipariş gelir sayılır. Sipariş verildikten sonra iptal, iade veya geri gönderim olursa aşağıdaki durum güncelleme ucuyla bildirin.

Yanıt

{ "success": true, "created": true, "id": "3f6c2b9e-6a41-4d6e-9d0a-2e6d4a0c5b11" }

Aynı orderId ikinci kez gönderilirse HTTP 200 döner, created false olur ve id ilk kaydın kimliğidir; ikinci gönderim sayılmaz ve hiçbir yan etki üretmez. Sayfa yenilemesinden doğan çift kayıt bu yüzden güvenlidir:

{ "success": true, "created": false, "id": "3f6c2b9e-6a41-4d6e-9d0a-2e6d4a0c5b11" }

Bu uç 409 döndürmez. İlk gönderimde kayıt dışındaki işler (segment yenileme, ürün birlikteliği, senaryo girişi) arka planda sürer; yanıt bunları beklemez.

Atıf

attribution verilmediğinde sunucu, aynı oturum, ziyaretçi ve müşteriye ait son temasa (kampanya, öneri, arama, zenginleştirme) bakarak atıf çıkarır. Tarayıcıdaki trackOrder bunu kendisi doldurur. Bir attribution gönderirseniz:

Alan	Açıklama
source	campaign, recommendation, search, enrichment
campaignId, recommendationWidgetId, enrichmentId	İlgili varlığın kimliği (UUID)
recommendationProductItemCode, searchProductId, searchQuery	Tıklanan ürün ve arama sorgusu

Sahte atıfı önlemek için recommendationWidgetId ve enrichmentId bu kanala ait değilse ya da UUID değilse çıkarılır. Sunucu tarafında atıf bilgisi taşımıyorsanız alanı hiç göndermeyin; yanlış bir atıf, hiç atıf olmamasından kötüdür. Ciro ve atıf kuralları için Atıf sayfasına bakın.

Ödeme sırasında pazarlama izni: marketingConsent

Ödeme sayfasındaki "kampanya e-postaları göndermenizi onaylıyorum" kutusunu siparişle birlikte bildirebilirsiniz:

Alan	Açıklama
kind	email veya phone
value	Adres ya da E.164 telefon (+905321112233)
optIn	true izin verir; false bu adres için çıkış kaydeder
note	İznin kanıtı, alışverişçinin gördüğü metin. En çok 500 karakter

Bu yol aboneliğini iptal etmiş birini yeniden abone yapmaz; yeniden abonelik yalnızca pazarlama izni ucundan, paneldeki kişi ekranından veya e-postadaki bağlantıdan olur. Bir izin yazımı başarısız olursa sipariş yine kaydedilir.

Sipariş durumunu güncelleme

Kapıda ödemesi reddedilen, iptal edilen ya da iade edilen bir sipariş, durumunu bildirmediğiniz sürece panelde ciro olarak kalır. Sipariş sisteminiz bu değişiklikleri sonradan şu uçla bildirir:

POST /api/v1/public/sites/:siteKey/orders/:orderId/status
Content-Type: application/json
x-selwise-api-key: swpk_live_...

• Kimlik: Her zaman API anahtarı, kapsam orders_write. Tarayıcıdan çağrılamaz; Origin başlığı anahtarın yerini tutmaz. Anahtarı panelde Kanallar → Kurulum → API anahtarları altında "Sipariş durumu senkronu" amacıyla oluşturun. Mobil anahtar (mobile_write) bu uç için geçmez: iptal yetkisi uygulama paketinin içinde taşınmamalı.
• :orderId: Siparişi gönderirken kullandığınız orderId.
• Sınır: Dakikada 600 istek.

curl -X POST https://api.selwise.com/api/v1/public/sites/SITE_KEY/orders/ORDER_12345/status \
  -H "Content-Type: application/json" \
  -H "x-selwise-api-key: swpk_live_..." \
  -d '{ "status": "partially_refunded", "refundedTotal": 40.00, "currency": "TRY" }'

Alan	Açıklama
status	Yeni durum, en çok 20 karakter. Yukarıdaki listedeki bir durum siparişi bütün ciro ve dönüşüm rakamlarından çıkarır
refundedTotal	Bu siparişte şimdiye kadar iade edilen toplam tutar; yalnız son iade değil. Sipariş toplamını aşamaz
currency	Gönderilirse siparişin para birimiyle aynı olmalı

En az biri, status ya da refundedTotal, gönderilmelidir.

Nasıl işlenir:

• İptal ve tam iade siparişi her yerden çıkarır. refundedTotal sipariş toplamına ulaşırsa durum refunded olarak saklanır.
• Kısmi iade tutarla birlikte gelirse sipariş durur, değeri düşer: atıf ve ciro ekranları total eksi refundedTotal sayar. Tutarsız bir partially_refunded durumu ise siparişi bütünüyle çıkarır, çünkü ne kadarının iade edildiği bilinmez.
• Tekrar güvenlidir. refundedTotal birikimli toplam olduğu için aynı çağrı iki kez iade yazmaz; ikinci çağrı changed: false döner.

{
  "orderId": "ORDER_12345",
  "status": "paid",
  "total": 129.9,
  "refundedTotal": 40,
  "netTotal": 89.9,
  "countsAsRevenue": true,
  "changed": true
}

Deney kollarının gelir toplamları sipariş anında yazılır ve sonradan gelen iade ile güncellenmez; deney sonuç sayfası iadeyi yansıtmaz.

Hatalar

Durum	message ya da code	Çözüm
400	orderId is required	orderId boş
400	placedAt must be a valid ISO date string	placedAt biçimini düzeltin
400	deprecated field is not allowed: id	id yerine orderId gönderin
400	kod VALUE_TOO_LONG	Bir alan sütununu aşıyor (status 20, deviceType 20, sessionId ve visitorId 64, kalem adı 500 karakter)
403	Site not verified, Invalid API key or insufficient scope	Alan adı doğrulanmamış ya da anahtarda mobile_write yok
400	Send a status, a refundedTotal, or both	Durum güncellemesi boş
400	refundedTotal … is more than the order total	İade toplamı sipariş toplamını aşıyor
401	Order status sync requires an API key …	Durum güncellemesinde anahtar yok
403	Invalid API key or insufficient scope	Durum güncellemesinde anahtarın kapsamı orders_write değil
404	No order … on this channel	Bu kanalda o orderId ile bir sipariş yok: kanal ya da kimlik yanlış
404	Site not found	Site anahtarı yanlış
429	ThrottlerException: Too Many Requests	Hız sınırı; Retry-After kadar bekleyin

Doğrulama

1. Test siparişini gönderin ve yanıtta created: true görün.
2. Aynı isteği tekrarlayın; bu kez created: false ve aynı id dönmeli.
3. Siparişin panelde göründüğünü kontrol edin: Ciro ve Atıf sayfaları ilgili ekranları anlatır (birkaç dakika sürebilir).
4. Sipariş kalemleri ürün raporunda boşsa productItemCode besleme ile eşleşmiyordur: Takip Sorunları.

Sırada ne var

• Sipariş Takibi — tarayıcıdan trackOrder
• Kullanıcı Kimliklendirme API'si — siteUserId tutarlılığı
• Hatalar ve Sınırlar