Headless CMS Mimarisi ve API Rehberi

Tecof CMS, tema bazlı collection ve item yönetimi sağlar. Admin paneli JWT korumalı /api/merchant/cms/* uçlarını kullanır; canlı storefront ise secret-key korumalı /api/store/cms/* uçlarıyla sadece yayınlanabilir içerikleri okur.

---

Veri Modeli

Collection

Collection; içerik şemasını, alan listesini, görüntülenecek alanı ve tema bağlantısını taşır.

Öne çıkan alanlar:

Alan	Açıklama
merchantId	Sahip merchant
themeId	Collection'ın bağlı olduğu aktif tema
name	Çok dilli collection adı
slug	Storefront erişim anahtarı
fields	Dinamik alan şeması
displayField	Listelerde gösterilecek alan
status	active veya inactive

Collection Item

Item; collection'a bağlı gerçek içerik kaydıdır.

Öne çıkan alanlar:

Alan	Açıklama
slug	Item slug
data	Dinamik alan verisi
metaTitle	SEO başlığı
metaDescription	SEO açıklaması
ogImage	Sosyal görsel
status	draft, scheduled, published
scheduledDate	Zamanlı yayın tarihi

---

Admin CMS API'leri

Bu uçlar satıcı paneli içindir ve JWT role auth ister.

Collection API

Metot	Endpoint	Açıklama
GET	/api/merchant/cms/collections/templates	Hazır collection şablonlarını listeler
GET	/api/merchant/cms/collections	Collection listesini getirir
GET	/api/merchant/cms/collections/by/id/:id	Collection detayını getirir
POST	/api/merchant/cms/collections	Collection oluşturur
PUT	/api/merchant/cms/collections/:id	Collection günceller
DELETE	/api/merchant/cms/collections/:id	Collection'ı soft delete yapar

Item API

Metot	Endpoint	Açıklama
GET	/api/merchant/cms/collections/:collectionId/items	Item listesini getirir
GET	/api/merchant/cms/collections/:collectionId/items/by/id/:id	Item detayını getirir
POST	/api/merchant/cms/collections/:collectionId/items	Item oluşturur
PUT	/api/merchant/cms/collections/:collectionId/items/:id	Item günceller
DELETE	/api/merchant/cms/collections/:collectionId/items/:id	Item'ı soft delete yapar
POST	/api/merchant/cms/collections/:collectionId/items/:id/publish	Item'ı yayına alır
POST	/api/merchant/cms/collections/:collectionId/items/:id/unpublish	Item'ı taslağa alır
POST	/api/merchant/cms/collections/:collectionId/items/:id/schedule	Item'ı ileri tarihe planlar
GET	/api/merchant/cms/collections/:collectionId/items/:id/revisions	Revizyon geçmişini listeler
POST	/api/merchant/cms/collections/:collectionId/items/:id/revisions/:revisionId/restore	Revizyon geri yükler
POST	/api/merchant/cms/collections/:collectionId/items/bulk-delete	Toplu siler
POST	/api/merchant/cms/collections/:collectionId/items/reorder	Sıralamayı günceller

---

Admin Query Parametreleri

Admin listelerinde desteklenen pratik parametreler:

Parametre	Açıklama
field=string	Çok dilli alanları seçilen dile düz string olarak çevirir
lang=tr	Çevrilecek dili belirtir
search=...	Slug ve data içinde arama yapar
status=published	Item status filtresi
page=1	Sayfalama
limit=20	Sayfa boyutu

Örnek:

GET /api/merchant/cms/collections/:collectionId/items?field=string&lang=tr&page=1&limit=20

---

Storefront CMS API'leri

Storefront uçları x-secret-key ister ve body üzerinden locale, page, limit, sort gibi değerleri alır.

Metot	Endpoint	Açıklama
POST	/api/store/cms/collections	Aktif collection listesini getirir
POST	/api/store/cms/collections/:slug	Collection detayını slug ile getirir
POST	/api/store/cms/collections/:slug/items	Collection item listesini getirir
POST	/api/store/cms/collections/:slug/items/:itemSlug	Tek item'ı slug ile getirir
POST	/api/store/cms/items/:id	Tek item'ı ID ile getirir

Örnek:

POST /api/store/cms/collections/blog/items
x-secret-key: merchant_secret_key
Content-Type: application/json

{
  "locale": "tr",
  "page": 1,
  "limit": 12,
  "sort": "newest"
}

---

Storefront Yayın Kuralları

Canlı API item görünürlüğünü şu kuralla sınırlar:

Item durumu	Storefront'ta görünür mü?
draft	Hayır
published	Evet
scheduled ve tarihi geldiyse	Evet
scheduled ve tarihi gelmediyse	Hayır

Storefront tarafı client'tan status filtresi kabul etmez. Böylece taslak içerikler yanlışlıkla temaya sızmaz.

---

Reference Alanları

Storefront CMS okuma katmanı reference ve multi-reference alanlarını tek seviye çözer. Referans verilen item canlı değilse değer null olur veya listeden çıkarılır.

Dönen item örneği:

{
  "_id": "item_id",
  "slug": "blog-yazisi",
  "data": {
    "title": "Blog Yazısı",
    "author": {
      "_id": "author_id",
      "slug": "ahmet",
      "data": {
        "name": "Ahmet"
      }
    }
  }
}

---

Webhook Davranışı

Bir CMS item yayına alındığında backend cms.item.published event'i için webhook dispatch eder. Payload içinde itemId, collectionId, slug, status ve publishedDate bulunur.

Webhook yönetimi için Uygulama Entegrasyonu sayfasına bakın.