# Public API Referansı

> Vitrin /api/store sözleşmesi: auth başlıkları, render, CMS, e-ticaret, müşteri hesabı, analytics ve ödeme sağlayıcı geri dönüşleri.
>
> Kaynak: https://tecof-app-dev.vercel.app/public-apis · Bölüm: API’ler · Son güncelleme: 2018-10-20

Bu sayfa canlı tema, headless storefront, checkout ve analytics için dışarı verilmesi uygun olan mevcut API yüzeyini özetler.

Base URL örneği:

```text
https://api.tecof.com
```

---

## Auth Başlıkları

### Storefront secret key

Canlı tema API'leri merchant bağlamını `x-secret-key` ile çözer:

```http
x-secret-key: merchant_secret_key
Content-Type: application/json
```

### Customer auth

Müşteri hesabı gerektiren uçlarda customer JWT eklenir:

```http
x-secret-key: merchant_secret_key
Authorization: customer_jwt
```

### Editor write auth

Editör mutasyonları secret key'e ek olarak merchant/team JWT ister:

```http
x-secret-key: merchant_secret_key
Authorization: merchant_or_team_jwt
```

---

## Tema ve Render API'leri

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/store/editor/:id` | secret key | Editör için draft sayfa verisini getirir |
| `PUT` | `/api/store/editor/:id` | secret key + JWT | Sayfa draft verisini kaydeder |
| `POST` | `/api/store/render?themeId=:themeId&locale=:locale` | secret key | Yayındaki sayfayı slug ile render için getirir |
| `GET` | `/api/store/merchant-info` | secret key | Dil, default dil, logo, favicon, custom script ve under construction bilgisini getirir |
| `GET` | `/api/store/pages` | secret key | Link alanları ve sitemap için sayfa listesini getirir |
| `POST` | `/api/store/upload` | secret key + opsiyonel JWT | Dosya upload eder |
| `GET` | `/api/store/uploads` | secret key + opsiyonel JWT | Medya kütüphanesini listeler |
| `POST` | `/api/store/translate` | secret key + opsiyonel JWT | Metni birden çok dile çevirir |
| `GET` | `/api/store/shared-components` | secret key | Shared component listesini getirir |
| `POST` | `/api/store/shared-components` | strict auth ayarına bağlı | Shared component oluşturur |
| `POST` | `/api/store/stock-media/search` | secret key + opsiyonel JWT | Stok görsel arar |
| `POST` | `/api/store/stock-media/import` | secret key + opsiyonel JWT | Stok görseli merchant storage'a aktarır |
| `POST` | `/api/store/component-preview` | secret key + opsiyonel JWT | Component screenshot PNG üretir |

`/api/store/render` body örneği:

```json
{
  "slug": "home",
  "themeId": "theme_id",
  "locale": "tr",
  "showDraftData": false
}
```

---

## Storefront CMS API'leri

Bu uçlar sadece canlı içerik döndürür. Taslak item'lar sızmaz; `published` item'lar ve zamanı gelmiş `scheduled` item'lar görünür.

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

Item liste body örneği:

```json
{
  "locale": "tr",
  "page": 1,
  "limit": 20,
  "sort": "newest"
}
```

---

## Storefront E-Ticaret API'leri

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/store/ecommerce/categories` | secret key | Kategori ağacı |
| `GET` | `/api/store/ecommerce/products` | secret key | Ürün listesi ve filtreleme |
| `GET` | `/api/store/ecommerce/products/:slug` | secret key | Ürün detayı |
| `GET` | `/api/store/ecommerce/products/:slug/related` | secret key | Benzer ürünler |
| `GET` | `/api/store/ecommerce/search/suggest` | secret key | Ürün/kategori autocomplete |
| `GET` | `/api/store/ecommerce/products/:productId/reviews` | secret key | Onaylı yorumlar ve puan özeti |
| `POST` | `/api/store/ecommerce/products/:productId/reviews` | customer auth | Ürün yorumu gönderir |
| `POST` | `/api/store/ecommerce/cart/validate` | secret key | Sepeti stok/fiyat/indirim için doğrular |
| `POST` | `/api/store/ecommerce/checkout` | secret key | Sepetten sipariş oluşturur |
| `POST` | `/api/store/ecommerce/coupon/validate` | secret key | Kuponu sepete göre doğrular |
| `POST` | `/api/store/ecommerce/shipping/rates` | secret key | Adrese göre kargo seçenekleri |
| `POST` | `/api/store/ecommerce/checkout/initiate-payment` | secret key | Checkout ödeme formunu başlatır |
| `POST` | `/api/store/ecommerce/checkout/callback` | secret key | Storefront ödeme callback sonucu |
| `POST` | `/api/store/ecommerce/checkout-session` | secret key | Hosted checkout session oluşturur |
| `GET` | `/api/store/ecommerce/checkout-session/:uuid` | public | Hosted checkout session getirir |
| `PUT` | `/api/store/ecommerce/checkout-session/:uuid` | public | Hosted checkout session günceller |
| `GET` | `/api/store/ecommerce/push/config` | secret key | VAPID public key |
| `POST` | `/api/store/ecommerce/push/subscribe` | secret key | Push aboneliği oluşturur |
| `POST` | `/api/store/ecommerce/push/unsubscribe` | secret key | Push aboneliğini kaldırır |
| `POST` | `/api/store/ecommerce/email/subscribe` | secret key | Bülten aboneliği oluşturur |

