Originos Storefront & Theme Developer API

Bu doküman Originos üzerinde web, mobil uygulama veya özel tema geliştiren frontend ekipleri içindir. Mağaza vitrininin ihtiyaç duyduğu tema config'i, katalog, sepet, checkout, müşteri hesabı, adres, sipariş ve dijital teslimat API'lerinin tamamını kapsar.

1. Hızlı başlangıç

Production API kökü:

https://originos.netkora.com/api/v1

Local API kökü:

http://127.0.0.1:8000/api/v1

Storefront isteklerinde mağazaya ait public API anahtarı gönderilir:

Accept: application/json
Content-Type: application/json
X-Store-Key: pk_live_...

Public storefront key tarayıcı veya mobil uygulamada kullanılabilir. sk_... ile başlayan secret anahtarlar frontend bundle'ına, public repository'ye veya tarayıcı storage'ına kesinlikle konulmamalıdır.

İlk bağlantı testi:

curl 'https://originos.netkora.com/api/v1/storefront/store' \
  -H 'Accept: application/json' \
  -H 'X-Store-Key: YOUR_PUBLIC_STORE_KEY'

JavaScript istemci örneği:

const API_URL = 'https://originos.netkora.com/api/v1'
const STORE_KEY = 'YOUR_PUBLIC_STORE_KEY'

async function originos(path, options = {}) {
  const response = await fetch(`${API_URL}${path}`, {
    ...options,
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
      'X-Store-Key': STORE_KEY,
      ...options.headers,
    },
  })

  const body = response.status === 204 ? null : await response.json()
  if (!response.ok) {
    throw Object.assign(new Error(body?.message || 'Originos API error'), {
      status: response.status,
      code: body?.code,
      errors: body?.errors,
      requestId: response.headers.get('X-Request-ID'),
    })
  }

  return body
}

2. Temel kurallar

Mağaza izolasyonu

X-Store-Key hangi mağazanın verisinin döneceğini belirler. Bir mağazaya ait ürün slug'ı, sepet token'ı, müşteri token'ı veya sipariş UUID'si başka mağazada kullanılamaz.

Doğrulanmış özel domain kullanılıyorsa mağaza host üzerinden de çözülebilir. Tema entegrasyonunda açık ve taşınabilir davranış için public store key gönderilmesi önerilir.

Kimlik doğrulama katmanları

Customer endpointlerinde hem X-Store-Key hem customer bearer token gönderilmelidir.

Para değerleri

Bütün amount alanları integer minor unit değeridir. Ondalıklı sayı kullanılmaz.

{"amount": 12990, "currency": "TRY"}

Bu değer 129,90 TRY anlamına gelir. Gösterim için para biriminin fraction digit bilgisi kullanılmalıdır:

function formatMoney(money, locale = 'tr-TR') {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency: money.currency,
  }).format(money.amount / 100)
}

Tarih, UUID ve sayfalama

• Tarihler ISO 8601 formatındadır.
• Public kaynak kimlikleri UUID'dir. Sepet item id değeri integer olabilir.
• Liste endpointleri genel olarak ?page=1&per_page=20 kabul eder.
• per_page en fazla 100 olabilir.
• Sayfalı yanıtlar Laravel resource formatındadır:

{
  "data": [],
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 20,
    "to": 1,
    "total": 1
  }
}

Rate limit

Limit aşılırsa 429 Too Many Requests döner. İstemci exponential backoff uygulamalı ve checkout için aynı Idempotency-Key değerini korumalıdır.

3. Originos Theme Contract 1.5.0

Hero alanı çoklu slider destekler. hero_slides en fazla 8 öğeden oluşur; her öğe title, subtitle, image, button_label ve button_url alanlarını taşır. hero_slider_autoplay otomatik geçişi, hero_slider_interval ise 3–15 saniye arasındaki geçiş süresini belirler. hero_slides boşsa geriye uyumluluk için hero_title, hero_subtitle, hero_image, hero_button_label ve hero_button_url alanları tek slide olarak kullanılmalıdır.

Her Originos teması aynı config şemasını kullanır. Müşteri tema değiştirdiğinde uyumlu mağaza ayarları korunur, eksik veya geçersiz değerler yeni temanın varsayılanlarıyla tamamlanır. Frontend'in tema bazında farklı config eşlemesi yapması gerekmez.

