# Headless CMS Mimarisi ve API Rehberi

> CMS koleksiyon ve öğe modeli, panel (JWT) yönetim uçları, vitrin canlı içerik okuma, yayın kuralları ve referans alanları.
>
> Kaynak: https://tecof-app-dev.vercel.app/headless-cms · Bölüm: API’ler · Son güncelleme: 2018-10-20

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:

```http
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:

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

```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:

```json
{
  "_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.

Uygulamaların bu olaya aboneliği için [Webhook’lar](/app-webhooks), mağaza webhook’larının panel uçları için [Mağaza webhook’ları](/app-webhooks#magaza-webhooklari-panelden) bölümüne bakın.