Medusa v2 ile headless commerce mimarisini, ürün listeleme, sepet, checkout, workflow ve operasyon katmanlarını uçtan uca anlatan kapsamlı bir rehber.

Medusa V2 Kullanımı: Headless E-Ticaret Altyapısı Nasıl Kurulur?

Medusa v2, klasik “hazır mağaza kur ve tema değiştir” yaklaşımından farklı düşünülmeli. Burada asıl değer, commerce çekirdeğini ayrı bir backend olarak kullanıp storefront, admin deneyimi ve operasyon akışlarını ihtiyaca göre şekillendirebilmekte. Bir e-ticaret projesinde ürün listeleme, varyant yönetimi, sepet, ödeme, stok, kampanya ve sipariş sonrası operasyonlar aynı sistemin parçalarıdır; ancak hepsinin aynı frontend içinde birbirine dolanması uzun vadede ciddi bakım maliyeti doğurur.

Medusa v2’de storefront ayrı bir uygulamadır. Bu uygulama Next.js, React, Vue veya başka bir frontend teknolojisi olabilir. Storefront, Medusa backendindeki Store API rotalarına veya JS SDK’ya istek atar. Böylece tasarım tamamen size ait kalırken commerce davranışları daha düzenli bir çekirdekte yönetilir. Bu ayrım özellikle özel ürün deneyimi, editorial landing page, B2B fiyatlandırma, hediye notu, paketleme tercihi veya kampanya otomasyonu gibi standart tema mantığının dışına çıkan senaryolarda çok önemlidir.

Mimariyi önce kavramak

Headless commerce mimarisinde üç ana katman vardır: commerce backend, storefront ve operasyon paneli. Commerce backend ürün, fiyat, stok, sepet ve sipariş kurallarını yönetir. Storefront kullanıcıya görünen deneyimdir. Operasyon paneli ise içerik, sipariş, müşteri veya özel workflow takibini sağlar. Bu üç katmanı ayırınca ekipler de daha rahat çalışır: tasarımcı ürün kartını iyileştirirken backend ekibi ödeme sağlayıcılarını, operasyon ekibi ise sipariş hazırlama akışını geliştirebilir.

Kullanıcı -> Storefront -> Store API / JS SDK -> Medusa Backend -> PostgreSQL / Redis
                                      -> Custom Workflows -> Operasyon / CRM / Bildirim

Storefront bağlantısı

Next.js storefront tarafında SDK istemcisini tek bir dosyada toplamak gerekir. Böylece base URL, publishable key, debug ayarı ve ileride eklenecek ortak header’lar dağılmaz. Medusa Store API rotaları publishable API key ile scope edilir; bu nedenle key yönetimini baştan doğru kurmak gerekir.

import Medusa from '@medusajs/js-sdk'

const MEDUSA_URL = process.env.NEXT_PUBLIC_MEDUSA_URL || 'http://localhost:9000'

export const sdk = new Medusa({
  baseUrl: MEDUSA_URL,
  debug: process.env.NODE_ENV === "development",
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
})

Bu dosya küçük görünür ama projenin sınır çizgisidir. Storefront component’leri doğrudan URL bilmez; sadece sdk üzerinden ürün, sepet veya müşteri verisini ister. Bu disiplin test yazmayı ve ortam değiştirmeyi kolaylaştırır.

Ürün listeleme stratejisi

Ürün listeleme yalnızca “ürünleri getir” değildir. Liste sayfasında hangi alanlar lazımsa onları baştan belirlemek gerekir: görsel, başlık, fiyat, indirim bilgisi, kategori, varyant sayısı, stok durumu ve kısa açıklama. Kart içinde fiyat gösterilecekse fiyat hesaplama alanları; filtre olacaksa kategori ve tag alanları; ürün hikayesi varsa metadata alanları düşünülmelidir.

export async function listProducts(regionId: string, query?: string) {
  const { products, count } = await sdk.store.product.list({
    region_id: regionId,
    q: query,
    limit: 24,
    fields: "*variants.calculated_price,+metadata,+tags",
  })

  return { products, count }
}

Burada fields parametresini bilinçli kullanmak performans açısından değerlidir. Gereksiz veri çekmek liste sayfasını şişirir; eksik veri çekmek ise kart başına ek istek oluşturur. En iyi çözüm, tasarımda görünen bilgiyi veri ihtiyacına çevirmektir.

Sepet ve checkout

Sepet state’i genellikle kullanıcı cihazında cart id ile tutulur. Fakat asıl sepet verisi backend’dedir. Bu nedenle frontend’de cart id saklanır, fakat line item, toplam, teslimat ve ödeme hesapları Medusa tarafında güncel tutulur. Sepet güncelleme işlemleri optimistic UI ile daha hızlı hissettirilebilir ama backend yanıtı her zaman tek gerçek kaynak kabul edilmelidir.