Tema config'i şu endpointten alınır:

GET /storefront/store

Manifest yapısı:

{
  "schema_version": "1.1.0",
  "assets": {
    "css": "https://cdn.example.com/originos/theme.css",
    "js": null
  },
  "settings": [
    {
      "key": "primary_color",
      "label": "Primary color",
      "group": "colors",
      "type": "color",
      "required": true,
      "default": "#111827"
    }
  ]
}

Runtime değerleri data.theme.settings içindeki key/value objesidir. Tasarım çalışırken manifestteki default yerine öncelikle bu resolved değerler kullanılmalıdır.

Kanonik tema ayarları

Önerilen CSS variable eşlemesi

function applyTheme(settings) {
  const root = document.documentElement

  root.style.setProperty('--color-primary', settings.primary_color)
  root.style.setProperty('--color-secondary', settings.secondary_color)
  root.style.setProperty('--color-accent', settings.accent_color)
  root.style.setProperty('--color-background', settings.background_color)
  root.style.setProperty('--color-text', settings.text_color)

  root.dataset.font = settings.font_family
  root.dataset.radius = settings.border_radius
  root.dataset.header = settings.header_style
  root.dataset.footer = settings.footer_style
  root.dataset.productCard = settings.product_card_style

  let customStyle = document.getElementById('originos-custom-css')
  if (!customStyle) {
    customStyle = document.createElement('style')
    customStyle.id = 'originos-custom-css'
    document.head.appendChild(customStyle)
  }
  customStyle.textContent = settings.custom_css || ''
}

Tema kodu bilinmeyen gelecekteki alanları görmezden gelmeli ve schema_version değerini kontrol etmelidir. Desteklenmeyen major sürüm görülürse güvenli bir varsayılan tasarım gösterilmelidir.

Tema paketi manifesti

Tema Originos kataloğuna eklenirken 38 alanın tamamını tekrar tanımlamak gerekmez. Tema yalnız değiştirmek istediği default değerlerini ve asset URL'lerini verir:

{
  "name": "Originos Modern",
  "slug": "originos-modern",
  "version": "1.1.0",
  "type": "free",
  "is_active": true,
  "is_public": true,
  "manifest": {
    "schema_version": "1.1.0",
    "assets": {
      "css": "https://cdn.example.com/originos-modern/1.1.0/theme.css",
      "js": null
    },
    "settings": [
      {"key": "primary_color", "default": "#2563eb"},
      {"key": "font_family", "default": "inter"},
      {"key": "header_style", "default": "centered"},
      {"key": "product_card_style", "default": "elevated"}
    ]
  }
}

Originos manifesti otomatik olarak tam sözleşmeye genişletir. 1.0.0–1.4.0 manifestler geriye uyumlulukla 1.5.0 sözleşmesine yükseltilir. Bilinmeyen key, farklı tip, farklı select seçenekleri veya desteklenmeyen schema version reddedilir.

4. Endpoint özeti

Tüm yollar https://originos.netkora.com/api/v1 köküne göredir.

Mağaza ve katalog

Sepet ve checkout

Customer hesabı

5. Mağaza config'i

GET /storefront/store

Storefront uygulamasının ilk açılışında çağrılması önerilir.

