# Commerce API kullanım senaryoları: widget ile yapamayacağınız yedi proje

> Vitrin widget'ı doğru biçim olmadığında: SaaS içine gömülü ticaret, çok yüzeyli kataloglar, beyaz etiketli mağazalar, özel kullanıcı deneyimi, yapay zekâ ajanları, özel BI. Ayrıca Shoprocket JS SDK'sından kod örnekleri.

Ryan Badger - 4 Ağustos 2025 - 5 dk okuma

## Gömme için bir e-ticaret API'si ne işe yarar

Çoğu e-ticaret platformu size bir widget verir. Bir script yapıştırırsınız, bir vitrin elde edersiniz. Mağazaların %95'i için gayet iyi çalışır.

Commerce API ise widget'ın yapamadığı bir şeyi yapmak istediğinizde başvurduğunuz araçtır: ürünleri kendi arayüzünüzün içinde göstermek, ödeme adımını bir SaaS panelinin içine gömmek, bir kataloğu birden çok yüzeye (web + mobil + ses) dağıtmak ya da hiçbir platformun hazır sunmadığı özel alıcı akışları kurmak.

Shoprocket ikisini de sunar. [Widget](https://v3.shoprocket.io/tr/blog/headless-ticaret-uc-kademe-gercek-secenekler-ve-hangisini-istiyorsunuz.md) varsayılandır. [`@shoprocket/core` SDK'sı](https://github.com/shoprocket/shoprocket-js) ise widget'ı aştığınızda ya da en baştan ona ihtiyaç duymadığınızda devreye girer.

## Widget değil API gerektiren senaryolar

Bunlar, widget'ın yetmediği projeler. Fikriniz bu listedeyse API alanındasınız.

### 1. SaaS ürününüzün içinde ticaret

SaaS panelinizin zaten kendi arayüzü var. Müşterilerinizin uygulamanızdan çıkmadan eklenti, kredi paketi, premium katman ya da fiziksel ürün satın almasını istiyorsunuz.

Widget yanlış biçim olur: kullanıcılarınızı tanımaz, tasarım sisteminizle uyuşmaz ve tam sayfa bir vitrin varsayar. API ile ürün kartlarını kendi bileşenlerinizle gösterir, düğme tıklamasında `cart.addItem()` çağırır ve kendi ödeme panelinizi açarsınız (uyumluluk işini ertelemek isterseniz barındırılan ödeme sayfasına yönlendirirsiniz).

```
import { ShoprocketCore } from '@shoprocket/core'

const sr = new ShoprocketCore({ publicKey: 'pk_...' })

// Eklenti kartlarını SaaS panelinizin içinde gösterin
const addons = await sr.products.list({ category: 'addons' })

// Kullanıcı "Kredi ekle" düğmesine tıklar
await sr.cart.addItem(addon.id, 1)
```

### 2. Çok yüzeyli katalog (web + yerel uygulama + ses + sohbet)

Tek ürün kataloğu, her yerde farklı gösterilir. Web vitrini tam ürün detayını gösterir, yerel iOS uygulaması kompakt bir liste sunar, sesli asistan ürünleri yüksek sesle anlatır, bir sohbet entegrasyonu satın alınabilir bir bağlantıyla yanıt verir.

Dört yüzey de aynı API'yi çağırır. Shoprocket panelinde bir ürünün fiyatını güncellediğinizde her yüzey bunu bir sonraki çağrıda yansıtır. Yüzey başına içerik senkronizasyonu yok.

### 3. Beyaz etiketli / iş ortağı vitrinleri

Başkalarının mallarını sattığı bir platformsunuz: topluluk pazar yeri, iş ortağı rehberi, bayilerin ayrı siteleri olan bir franchise ağı. Her iş ortağının markası sizin değil, kendisinin.

Her iş ortağının sitesi sizin altyapınızı çalıştırır ama commerce API'yi kendi `publicKey`'iyle çağırır. Ürünleri, siparişleri, ödemeleri hep kendi hesabına bağlı. Hiçbir widget markalarının önüne geçmez.

### 4. Tamamen özel alıcı deneyimi

Etkileşimli ürün yapılandırıcıları (özel PC konfigürasyonları, kişiye özel mücevher, sipariş üzerine mobilya). 3B ürün görüntüleyiciler. Bir görseldeki piksellere tıklayınca ürünü sepete ekleyen "odayı satın al" fotoğraf galerileri. E-postanın içinde hızlı yeniden sipariş düğmeleri.

Widget bunların hiçbirini yapamaz. API yapabilir. Tasarımcınızın hayal ettiği arayüzü siz çizersiniz; arkasındaki ticaret mekaniğini API halleder.

### 5. Yapay zekâ ajanları ve ajan tabanlı ticaret

Ürünlere göz atabilen ve kullanıcı adına satın alma tamamlayabilen bir yapay zekâ ajanı (ChatGPT, Claude, özel bir ajan). Ajanın, ayrıştırmak zorunda kalacağı bir DOM widget'ına değil, kataloğunuza ve sepetinize programatik erişime ihtiyacı var.

Shoprocket, standart API erişiminin yanında yapay zekâ ticaret protokolleri için beslemeler de sunar. "50 $ altında, ücretsiz kargolu hangi ürünler stokta" diye sorulan bir ajan, ekran kazıma değil yapılandırılmış bir yanıt alır.

### 6. İçerik araçlarına gömülü ticaret

Blokları satın alınabilir olan bir Notion sayfası. Tıkla-satın-al noktaları olan bir Framer tasarımı. Abonelerin e-postadan çıkmadan bir ürün kartına dokunup ödeme yapabildiği bir bülten aracı. Hepsi bir API üzerine kurulu.

### 7. Özel raporlama ve BI panoları

Shoprocket paneli geliri, dönüşümü, en çok satan ürünleri gösterir. Göstermediği şey *sizin* özel metrikleriniz: müşteri kohortuna göre yaşam boyu değer, yönlendirme kaynağına göre sipariş, tedarikçi maliyeti sonrası marj. API sipariş ve müşteri verisini açar; böylece kendi BI aracınıza, elektronik tablonuza ya da iç panonuza akıtabilirsiniz.

## SDK bugün size ne veriyor

`@shoprocket/core` içinden:

```
// Products
sr.products.list({ limit, offset, sort, category })
sr.products.get(productId)

// Cart
sr.cart.get()
sr.cart.addItem(productId, quantity)
sr.cart.updateItem(itemId, quantity)
sr.cart.removeItem(itemId)

// Session
sr.session.create()
sr.setSessionToken(token)
```

Ayrıca SDK'nın henüz sarmalamadığı her şey için (siparişler, müşteriler, indirimler, ürün yazma) tam REST API var. Eksiksiz referans için [api.shoprocket.io/docs](https://api.shoprocket.io/docs) adresine bakın.

## API öncelikli yaklaşımın hata olduğu yerler

Widget'ın doğru seçim, API'nin ise gereğinden fazla olduğu birkaç durum:

- **10-200 ürünlü basit bir vitrin.** Widget bunu mükemmel gösterir; kendi katalog arayüzünüzü yazmak çözülmüş bir işi baştan yapmaktır.
- **Ayrılmış bir ön yüz mühendisliği kapasiteniz yok.** API öncelikli yaklaşım; yükleme durumlarını, varyant arayüzünü, hata yönetimini, erişilebilirliği ve 21 dilde i18n'i kendinizin yazıp sürdürmesini gerektirir. Widget bu haftalık işi size bedava verir.
- **Önceliğiniz yayına çıkış hızı.** Widget dakikalar sürer; API öncelikli yaklaşım en az haftalar.

Varsayılan olarak widget'ı kullanın. Widget'ın yapamadığı bir şeye çarptığınızda API'ye başvurun.

## Gerçekçi bir ilk proje

"API'ye ihtiyacım var" projelerinin en yaygını: kendi panelinin içinde kredi, abonelik ya da tek seferlik eklenti satmak isteyen bir SaaS ürünü.

Yaklaşım:

1. Ön yüzünüze `@shoprocket/core` kurun
2. Shoprocket'ta "Eklentiler" ya da benzeri bir kategori oluşturun
3. İstediğiniz tam fiyat / açıklamayla ürünleri ekleyin
4. Ürün listesini panelinizde kendi bileşen kütüphanenizle gösterin
5. Tıklamada sepete ekleyin + Shoprocket'ın barındırılan ödeme sayfasına yönlendirin (ek işe razıysanız ödeme adımını satır içi de gömebilirsiniz)
6. Satın alımın açtığı şeyi (kredi, erişim, gönderi) tanımlayabilmek için `order.paid` olaylarını alacak bir webhook uç noktası yapılandırın

Hepsi bu. Birkaç dosya, API çağırmaya alışkın biri için bir günlük iş. Widget yok, iframe yok, ürününüzün arayüzünden taviz yok.

## Önermediğimiz şey

Widget'ın zaten yaptığına çok benzeyen eksiksiz bir katalog arayüzünü baştan yazmayın. "Filtreli ve aramalı ürün ızgarası" için haftalar harcıyorsanız, widget'ın dakikalar içinde sunduğunu yazıyorsunuz demektir. Bu biçim için widget'ı kullanın, gerçekten farklı biçimler için API'yi.

> **İpucu:** Widget'ın varsayılan stili markanıza uymuyor diye API öncelikli yaklaşıma geçmeyi düşünüyorsanız, önce [widget'ın stil kancalarını](https://github.com/shoprocket/shoprocket-js) deneyin. Widget göründüğünden çok daha fazla CSS özelleştirmesi kabul eder. Tam API ile baştan kurmak çok daha ağır bir iştir.

## Kısaca

- **Widget** = varsayılan, mağazaların %95'ini kapsar
- **API / SDK** = widget doğru biçim olmadığında (SaaS içine gömülü ticaret, çok yüzey, beyaz etiket, özel kullanıcı deneyimi, yapay zekâ ajanları, özel BI)
- **Bugünkü SDK kapsamı:** ürünler, sepet, oturumlar; ayrıca siparişler / müşteriler / indirimler için tam REST API
- **İlk proje kalıbı:** kredi ya da eklentileri SDK + webhook ile tetiklenen yetkilendirme üzerinden satan SaaS paneli
- **Widget'ın zaten iyi yaptığı şeyi API ile baştan kurmayın**; biçiminizi seçin

[Ücretsiz denemeyi başlatın](https://app-v3.shoprocket.io/signup) ve bir public key alın; SDK her Shoprocket planında ücretsiz kullanılır. 14 gün, kart yok.

---

- HTML version: https://v3.shoprocket.io/tr/blog/commerce-api-kullanim-senaryolari-widget-ile-yapilamayan-yedi-proje
- Language: Türkçe (tr)
- Also in: [العربية](https://v3.shoprocket.io/ar/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Deutsch](https://v3.shoprocket.io/de/blog/commerce-api-anwendungsfaelle-sieben-builds-ohne-widget.md), [Ελληνικά](https://v3.shoprocket.io/el/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [English](https://v3.shoprocket.io/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Español](https://v3.shoprocket.io/es/blog/casos-de-uso-api-de-comercio-siete-proyectos-que-un-widget-no-puede-hacer.md), [Français](https://v3.shoprocket.io/fr/blog/api-commerce-sept-cas-usage-impossibles-avec-un-widget.md), [עברית](https://v3.shoprocket.io/he/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [हिन्दी](https://v3.shoprocket.io/hi/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Bahasa Indonesia](https://v3.shoprocket.io/id/blog/kasus-penggunaan-commerce-api-tujuh-hal-yang-tidak-bisa-dilakukan-widget.md), [Italiano](https://v3.shoprocket.io/it/blog/api-commerce-sette-casi-duso-che-un-widget-non-copre.md), [日本語](https://v3.shoprocket.io/ja/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Lietuvių](https://v3.shoprocket.io/lt/tinklarastis/prekybos-api-panaudojimo-atvejai-septyni-sprendimai-kuriu-nepadarysite-su-valdykle.md), [Norsk](https://v3.shoprocket.io/nb/blogg/handels-api-sju-ting-du-ikke-kan-bygge-med-en-widget.md), [Nederlands](https://v3.shoprocket.io/nl/blog/commerce-api-use-cases-zeven-projecten-zonder-widget.md), [Polski](https://v3.shoprocket.io/pl/blog/api-do-e-commerce-siedem-zastosowan-ktorych-nie-zrobisz-widzetem.md), [Português](https://v3.shoprocket.io/pt/blog/casos-de-uso-api-de-commerce-sete-projetos-que-widget-nao-faz.md), [Română](https://v3.shoprocket.io/ro/blog/cazuri-de-utilizare-api-comert-sapte-proiecte-fara-widget.md), [Русский](https://v3.shoprocket.io/ru/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [ไทย](https://v3.shoprocket.io/th/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [中文](https://v3.shoprocket.io/zh/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md)