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

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

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şturun.

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ın. WordPress’e JWT Authentication eklentisini yükleyin.

// 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. Bunlardan birini kullanın:

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. İş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ız varken tüm ürün nesnelerini çekmeyin:

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

2. Batch İstekleri

Birden fazla ürünü tek çağrıda güncelleyin:

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ın. Asla tüm ürünleri bir seferde çekmeyin. Response header’ı X-WP-TotalPages kaç sayfa olduğunu söyler.

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ınızda olabilir. Yük altında test edin.

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

Sonuç

WooCommerce REST API, tam bir headless mağazayı güçlendirecek kadar kapsamlıdır. 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ın ve ödeme akışınızı dikkatli planlayın. API kararlı, iyi dokümante edilmiş ve production headless commerce için hazır.