{
  "data": {
    "id": "STORE_UUID",
    "name": "Demo Store",
    "currency": "TRY",
    "locale": "tr",
    "timezone": "Europe/Istanbul",
    "maintenance": false,
    "logo_url": "https://cdn.example.com/logo.png",
    "favicon_url": "https://cdn.example.com/favicon.png",
    "settings": {
      "commerce": {
        "show_prices_with_tax": true,
        "show_out_of_stock": true
      },
      "contact": {
        "support_email": "support@example.com",
        "support_phone": "+905551112233"
      },
      "seo": {
        "title": "Demo Store",
        "description": "Mağaza açıklaması"
      },
      "announcement": {
        "enabled": true,
        "message": "Aynı gün kargo"
      },
      "payments": {
        "default_method": "bank_transfer",
        "bank_transfer": {
          "enabled": true,
          "bank_name": "Örnek Banka",
          "account_holder": "Demo Store A.Ş.",
          "iban": "TR00 0000 0000 0000 0000 0000 00",
          "branch": "Merkez",
          "instructions": "Sipariş numaranızı ödeme açıklamasına yazınız."
        }
      }
    },
    "homepage": {
      "section_order": ["hero", "announcement", "featured_products", "categories", "new_arrivals", "promo"],
      "hero": {"enabled": true, "title": "Welcome", "subtitle": "", "image": null, "button_label": "Shop now", "button_url": null},
      "announcement": {"enabled": true, "message": "Aynı gün kargo", "position": "top", "style": "bar"},
      "featured_products": {"enabled": true, "title": "Featured products", "limit": 8},
      "categories": {"enabled": true, "title": "Shop by category", "limit": 8},
      "new_arrivals": {"enabled": true, "title": "New arrivals", "limit": 8},
      "promo": {"enabled": false, "title": "Special offer", "subtitle": "Discover our latest offers.", "image": null, "button_label": "Explore", "button_url": null},
      "custom_css": ""
    },
    "theme": {
      "id": "THEME_UUID",
      "name": "Originos Starter",
      "slug": "originos-starter",
      "version": "1.1.0",
      "manifest": {
        "schema_version": "1.1.0",
        "assets": {"css": null, "js": null},
        "settings": "38 kanonik setting definition"
      },
      "settings": {
        "primary_color": "#111827",
        "secondary_color": "#ffffff",
        "accent_color": "#10b981",
        "background_color": "#ffffff",
        "text_color": "#111827",
        "font_family": "system",
        "border_radius": "medium",
        "header_style": "minimal",
        "footer_style": "columns",
        "product_card_style": "bordered",
        "catalog_columns": 4,
        "show_search": true,
        "show_categories": true,
        "hero_enabled": true,
        "hero_title": "Welcome",
        "hero_subtitle": "",
        "hero_image": null,
        "hero_button_label": "Shop now",
        "hero_button_url": null,
        "announcement_position": "top",
        "announcement_style": "bar",
        "homepage_section_order": ["hero", "announcement", "featured_products", "categories", "new_arrivals", "promo"],
        "homepage_featured_products_enabled": true,
        "homepage_featured_products_title": "Featured products",
        "homepage_featured_products_limit": 8,
        "homepage_categories_enabled": true,
        "homepage_categories_title": "Shop by category",
        "homepage_categories_limit": 8,
        "homepage_new_arrivals_enabled": true,
        "homepage_new_arrivals_title": "New arrivals",
        "homepage_new_arrivals_limit": 8,
        "promo_enabled": false,
        "promo_title": "Special offer",
        "promo_subtitle": "Discover our latest offers.",
        "promo_image": null,
        "promo_button_label": "Explore",
        "promo_button_url": null,
        "custom_css": ""
      }
    }
  }
}

theme aktif tema yoksa null olabilir. maintenance: true iken vitrin okunabilir; sepet oluşturma/değiştirme, customer register ve checkout STORE_MAINTENANCE ile durdurulur.

6. Ürünler

GET /storefront/products

Query parametreleri:

GET /storefront/products?search=kulaklık&page=1&per_page=24

Ürün örneği:

{
  "id": "PRODUCT_UUID",
  "type": "physical",
  "name": "Kablosuz Kulaklık",
  "slug": "kablosuz-kulaklik",
  "short_description": "Kısa açıklama",
  "description": "Uzun ürün açıklaması",
  "brand": "Originos",
  "image_url": "https://cdn.example.com/product.jpg",
  "categories": [
    {"id": "CATEGORY_UUID", "name": "Elektronik", "slug": "elektronik", "image_url": "https://cdn.example.com/category.jpg"}
  ],
  "options": [
    {
      "id": "OPTION_UUID",
      "name": "Renk",
      "values": [
        {"id": "VALUE_UUID", "value": "Siyah"}
      ]
    }
  ],
  "media": [
    {
      "id": "MEDIA_UUID",
      "type": "image",
      "url": "https://cdn.example.com/product.jpg",
      "alt_text": "Siyah kablosuz kulaklık"
    }
  ],
  "variants": [
    {
      "id": "VARIANT_UUID",
      "sku": "KB-SIYAH",
      "title": "Siyah",
      "price": {"amount": 129900, "currency": "TRY"},
      "option_values": ["Siyah"],
      "available": true
    }
  ]
}