export async function addLineItem(cartId: string, variantId: string, quantity = 1) {
  return sdk.store.cart.createLineItem(cartId, {
    variant_id: variantId,
    quantity,
  })
}

export async function setLineItemQuantity(cartId: string, lineId: string, quantity: number) {
  return sdk.store.cart.updateLineItem(cartId, lineId, { quantity })
}

Workflow ile özelleştirme

Medusa v2’nin güçlü yanlarından biri workflow yaklaşımıdır. Standart sipariş akışının önüne veya arkasına özel iş kuralları ekleyebilirsiniz. Örneğin hediye notu doğrulama, özel paketleme görevi oluşturma, stok dışında tedarik bildirimi üretme veya sipariş sonrası CRM’e aktivite düşme gibi işlemler workflow ile modellenebilir.

import { createWorkflow, WorkflowResponse } from '@medusajs/framework/workflows-sdk'

type Input = {
  orderId: string
  giftNote?: string
  packageType?: "standard" | "premium"
}

export const prepareOrderWorkflow = createWorkflow('prepare-order', (input: Input) => {
  // 1. Siparişi oku
  // 2. Özel alanları doğrula
  // 3. Operasyon görevi oluştur
  // 4. Bildirim veya CRM entegrasyonunu tetikle
  return new WorkflowResponse({ order_id: input.orderId })
})

Sonuç

Medusa v2 kullanırken asıl mesele “ürün listeleyebiliyor muyum?” değil, commerce davranışlarını ne kadar temiz sınırlara böldüğünüzdür. Storefront tasarım özgürlüğünü korur, Medusa commerce kurallarını yönetir, workflow katmanı ise işletmeye özgü süreci sisteme taşır. Bu üçlü doğru kurulduğunda e-ticaret projesi yalnızca satış ekranı değil, büyüyebilir bir operasyon altyapısı haline gelir.

Uygulamada dikkat edilmesi gereken detaylar

E-ticaret altyapısında en sık yapılan hata, kullanıcı arayüzünü commerce kurallarından kopuk tasarlamaktır. Ürün kartında görünen fiyat, sepet toplamında hesaplanan fiyatla aynı kaynaktan beslenmelidir. Varyant seçimi, stok durumu, bölge bazlı para birimi ve indirim bilgisi aynı veri modeline bağlanmadığında kullanıcı arayüzü güven kaybeder. Bu yüzden tasarımda görünen her bilgi için backend’de net bir kaynak belirlemek gerekir.

Bir diğer kritik nokta cache stratejisidir. Ürün listeleme sayfaları cachelenebilir; fakat sepet, ödeme, stok uyarısı ve kişiye özel fiyat gibi alanlarda daha dikkatli olunmalıdır. Statik hız ile canlı veri doğruluğu arasında denge kurulmalıdır. Özellikle kampanya dönemlerinde fiyat ve stok bilgisinin yanlış görünmesi, performans sorunundan daha büyük bir problemdir.

Test senaryoları

Canlıya çıkmadan önce yalnızca mutlu akış test edilmemelidir. Varyant stoğu bitince ne oluyor, ödeme oturumu yenilenemeyince kullanıcı ne görüyor, kargo seçeneği yoksa checkout nasıl davranıyor, indirim kodu geçersizse mesaj anlaşılır mı? Bu sorular test planına eklenmelidir.

Ölçüm

Başarıyı yalnızca sipariş sayısıyla ölçmek eksik kalır. Ürün detaydan sepete ekleme oranı, sepette terk oranı, checkout adımı bazlı düşüş, ödeme hatası oranı ve mobil dönüşüm oranı birlikte takip edilmelidir. Bu metrikler hem tasarım hem altyapı kararlarını iyileştirir.

Uygulama planı

Bu yaklaşımı gerçek bir projeye taşırken önce küçük ama doğru çalışan bir çekirdek kurulmalıdır. İlk adım veri modelini netleştirmek, ikinci adım API sözleşmesini belirlemek, üçüncü adım kullanıcı arayüzündeki ana akışı tamamlamak olmalıdır. Bundan sonra otomasyon, çeviri, raporlama veya medya yönetimi gibi ek katmanlar sırayla eklenebilir. Böyle ilerlemek hem geliştirme hızını korur hem de karmaşıklığın erkenden büyümesini engeller.

Ayrıca her teknik kararın kullanıcı veya operasyon karşılığı olmalıdır. Bir tablo, queue, SDK ya da dashboard bileşeni yalnızca teknik olarak doğru olduğu için değil, süreci daha anlaşılır, daha hızlı veya daha ölçülebilir yaptığı için eklenmelidir. Sağlam ürünler bu disiplinle büyür.