Ürün liste query parametreleri:

```text
locale, page, limit, sort, category, brand, search, minPrice, maxPrice, tag
```

Desteklenen `sort` değerleri:

```text
newest, oldest, priceAsc, priceDesc, nameAsc, nameDesc
```

---

## Müşteri Hesabı API'leri

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/store/ecommerce/customer/register` | secret key | Müşteri kaydı |
| `POST` | `/api/store/ecommerce/customer/login` | secret key | Müşteri girişi |
| `POST` | `/api/store/ecommerce/customer/convert-guest` | secret key | Guest müşteriyi hesaba çevirir |
| `POST` | `/api/store/ecommerce/customer/verify-email` | secret key | E-posta doğrular |
| `POST` | `/api/store/ecommerce/customer/resend-verification` | customer auth | Doğrulama e-postasını yeniden gönderir |
| `POST` | `/api/store/ecommerce/customer/forgot-password` | secret key | Şifre sıfırlama e-postası ister |
| `POST` | `/api/store/ecommerce/customer/reset-password` | secret key | Şifre sıfırlar |
| `GET` | `/api/store/ecommerce/customer/me` | customer auth | Profil getirir |
| `PUT` | `/api/store/ecommerce/customer/me` | customer auth | Profil günceller |
| `PUT` | `/api/store/ecommerce/customer/password` | customer auth | Şifre değiştirir |
| `GET` | `/api/store/ecommerce/customer/orders` | customer auth | Siparişleri listeler |
| `GET` | `/api/store/ecommerce/customer/orders/:orderNumber` | customer auth | Sipariş detayı |
| `GET` | `/api/store/ecommerce/customer/addresses` | customer auth | Adresleri listeler |
| `POST` | `/api/store/ecommerce/customer/addresses` | customer auth | Adres ekler |
| `PUT` | `/api/store/ecommerce/customer/addresses/:addressId` | customer auth | Adres günceller |
| `DELETE` | `/api/store/ecommerce/customer/addresses/:addressId` | customer auth | Adres siler |
| `PUT` | `/api/store/ecommerce/customer/addresses/:addressId/default` | customer auth | Varsayılan adres yapar |

---

## Analytics API'leri

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/analytics/event` | public | Storefront event toplar, başarılıysa `204 No Content` döner |
| `GET` | `/api/analytics/stats` | JWT | Pageview, visitor, referrer, device ve top URL istatistikleri |
| `GET` | `/api/analytics/live` | JWT | Anlık ziyaretçi, bugünkü oturumlar ve checkout davranışı |

Event payload örneği:

```json
{
  "merchantId": "merchant_id",
  "url": "/products/example",
  "referrer": null,
  "type": "cart_add",
  "data": {
    "productId": "product_id",
    "quantity": 1
  },
  "ts": 1760000000000
}
```

Desteklenen event tipleri:

```text
pageview, custom, web-vital, cart_add, cart_remove, checkout_start
```

---

## Payment Provider Callback

Ödeme sağlayıcılarının çağırdığı public callback endpoint:

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/merchant/ecommerce/payments/callback/:provider` | public | `iyzico` veya `paytr` callback işler |

Bu endpoint müşteri tarayıcısından manuel çağrılmak için değil, ödeme sağlayıcı sunucularının callback'i için tasarlanmıştır.