Yalnız active, public ve yayın zamanı gelmiş ürünler döner. Ürün tipleri physical, digital veya epin olabilir. Sepete eklerken ürün ID'si değil variants[].id gönderilir. available: false varyantın satın alma butonu kapatılmalıdır.

GET /storefront/products/{slug}

Listeyle aynı ürün şemasını tek data objesi olarak döndürür. SEO/product detail sayfalarında canonical kimlik olarak slug kullanılabilir.

7. Kategoriler

GET /storefront/categories

Aktif kök kategorileri sort_order sırasıyla ve children alanıyla döndürür. Varsayılan per_page=50, maksimum 100.

{
  "data": [
    {
      "id": "CATEGORY_UUID",
      "name": "Elektronik",
      "slug": "elektronik",
      "description": null,
      "image_url": "https://cdn.example.com/category.jpg",
      "sort_order": 10,
      "parent_id": null,
      "children": []
    }
  ]
}

GET /storefront/categories/{slug}

Kategori bilgisi, çocuk kategoriler ve products alanını döndürür. Doğrudan ürünlerde varyantlar, stok durumu, medya ve birincil image_url bulunur.

8. Kargo seçenekleri

GET /storefront/shipping-methods

{
  "data": [
    {
      "id": "SHIPPING_UUID",
      "name": "Standart Kargo",
      "code": "standard",
      "type": "flat",
      "price": {"amount": 4990, "currency": "TRY"}
    }
  ]
}

Checkout ve hesaplama isteklerinde UUID değil code gönderilir. Sepette fiziksel ürün yoksa kargo otomatik olarak 0 olur.

9. Sepet

Sepet token'ı 64 karakterdir, mağazaya özeldir ve varsayılan olarak 7 gün geçerlidir. Tarayıcıda cookie veya local storage içinde saklanabilir. Customer token ile aynı şey değildir.

Sepet oluşturma

POST /storefront/cart

Body gerekmez.

{
  "data": {
    "id": "CART_UUID",
    "token": "64_CHARACTER_CART_TOKEN",
    "status": "active",
    "currency": "TRY",
    "items": [],
    "subtotal": {"amount": 0, "currency": "TRY"},
    "expires_at": "2026-08-17T12:00:00+03:00"
  }
}

Sepeti getirme

GET /storefront/cart/{token}

Varyant ekleme

POST /storefront/cart/{token}/items

{
  "variant_id": "VARIANT_UUID",
  "quantity": 2
}

quantity 1–100 arasındadır. Aynı varyant yeniden gönderildiğinde yeni satır açılmaz; mevcut satır miktarı verilen değerle değiştirilir.

Sepet item örneği:

{
  "id": 42,
  "product_id": "PRODUCT_UUID",
  "variant_id": "VARIANT_UUID",
  "name": "Kablosuz Kulaklık",
  "quantity": 2,
  "unit_price": {"amount": 129900, "currency": "TRY"},
  "line_total": {"amount": 259800, "currency": "TRY"}
}

Miktar güncelleme

PATCH /storefront/cart/{token}/items/{item}

{"quantity": 3}

Buradaki {item} sepet response'undaki integer item id değeridir.

Satır silme

DELETE /storefront/cart/{token}/items/{item}

Başarılı cevap 204 No Content.

Server-side hesaplama

POST /storefront/cart/{token}/calculate

{
  "coupon_code": "WELCOME10",
  "shipping_method_code": "standard",
  "payment_method": "bank_transfer"
}

Her iki alan da opsiyoneldir.

{
  "data": {
    "currency": "TRY",
    "items": [
      {
        "cart_item_id": 42,
        "product_id": "PRODUCT_UUID",
        "variant_id": "VARIANT_UUID",
        "name": "Kablosuz Kulaklık",
        "quantity": 2,
        "unit_price_amount": 129900,
        "subtotal_amount": 259800,
        "discount_amount": 25980,
        "tax_amount": 0,
        "total_amount": 233820
      }
    ],
    "subtotal": {"amount": 259800, "currency": "TRY"},
    "discount": {"amount": 25980, "currency": "TRY", "code": "WELCOME10"},
    "shipping": {"amount": 4990, "currency": "TRY", "method": "standard"},
    "tax": {"amount": 0, "currency": "TRY"},
    "total": {"amount": 238810, "currency": "TRY"}
  }
}

