WooCommerce REST API Derinlemesine İnceleme: Headless Mağazanızı Güçlendirin

🇬🇧 English: Read this in English →

WooCommerce REST API, her headless WooCommerce kurulumunun omurgasıdır. WPGraphQL esnekliğiyle daha çok dikkat çekse de, REST API en çok savaş testinden geçmiş, en iyi dokümante edilmiş ve en yaygın desteklenen seçenek olmaya devam ediyor. Üzerine production seviyesinde bir headless mağaza kurman için bilmen gereken her şey burada.

Açık konuşayım: yeni ve parlak olana koşmayı severim ama müşteri mağazası kurarken karar kriterim heyecan değil, dayanıklılık. REST API’nin en büyük artısı tam da sıkıcı olması — on yıldır ortalıkta, her dilde istemcisi var, her sorunu birileri Stack Overflow’da çoktan çözmüş. Bu yazıda kimlik doğrulamadan ödeme akışına, performanstan tuzaklara kadar sahada gerçekten işine yarayacak kısımları anlatacağım.

Kimlik Doğrulama

WooCommerce REST API üç kimlik doğrulama yöntemini destekler:

Consumer Key/Secret (Sunucudan Sunucuya)

Server-side rendering ve backend operasyonları için en iyisi. WooCommerce > Settings > REST API’da key’leri oluştur. Bu anahtarları sunucu tarafında, ortam değişkenlerinde tut — asla frontend paketine gömme, çünkü bu anahtar mağazanın tüm kapılarını açar.

import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api";

const api = new WooCommerceRestApi({
url: "https://your-store.com",
consumerKey: process.env.WC_CONSUMER_KEY,
consumerSecret: process.env.WC_CONSUMER_SECRET,
version: "wc/v3"
});

JWT Authentication (Client-Side)

Müşteri taraflı işlemler için (siparişleri görüntüleme, hesap yönetme) JWT kullan. WordPress’e JWT Authentication eklentisini yükle. Kimlik doğrulamanın inceliklerine ayrı bir yazıda daha derin girdim; burada aklında tutman gereken tek şey, token’ı güvenle nerede sakladığın.

// Login ve token alma
const auth = await fetch('https://your-store.com/wp-json/jwt-auth/v1/token', {
method: 'POST',
body: JSON.stringify({ username, password })
});
const { token } = await auth.json();

// Token'ı kimlik doğrulamalı istekler için kullanma
const orders = await fetch('https://your-store.com/wp-json/wc/v3/orders', {
headers: { 'Authorization': Bearer ${token} }
});

Application Passwords (WordPress 5.6+)

WordPress core’una yerleşik. Basit ama halka açık uygulamalar için daha az uygun.

Headless Mağazalar için Temel Endpoint’ler

Ürünler

GET    /wp-json/wc/v3/products              # Ürün listesi
GET    /wp-json/wc/v3/products/{id}          # Tek ürün
GET    /wp-json/wc/v3/products/{id}/variations  # Ürün varyasyonları
GET    /wp-json/wc/v3/products/categories    # Kategoriler
GET    /wp-json/wc/v3/products/tags          # Etiketler
GET    /wp-json/wc/v3/products/attributes    # Öznitelikler (Boyut, Renk, vb.)

Temel sorgu parametreleri:

• per_page (max 100), page — sayfalama
• category — kategori ID’sine göre filtreleme
• tag — etiket ID’sine göre filtreleme
• search — anahtar kelime arama
• orderby — date, title, price, popularity, rating
• min_price, max_price — fiyat aralığı filtresi
• stock_status — instock, outofstock, onbackorder

Sepet (CoCart veya Store API ile)

WooCommerce’in native REST API’sı sepet endpoint’lerini içermez — ve headless’a ilk geçenlerin en çok takıldığı yer tam olarak burasıdır. Ürünleri listeledin, siparişi oluşturdun, sıra sepete geldi ve elinde endpoint yok. İki gerçek seçenek var:

WooCommerce Store API (Block-tabanlı):

GET    /wp-json/wc/store/v1/cart
POST   /wp-json/wc/store/v1/cart/add-item
POST   /wp-json/wc/store/v1/cart/remove-item
POST   /wp-json/wc/store/v1/cart/update-item
POST   /wp-json/wc/store/v1/cart/apply-coupon

CoCart Eklentisi:

GET    /wp-json/cocart/v2/cart
POST   /wp-json/cocart/v2/cart/add-item
DELETE /wp-json/cocart/v2/cart/item/{item_key}

Siparişler

POST   /wp-json/wc/v3/orders      # Sipariş oluştur (ödeme)
GET    /wp-json/wc/v3/orders/{id}  # Sipariş detayları
PUT    /wp-json/wc/v3/orders/{id}  # Siparişi güncelle

Müşteriler

POST   /wp-json/wc/v3/customers        # Kayıt ol
GET    /wp-json/wc/v3/customers/{id}    # Profil
PUT    /wp-json/wc/v3/customers/{id}    # Profili güncelle

Ödeme Akışını Kurma

