Kendi altyapınızla çalışan mağazanızı çapraz satış ağına API ile bağlayın.
Ürünlerinizi gönderin, partner mağazaların tamamlayıcı ürünlerini kendi sayfanızda gösterin, siparişi bildirin. Düz HTTPS + JSON; sunucusundan istek atabilen her dil kullanabilir.
- Düz HTTPS + JSON
- 10 dilde örnek
- Test modu, komisyonsuz
- OpenAPI şeması
Hazır altyapı mı kullanıyorsunuz (ikas, Ticimax, T-Soft)? Kurulum rehberleri →
curl https://api.crossandsell.com/v1/store \ -H "Authorization: Bearer $CROSSANDSELL_API_KEY"- Ürün gönder
- Ürün seç
- Teklif göster
- Sipariş bildir
Geliştirici hızlı başlangıç
Mağaza anahtarınızla ilk isteği gönderin ve bağlantınızı doğrulayın.
AI aracınıza verin, entegrasyonu kurdurun
Aşağıdaki promptu kopyalayıp kullandığınız AI kod aracına yapıştırın; araç belgeleri ve şemayı okuyup entegrasyonu adım adım kurar.
Görev: Bu mağazayı Cross&Sell çapraz satış ağına Mağaza API'si v1 ile bağla. İşi tek seferde, baştan sona bitir: aşağıdaki sekiz adımın hepsini kur, dene ve raporla. Soru sorup bekleme; karar gereken yerde bu metindeki varsayılanı uygula ve raporda belirt. Bir adımı kuramıyorsan nedenini raporda yaz, diğer adımlara devam et.
Cross&Sell ne yapar: birbirini tamamlayan mağazaları eşleştirir. Bu mağazanın ürün sayfasında partner mağazanın ürünü teklif olarak görünür; tıklayan ziyaretçi partner mağazaya gider. Partner mağazaların sayfalarında da bu mağazanın ürünleri görünür; oradan gelen ziyaretçinin siparişi Cross&Sell'e bildirilir.
Adresler:
- İstek tabanı: https://api.crossandsell.com/v1
- OpenAPI şeması (uçlar, alanlar, hata kodları; tek doğru kaynak): https://app.crossandsell.com/openapi/store-v1.json
- Belgeler (her uç için curl, TypeScript, Node.js, Python, PHP, Go, Java, C#, Ruby ve Dart örneği): https://app.crossandsell.com/developer-docs
- API anahtarı buradan alınır: https://app.crossandsell.com/panel?view=keys
Koda başlamadan önce:
- Şemayı indirip oku, belgeyi oku. Orada olmayan uç, alan ya da parametre uydurma; bu metinle şema çelişirse şemaya uy.
- Bu projeyi incele ve şunları bul: dil ve çatı; ürün verisinin kaynağı (tablo, model ya da dosya); ürün sayfası şablonu; ödemenin kesinleştiği yer (ödeme sağlayıcısının onayı, sipariş onayı); iade ve iptal işlemi; ortam değişkenlerinin okunduğu yer; zamanlanmış iş ya da kuyruk olup olmadığı.
- Mevcut katmanlara, adlandırmaya ve kod biçimine uy. Yeni bağımlılık ekleme: HTTP isteği için projenin zaten kullandığı istemciyi ya da dilin standart kitaplığını kullan.
- Proje sunucusuz, yalnız statik sayfalardan oluşuyorsa: anahtar isteyen adımlar tarayıcıdan yapılamaz. Bu durumda belgelerdeki "Vitrin kodu" bölümündeki kodu sayfalara ekle, 3. ve 4. adım için yerelde çalıştırılacak tek seferlik bir betik yaz, 5. ve 7. adımın sunucu gerektirdiğini raporda yaz.
Anahtar ve güvenlik:
- API anahtarı CROSSANDSELL_API_KEY ortam değişkeninde durur ve yalnız sunucuda kullanılır ("Authorization: Bearer <anahtar>"). Anahtarı tarayıcı koduna, loglara, hata iletilerine ya da depoya yazma. Örnek ortam dosyası varsa yalnız değişkenin adını ekle.
- Değişken tanımlı değilse anahtar uydurma. Entegrasyon sessizce devre dışı kalsın, site eskisi gibi çalışsın; raporda anahtarın yukarıdaki adresten alınacağını yaz.
- Bütün Cross&Sell çağrılarını tek bir istemci modülünde topla: taban adres, başlık, zaman aşımı (teklif isteği 1,5 saniye, diğerleri 10 saniye), JSON ayrıştırma ve hata nesnesi (error.code, error.message, error.param).
- Cross&Sell'e ulaşılamaması mağazanın kendi akışını (ürün sayfası, sepet, ödeme) hiçbir zaman bozmasın: hatayı yakala, anahtarsız logla, devam et.
Adımlar (bu sırayla):
1. Bağlantı. GET /store ile sına; yanıttaki mode, domainVerified, verificationCode ve limits alanlarını oku. 401 dönerse anahtar yanlıştır: dur ve raporla.
2. Alan adı. verificationCode değerini https://<alan adı>/.well-known/crossandsell-verification.txt yolunda düz metin olarak sun; dosyada bu değerden başka hiçbir şey olmasın. Sonra POST /domain/verify çağır. Doğrulama başarısızsa error.reason değerini raporla.
3. Katalog. PUT /products ile gönder: gövde { "products": [...] }. Her üründe id (mağazadaki kalıcı ürün kimliği), title ve url zorunlu; url https olmalı ve mağazanın kendi alan adında durmalı. Varsa imageUrl, price, salePrice, currency ("TRY"), stock, categories, brand ve active alanlarını da gönder. İstek başına en fazla 500 ürün; fazlasını parçalara böl. İlk kurulum için bütün aktif ürünleri gönderen bir komut yaz. Sonrasında ürün eklenince ya da fiyat, stok, ad, görsel, adres değişince o ürünü yeniden gönder (projenin kayıt sonrası kancası ya da zamanlanmış işi). Satıştan kalkan ürün için DELETE /products/{id}; 409 dönerse silmeyi zorlama, raporla.
4. Seçim. PUT /products/selection ile ayarla: selected_ids (seçilen ürünler), isteğe bağlı offer_ids (teklif açılacak ürünler; selected_ids içinden). Hangi ürünlerin seçileceği mağaza sahibinin kararıdır: listeyi bir ayardan ya da ortam değişkeninden oku. Böyle bir liste yoksa ilk kurulumda en yeni aktif ürünlerden, 1. adımdaki limits.products sayısı kadarını seç ve bunu raporda belirt. 422 dönerse (plan sınırı; error.limit) listeyi sınıra indirip yeniden gönder. 409 dönerse seçimi zorlama, bunun panelden yapılacağını bildir.
5. Teklifler. Ürün sayfası sunucuda hazırlanırken teklifleri al: GET /offers?product_id=<ürün kimliği>&placement=product_page&visitor=<opak ziyaretçi kimliği>. Ziyaretçi kimliği için birinci taraf çerezde rastgele bir değer tut; e-posta, telefon gibi kişisel veri gönderme. Yanıt tek ziyaretçiye özeldir: ortak önbelleğe koyma. Her teklifte title, image_url, price, sale_price, currency, store_name, click_url ve impression_url gelir. Tekliflerle sitenin tasarımına uyan küçük bir kart alanı çiz; kartta ürünün partner mağazaya ait olduğu ve mağazanın adı görünsün. Liste boşsa, istek başarısızsa ya da zaman aşımına uğrarsa alanı hiç çizme; sayfa eskisi gibi açılsın.
6. Gösterim ve tıklama. Teklif kartı ekranda görünür olunca tarayıcıdan, kart başına bir kez impression_url adresini çağır (anahtar gerekmez). Kartın bağlantısında click_url adresini değiştirmeden kullan ve yeni sekmede aç.
7. Sipariş. Ziyaretçi siteye adresinde cs_click parametresiyle gelirse (hangi sayfa olursa olsun) değeri oturumda ya da çerezde 7 gün sakla. Ödeme kesinleşince sunucudan POST /orders gönder: id (sipariş kimliği), number, createdAt (ISO 8601; gelecekte ya da 8 günden eski olamaz), currency "TRY", lines (her satırda productId, quantity, unitPrice). productId 3. adımdaki id ile aynı olmalı; unitPrice müşterinin ödediği indirim sonrası birim fiyattır. Saklanan cs_click varsa clickId alanına yaz, yoksa alanı hiç gönderme. Aynı siparişi yeniden göndermek zararsızdır; 409 order_conflict dönerse yeniden deneme, logla. İade ya da iptalde POST /orders/{id}/refund gönder: gövde { "status": "refunded" } ya da { "status": "cancelled" }.
8. Hatalar. Hataları ileti metnine göre değil error.code değerine göre işle. 429 yanıtında Retry-After başlığındaki saniye kadar bekleyip yeniden dene (en fazla 3 deneme). Ağ hatasında ve 5xx yanıtında katalog ve sipariş isteklerini artan beklemeyle en fazla 3 kez dene; teklif isteğini yeniden deneme. 400 ve 422 yanıtlarını yeniden deneme; error.param ve error.issues değerlerini logla.
Test modu:
- Mağaza test modunda başlar ve yalnız test mağazalarıyla eşleşir; test modunda komisyon doğmaz. Kurulum adımları panelde izlenir: https://app.crossandsell.com/panel?view=setup
- Paneldeki Kurulum kartı altı adım gösterir: anahtar, alan adı, ürünler, seçim, gösterim, sipariş. Buradaki sekiz uygulama adımı bunları karşılar (1. adım anahtarı sınar; 8. adım hata işleme kurulum adımı değildir).
- Test modunda teklif çoğu zaman gelmez (yanıtta reason: "test_no_partner"). Gösterim, tıklama ve sipariş akışını denemek için teklif isteğine demo=1 ekle: örnek teklif döner (demo: true). impression_url çağrısı gösterim adımını tamamlar; click_url ürün sayfasına cs_click=demo_… ile döner; bu değerle gönderilen sipariş reason: "demo_click" döner ve sipariş adımını tamamlar. demo=1 canlıda yok sayılır; yine de yalnız deneme için kullan ve raporda belirt.
- Boş teklif listesinde, attributed: 0 siparişte ve updated: 0 iadede yanıttaki reason ve message değerlerini logla; bunlar hata değildir, yeniden deneme. Panelin Olaylar sayfası mağazaya dönen API hatalarını listeler.
- Anahtar tanımlıysa her adımı gerçek istekle dene. Tanımlı değilse istemci modülünü sahte yanıtlarla sınayan testler yaz.
- Canlıya almayı mağaza sahibi panelden yapar; sen canlıya alma.
Bitirme ölçütü (hepsi sağlanmadan işi bitmiş sayma):
- Bağlantı isteği 200 dönüyor ya da anahtar eksikliği raporda açıkça yazıyor.
- Doğrulama dosyası sunuluyor.
- Katalog gönderimi ve güncellemesi çalışıyor; gönderilen ürün sayısı yanıttaki catalogCount ile uyuşuyor.
- Ürün seçimi yapıldı.
- Ürün sayfası teklif yokken ve Cross&Sell kapalıyken hatasız açılıyor; teklif varken kart, gösterim ve tıklama çalışıyor.
- Sipariş ve iade bildirimi ödeme akışına bağlandı; cs_click değeri siparişe taşınıyor.
- Projenin kendi testleri ve derlemesi geçiyor.
İş bitince şunları yaz:
- Değişen ve eklenen dosyaların listesi
- Eklenen ortam değişkenleri
- Her adımı nasıl denediğin (komut ya da istek, beklenen yanıt)
- Uyguladığın varsayılanlar ve kuramadığın adımlar
- Mağaza sahibinin yapması gerekenler (anahtarı tanımlamak, doğrulama dosyasını yayına almak, panelden canlıya almak)Geliştirmeye başla
Mağazayı bağla ve doğrula
Alan adınızın sahipliğini doğrulayın.
Ürün gönder
Kataloğunuzu gönderin ve güncel tutun.
Teklifleri göster
Partner ürünlerini vitrininize ekleyin.
Gösterim ve tıklamayı kaydet
Vitrin etkileşimlerini bildirin.
Sipariş ve iadeyi bildir
Satışları sunucunuzdan bildirin.
Test modu ve canlıya geçiş
Entegrasyonu deneyin, sonra yayına alın.
Hata kodları ve sınırlar
Yanıtları ve istek sınırlarını inceleyin.
OpenAPI şeması
Makinece okunan API tanımını açın.
Test modundan canlıya
Yeni mağaza test modunda açılır ve yalnız diğer test mağazalarıyla eşleşir; test modunda komisyon yoktur. Paneldeki Kurulum kartı beş adımı sırayla denetler, sonra Canlıya al ile yayına çıkarsınız.
- 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 /v1/domain/verify. - 3. Ürünler
PUT /v1/productsile başarılı bir gönderim (ya da katalogda ürün bulunması). - 4. SeçimEn az bir seçili ürün ve en az bir açık partner teklifi: panelde ya da
PUT /v1/products/selectionile. - 5. GösterimAlan 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ş bildirimiKabul edilen herhangi bir
POST /v1/ordersbildirimi (clickIdolsun ya da olmasın). Bu adım bildirimin ulaştığını gösterir; sipariş verisinin doğruluğunu ayrıca doğrulamaz.
SDK'larYakında
Node.js ve PHP istemcileri ile WooCommerce eklentisi hazırlanıyor.
Şimdilik belgelerdeki örnekler paketsiz çalışır: curl, TypeScript, Node.js, Python, PHP, Go, Java, C#, Ruby ve Dart.
OpenAPI
Bütün uçların makine okunur tanımı (OpenAPI 3.1). İstemci üretmek ya da API aracınıza almak için kullanın.
store-v1.json dosyasını aç ↗ (yeni sekmede açılır)Planlar ve komisyon
Ücretsiz planla başlarsınız. Komisyon yalnız partner teklifinden gelen satışta alınır; oran ve sınırlar planınıza bağlıdır.
Planları gör ↗ (yeni sekmede açılır)Beta koşulları
Mağaza API'si Beta'dadır. Neye söz verdiğimiz ve vermediğimiz belgede yazılı.
Beta koşullarını oku →