Frontend fiyat, indirim, kargo, vergi veya total üretmemelidir. Gösterilen nihai tutarlar her zaman bu endpointten veya checkout response'undan alınmalıdır.

10. Checkout

POST /storefront/checkout
Idempotency-Key: 0194f25b-6e24-7d12-a843-29f14e9bc542

Guest checkout body:

{
  "cart_token": "64_CHARACTER_CART_TOKEN",
  "email": "buyer@example.com",
  "phone": "+905551112233",
  "billing_address": {
    "first_name": "Ali",
    "last_name": "Yılmaz",
    "country": "TR",
    "city": "İstanbul",
    "address_line_1": "Örnek Mah. No: 1"
  },
  "shipping_address": {
    "first_name": "Ali",
    "last_name": "Yılmaz",
    "country": "TR",
    "city": "İstanbul",
    "address_line_1": "Örnek Mah. No: 1"
  },
  "coupon_code": "WELCOME10",
  "shipping_method_code": "standard"
}

Kurallar:

• Idempotency-Key zorunlu ve 16–255 karakterdir. Her yeni checkout denemesi için UUID önerilir.
• Network timeout veya belirsiz cevapta aynı body ve aynı key ile retry yapılır.
• Aynı key farklı body ile kullanılırsa 409 IDEMPOTENCY_KEY_REUSED döner.
• Registered checkout için aynı isteğe Authorization: Bearer {customer_token} eklenir. Backend email'i müşteri hesabından alır.
• billing_address zorunludur. country iki harf ISO ülke kodudur.
• shipping_address, coupon_code, shipping_method_code, payment_method ve phone opsiyoneldir.
• payment_method gönderilmezse settings.payments.default_method kullanılır. bank_transfer ve paytr desteklenir. PayTR seçildiğinde sipariş oluşturulduktan sonra /storefront/payments/paytr/token çağrılarak güvenli iframe URL'si alınır; sipariş durumu yalnız PayTR callback'i sonrasında değişir.
• Backend cart fiyatlarını yeniden okur, kuponu/kargoyu yeniden doğrular, fiziksel stok ile EPIN stoklarını transaction içinde rezerve eder.

Guest checkout response'unda guest_access_token yalnız sipariş ilk oluşturulduğunda düz metin olarak döner. Güvenli biçimde saklanmalıdır:

{
  "data": {
    "order_id": "ORDER_UUID",
    "order_number": "100001",
    "status": "pending",
    "payment_status": "pending",
    "fulfillment_status": "unfulfilled",
    "subtotal": {"amount": 259800, "currency": "TRY"},
    "discount": {"amount": 25980, "currency": "TRY", "code": "WELCOME10"},
    "shipping": {"amount": 4990, "currency": "TRY"},
    "tax": {"amount": 0, "currency": "TRY"},
    "total": {"amount": 238810, "currency": "TRY"},
    "items": [],
    "placed_at": "2026-08-10T12:00:00+03:00",
    "created_at": "2026-08-10T12:00:00+03:00",
    "guest_access_token": "ONE_TIME_GUEST_ORDER_TOKEN"
  }
}

Siparişe bank_transfer provider'ı eklenir ve ödeme durumu yönetici tahsilatı onaylayana kadar pending kalır. Tema kart bilgisi veya payment status üretmemeli; banka adı, hesap sahibi, IBAN, şube ve açıklamayı storefront config'ten göstermelidir.

11. Customer kayıt ve login

Kayıt

POST /storefront/customer/auth/register

{
  "first_name": "Ayşe",
  "last_name": "Demir",
  "email": "ayse@example.com",
  "phone": "+905551112233",
  "password": "Secure123",
  "password_confirmation": "Secure123",
  "device_name": "web-storefront"
}

Parola en az 8 karakter, en az bir harf ve bir rakam içermelidir. E-posta benzersizliği mağaza bazındadır.

201 yanıtı:

