Kendi yazılımınızla ya da açık kaynak bir altyapıyla çalışan mağazanızı Cross&Sell'e bağlayın: ürünlerinizi gönderin, teklifleri Teklif API'si ya da vitrin koduyla gösterin, siparişlerinizi bildirin.
Bu belge ikas, Ticimax, T-Soft ya da Shopify kullanmayan mağazalar içindir: kendi yazılımı olan ya da WooCommerce, OpenCart, PrestaShop, Magento ve benzeri bir altyapıyla çalışan mağazalar.
Tek şart: site şablonunuza bir <script> ekleyebilmeniz ve sunucunuzdan HTTPS isteği atabilmeniz. API düz HTTPS + JSON'dur; HTTP isteği atabilen her dil kullanabilir (örnekler curl, Node.js, PHP, Python ve Dart ile).
Hesap açın, panelden API anahtarı alın ve alan adınızı doğrulayın.
Ürünlerinizi API ile gönderin; Cross&Sell'e katılacak ürünleri ve partner teklifi açılacakları panelde ya da API ile seçin.
Teklifleri gösterin: Teklif API'si ile kendi tasarımınızda ya da vitrin koduyla.
Ödenen siparişleri sunucunuzdan API ile bildirin.
Test modunda deneyin; adımlar tamamlanınca mağazanızı canlıya alın.
Bütün uçların kökü:
text
https://api.crossandsell.com/v1
Eski adres https://app.crossandsell.com/api/v1/store de çalışmaya devam eder; uç başlıklarındaki /api/v1/store/… yolları bu biçimdedir ve yeni kökte /v1/… olur (mağaza özeti GET /v1/store).
İstek ve cevap gövdeleri JSON'dur. Başarılı cevap { "data": … } (liste { "object": "list", "data": [ … ] }), hata { "error": { "message", "type", "code", "param" } } biçimindedir. Her cevapta X-Request-Id başlığı vardır; destek isterken bu değeri iletin.
Bütün uçların makine okunur tanımı (OpenAPI 3.1): https://api.crossandsell.com/openapi/store-v1.json.
Kurulum, paneldeki Kurulum kartıyla aynı sırayla ilerler. Aşağıdaki listede kart adımlarının (2-7) başında hesap açma, sonunda canlıya alma vardır; Kurulum kartı aradaki altı adımı denetler:
app.crossandsell.com/login adresinde e-posta, şifre, mağaza adı ve mağaza adresinizle hesap açın; e-postanıza gelen bağlantıyla adresinizi doğrulayın. Mağazanız doğrulamadan sonra test modunda açılır. Mağaza adresi sitenizin yayındaki alan adıdır: localhost ve IP adresi kabul edilmez, çünkü doğrulama dosyasını sunucumuz okur. Kendi bilgisayarınızda geliştiriyorsanız sitenizi Netlify, GitHub Pages ya da benzeri ücretsiz bir barındırmada yayınlayıp o adresi girin. Adresi test modundayken panelin Hesap sayfasından değiştirebilirsiniz (anahtarlar, ürünler ve kurulum adımları sıfırlanır).
Panelde Geliştirici penceresinden bir API anahtarı oluşturun (aşağıda).
Alan adınızı doğrulayın (Alan adı doğrulama bölümü).
Ürünlerinizi gönderin (Ürünler bölümü).
Ürünleri seçin: Cross&Sell'e katılacak ürünleri ve partner teklifi açılacakları panelde ya da PUT /api/v1/store/products/selection ile seçin (Ürünler bölümü, Ürün seçimi).
Teklifleri gösterin: Teklif API'si ve gösterim bildirimi (Teklifler ve gösterim bölümü) ya da vitrin kodu (Vitrin kodu bölümü).
Bir test siparişi bildirin (Siparişler ve iade bölümü).
Kurulum kartındaki adımlar tamamlanınca Canlıya al'a basın (Test modu ve canlıya geçiş bölümü).
Anahtar cs_store_… biçimindedir ve yalnızca oluşturulduğunda bir kez gösterilir; hemen güvenli bir yere kaydedin. Aynı anda en fazla 5 etkin anahtarınız olabilir. Bir anahtarı istediğiniz an iptal edebilirsiniz; iptal edilen anahtarla gelen istekler reddedilir.
Anahtarı yalnızca sunucunuzda tutun (ortam değişkeni ya da gizli ayar). Tarayıcıda çalışan koda, mobil uygulamaya (ör. Flutter), tema dosyasına ya da herkese açık bir depoya koymayın; uygulamanız API'yi kendi sunucunuz üzerinden çağırsın.
Bağlantı sınaması. Mağazanızın özetini döner: kip (mode: test ya da live), alan adının doğrulanıp doğrulanmadığı (domainVerified) ve doğrulama kodu (verificationCode), alan adınızdan gelen son gösterim (integrationSeenAt), plan sınırlarınız (limits.products seçebileceğiniz ürün, limits.offers partner teklifi açabileceğiniz ürün sayısı), gönderdiğiniz ürün sayısı (catalogCount), seçili ürün sayısı (selectedCount) ve vitrininizin hazır olup olmadığı (scriptInstalled; Vitrin kodu bölümü).
Hız sınırı (yaklaşık, mağaza başına dakikada): ürün 60, sipariş 300, teklif 600 istek; bu uç ve alan adı doğrulama birlikte 60. Sınır aşılırsa 429 rate_limited döner; Retry-After başlığındaki süre kadar bekleyip yeniden deneyin.
Alan adı doğrulaması, hesaptaki alan adının size ait olduğunu gösterir. Canlıya geçmek için şarttır. Test modunda doğrulanmış alan adı eşleştirmenin başlaması için yeter.
Doğrulama kodunu alın: paneldeki Kurulum kartında ve GET /api/v1/store cevabındaki verificationCode alanında yazar (crossandsell-verification=…).
Kodu sitenizde https://<alan adınız>/.well-known/crossandsell-verification.txt adresinde düz metin olarak yayınlayın. Dosyada yalnız kod olsun; baştaki ve sondaki boşluk ve satır sonu önemsizdir.
Paneldeki Kurulum kartında Doğrula'ya basın ya da POST /api/v1/store/domain/verify çağırın. İkisi aynı denetimi yapar.
Gövde istemez. Sunucumuz dosyayı hesabınızdaki alan adından okur ve içeriği kodla karşılaştırır. Başarılıysa { "data": { "domainVerified": true, "domainVerifiedAt": "…" } } döner. Yeniden çağırmak zararsızdır: dosya yerindeyse ilk doğrulama tarihi döner. Bu uç GET /api/v1/store ile aynı hız sınırını paylaşır (mağaza başına dakikada yaklaşık 60 istek).
curl -X POST https://api.crossandsell.com/v1/domain/verify \
-H "Authorization: Bearer cs_store_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
Okuma kuralı
Değer
Protokol
Yalnız https, standart port.
Adres
Hesabınızdaki alan adı. Yerel ağ ya da özel IP adresine çözülen alan adı okunmaz.
Süre
Yönlendirme dahil toplam 5 saniye.
Dosya boyutu
En fazla 1 KB (1.024 bayt).
Yönlendirme
En fazla bir: yalnız aynı dosya yoluna, alan adınızın www'li ya da www'siz eşine, https ile.
Cevap
HTTP 200 ve içerik kodla aynı.
Doğrulama başarısızsa 422 domain_verification_failed döner; neden reason alanındadır. Paneldeki Doğrula düğmesi aynı nedeni mesaj olarak gösterir.
reason
Anlamı
unreachable
Dosya okunamadı: bağlantı kurulamadı, https çalışmıyor, 5 saniyede cevap gelmedi, dosya 1 KB'tan büyük ya da alan adı özel bir adrese çözülüyor. Adresi tarayıcıda https ile açmayı deneyin.
not_found
Sunucunuz 200 dışında bir durum döndü (ör. 404) ya da izin verilmeyen bir yönlendirme yaptı. Dosya yolunu ve yönlendirme kurallarınızı kontrol edin.
mismatch
Dosya okundu ama içerik kodla aynı değil. Kodu olduğu gibi, tek satır yazın.
Ürünleri ekler ya da günceller. Ürün id ile tanınır: aynı id yeniden gelirse ürün güncellenir. Bir istekte en fazla 500 ürün, mağaza başına toplam en fazla 5.000 ürün gönderebilirsiniz. Daha büyük kataloğu 500'lük parçalar halinde gönderin.
Alan
Tür
Zorunlu
Kural
id
metin
evet
1-128 karakter. Sizin ürün kimliğiniz; siparişte ve vitrin kodunda aynısını kullanın.
title
metin
evet
1-300 karakter.
url
metin
evet
https ile başlar, en fazla 2.000 karakter, ana sayfa olamaz. Mağazanızın alan adında ya da alt alanında olmalı.
imageUrl
metin
hayır
https ile başlayan görsel adresi; en fazla 2.000 karakter.
price
sayı
hayır
0 ile 9.999.999.999 arası.
salePrice
sayı
hayır
İndirimli fiyat; 0 ile 9.999.999.999 arası.
currency
metin
hayır
3 harfli para birimi kodu; varsayılan TRY.
stock
tam sayı
hayır
0 ile 1.000.000.000 arası.
categories
metin dizisi
hayır
Kendi kategori adlarınız; en fazla 10, her biri en fazla 120 karakter.
Cevap { "data": { "upserted", "catalogCount" } }. Adresi alan adınızın dışında olan ürün varsa istek hiç yazılmaz ve 422 url_not_on_domain döner (productIds alanında ilgili ürünler); müşteri başka bir siteye yönlendirilemez.
GET/api/v1/store/products
Gönderdiğiniz kataloğu id sırasıyla sayfa sayfa döner. limit en fazla 200'dür; cevap { "object": "list", "data": [ … ], "has_more", "next_cursor" } biçimindedir; sonraki sayfa için next_cursor değerini cursor olarak gönderin (has_more false ve next_cursornull ise son sayfadasınız). Her üründe selected (panelde seçili mi) ve offerEnabled (partner teklifi açık mı) alanları vardır.
DELETE/api/v1/store/products/{id}
Ürünü kataloğunuzdan siler. Ürün seçiliyse hemen seçimden düşer ve partner teklifleri kalkar. Katalogda olmayan ürün için 404 not_found döner. Yayında 3 ya da daha fazla partner teklifi olan (kilitli) seçili ürün silinmez: 409 locked_offer; bu değişiklik panelden yapılır.
Gönderdiğiniz her ürün otomatik olarak Cross&Sell'e katılmaz. Hangi ürünlerin katılacağını ve hangilerine partner teklifi açılacağını siz seçersiniz: panelde ya da aşağıdaki uçla. Seçebileceğiniz ürün ve teklif sayısı planınıza bağlıdır; güncel sayıları GET /api/v1/store cevabındaki limits alanından okuyun. Seçili ürünler her ürün gönderiminizde tazelenir.
Ürün seçimi
PUT/api/v1/store/products/selection
Paneldeki ürün seçim penceresini kaydetmekle aynıdır, kurallar da aynıdır. selected_ids seçimin tamamıdır: listede olmayan seçili ürün seçimden çıkar. offer_ids bu ürünlerden partner teklifi açılacakları belirtir; yalnız açar, açık bir teklifi kapatmaz (kapatmak panelden yapılır). Aynı isteği tekrar göndermek aynı sonucu verir. Reddedilen istek hiçbir şey yazmaz.
Alan
Tür
Zorunlu
Kural
selected_ids
metin dizisi
evet
1-500 ürün kimliği (ürünler isteğinde gönderdiğiniz id). Seçimin tamamı; plan sınırınızı (limits.products) aşamaz.
offer_ids
metin dizisi
hayır
selected_ids içinden partner teklifi açılacak ürünler. Açık teklif sayısı plan sınırınızı (limits.offers) aşamaz.
Cevap { "data": { "selected", "offers", "limits": { "products", "offers" } } }: seçili ürün sayısı, sınıra sayılan açık partner teklifi sayısı ve plan sınırlarınız. Kataloğunuzda olmayan kimlik 422 unknown_product döner (kimlikler ids alanında). Plan sınırı aşılırsa 422 too_many_products ya da 422 too_many_offers döner (limit, current: şu anki, requested: isteğin yapacağı). Panelde onay ya da değiştirme hakkı isteyen değişiklikler API'de yapılmaz ve 409 döner: locked_offer (yayında 3 ya da daha fazla partner teklifi olan ürün seçimden çıkarılamaz) ve swap_required (seçimden çıkan ürünün boşalttığı yere teklif açmak değiştirme hakkı ister).
Teklif API'si vitrin kodunun yerine kullanılır: partner tekliflerini sunucunuzdan alır, kendi tasarımınızla gösterirsiniz. İkisinden birini kullanmanız yeter (Vitrin kodu bölümü). Hangi teklifin gösterileceği ve görünme kuralları vitrin koduyla aynıdır.
1: test modunda o ürüne gerçek teklif yoksa seçili ürününüzden örnek bir teklif döner ("demo": true). Ürün katalogda ve seçili olmalı. Canlıda yok sayılır (Test modu ve canlıya geçiş bölümü).
visitor
evet
1-128 karakter. Ziyaretçiyi tanıyan opak kimliğiniz (ör. kendi çerezinizdeki rastgele bir değer); aynı ziyaretçi için hep aynı değeri gönderin. Gösterim bu ziyaretçiye bağlanır ve ziyaretçi her ürün için günde bir kez sayılır. Kimliğin kendisi saklanmaz, yalnız mağazanıza bağlı özeti saklanır; e-posta ya da telefon gibi kişisel veri göndermeyin.
Müşterinin ödeyeceği fiyat (indirim varsa indirimli fiyat) ya da null.
sale_price
Beta'da her zaman null; price zaten ödenecek fiyattır.
currency
3 harfli para birimi kodu ya da null.
store_name
Partner mağazanın adı.
click_url
Teklif bağlantısının adresi. Tıklamayı kaydeder ve müşteriyi partner ürün sayfasına götürür.
impression_url
Teklif ekranda göründüğünde tarayıcıdan bir kez çağırın; 30 dakika geçerli.
Boş liste ("data": []) hata değildir: o ürün için şu an gösterilecek teklif yoktur. Ürün panelde seçili değilse, ürün için henüz eşleşme yoksa ya da görünme kuralları (iki ürünün de partner teklifi açık, iki mağazanın vitrini hazır, teklif askıda değil) karşılanmıyorsa liste boş döner. Sayfayı teklifsiz açın. Boş listede neden reason ve message alanlarında yazar:
reason
Anlamı
product_not_in_catalog
Bu product_id ile ürün gönderilmemiş.
product_not_selected
Ürün seçili değil.
offer_not_enabled
Ürünün partner teklifi kapalı.
domain_not_verified
Alan adı doğrulanmadı.
test_no_partner
Test modundasınız ve bu ürüne test teklifi yok; denemek için demo=1 ekleyin.
no_partner_offer
Şu an yayında partner teklifi yok (eşleştirme sürüyor ya da uygun partner yok).
Cevap Cache-Control: private, no-store başlığıyla döner. Her impression_url tek bir ziyaretçiye bağlıdır: cevabı ziyaretçiler arasında paylaşmayın, ortak önbelleğe (CDN, tam sayfa önbelleği) koymayın. Önbellek gerekiyorsa yalnız aynı ürün, yerleşim ve ziyaretçi için ve 30 dakikadan çok daha kısa süre tutun.
Teklif isteği gösterim sayılmaz. Çağrı başarısız olursa ya da gecikirse sayfayı teklifsiz açın; örneklerdeki kısa zaman aşımı bunun içindir.
GET/api/v1/store/events/impression
Gösterimi tarayıcı bildirir: teklif ekranda göründüğünde, mağazanızın alan adındaki sayfadan impression_url adresine bir GET isteği atın. Anahtar istemez, CORS açıktır; başarılıysa gövdesiz 204 döner. Sunucunuzdan çağırmayın: gösterimin alan adınızdan geldiği, isteğin Origin (yoksa Referer) başlığından anlaşılır.
html
<!-- Teklif kartı / offer card: click_url bağlantıda, impression_url data özniteliğinde -->
<a class="cs-offer" href="{{ offer.click_url }}" data-impression="{{ offer.impression_url }}">…</a>
<script>
// Teklif ekranda görününce bir kez / once, when the offer becomes visible
document.querySelectorAll('.cs-offer[data-impression]').forEach(function (el) {
new IntersectionObserver(function (entries, observer) {
if (!entries[0].isIntersecting) return;
observer.disconnect();
fetch(el.dataset.impression, { keepalive: true }).catch(function () {});
}).observe(el);
});
</script>
Belirteç 30 dakika geçerlidir; süresi dolmuş ya da bozuk belirteç 400 invalid_token döner. Belirteç alındığı andaki kipi (test ya da canlı) taşır: mağazanız canlıya geçtiyse test modunda alınmış belirteç de invalid_token döner. Aynı ziyaretçi, ürün ve gün için tekrar gelen gösterim günlük sayaçta yeniden sayılmaz. Hız sınırı IP başına dakikada yaklaşık 300 istek.
Alan adınızdan gelen gösterim, paneldeki Kurulum kartının "Gösterim geldi" adımını tamamlar (Test modu ve canlıya geçiş bölümü). Alan adınız doğrulanmışsa vitrininiz de hazır sayılır (scriptInstalled: true).
Vitrin kodu, Teklif API'sinin alternatifidir: ikisinden birini kullanmanız yeter (Teklifler ve gösterim bölümü). Vitrin kodu teklifleri kendisi gösterir, gösterimi ve tıklamayı kendisi ölçer.
Kodu sitenizin bütün sayfalarına, </body> etiketinden hemen önce ekleyin; en önemlileri ürün, sepet ve sipariş tamamlandı sayfalarıdır. Mağaza kimliğiniz kodla birlikte paneldeki Geliştirici penceresinde yazılıdır; kodu oradan kopyalamanız en kolayıdır.
Ürün sayfasında hangi ürünün gösterildiğini Cross&Sell'e söyleyin. Sayfadaki herhangi bir öğeye data-sellcross-product-id ekleyin ya da window.__SELLCROSS_PRODUCT_ID__ değişkenini yazın. Değer, ürünler isteğinde gönderdiğiniz id ile aynı olmalı.
html
<!-- Ürün sayfasında herhangi bir öğe / any element on the product page -->
<div data-sellcross-product-id="SKU-1001"></div>
<!-- ya da / or -->
<script>
window.__SELLCROSS_PRODUCT_ID__ = 'SKU-1001';
</script>
Tek sayfalık uygulamalarda (sayfa yenilenmeden ürün değişen sitelerde) değişkeni her rota değişiminde yeni ürünün kimliğiyle güncelleyin. Kimlik verilmezse ürün sayfa adresinden ya da başlığından tanınmaya çalışılır; kimlik vermek daha kesindir.
Teklifler, iki mağazanın da vitrini hazır olduğunda görünür. Vitrininiz, vitrin kodu sitenizde bulununca hazır sayılır; Teklif API'si kullanıyorsanız alan adınız doğrulanınca (test modunda bu yeter, canlıda alan adınızdan bir gösterim de gelmiş olmalı). Durumu GET /api/v1/store cevabındaki scriptInstalled alanından görebilirsiniz.
Sitenizde, alan adınızda çalışan vitrin kodu Kurulum kartının "Gösterim geldi" adımını da tamamlar.
Komisyon, diğer bütün altyapılarda olduğu gibi bildirilen siparişlerden hesaplanır: Cross&Sell teklifine tıklayıp sitenize gelen müşterinin siparişi o tıklamaya bağlanır. Bu yüzden siparişleri bildirmek zorunludur.
POST/api/v1/store/orders
Siparişi ödendiği anda sunucunuzdan gönderin; tarayıcıdan göndermeyin.
Alan
Tür
Zorunlu
Kural
id
metin
evet
1-128 karakter. Sizin sipariş kimliğiniz; iadede de bu kullanılır.
number
metin
hayır
Müşteriye gösterilen sipariş numarası; en fazla 64 karakter.
createdAt
metin
evet
Saat dilimli ISO 8601 tarih (ör. 2026-11-12T10:15:00+03:00). Gelecekte olamaz, 8 günden eski olamaz.
currency
metin
hayır
Beta'da yalnız TRY (büyük/küçük harf fark etmez); verilmezse TRY. Başka para birimi 422 unsupported_currency döner.
clickId
metin
hayır
Ziyaretçinin geldiği adresteki cs_click değeri; en fazla 64 karakter. Yoksa sipariş kabul edilir ama satış bağlanmaz.
lines
dizi
evet
1-500 satır.
lines[].productId
metin
evet
Ürünler isteğinde gönderdiğiniz id; 1-128 karakter.
lines[].quantity
tam sayı
evet
1 ile 100.000 arası.
lines[].unitPrice
sayı
evet
Müşterinin bir adet için ödediği tutar, indirimler düşüldükten sonra; 0 ile 9.999.999.999 arası (negatif olamaz). Satır tutarı unitPrice × quantity; aynı ürünün satırları toplamı 9.999.999.999,99'u aşarsa 422 amount_too_large.
Aynı siparişi iki kez göndermek güvenlidir; ikinci gönderim yeni satış kaydı açmaz ve aynı attributed değerini döner. Ağ hatasında isteği tekrarlayabilirsiniz. Satışa bağlanmış bir siparişi aynı id ile farklı tutarla gönderirseniz 409 order_conflict döner ve kayıt değişmez; iade ya da iptal için iade ucunu kullanın.
Partner teklifinden gelen ziyaretçinin adresinde cs_click parametresi bulunur. Bu değeri oturumda ya da sepette saklayıp siparişle clickId olarak gönderin: sipariş yalnızca o tıklamaya bağlanır. Tıklama son 7 gün içinde olmalı ve siparişte tıklanan ürün bulunmalıdır. clickId göndermezseniz sipariş kabul edilir ama satış bağlanmaz ve komisyon doğmaz.
Cevap { "data": { "attributed": n } }: n siparişe bağlanan Cross&Sell satışı sayısıdır. 0 olduğunda sipariş yine kabul edilmiştir (bildirim adımı sayılır, yeniden göndermeyin) ve neden reason ile message alanlarında yazar. clickId ile ilgili nedenler panelin Olaylar sayfasındaki API hataları listesine uyarı olarak da düşer.
reason
Anlamı
no_click_id
clickId gönderilmedi; satış bağlanmaz (olağan).
demo_click
Test modundaki demo teklifin cs_click=demo_… değeri; bildirim doğru, satış kaydı açılmaz.
click_not_found
clickId mağazanızın hiçbir tıklamasıyla eşleşmiyor (değer değiştirilmiş ya da uydurulmuş).
click_already_used
Tıklama daha önce başka bir siparişe bağlandı.
click_expired
Tıklama, sipariş tarihine göre 7 günden eski.
click_after_order
Tıklama sipariş tarihinden sonra; createdAt değerini kontrol edin.
product_not_in_order
Tıklanan ürün siparişin satırlarında yok.
not_attributed
Beklenmeyen durum; X-Request-Id ile bize yazın.
POST/api/v1/store/orders/{id}/refund
Sipariş iade edildiğinde ya da iptal edildiğinde gönderin: gövde { "status": "refunded" } ya da { "status": "cancelled" }. Siparişin tamamı için geçerlidir; kısmi iade yoktur. Cevap { "data": { "updated": n } }; 0 o siparişe bağlı satış olmadığını gösterir (sipariş hiç bildirilmemiş ya da bir tıklamaya bağlanmamış), yine 200 döner ve reason: "no_attributed_sales" ile message eklenir. Bağlanmamış siparişlerin iadesini de göndermeniz zararsızdır.
Yeni mağaza test modunda açılır. Test mağazası yalnız diğer test mağazalarıyla eşleşir: teklifleriniz gerçek mağazaların vitrininde görünmez, gerçek mağazaların teklifleri de sizde görünmez. Test modunda satışlar komisyon doğurmaz.
Kurulum adımları
Paneldeki Kurulum kartı altı adımı sırayla gösterir ve her birini sunucuda denetler:
Adım
Ne tamamlar
1. API anahtarı
Geliştirici penceresinde oluşturulmuş, iptal edilmemiş bir anahtar.
2. Alan adı
Başarılı alan adı doğrulaması: Doğrula düğmesi ya da POST /api/v1/store/domain/verify.
3. Ürünler
PUT /api/v1/store/products ile başarılı bir gönderim (ya da katalogda ürün bulunması).
4. Seçim
En az bir seçili ürün ve en az bir açık partner teklifi: panelde ya da PUT /api/v1/store/products/selection ile.
5. Gösterim
Alan adınızdan gelen bir gösterim: Teklif API'sinin impression_url çağrısı ya da alan adınızda çalışan vitrin kodu.
6. Sipariş bildirimi
Kabul edilen herhangi bir POST /api/v1/store/orders bildirimi (clickId olsun ya da olmasın). Bu adım bildirimin ulaştığını gösterir; sipariş verisinin doğruluğunu ayrıca doğrulamaz.
Teklif API'si yolunda gösterim için önce bir teklif gelmelidir; test modunda teklif yalnız eşleşilecek başka bir test mağazası varsa gelir ve çoğu zaman gelmez (reason: "test_no_partner"). Bu durumda teklif isteğine demo=1 ekleyin: seçili ürününüzden örnek bir teklif döner ("demo": true, satıcı "Cross&Sell Demo").
Örnek teklifin impression_url adresini sitenizden çağırınca gösterim adımı tamamlanır.
click_url sizi kendi ürün sayfanıza cs_click=demo_… ile götürür: tıklama yakalama kodunuzu böyle denersiniz.
Bu değerle gönderdiğiniz sipariş attributed: 0, reason: "demo_click" döner ve sipariş adımını tamamlar; satış ya da komisyon kaydı açılmaz.
Canlıda demo yok sayılır: parametreyi kodda unutmanız vitrininizi bozmaz.
Canlıya al düğmesi alan adı, ürün, seçim, gösterim ve sipariş adımları tamamlanınca açılır (anahtar bu adımlar için zaten gerekir). Sunucu şartı düğmeye bastığınız anda yeniden denetler.
Canlıya geçince
Test teklifleriniz geri çekilir; bundan sonra gerçek mağazalarla eşleşirsiniz. Eşleştirme hemen başlar.
Satışa dönüşmemiş test tıklamaları ve test sayaçları (Geliştirici penceresindeki günlük sayılar) silinir.
Canlıya geçişten önce açılmış tıklamalardan gelen satışlar hiçbir zaman komisyon borcuna girmez.
Bundan sonraki satışlar planınızdaki orana göre komisyon doğurur.
Canlıya geçiş panelden geri alınamaz.
Cross&Sell mağazanızı yeniden test moduna aldıysa kendiniz tekrar canlıya alamazsınız: düğme kapalı kalır, istek 409 operator_hold döner. Destekle iletişime geçin.
Canlı mağazanın alan adından 7 gün gösterim gelmezse panelde uyarı görünür (canlıya geçişten sonra hiç gösterim yoksa süre geçiş anından sayılır). Bu yalnız uyarıdır; hiçbir şey otomatik olarak askıya alınmaz. Trafiğiniz varsa vitrin kodunu ya da impression_url çağrısını kontrol edin.
Hatalı istekte cevap gövdesi error nesnesidir: mesaj (message), tür (type), sabit kod (code) ve ilgili alan (param, yoksa null). Programınızda mesaja değil koda göre karar verin; mesaj Türkçedir ve değişebilir. Anahtarınızla gelen isteklere dönen hatalar (4xx, 5xx) ve satış bağlanmayan siparişler son 7 gün boyunca panelin Olaylar sayfasında, API hataları listesinde istek kimliğiyle (X-Request-Id) görünür.
Şablonuna <script> eklenebilen ve sunucusundan HTTPS isteği atabilen her site uyumludur. Hazır bir eklenti yoktur; bağlantıyı kendi sunucunuzda kurarsınız.
Altyapı
Vitrin kodu nereye
Ürünler ve siparişler nasıl
WooCommerce
Temanın alt bilgi şablonu ya da temanın özel kod alanı
Sunucuda zamanlanmış bir görev ürünleri gönderir; sipariş ödendi olayında sipariş bildirilir.
OpenCart
Temanın alt bilgi şablonu
Sunucuda zamanlanmış bir görev ürünleri gönderir; sipariş ödendi olayında sipariş bildirilir.
PrestaShop
Temanın alt bilgi şablonu
Sunucuda zamanlanmış bir görev ürünleri gönderir; sipariş ödendi olayında sipariş bildirilir.
Magento
Temanın sayfa yerleşim şablonu
Sunucuda zamanlanmış bir görev ürünleri gönderir; sipariş ödendi olayında sipariş bildirilir.
Özel yazılım (Laravel, Node.js, .NET …)
Bütün sayfaların ortak yerleşim şablonu
Ürün kaydedilince ya da zamanlanmış bir görevle ürünler gönderilir; ödeme onaylanınca sipariş bildirilir.
ikas, Ticimax, T-Soft ve Shopify mağazaları API'ye gerek duymaz; hazır uygulamayı kurar:
Evet. Mağazanız test modunda açılır: yalnızca test mağazalarıyla eşleşir ve satışlarınız komisyon doğurmaz. Paneldeki Kurulum kartı adımları sizin yerinize doğrular. Alan adınız doğrulandığında, ürünleriniz geldiğinde, ürün seçip en az bir partner teklifi açtığınızda, alan adınızdan bir gösterim geldiğinde (vitrin kodu ya da Teklif API'si) ve bir sipariş bildiriminiz ulaştığında Canlıya al düğmesi açılır. Canlıya alınca test teklifleri geri çekilir, test tıklamaları ve sayaçları silinir; bundan sonra gerçek mağazalarla eşleşirsiniz ve satışlar planınıza göre komisyon doğurur.
Bütün ürünlerimi göndermem gerekiyor mu?
Hayır. Panelde aralarından seçim yapmak istediğiniz ürünleri gönderin; mağaza başına en fazla 5.000 ürün.
Sattığım bir ürünü kaldırırsam ne olur?
DELETE /api/v1/store/products/{id} ile kataloğunuzdan silin. Ürün seçiliyse hemen seçimden düşer. Yayında 3 ya da daha fazla partner teklifi olan ürün silinmez (409 locked_offer); onu panelden değiştirin.
Tıklamadan gelmeyen siparişi de göndermeli miyim?
Evet, bütün ödenen siparişleri gönderin; hangisinin Cross&Sell'den geldiğine Cross&Sell karar verir. Tıklamaya bağlanmayan sipariş attributed: 0 döner ve komisyon doğmaz.
Aynı siparişi iki kez gönderirsem?
Sorun olmaz; ikinci gönderim yeni satış kaydı açmaz.
Siparişin bir kısmı iade edildi, ne göndermeliyim?
Kısmi iade desteklenmez. İade bildirimi siparişin tamamı için geçerlidir.