Headless ödeme en karmaşık kısımdır — ve bir projede zaman ve para nereye gidecekse, açık ara burasıdır. Ürün listelemek bir öğleden sonra, sağlam bir ödeme akışı ise haftalar meselesi. İşte tipik akış:

1. Sepet (Store API) → Ürünleri topla
Kargo bölgeleri → Kargo hesapla
Ödeme → Gateway üzerinden işle
Sipariş oluştur → Tüm veriyle POST /orders
Onay → Sipariş detaylarını göster

Ödemeli sipariş oluşturma:

const order = await api.post('orders', {
payment_method: 'stripe',
payment_method_title: 'Credit Card',
set_paid: false, // Payment gateway bunu halleder
billing: {
first_name: 'John', last_name: 'Doe',
address_1: '123 Main St', city: 'New York',
state: 'NY', postcode: '10001', country: 'US',
email: '[email protected]', phone: '555-0123'
},
shipping: { / aynı yapı / },
line_items: [
{ product_id: 93, quantity: 2 },
{ variation_id: 1234, quantity: 1 }
],
shipping_lines: [
{ method_id: 'flat_rate', method_title: 'Standard', total: '5.00' }
]
});

Performans Optimizasyonu

1. Alan Filtreleme

Sadece başlık, fiyat ve resme ihtiyacın varken tüm ürün nesnelerini çekme. Tek bir WooCommerce ürün nesnesi devasadır; liste sayfasında bunun onda birine bile ihtiyacın yok. _fields ile yükü küçültmek, ölçülebilir en ucuz hızlanmalardan biri:

GET /wp-json/wc/v3/products?_fields=id,name,price,images

2. Batch İstekleri

Birden fazla ürünü tek çağrıda güncelle. Elli ürünü tek tek elli istekle güncellemek, hem senin sunucunu hem WordPress’i boşuna yorar; batch endpoint bu işi tek turda halleder:

await api.post('products/batch', {
update: [
{ id: 1, stock_quantity: 50 },
{ id: 2, stock_quantity: 30 }
]
});

3. Cache Stratejisi

• Ürün listeleri: 5-10 dakika cache (Next.js’te ISR)
• Tek ürünler: 1-5 dakika cache
• Sepet: Asla cache’leme
• Stok seviyeleri: Maksimum 60 saniye cache

4. Sayfalama

Her zaman sayfalama yap. Asla tüm ürünleri bir seferde çekme. Response header’ı X-WP-TotalPages kaç sayfa olduğunu söyler. Bunu unutup on bin ürünlü bir katalogu tek istekle çekmeye kalkan bir kod, ilk büyük müşteride zaman aşımına düşer — sonra da “site neden yavaş” diye günlerce yanlış yerde ararsın.

Yaygın Tuzaklar

CORS: WordPress varsayılan olarak CORS’u etkinleştirmez. Theme’nizin functions.php’sine ekleyin veya eklenti kullanın:

add_action('init', function() {
header('Access-Control-Allow-Origin: https://your-frontend.com');
header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE');
header('Access-Control-Allow-Headers: Content-Type, Authorization');
});

Rate Limiting: WooCommerce’te yerleşik rate limiting yoktur, ama hosting sağlayıcında olabilir. Yük altında test et.

Resim URL’leri: Ürün resimleri tam WordPress URL’lerini döndürür. Frontend’in farklı domain’deyse, resimleri kendi CDN’in üzerinden proxy’lemeyi düşün.

Peki REST mi, WPGraphQL mi

Bu soru her headless projesinin başında masaya gelir, o yüzden dürüst cevabımı vereyim. WPGraphQL gerçekten zarif: tek istekte tam ihtiyacın olan alanları çekersin, iç içe verileri tek turda toplarsın, aşırı veri çekme (over-fetching) sorunu ortadan kalkar. Karmaşık, veri-yoğun bir arayüz kuruyorsan ciddi bir avantaj.

Ama ben olsam ilk mağazamı yine de REST üzerine kurardım, ve sebebi olgunluk. REST tarafında ekosistem daha geniş, resmi @woocommerce/woocommerce-rest-api istemcisi var, ödeme ve sipariş uç noktaları yıllardır aynı ve öngörülebilir. WPGraphQL için WooGraphQL katmanını ayrıca kurar, sürüm uyumunu ayrıca kollarsın. Kararı şuna indirgiyorum: ekibin GraphQL’i gerçekten biliyor ve arayüz veri grafiği karmaşıksa, WPGraphQL’e değer. Aksi halde REST ile başla; sıkıcı olan, gecenin üçünde seni uyandırmayandır.

Sonuç

WooCommerce REST API, tam bir headless mağazayı güçlendirecek kadar kapsamlı. Ana boşluklar — sepet yönetimi ve gerçek zamanlı özellikler — Store API ve CoCart tarafından doldurulur. Performans için alan filtreleme ve cache’lemeye odaklan, ödeme akışını da baştan dikkatli planla; çünkü asıl emek oraya gidiyor. API kararlı, iyi dokümante edilmiş ve production headless commerce için hazır. Yıllardır aynı şeyi söylüyorum: bir mağazanın altına koyacağın temel heyecan verici değil, güvenilir olmalı.