{
  "data": {
    "token": "1|CUSTOMER_TOKEN",
    "token_type": "Bearer",
    "customer": {
      "id": "CUSTOMER_UUID",
      "first_name": "Ayşe",
      "last_name": "Demir",
      "email": "ayse@example.com",
      "phone": "+905551112233",
      "created_at": "2026-08-10T12:00:00+03:00"
    }
  }
}

Login

POST /storefront/customer/auth/login

{
  "email": "ayse@example.com",
  "password": "Secure123",
  "device_name": "web-storefront"
}

Aynı device_name ile yeniden login olunduğunda önceki aynı adlı token iptal edilir.

Profil

GET /storefront/customer/me
Authorization: Bearer CUSTOMER_TOKEN

Logout

POST /storefront/customer/auth/logout
Authorization: Bearer CUSTOMER_TOKEN

Yalnız aktif token iptal edilir.

12. Customer adresleri

Customer bearer token gerektirir.

Adres şeması:

{
  "type": "both",
  "label": "Ev",
  "first_name": "Ayşe",
  "last_name": "Demir",
  "company": null,
  "phone": "+905551112233",
  "address_line_1": "Örnek Mah. No: 1",
  "address_line_2": "Daire 4",
  "city": "İstanbul",
  "state": "Kadıköy",
  "postal_code": "34710",
  "country": "TR",
  "is_default": true
}

type: billing, shipping veya both. Aynı tipte yeni bir adres is_default: true yapıldığında önceki varsayılan adres otomatik kaldırılır.

Başka müşterinin adresi güvenlik amacıyla 404 döner.

13. Sipariş görüntüleme

Registered customer siparişleri

GET /storefront/customer/orders?page=1&per_page=20
Authorization: Bearer CUSTOMER_TOKEN

GET /storefront/customer/orders/{order}
Authorization: Bearer CUSTOMER_TOKEN

Customer yalnız kendi siparişlerini görebilir.

Guest sipariş

GET /storefront/guest/orders/{order}
X-Order-Token: GUEST_ACCESS_TOKEN

Guest token yalnız checkout sırasında düz metin döner ve yalnız o sipariş için geçerlidir.

Sipariş durum alanları:

• status: pending, confirmed, processing, completed, cancelled
• payment_status: pending, authorized, paid, failed, partially_refunded, refunded
• fulfillment_status: unfulfilled, partial, fulfilled, cancelled

Order detail, ürün satırlarını ve yüklenmişse dijital downloads listesini döndürür. Müşteri response'unda yöneticiye özel payment transaction, fatura adresi ve dahili operasyon alanları gösterilmez.

14. Dijital ürün indirme

Ödeme ve fulfillment tamamlandıktan sonra customer veya guest order detail içindeki downloads[].download_url kullanılır:

{
  "id": "GRANT_UUID",
  "file": {
    "id": "FILE_UUID",
    "name": "E-kitap",
    "original_name": "kitap.pdf",
    "mime_type": "application/pdf",
    "size": 4829102
  },
  "download_url": "https://originos.netkora.com/api/v1/storefront/downloads/...?...",
  "download_count": 0,
  "max_downloads": 5,
  "expires_at": "2026-09-10T12:00:00+03:00"
}

download_url kısa süreli signed URL'dir ve olduğu gibi çağrılmalıdır. Registered customer grant'ında ayrıca customer bearer token gönderilir. Guest grant'ında URL içindeki signature ve token yeterlidir. Başarılı yanıt JSON değil dosya stream'idir.

Frontend URL süresi dolduğunda order detail'i yeniden çağırarak yeni signed URL almalıdır.

15. Hata formatları

Domain hatası:

{
  "message": "Cart has expired.",
  "code": "CART_EXPIRED"
}

Validation hatası:

{
  "message": "The given data was invalid.",
  "errors": {
    "billing_address.city": [
      "The billing address.city field is required."
    ]
  }
}

Önemli storefront hata kodları:

Her API response'unda X-Request-ID header'ı bulunur. Hata ekranında veya loglarda bu değer saklanmalı; destek taleplerinde paylaşılmalıdır.

16. Önerilen storefront akışı

