Ücretsiz başla
Ürün
Online mağazaTema editörüÜrün yönetimiPazaryerleriÖdeme ve siparişPazarlama
Kaynaklar
Geliştirici portalıStorefront APIYol haritasıSık sorulanlar
TemalarFiyatlarGeliştiriciler
Ücretsiz başlaGiriş yap

Geliştiriciler / Vitrin

Storefront API

Mağazanın herkese açık veri katmanı. Yerleşik temalar da bu API’yi kullanır; kendi vitrininizi, mobil uygulamanızı ya da başka bir sitedeki “satın al” düğmenizi aynı uçlarla kurarsınız.

Temel adres ve sürüm

Bütün uçlar /storefront/v1 altındadır. Kırıcı bir değişiklik yeni bir sürüm (v2) olarak yayımlanır; v1 geçiş dönemi boyunca çalışmaya devam eder.

adres
https://api.<platform-alan-adı>/storefront/v1

Mağazayı tanıtmak

Her istek bir mağazaya aittir. Mağazayı alan adından çözün, dönen tenantId’yi sonraki isteklerde x-tenant-id başlığıyla gönderin. Katalog uçları ayrıca channelId ister.

curl
# 1. Alan adından mağazayı çöz
curl "https://api.ornek.com/storefront/v1/resolve?hostname=www.magazaniz.com"

# 2. Kiracı başlığıyla ürünü getir
curl "https://api.ornek.com/storefront/v1/products/keten-gomlek?channelId=$CHANNEL" \
  -H "x-tenant-id: $TENANT"
Storefront API yalnızca yayımlanmış katalog verisi döner; yönetim verisine (müşteri listesi, maliyet, ayarlar) bu yoldan ulaşılamaz. Yönetim işlemleri için anahtarlı API yol haritasında.

Para ve hatalar

Tutarlar kuruş cinsinden metin olarak gelir ("129900" = 1.299,00 TL); istemcide BigInt ya da tam sayı aritmetiğiyle işleyin. Başarısız istekler HTTP durum kodu ve Türkçe, alan bazlı bir gövde döner:

400 Bad Request
{
  "message": "Gönderilen veri geçersiz.",
  "errors": [{ "field": "quantity", "message": "Number must be greater than or equal to 1" }]
}

Mağaza

Kiracı başlığı gerektirmeyen tek uç resolvedur; diğer bütün uçlar x-tenant-id ister.

YöntemYolAçıklama
GET/resolve?hostname=Alan adından mağaza: tenantId, channelId, yerel ayar, para birimi, yayındaki tema ve menüler
GET/categoriesKategori ağacı
GET/trackingVitrinde çalışacak piksel yapılandırması (erişim jetonları dönmez)
GET/shipping-methodsKargo yöntemleri ve ücretleri
GET/payment-methods?amount=Tutara göre ödeme seçenekleri ve taksitler

Katalog

Katalog uçları channelId ister; fiyat ve stok o kanalın fiyat listesinden gelir.

YöntemYolAçıklama
GET/products/:slug?channelId=Ürün ayrıntısı: varyantlar, görseller (renge bağlı), fiyat, stok
GET/collections/:slug?channelId=&page=Kategori/koleksiyon sayfası, sayfalı
GET/search?channelId=&q=&page=Arama sonuçları
GET/product-lists/:source?channelId=&limit=Hazır listeler: best-sellers, newest, most-viewed
POST/product-viewÜrün görüntüleme kaydı (analitik)

Sepet

Sepet bir jetonla tanınır. Tutarlar her zaman sunucuda, kampanya motorundan geçerek hesaplanır.

YöntemYolAçıklama
POST/cartYeni sepet; { token } döner
GET/cart/:token?shipping=Sepet, satırlar ve fiyatlandırma
POST/cart/:token/linesSatır ekle { variantId, quantity }
POST/cart/:token/quantityAdet değiştir; 0 satırı siler
POST/cart/:token/couponKupon uygula ya da kaldır { couponCode | null }
POST/cart/priceJetonsuz fiyat hesaplama (satırlar, kupon, ödeme yöntemi)

Ödeme

Kart bilgisi platforma hiç girmez: ödeme, sağlayıcının güvenli sayfasına yönlendirmeyle alınır.

YöntemYolAçıklama
POST/checkoutSiparişi oluşturur (müşteri, adres, kargo, ödeme yöntemi)
POST/payments/startÖdeme oturumu; yönlendirilecek adres ya da iframe döner
GET/orders/:orderNumber?email=Misafir sipariş özeti

Müşteri hesabı

Oturumlu uçlar x-customer-token başlığı ister; jeton girişte bir kez döner.

YöntemYolAçıklama
POST/account/registerÜye ol
POST/account/loginGiriş; müşteri jetonu döner
POST/account/logoutÇıkış
GET/account/meOturumdaki müşteri
GET/account/ordersMüşterinin siparişleri
GET/account/addressesAdres defteri
POST/account/addressesAdres ekle/güncelle
POST/account/addresses/:id/deleteAdres sil
POST/account/password-reset/requestParola sıfırlama e-postası
POST/account/password-reset/applyYeni parolayı uygula

İçerik ve iletişim

Blog yazıları, içerik sayfaları ve formlar.

YöntemYolAçıklama
GET/postsBlog yazıları
GET/posts/:slugBlog yazısı
GET/pages/:slugİçerik sayfası (politikalar dahil)
POST/newsletterE-bülten aboneliği { email }
POST/contactİletişim formu { name, email, phone?, message }
GET/catalog-feedÜrün beslemesi (Google Merchant / Meta)

Uçtan uca örnek: sepetten ödemeye

odeme.ts
const { token } = await shop.createCart(store.channelId);
await shop.addToCart(token, variantId, 2);
await shop.setCartCoupon(token, 'HOSGELDIN');

const order = await shop.checkout({
  cartToken: token,
  channelId: store.channelId,
  email: '[email protected]',
  fullName: 'Ad Soyad',
  phone: '05xx xxx xx xx',
  address: { city: 'İstanbul', line1: '…' },
});

const payment = await shop.startPayment({
  orderId: order.orderId,
  provider: 'paytr',
  returnUrl: 'https://www.magazaniz.com/siparis',
});
// payment.redirectUrl → müşteriyi ödeme sayfasına yönlendirin