1. Uygulama açılışında GET /storefront/store çağır.
2. Locale, currency, SEO, announcement ve tema config'ini uygula.
3. GET /storefront/categories ile navigasyonu oluştur.
4. GET /storefront/products ile kataloğu, slug endpointiyle ürün detayını göster.
5. İlk sepete eklemede POST /storefront/cart çağır ve token'ı sakla.
6. Varyantları POST /cart/{token}/items ile ekle.
7. Checkout ekranında kargo yöntemlerini al ve her değişiklikte /calculate çağır.
8. Customer login olmuşsa bearer token ekle; değilse guest checkout politikasına göre devam et.
9. Yeni UUID Idempotency-Key ile checkout çağır.
10. Guest siparişte dönen guest_access_token değerini güvenli sakla.
11. Sipariş detayını customer veya guest endpointinden takip et.
12. Dijital ürünlerde order detail'deki signed download URL'lerini kullan.

17. Frontend güvenlik kontrol listesi

• Yalnız pk_... public store key'i client tarafında kullan.
• Secret API key, merchant token veya platform token'ını temaya gömme.
• API'den gelen HTML metnini sanitize et; ürün açıklamasını kontrolsüz innerHTML ile basma.
• custom_css yalnız mağaza yöneticisinin güvenilen girdisi olarak ele alınmalı, <style>.textContent ile uygulanmalı ve HTML/script olarak çalıştırılmamalıdır.
• Tema asset URL'lerini yalnız güvenilen Originos/CDN kaynaklarından yükle ve mümkünse CSP allowlist kullan.
• Customer token'ını üçüncü taraf scriptlere aktarma.
• Checkout butonunu çift tıklamaya karşı kilitle; network retry'da aynı idempotency key'i koru.
• Fiyatları client tarafında otorite kabul etme.
• Guest order token'ını URL path, analytics event veya public log içine yazma.
• available: false varyantları sepete göndermeden engelle; backend kontrolünü yine de esas kabul et.
• X-Request-ID, hata code ve HTTP status değerlerini gözlemlenebilirlik için kaydet.

18. CORS

Storefront domain'i production ortamında CORS_ALLOWED_ORIGINS listesine eklenmelidir. İzin verilen request header'ları:

Accept
Authorization
Content-Type
Idempotency-Key
X-Order-Token
X-Request-ID
X-Store-Key

X-Request-ID browser tarafından okunabilir. Cookie credential kullanılmaz; customer auth bearer token ile çalışır.

19. API artifact'leri

• OpenAPI: https://originos.netkora.com/docs/openapi.yaml
• Postman Collection: https://originos.netkora.com/docs/postman/collection.json
• Production Environment: https://originos.netkora.com/docs/postman/production-environment.json
• Bu rehberin Markdown sürümü: https://originos.netkora.com/docs/storefront-theme-api.md
• Tarayıcıda okunabilir sürüm: https://originos.netkora.com/docs/storefront-theme-api

OpenAPI dosyası code generation ve şema inceleme; Postman collection ise gerçek akışları sırayla çalıştırmak için kullanılabilir.

20. Tema teslim kriterleri

Bir tema Originos'a hazır kabul edilmeden önce:

• Theme Contract 1.5.0 içindeki 84 ayarın tamamıyla çalışmalı. Müşteri hesabı ayarlarına ek olarak favori drawer'ı, cihazda saklanan son görüntülenen ürünler, indirim/karşılaştırma fiyatı ve mobil sticky satın alma seçenekleri desteklenmelidir.
• homepage.section_order sırasını, kapalı bölümleri ve bölüm limitlerini dikkate almalı.
• Banka havalesi ekranı settings.payments.bank_transfer alanlarını göstermeli; PayTR varsayılan olduğunda resmi PayTR logosu footer'da görünmeli ve ödeme PayTR güvenli iframe'i içinde açılmalıdır.
• Tema değiştirme sonrası ek config migration istememeli.
• theme: null durumunda güvenli fallback göstermeli.
• Mobile, tablet ve desktop responsive olmalı.
• Ürün tipi physical, digital ve epin için uygun durumları göstermeli.
• Varyant available durumunu dikkate almalı.
• Boş katalog, boş kategori, boş sepet, bakım ve API hata ekranları bulunmalı.
• Guest ve registered checkout akışları çalışmalı.
• Minor-unit para değerleri doğru formatlanmalı.
• Loading, retry ve rate-limit durumları yönetilmeli.
• Customer order ve signed digital download akışları doğrulanmalı.
• Secret credential içermemeli.