# Fiyat listelerini listele (/api/fiyatlar/fiyat-listelerini-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Fiyat listesi oluştur (/api/fiyatlar/fiyat-listesi-olustur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Fiyat listesini getir (/api/fiyatlar/fiyat-listesini-getir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Fiyat listesini güncelle (/api/fiyatlar/fiyat-listesini-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Fiyat listesini sil (/api/fiyatlar/fiyat-listesini-sil)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Listeye fiyat yaz (/api/fiyatlar/listeye-fiyat-yaz)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Toplu fiyat güncelle (/api/fiyatlar/toplu-fiyat-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# API referansı (/api)

Bütün uçlar `https://api.multikolay.com/v1/` altında. Önce [Başlangıç](/baslangic)'taki kuralları oku:
[kimlik doğrulama](/baslangic/kimlik-dogrulama), [sayfalama](/baslangic/sayfalama), [hatalar](/baslangic/hatalar),
[tekrar anahtarı](/baslangic/tekrar-anahtari).

<Callout title="Her uç sayfasında Dene">
  **Dene** düğmesi isteği tarayıcından [test mağazasına](/baslangic/test-magazasi) atar; anahtar alanı herkese açık
  test anahtarıyla dolu gelir. Örnek yanıtlar da o mağazanın gerçek yanıtlarıdır.
</Callout>

| Bölüm | Ne var |
| --- | --- |
| [Mağaza](/api/magaza/magazayi-getir) | Anahtarın mağazası ve izinleri |
| [Ürünler](/api/urunler/urunleri-listele) | Ürün ve varyant ekle, değiştir, sil |
| [Kategoriler](/api/kategoriler/kategorileri-listele) | Kategoriler, koleksiyonlar, markalar |
| [Stok](/api/stok/stok-seviyelerini-listele) | Depo stokları, toplu stok |
| [Fiyatlar](/api/fiyatlar/toplu-fiyat-guncelle) | Toplu fiyat, fiyat listeleri |
| [Siparişler](/api/siparisler/siparisleri-listele) | Siparişler, kargoya verme, teslim, iptal, not, havale onayı, iadeler |
| [Müşteriler](/api/musteriler/musterileri-listele) | Müşteriler ve müşteri grupları |
| [Kampanyalar](/api/kampanyalar/kampanyalari-listele) | Kampanyalar ve indirim kodları |
| [Sayfalar ve menüler](/api/sayfalar-ve-menuler/sayfalari-listele) | İçerik sayfaları, menüler |
| [Webhook'lar](/api/webhooklar/webhooklari-listele) | Abonelikler, test olayı, teslimatlar |

Bütün tanım OpenAPI 3.1 olarak [`/v1/openapi.json`](https://api.multikolay.com/v1/openapi.json)'da; Postman,
Insomnia ya da kod üreticine doğrudan verebilirsin.


# Kampanya oluştur (/api/kampanyalar/kampanya-olustur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Kampanyaları listele (/api/kampanyalar/kampanyalari-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Kampanyayı getir (/api/kampanyalar/kampanyayi-getir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Kampanyayı güncelle (/api/kampanyalar/kampanyayi-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Kampanyayı sil (/api/kampanyalar/kampanyayi-sil)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Kategori güncelle (/api/kategoriler/kategori-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Kategori oluştur (/api/kategoriler/kategori-olustur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Kategori sil (/api/kategoriler/kategori-sil)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Kategorileri listele (/api/kategoriler/kategorileri-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Koleksiyon güncelle (/api/kategoriler/koleksiyon-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Koleksiyon oluştur (/api/kategoriler/koleksiyon-olustur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Koleksiyon sil (/api/kategoriler/koleksiyon-sil)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Koleksiyonları listele (/api/kategoriler/koleksiyonlari-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Marka güncelle (/api/kategoriler/marka-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Marka oluştur (/api/kategoriler/marka-olustur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Marka sil (/api/kategoriler/marka-sil)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Markaları listele (/api/kategoriler/markalari-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Mağazayı getir (/api/magaza/magazayi-getir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Gruba müşteri ekle / çıkar (/api/musteriler/gruba-musteri-ekle-cikar)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Müşteri grubu oluştur (/api/musteriler/musteri-grubu-olustur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Müşteri grubunu sil (/api/musteriler/musteri-grubunu-sil)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Müşteri gruplarını listele (/api/musteriler/musteri-gruplarini-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Müşteri oluştur (/api/musteriler/musteri-olustur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Müşterileri listele (/api/musteriler/musterileri-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Müşteriyi getir (/api/musteriler/musteriyi-getir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Müşteriyi güncelle (/api/musteriler/musteriyi-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Menüyü getir (/api/sayfalar-ve-menuler/menuyu-getir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Menüyü temaya döndür (/api/sayfalar-ve-menuler/menuyu-temaya-dondur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Menüyü yaz (/api/sayfalar-ve-menuler/menuyu-yaz)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Sayfa oluştur (/api/sayfalar-ve-menuler/sayfa-olustur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Sayfaları listele (/api/sayfalar-ve-menuler/sayfalari-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Sayfayı getir (/api/sayfalar-ve-menuler/sayfayi-getir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Sayfayı güncelle (/api/sayfalar-ve-menuler/sayfayi-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Sayfayı sil (/api/sayfalar-ve-menuler/sayfayi-sil)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Sayfayı yayından kaldır (/api/sayfalar-ve-menuler/sayfayi-yayindan-kaldir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Sayfayı yayınla (/api/sayfalar-ve-menuler/sayfayi-yayinla)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Havale ödemesini onayla (/api/siparisler/havale-odemesini-onayla)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# İadeleri listele (/api/siparisler/iadeleri-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# İadeyi getir (/api/siparisler/iadeyi-getir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Kargoya ver (/api/siparisler/kargoya-ver)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Siparişe not ekle (/api/siparisler/siparise-not-ekle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Siparişi getir (/api/siparisler/siparisi-getir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Siparişi iptal et (/api/siparisler/siparisi-iptal-et)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Siparişleri listele (/api/siparisler/siparisleri-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Teslim edildi olarak işaretle (/api/siparisler/teslim-edildi-olarak-isaretle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Depoları listele (/api/stok/depolari-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Stok seviyelerini listele (/api/stok/stok-seviyelerini-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Toplu stok güncelle (/api/stok/toplu-stok-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Ürün oluştur (/api/urunler/urun-olustur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Ürünleri listele (/api/urunler/urunleri-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Ürünü getir (/api/urunler/urunu-getir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Ürünü güncelle (/api/urunler/urunu-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Ürünü sil (/api/urunler/urunu-sil)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Varyantı güncelle (/api/urunler/varyanti-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# İmza sırrını yenile (/api/webhooklar/imza-sirrini-yenile)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Olay türlerini listele (/api/webhooklar/olay-turlerini-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Teslimatı yeniden gönder (/api/webhooklar/teslimati-yeniden-gonder)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Teslimatları listele (/api/webhooklar/teslimatlari-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Test olayı gönder (/api/webhooklar/test-olayi-gonder)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Webhook oluştur (/api/webhooklar/webhook-olustur)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Webhook'ları listele (/api/webhooklar/webhooklari-listele)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Webhook'u getir (/api/webhooklar/webhooku-getir)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Webhook'u güncelle (/api/webhooklar/webhooku-guncelle)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# Webhook'u sil (/api/webhooklar/webhooku-sil)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}


# AI ajanlarıyla (/baslangic/ai-ajanlari)

Kod yazarken kullandığın AI ajanı MultiKolay'ı tahmin etmek zorunda değil: **MCP sunucumuz** ona belgeleri, API
şemasını ve tema denetimini doğrudan verir.

```txt
https://docs.multikolay.com/mcp
```

Giriş gerekmez; sunucu yalnız okur, mağaza verisine dokunmaz. API isteklerini ajan kendi anahtarınla (ya da
[test anahtarıyla](/baslangic/test-magazasi)) kendisi atar.

## Bağlan [#bağlan]

<Tabs items={['Claude Code', 'Claude Desktop', 'Cursor', 'VS Code']}>
<Tab value="Claude Code">

```bash
claude mcp add --transport http multikolay https://docs.multikolay.com/mcp
```

</Tab>
<Tab value="Claude Desktop">

**Ayarlar → Bağlayıcılar → Özel bağlayıcı ekle**; adres olarak `https://docs.multikolay.com/mcp` yaz.

</Tab>
<Tab value="Cursor">

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "multikolay": { "url": "https://docs.multikolay.com/mcp" }
  }
}
```

</Tab>
<Tab value="VS Code">

```json title=".vscode/mcp.json"
{
  "servers": {
    "multikolay": { "type": "http", "url": "https://docs.multikolay.com/mcp" }
  }
}
```

</Tab>
</Tabs>

## Araçlar [#araçlar]

| Araç | Ne yapar |
| --- | --- |
| `belge_ara` | Belgelerde arar; sayfa adresleri ve ilgili parçalar döner. |
| `belge_oku` | Bir sayfanın tamamını Markdown olarak döner. Adres `/` bütün sayfaların listesi. |
| `api_uclari` | API uçlarının listesi: yöntem, yol, gereken izin, belge sayfası. Bölüme göre süzülür. |
| `api_ucu` | Bir ucun parametreleri, istek gövdesi ve yanıt şeması. |
| `tema_dogrula` | Tema paketini yüklemedeki denetimin aynısıyla denetler; [temel tema](/tema/tema-mirasi) varsa onunla birlikte. |
| `bolum_ciz` | Paketteki bir bölümü vitrindeki motorla, örnek mağaza verisiyle HTML'e çizer. |

Sunucu IP başına dakikada 120 isteğe ve 5 MB pakete kadar yanıt verir.

## Hazır komutlar [#hazır-komutlar]

Sunucu üç hazır komut da verir. Claude Code'da `/` yazınca görünür:

| Komut | Ne yapar |
| --- | --- |
| `/mcp__multikolay__tema-yaz` | Tarif ettiğin temayı Liman'dan miras alarak yazar, denetler, bölümleri çizer; `npx @multikolay/tema paketle` ile zip'ler. |
| `/mcp__multikolay__api-entegrasyonu` | Bir işi (stok eşitleme, sipariş aktarma…) API'yle yapan kodu yazar, test mağazasında dener. |
| `/mcp__multikolay__webhook-karsila` | Seçtiğin olayları alıp imzayı doğrulayan uç noktayı yazar. |

Komut kullanmak zorunda değilsin: ajanına ne istediğini yazman yeter, araçları kendisi çağırır. Bağlantıyı yeni
eklediysen araçlar ve komutlar **yeni oturumda** görünür; Claude Code'da `/mcp` ile durumuna bakabilirsin.

## Örnek istekler [#örnek-istekler]

- "MultiKolay API'siyle stok kodu GLS-VAZO olan ürünün stoğunu 12 yapan bir Node betiği yaz, test anahtarıyla dene."
- "Liman'dan miras alan, giriş bölümü tam ekran video olan bir tema yaz; tema_dogrula ile denetle, zip'le."
- "Yeni sipariş webhook'unu karşılayıp imzasını doğrulayan bir PHP uç noktası yaz."

## MCP'siz [#mcpsiz]

Ajanın MCP desteklemiyorsa belgelerin düz metnini ver:

- [`/llms.txt`](/llms.txt): bütün sayfaların listesi
- [`/llms-full.txt`](/llms-full.txt): bütün belgeler tek dosyada
- Her sayfanın sonuna `.md` ekle: [`/baslangic/hatalar.md`](/baslangic/hatalar.md)
- API'nin makinece tanımı: [`/v1/openapi.json`](https://api.multikolay.com/v1/openapi.json)


# Hatalar (/baslangic/hatalar)

Başarısız her istek bir HTTP durum kodu ve şu gövdeyi döner:

```json
{
  "hata": {
    "kod": "izin_yok",
    "mesaj": "Bu anahtarın \"siparis:yazma\" izni yok. Panelde Ayarlar → API anahtarları'ndan yeni anahtar oluşturun."
  }
}
```

- **`kod`** makine içindir: sabit, küçük harf, alt çizgili. Kodunda buna göre dallan.
- **`mesaj`** insan içindir: Türkçe, ne yapılacağını söyler. Metni değişebilir; koşul olarak kullanma.

## Kodlar [#kodlar]

| Durum | `kod` | Anlamı |
| --- | --- | --- |
| 400 | `gecersiz_json` | Gövde geçerli JSON değil |
| 400 | `gecersiz_tekrar_anahtari` | `Idempotency-Key` 1–255 karakter olmalı |
| 401 | `anahtar_yok` | `Authorization: Bearer …` başlığı yok ya da biçimi yanlış |
| 401 | `anahtar_gecersiz` | Anahtar geçersiz ya da iptal edilmiş |
| 403 | `izin_yok` | Anahtarda bu ucun izni yok |
| 403 | `magaza_donduruldu` | Mağaza dondurulmuş |
| 403 | `acik_anahtar_silemez` | Test anahtarıyla silme denendi |
| 404 | `bulunamadi` | Kayıt ya da uç yok |
| 409 | `tekrar_suruyor` | Aynı `Idempotency-Key` ile bir istek hâlâ işleniyor |
| 409 | `musteri_var` | Bu e-postayla müşteri zaten var |
| 409 | `depo_yok` | Verilen depo bu mağazada yok |
| 415 | `json_gerekli` | Gövdeli istekte `Content-Type: application/json` yok |
| 422 | `gecersiz_girdi` | Alan doğrulaması tutmadı; mesaj alanı söyler (`kalemler.0.miktar: …`) |
| 422 | `varyant_bulunamadi` | SKU ya da varyant kimliği yok |
| 422 | `tekrar_anahtari_kullanildi` | `Idempotency-Key` başka bir istekle kullanılmış |
| 422 | `gorsel_indirilemedi`, `gorsel_turu`, `gorsel_buyuk` | Verilen görsel adresi indirilemedi, türü ya da boyutu uygun değil |
| 429 | `istek_siniri` | [İstek sınırı](/baslangic/istek-siniri) aşıldı |
| 500 | `sunucu_hatasi` | Bizim tarafta bir sorun; tekrar dene, sürerse bize yaz |

## Tekrar denemeli mi? [#tekrar-denemeli-mi]

- **429 ve 5xx:** evet. 429'da `Retry-After` kadar bekle; 5xx'te artan aralıklarla (1, 2, 4… sn) dene.
  Yazan isteklerde [`Idempotency-Key`](/baslangic/tekrar-anahtari) gönderdiysen tekrar güvenlidir.
- **4xx (429 dışı):** hayır. İstek değişmeden tekrar edilirse aynı hatayı alır.


# Hızlı başlangıç (/baslangic/hizli-baslangic)

<Steps>
<Step>

### Anahtar al [#anahtar-al]

Kendi mağazan için: panelde **Ayarlar → API anahtarları → Yeni anahtar**. Anahtara bir ad ver (ör. "Logo ERP") ve
yalnız gereken [izinleri](/baslangic/kimlik-dogrulama#izinler) seç. Anahtar **bir kez** gösterilir; hemen sakla.

Henüz mağazan yoksa herkese açık test anahtarını kullan:

```bash
export MK_API_ANAHTARI=mk_test_7s2aioX6OhmIG4rvnCt1HpXowToq3sdx
```

</Step>
<Step>

### İlk isteği at [#i̇lk-isteği-at]

`GET /v1/magaza` anahtarın hangi mağazaya ait olduğunu ve hangi izinleri taşıdığını söyler.

```bash
curl https://api.multikolay.com/v1/magaza \
  -H "Authorization: Bearer $MK_API_ANAHTARI"
```

```json
{
  "id": "gelistirici",
  "ad": "geliştirici",
  "adres": "https://gelistirici.multikolay.com",
  "para_birimi": "TRY",
  "dil": "tr-TR",
  "plan": "plus",
  "anahtar": { "test": true, "kapsamlar": ["urun:okuma", "urun:yazma", "…"] },
  "sunucu_saati": "2026-10-19T05:28:12.919Z"
}
```

</Step>
<Step>

### Veri çek [#veri-çek]

Ürünleri iki iki listele. Yanıttaki `sonraki` doluysa bir sonraki sayfayı onunla iste.

<Tabs items={['cURL', 'Node.js', 'PHP', 'Python']}>
<Tab value="cURL">

```bash
curl "https://api.multikolay.com/v1/urunler?limit=2" \
  -H "Authorization: Bearer $MK_API_ANAHTARI"
```

</Tab>
<Tab value="Node.js">

```js
const yanit = await fetch('https://api.multikolay.com/v1/urunler?limit=2', {
  headers: { Authorization: `Bearer ${process.env.MK_API_ANAHTARI}` },
})
const { veri, sonraki } = await yanit.json()
for (const urun of veri) console.log(urun.ad, urun.varyantlar[0].fiyat / 100, '₺')
```

</Tab>
<Tab value="PHP">

```php
$ch = curl_init('https://api.multikolay.com/v1/urunler?limit=2');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('MK_API_ANAHTARI')],
]);
$yanit = json_decode(curl_exec($ch), true);
foreach ($yanit['veri'] as $urun) echo $urun['ad'], PHP_EOL;
```

</Tab>
<Tab value="Python">

```python
import os, requests

yanit = requests.get(
    "https://api.multikolay.com/v1/urunler",
    params={"limit": 2},
    headers={"Authorization": f"Bearer {os.environ['MK_API_ANAHTARI']}"},
)
for urun in yanit.json()["veri"]:
    print(urun["ad"])
```

</Tab>
</Tabs>

</Step>
<Step>

### Yaz, sonra canlıya al [#yaz-sonra-canlıya-al]

Bir varyantın stoğunu SKU ile güncelle. Yazan isteklerde `Idempotency-Key` gönder: bağlantı koparsa aynı isteği
güvenle tekrarlayabilirsin ([ayrıntı](/baslangic/tekrar-anahtari)).

```bash
curl -X POST https://api.multikolay.com/v1/stok/toplu \
  -H "Authorization: Bearer $MK_API_ANAHTARI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stok-2026-10-19-001" \
  -d '{ "kalemler": [{ "sku": "GLS-VAZO", "miktar": 12 }] }'
```

Test mağazasında çalışan kodun, kendi mağazanın `mk_canli_…` anahtarıyla aynen çalışır. Değişen tek şey anahtar.

</Step>
</Steps>


# MultiKolay geliştirici belgeleri (/baslangic)

MultiKolay'da üç şekilde geliştirme yapabilirsin. Her birinin kendi rehberi ve referansı var.

<Cards>
  <Card title="Tema geliştir" href="/tema">
    Liquid bölümler, ayar şeması ve tema mirasıyla mağaza vitrini yaz.
  </Card>
  <Card title="API ile entegre et" href="/api">
    Ürün, stok, fiyat ve siparişleri ERP, muhasebe ya da depo yazılımınla eşitle.
  </Card>
  <Card title="Olaylara abone ol" href="/webhook">
    Sipariş gelince, stok değişince, iade açılınca kendi sunucuna haber al.
  </Card>
  <Card title="5 dakikada başla" href="/baslangic/hizli-baslangic">
    Herkese açık test anahtarıyla ilk isteğini hemen at.
  </Card>
  <Card title="AI ajanlarıyla" href="/baslangic/ai-ajanlari">
    Claude, Cursor gibi ajanlarını MCP sunucumuza bağla.
  </Card>
</Cards>

## API'nin temel kuralları [#apinin-temel-kuralları]

- **Adres:** `https://api.multikolay.com/v1/…`. Hangi mağazayla çalışacağını anahtar belirler; adreste mağaza adı yoktur.
- **Türkçe adlar:** uçlar ve alanlar Türkçedir: `/v1/urunler`, `siparisler`, `toplam`, `guncelleme`.
- **Para kuruş cinsinden tam sayıdır,** KDV dahil: `184990` = 1.849,90 ₺. Ayrıntı: [Para ve tarih](/baslangic/para-ve-tarih).
- **Listeler imleçle sayfalanır:** `?limit=…&sonraki=…`. Ayrıntı: [Sayfalama](/baslangic/sayfalama).
- **Hatalar tek biçimdedir:** `{ "hata": { "kod", "mesaj" } }`. Ayrıntı: [Hatalar](/baslangic/hatalar).
- **Bütün paketlerde açık:** paket yalnız [istek sınırını](/baslangic/istek-siniri) değiştirir.

Bütün uçların makinece okunur tanımı OpenAPI 3.1 biçiminde
[`/v1/openapi.json`](https://api.multikolay.com/v1/openapi.json) adresinde. Postman, Insomnia ya da kod üreticine
doğrudan verebilirsin.


# İstek sınırı (/baslangic/istek-siniri)

| Paket | Dakikada istek (anahtar başına) |
| --- | --- |
| Temel | 120 |
| Plus | 600 |
| Pro | 1200 |
| [Test mağazası](/baslangic/test-magazasi) | 60 (IP başına) |

Sayaç her dakikanın başında sıfırlanır. Her yanıtta durum başlıklarda:

| Başlık | Anlamı |
| --- | --- |
| `X-Istek-Siniri` | Bu dakikadaki sınır |
| `X-Istek-Kalan` | Bu dakikada kalan istek |
| `X-Istek-Sifirlanma` | Sayacın sıfırlanmasına kalan saniye |

Sınırı aşınca `429 istek_siniri` ve `Retry-After` (saniye) gelir:

```json
{ "hata": { "kod": "istek_siniri", "mesaj": "Dakikada 600 istek sınırı aşıldı. 23 saniye sonra tekrar deneyin." } }
```

<Callout title="Daha az istekle daha çok iş">
  Stok ve fiyatta tek tek güncelleme yerine toplu uçları kullan (`POST /v1/stok/toplu`, `POST /v1/fiyat/toplu`:
  istek başına 500 kalem). Değişiklikleri sorgulamak yerine [webhook](/webhook) ile dinle.
</Callout>


# Kimlik doğrulama (/baslangic/kimlik-dogrulama)

Her isteğe `Authorization` başlığı ekle:

```http
Authorization: Bearer mk_canli_8f3eK2…
```

Anahtar hangi mağazaya aitse istek o mağazada çalışır; adreste mağaza adı geçmez.

## Anahtar biçimi [#anahtar-biçimi]

| Önek | Nerede |
| --- | --- |
| `mk_canli_` + 32 karakter | Kendi mağazan. Gerçek siparişler, gerçek stok. |
| `mk_test_` + 32 karakter | [Test mağazası](/baslangic/test-magazasi). |

Anahtarı panelde **Ayarlar → API anahtarları**'ndan mağaza sahibi ya da yönetici oluşturur. Anahtar **yalnız bir
kez** gösterilir; biz yalnız özetini saklarız, kaybedersen yenisini oluştur. Bir mağazada en çok 50 etkin anahtar
olabilir. Kullanmadığın anahtarı aynı ekrandan iptal et.

<Callout type="error" title="Anahtarı tarayıcıya koyma">
  Canlı anahtar mağazanın verisine erişir. Yalnız sunucunda kullan; ön yüz koduna, mobil uygulamaya ya da Git
  deposuna koyma.
</Callout>

## İzinler [#i̇zinler]

Anahtarı oluştururken yalnız gereken izinleri seç. Yazma izni aynı kaynağın okumasını da kapsar
(`urun:yazma` → `urun:okuma`).

| İzin | Ne yapar |
| --- | --- |
| `urun:okuma` / `urun:yazma` | Ürünler, varyantlar, kategoriler, koleksiyonlar, markalar |
| `stok:okuma` / `stok:yazma` | Depo stokları, toplu stok |
| `fiyat:okuma` / `fiyat:yazma` | Toplu fiyat, fiyat listeleri |
| `siparis:okuma` / `siparis:yazma` | Siparişler, kargoya verme, iptal, not, iadeler |
| `musteri:okuma` / `musteri:yazma` | Müşteriler ve müşteri grupları |
| `kampanya:okuma` / `kampanya:yazma` | Kampanyalar ve indirim kodları |
| `icerik:okuma` / `icerik:yazma` | Sayfalar ve menüler |
| `webhook:yonet` | Webhook abonelikleri |

`GET /v1/magaza` her anahtarla açıktır ve anahtarın izinlerini döner.

## Hatalar [#hatalar]

| Durum | `kod` | Ne zaman |
| --- | --- | --- |
| 401 | `anahtar_yok` | Başlık yok ya da biçimi yanlış |
| 401 | `anahtar_gecersiz` | Anahtar yok, iptal edilmiş ya da başka ortama ait |
| 403 | `izin_yok` | Anahtarda bu ucun izni yok |
| 403 | `magaza_donduruldu` | Mağaza dondurulmuş; API kapalı |


# Para ve tarih (/baslangic/para-ve-tarih)

## Para [#para]

Bütün tutarlar **kuruş cinsinden tam sayıdır** ve **KDV dahildir**. Ondalık yok, yuvarlama hatası yok.

| API'de | Ekranda |
| --- | --- |
| `52000` | 520,00 ₺ |
| `184990` | 1.849,90 ₺ |
| `0` | Ücretsiz |

Ürünün `fiyat` alanı satış fiyatıdır; `indirimsiz_fiyat` doluysa vitrinde üstü çizili gösterilen fiyattır. Para birimi
mağazanın `para_birimi` alanındadır (`GET /v1/magaza`); MultiKur açıksa her varyantın `fiyatlar` dizisi başka para
birimlerindeki tutarları da verir.

```js
const tl = (kurus) => (kurus / 100).toLocaleString('tr-TR', { style: 'currency', currency: 'TRY' })
tl(184990) // "₺1.849,90"
```

## Tarih [#tarih]

Tarihler ISO 8601 biçiminde ve **UTC**'dir: `2026-10-19T05:16:27.230Z`. Türkiye saati için +3 saat ekle ya da
tarihi `Europe/Istanbul` saat dilimiyle göster. Sunucunun saatini `GET /v1/magaza` yanıtındaki `sunucu_saati`'nden
okuyabilirsin.

## Kimlikler [#kimlikler]

Her kaydın kimliği türünü söyleyen bir önekle başlar ve değişmez:

| Önek | Kayıt |
| --- | --- |
| `prod_` | Ürün |
| `variant_` | Varyant |
| `pcat_` | Kategori |
| `order_` | Sipariş |
| `cus_` | Müşteri |
| `evt_` | Webhook olayı |


# Sayfalama (/baslangic/sayfalama)

Liste uçları iki parametre alır:

| Parametre | Açıklama |
| --- | --- |
| `limit` | Bir sayfadaki kayıt sayısı, 1–100. Varsayılan 20. |
| `sonraki` | Önceki yanıttaki `sonraki` değeri. Boşsa ilk sayfa. |

Yanıt hep aynı biçimdedir:

```json
{
  "veri": [{ "id": "prod_01M599DX6Y1SBPFXMZ531PVQQX", "ad": "Bambu Servis Tepsisi (taslak)" }],
  "sonraki": "WyJwcm9kXzAxTTU5OURYNlkxU0JQRlhNWjUzMVBWUVFYIl0"
}
```

`sonraki` `null` ise son sayfadasın. İmleci olduğu gibi geri gönder; içini çözmeye ya da kendin üretmeye çalışma,
biçimi değişebilir.

## Bütün kayıtları gez [#bütün-kayıtları-gez]

```js
let sonraki = null
do {
  const adres = new URL('https://api.multikolay.com/v1/urunler')
  adres.searchParams.set('limit', '100')
  if (sonraki) adres.searchParams.set('sonraki', sonraki)
  const yanit = await fetch(adres, { headers: { Authorization: `Bearer ${process.env.MK_API_ANAHTARI}` } })
  const sayfa = await yanit.json()
  for (const urun of sayfa.veri) {
    // …
  }
  sonraki = sayfa.sonraki
} while (sonraki)
```

<Callout title="Eşitleme için">
  Bütün kataloğu her seferinde çekmek yerine değişikliklere [webhook](/webhook) ile abone ol; yalnız stok gerekiyorsa
  ürünlerin tamamı yerine `GET /v1/stok` kullan.
</Callout>


# Tekrar anahtarı (Idempotency-Key) (/baslangic/tekrar-anahtari)

`POST`, `PATCH`, `PUT` ve `DELETE` isteklerine `Idempotency-Key` başlığı ekleyebilirsin. Aynı anahtarla aynı istek
**24 saat** içinde tekrar gelirse iş yeniden yapılmaz; ilk yanıt aynen döner ve yanıtta
`Idempotent-Replayed: true` başlığı olur.

```bash
curl -X POST https://api.multikolay.com/v1/siparisler/order_01M599DZ…/kargo \
  -H "Authorization: Bearer $MK_API_ANAHTARI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kargo-6-2026-10-19" \
  -d '{ "firma": "Yurtiçi Kargo", "takip_no": "123456789" }'
```

- Anahtar 1–255 karakter. Her yeni iş için yeni anahtar üret (UUID ya da kendi kayıt numaran).
- Aynı anahtar **farklı bir gövdeyle** gelirse `422 tekrar_anahtari_kullanildi`.
- İlk istek hâlâ işlenirken aynı anahtar gelirse `409 tekrar_suruyor`; biraz bekleyip tekrar dene.
- Anahtar mağaza ve API anahtarı başınadır; başka entegrasyonların anahtarlarıyla çakışmaz.

<Callout title="Ne zaman şart">
  Para, stok ya da sipariş durumu değiştiren her istekte. Zaman aşımında "gitti mi gitmedi mi" sorusunun tek güvenli
  cevabı aynı anahtarla tekrar göndermek.
</Callout>


# Test mağazası (/baslangic/test-magazasi)

`gelistirici` herkesin kullanabildiği bir deneme mağazasıdır. Vitrini
[gelistirici.multikolay.com](https://gelistirici.multikolay.com) adresinde açık (arama motorlarına kapalı).

```bash
export MK_API_ANAHTARI=mk_test_7s2aioX6OhmIG4rvnCt1HpXowToq3sdx
```

Bu anahtar gizli değil; belgelerdeki bütün örnekler onunla çalışır.

## Neler açık [#neler-açık]

- **Bütün izinler**, okuma ve yazma: ürün, stok, fiyat, sipariş, müşteri, kampanya, içerik, webhook.
- **Silme kapalı:** `DELETE` istekleri `403 acik_anahtar_silemez` döner. Silmeyi kendi mağazanın anahtarıyla dene.
- **İstek sınırı IP başına dakikada 60.** Anahtarı herkes paylaştığı için sınır anahtara değil adresine göre sayılır.
- **En çok 5 webhook** aboneliği.
- **Yan etki yok:** e-posta gitmez, gerçek ödeme ve kargo yoktur.

<Callout type="warn" title="Her gece 03.00'te (TSİ) sıfırlanır">
  Senin ve başkalarının yaptığı bütün değişiklikler silinir, mağaza aşağıdaki örnek veriyle baştan kurulur. Kalıcı bir
  şey saklama; aynı anda başkaları da yazıyor olabilir.
</Callout>

## Örnek veri [#örnek-veri]

| Ne | İçerik |
| --- | --- |
| Ürünler | 11 ürün, SKU'lar `GLS-…`: `GLS-KUPA` (renk seçenekli), `GLS-YASTIK` (ölçü seçenekli), `GLS-TAHTA`, `GLS-VAZO`, `GLS-LAMBA`… ve 1 taslak (`GLS-TASLAK`) |
| Kategoriler | Mutfak, Dekorasyon, Aydınlatma, Tekstil |
| Müşteriler | 8 müşteri (`…@example.com`), 3'ü **VIP** grubunda |
| Kampanyalar | `HOSGELDIN10` (%10 indirim), kargo bedava |
| Siparişler | 6 sipariş: 2 yeni, 2 kargoda, 1 teslim edildi, 1 iptal |
| İçerik | 2 sayfa (`hakkimizda` ve bir tane daha), üst menü |

Kimlikler (`prod_…`, `order_…`) her gece yeniden üretilir; koduna kimlik gömme, SKU ya da `tanitici` ile ara.

## Kendi mağazana geçiş [#kendi-mağazana-geçiş]

Test mağazasında çalışan kod, kendi mağazanın panelinden aldığın `mk_canli_…` anahtarıyla aynen çalışır. Adres de
alanlar da aynıdır.


# Değişiklikler (/degisiklikler)

## 19 Ekim 2026 [#19-ekim-2026]

- **Yeni:** tema aracı [`@multikolay/tema`](/tema/gelistirme-akisi): `yeni`, yerelde canlı önizleme (`gelistir`),
  `dogrula`, `paketle`. Liman açık kaynak: `npx @multikolay/tema indir liman`.
- **Yeni:** [MCP sunucusu](/baslangic/ai-ajanlari) `https://docs.multikolay.com/mcp`: AI ajanları belgeleri
  okur, API şemasını alır, temayı denetleyip örnek veriyle çizer.
- **Yeni:** [tema geliştirme rehberi](/tema): klasör yapısı, şema ve ayar türleri, Liquid nesneleri ve süzgeçleri,
  adalar, özel alanlar, tema mirası.
- **Yeni:** [API referansı](/api) her uçta "Dene" ve test mağazasından gerçek örnek yanıtlarla.
- **Yeni:** yüklenen özel tema incelemeyi beklemeden mağazanın taslağında önizlenir ve denenir; yayına almak
  incelemeden sonra.
- **Yeni:** herkese açık [test mağazası](/baslangic/test-magazasi) `gelistirici` ve anahtarı. Her gece 03.00'te
  baştan kurulur.
- **Yeni:** `/v1/*` uçları `docs.multikolay.com`'dan tarayıcıyla çağrılabilir (CORS).

## 18 Ekim 2026 [#18-ekim-2026]

- **Yeni:** [webhook'lar](/webhook): 12 olay, `MK-Imza` ile imzalı, ~22 saat yeniden deneme.
- **Yeni:** yazma uçları (ürün, varyant, toplu stok ve fiyat, sipariş kargo/teslim/iptal, müşteri, kampanya, içerik)
  ve [`Idempotency-Key`](/baslangic/tekrar-anahtari).
- **Yeni:** açık API'nin ilk sürümü: [API anahtarları](/baslangic/kimlik-dogrulama) ve okuma uçları.


# Adalar ve uygulamalar (/tema/adalar-ve-uygulamalar)

## Adalar [#adalar]

Sepet, ödeme, arama, favoriler, taksit hesabı gibi parçaların mantığını platform yönetir. Temada yerini
`{% ada %}` ile işaretle; içine sayfa ilk açıldığında görünecek **yedek HTML**'i yaz. Tarayıcıda platformun parçası
yedeğin yerine geçer.

```liquid
<div class="urun-satin-al">
  {% ada 'sepete-ekle' %}
    <button class="dugme" disabled>Sepete ekle</button>
  {% endada %}
  {% ada 'taksit' %}{% endada %}
</div>
```

Adaya ayar verebilirsin; değer Liquid ifadesidir:

```liquid
{% ada 'arama', gorunum: 'ikon' %}<a href="{{ yollar.ara }}">Ara</a>{% endada %}
{% ada 'kart-favori', urun: p.id, baslik: p.title %}{% endada %}
```

Her ada belli bir sayfa bölgesinde çalışır. Bölgesi dışında kullanılan ada yalnız yedeğini gösterir.

| Bölge | Adalar |
| --- | --- |
| Üst kısım (header) | `arama`, `favori`, `hesap`, `sepet`, `dil`, `para`, `mobil-menu`, `menu` |
| Ürün sayfası | `sepete-ekle`, `taksit`, `taksit-tablosu`, `guven`, `urun-yorumlari`, `galeri`, `favori-dugmesi` |
| Ürün listesi | `filtreler`, `urun-izgarasi` |
| Alt kısım (footer) | `iyzico`, `cerez` |
| İçerik sayfası | `arama-kutusu`, `yorum-seridi` |
| Her yerde | `kart-favori` (ürün kartındaki kalp; `urun`, `baslik`) |

## Uygulamalar [#uygulamalar]

Mağazanın açtığı uygulamalar `uygulamalar.<ad>` olarak gelir: `acik` (açık mı) ve uygulamanın ayarları. Bugün
temaya açık uygulamalar: `yorumlar`, `teklif` (teklif iste), `bulten` (e-bülten).

Görünümü kendin yazabilirsin:

```liquid
{%- if uygulamalar.bulten.acik -%}
  <form class="bulten">…</form>
{%- endif -%}
```

Ya da platformun hazır parçasını çağırırsın; senin renk değişkenlerinle çizilir, uygulama kapalıysa hiçbir şey
çizilmez:

```liquid
{% uygulama 'bulten' %}
```

Hazır parçayı değiştirmek istersen temana `parcalar/uygulama-<ad>.liquid` koy (`parcalar/uygulama-bulten.liquid`);
`{% uygulama %}` seninkini kullanır.


# Ayar türleri (/tema/ayar-turleri)

Her ayar `{ "type", "id", "label" }` ister; `default`, `info` (alanın altındaki yardım metni) her türde kullanılabilir.

| `type` | Düzenleyicide | Liquid'de değer |
| --- | --- | --- |
| `text` | Tek satır yazı | metin |
| `textarea` | Çok satırlı yazı | metin; satır sonları için `\| newline_to_br` |
| `richtext` | Biçimli metin | temizlenmiş HTML, `\| raw` ile bas |
| `image_picker` | Medya kitaplığından görsel | `{ url, alt, … }`; `\| image_url: width: 1200` ile adres |
| `url` | Sayfa, ürün, kategori ya da dış adres | metin (`/store`, `/categories/x`, `https://…`) |
| `checkbox` | Aç/kapa | `true` / `false` |
| `number` | Sayı | sayı |
| `range` | Sayı (`min`, `max`, `step`, `unit`) | sayı |
| `select` | Açılır liste (`options: [{ value, label }]`) | seçilen `value` |
| `color` | Renk | `#rrggbb`; stile yazarken `\| renk` |
| `icon` | İkon seçici (`icon_set: "line"` ince çizgi seti) | ikon adı; `\| bolum_ikonu` ya da `\| cizgi_ikonu` |
| `text_list` | Metin listesi | metin dizisi |
| `datetime` | Tarih ve saat | `2026-11-28T23:59` (Türkiye saati) |
| `time` | Saat | `15:00` |
| `link_list` | Menü seçici | menünün kimliği |
| `collection` | Kategori seçici | kategori nesnesi (aşağıda) |
| `collection_list` | Birden çok kategori | kategori nesnelerinin listesi |
| `product` | Ürün seçici | ürün kartlarının listesi, seçilen sırayla |

## Ortak seçenekler [#ortak-seçenekler]

| Seçenek | Türler | Açıklama |
| --- | --- | --- |
| `localized: true` | metin türleri | Mağaza birden çok dilde açıksa her dil için ayrı değer girilir; Liquid ziyaretçinin dilindekini görür. |
| `maxLength` | metin türleri | Alanın karakter sınırı. |
| `min`, `max`, `step`, `unit` | `number`, `range` | Sayı aralığı ve birimi (`px`, `%`). |
| `when` | hepsi | Alanı yalnız başka bir ayar belli değerdeyken göster: `{ "field": { "key": "gorunum", "in": ["kart"] } }` |
| `gizli: true` | hepsi | Düzenleyicide gösterme (yalnız veri). |

## Katalog ayarları [#katalog-ayarları]

`collection`, `collection_list` ve `product` ayarlarının değeri çizimden önce gerçek veriye çözülür; şablon kimlik
değil nesne görür.

```json
{ "type": "collection", "id": "kategori", "label": "Kategori", "limit": 8, "bossa": "en_yeni" }
```

```liquid
{%- assign k = section.settings.kategori -%}
{%- if k -%}
  <h2><a href="{{ k.url }}">{{ k.title }}</a></h2>
  {%- for p in k.products -%}{% render 'urun-karti', p: p %}{%- endfor -%}
{%- endif -%}
```

- **Kategori nesnesi:** `id`, `title`, `url`, `description`, `image`, `products` (ürün kartları), `products_count`.
- `limit`: kategori başına ürün sayısı, 0–48. Varsayılan `collection`'da 12, `collection_list`'te 0 (yalnız kategori).
- `bossa: "en_yeni"`: seçim boşsa ya da kategoride ürün yoksa en yeni ürünler. `collection_list`'te
  `bossa: "ust"`: seçim boşsa üst düzey kategoriler.
- `birlesik: true` (`collection_list`): seçilen kategorilerin ürünleri tek listede:
  `{ collections, products, url }`.
- Ürün kartının alanları: [Liquid nesneleri → ürün kartı](/tema/liquid-nesneleri#ürün-kartı).


# Bölümler ve şema (/tema/bolumler)

Her bölüm `bolumler/<ad>.liquid` dosyasıdır. Dosya adı bölümün kalıcı adıdır (küçük harf, rakam, `-`); satıcının
sayfaları bu adla kaydedilir, sonraki sürümlerde değiştirme.

```liquid title="bolumler/baglantilar.liquid"
{%- assign s = section.settings -%}
<div class="baglantilar">
  {%- if s.heading != blank -%}<h3>{{ s.heading }}</h3>{%- endif -%}
  <ul>
    {%- for b in section.blocks -%}
      <li {{ b.nitelik }}><a href="{{ b.settings.href | default: '/' }}">{{ b.settings.label }}</a></li>
    {%- endfor -%}
  </ul>
</div>

{% schema %}
{
  "name": "Bağlantılar",
  "settings": [
    { "type": "text", "id": "heading", "label": "Başlık", "maxLength": 120, "localized": true }
  ],
  "blocks": [
    {
      "type": "link",
      "name": "Bağlantı",
      "settings": [
        { "type": "text", "id": "label", "label": "Yazı", "maxLength": 60, "localized": true },
        { "type": "url", "id": "href", "label": "Bağlantı" }
      ]
    }
  ],
  "max_blocks": 12,
  "presets": [
    { "name": "Bağlantılar", "settings": { "heading": "Kurumsal" }, "blocks": [{ "type": "link" }, { "type": "link" }] }
  ]
}
{% endschema %}
```

<Callout type="warn" title="Bloğun kapsayıcısına {{ b.nitelik }} yaz">
  Düzenleyici bloğu bu nitelikle bulur. Yazmazsan satıcı önizlemede bloğa tıklayıp düzenleyemez.
</Callout>

## Şema [#şema]

| Alan | Açıklama |
| --- | --- |
| `name` | Zorunlu. Düzenleyicide bölüm listesinde görünen ad. |
| `settings` | Bölümün ayarları. Bkz. [Ayar türleri](/tema/ayar-turleri). |
| `blocks` | Satıcının ekleyip sıraladığı tekrar eden parçalar: `{ type, name, settings, limit }`. `limit`: o türden en çok kaç tane. |
| `max_blocks` | Bölümdeki toplam blok sınırı. |
| `presets` | Satıcı bölümü eklediğinde gelen hazır kurgular: ayar değerleri ve bloklar. |

Şema geçerli JSON olmalı; ayar kimlikleri (`id`) küçük harf, rakam ve `_` ile yazılır, harfle başlar.

## section nesnesi [#section-nesnesi]

Bölümün içinde:

| Alan | Açıklama |
| --- | --- |
| `section.id` | Bu bölümün sayfadaki kimliği. CSS ve JS'te tekil seçici için. |
| `section.ad` | Bölüm dosyasının adı. |
| `section.settings.<id>` | Ayar değeri; satıcı değiştirmediyse şemadaki `default`. |
| `section.blocks` | Bloklar, satıcının sırasıyla. Gizlenen blok listede yoktur. |
| `b.type`, `b.id` | Bloğun türü ve kimliği. |
| `b.settings.<id>` | Bloğun ayarı. |
| `b.nitelik` | Bloğun kapsayıcısına yazılacak nitelik (yukarıdaki uyarı). |

Çizilen bölüm `<div class="mk-tema" data-mk-tema="<ad>" id="mk-tema-<section.id>">` içine konur.

## Parçalar [#parçalar]

Bölümlerin ortak kullandığı HTML'i `parcalar/<ad>.liquid`'e koy, `{% render %}` ile çağır:

```liquid
{%- for p in section.settings.urunler -%}
  {% render 'urun-karti', p: p %}
{%- endfor -%}
```

Parçanın şeması olmaz; yalnız ona verdiğin değişkenleri ve genel nesneleri (`shop`, `kart`…) görür.

## Sınırlar [#sınırlar]

- Bir bölümün çizimi 500 ms'yi aşarsa kesilir; canlıda o bölüm görünmez, sayfa çizilmeye devam eder.
- Şablon yalnız kendi nesnelerinin alanlarını okur; `constructor` gibi iç özelliklere erişilemez.
- Bilinmeyen süzgeç hata verir (yazım hatasını yüklemede yakalarsın).


# Geliştirme akışı (/tema/gelistirme-akisi)

Tema aracı `@multikolay/tema` npm'de; kurulum gerekmez, Node 20 ve üstüyle `npx` yeter.

<Steps>
<Step>

### Yeni tema aç [#yeni-tema-aç]

```bash
npx @multikolay/tema yeni benim-temam
cd benim-temam
```

Varsayılan olarak [Liman'dan miras alan](/tema/tema-mirasi) bir alt tema kurulur: Liman'ın bütün bölümleri hazır
gelir, sen yalnız farklı olanı yazarsın. Sıfırdan başlamak için `--bos` ekle.

```txt title="benim-temam/"
benim-temam/
├── tema.json                 # ad, başlık, sürüm, "temel": Liman
├── bolumler/merhaba.liquid   # örnek bölüm: ayarlar, bloklar, hazır kurgu
└── varliklar/tema.css        # satıcının --mk-* değişkenleriyle stil
```

</Step>
<Step>

### Yerelde önizle [#yerelde-önizle]

```bash
npx @multikolay/tema gelistir
```

`http://localhost:4300` açılır. Her bölüm vitrindeki şablon motoruyla, örnek mağaza verisiyle (ürünler, kategori,
menü) çizilir. Dosyayı kaydettiğinde paket yeniden denetlenir ve sayfa kendiliğinden yenilenir; hata varsa dosya
ve satırıyla gösterilir.

- **Bölümler:** temanın ve Liman'dan gelen her bölüm ayrı sayfada, şemadaki ilk hazır kurguyla (`presets`).
- **Sayfa türü:** üst çubuktan `urun`, `liste` ya da `icerik` seç; ürün sayfası bölümleri `product`, liste
  bölümleri `collection` görür.
- **Yaklaşık:** satıcının renkleri yerine varsayılan renkler, gerçek ürün yerine örnek veri kullanılır.
  Kesin görünüm için temayı taslağa yükle (aşağıda).

</Step>
<Step>

### Denetle ve paketle [#denetle-ve-paketle]

```bash
npx @multikolay/tema paketle
```

Yüklemedeki denetimin aynısını yapar ([ne denetlenir](#denetim)) ve `benim-temam-0.1.0.zip`'i yazar. Yalnız
pakete girebilen dosyaları alır; diğerlerini (notların, kaynak dosyaların) listeler. Yalnız denetlemek için
`npx @multikolay/tema dogrula` (hata varsa çıkış kodu 1; CI'da kullanabilirsin).

</Step>
<Step>

### Panelden yükle, taslakta dene [#panelden-yükle-taslakta-dene]

Çalıştığın mağazada **Mağaza Düzenleyici**'yi kullanabilen bir personel hesabın olmalı (mağaza sahibi seni
Ayarlar → Personel'den ekler). Panelde **Mağaza → Tema mağazası → Özel tema yükle → Tema dosyanızı ekleyin**.

Denetimden geçen tema **hemen** önizlenebilir ve mağazanın taslağına kurulabilir: **Önizle** mağazanın bugünkü
içeriğini senin temanla gösterir, **Taslağa kur** temayı düzenleyiciye getirir. Ziyaretçiler bu sırada bugünkü
siteyi görmeye devam eder. Değişiklik yaptıkça `surum`'u artırıp yeniden paketle ve yükle.

</Step>
<Step>

### İnceleme ve yayın [#i̇nceleme-ve-yayın]

Her yüklenen sürümü MultiKolay ekibi inceler (genelde 1 iş günü). Onaylanınca satıcı düzenleyicide
**Yayınla**'ya basar. Onaylanmamış sürüm taslakta denenir ama yayınlanamaz. Düzeltme istenirse notu Tema
mağazasında görürsün; düzeltip yeni sürüm numarasıyla yükle.

Yüklenen tema yalnız o mağazada kullanılır; tema mağazası kataloğunda görünmez.

</Step>
</Steps>

## Komutlar [#komutlar]

| Komut | Ne yapar |
| --- | --- |
| `yeni <klasör> [--bos]` | Yeni tema (varsayılan Liman alt teması) |
| `indir <tema> [klasör]` | Açık bir temanın kaynağını indirir: `indir liman` |
| `gelistir [klasör] [--port 4300]` | Yerel önizleme, değişince yenilenir |
| `dogrula [klasör]` | Yüklemedeki denetim |
| `paketle [klasör] [--cikti x.zip]` | Denetler ve zip'i yazar |

<Callout title="Araçsız da olur">
  Araç yalnız kolaylık: klasörü kendin zip'leyip yükleyebilirsin. Zip'in kökünde dosyalar ya da tek bir klasör
  olabilir; `.DS_Store`, `__MACOSX` gibi kalıntılar yok sayılır.
</Callout>

## Sürüm ve ad kuralları [#sürüm-ve-ad-kuralları]

- `ad`: küçük harf, rakam ve `-` (en çok 48 karakter). Bir mağazanın temasının adını başka mağaza ya da katalog
  teması alamaz.
- `surum`: `1.2.3` biçiminde. Aynı sürüm aynı içerikle tekrar yüklenirse bir şey olmaz; **farklı içerikle
  yüklenemez**, sürümü artır.

## Denetim [#denetim]

Yüklemede şunlar denetlenir. Hata varsa paket kaydedilmez.

| Kural | Sınır |
| --- | --- |
| İzinli yollar | `tema.json`, `bolumler/<ad>.liquid`, `parcalar/<ad>.liquid`, `varliklar/<ad>.css \| .js \| .svg \| .json` |
| Dosya adları | küçük harf, rakam, `-` (varlıklarda `.` ve `_` de) |
| Dosya sayısı | en çok 300 |
| Dosya boyutu | dosya başına 1 MB, paket toplamı 5 MB |
| `tema.json` | geçerli JSON; `ad` ve `surum` paketle aynı, `baslik` dolu |
| Bölümler | en az bir bölüm (alt temada gerekmez); her bölümde geçerli `{% schema %}` |
| Şablonlar | her bölüm ve parça hatasız ayrıştırılmalı; bilinmeyen [ada ya da uygulama](/tema/adalar-ve-uygulamalar) adı hata |

<Callout title="Görseller pakette değil">
  Paket metin dosyalarından oluşur. Fotoğraflar satıcının medya kitaplığından gelir (`image_picker` ayarı); küçük
  ikon ve desenler için `varliklar/*.svg` kullan.
</Callout>


# Tema nedir? (/tema)

Bir MultiKolay teması dört parçadan oluşur:

```txt title="Klasör yapısı"
benim-temam/
├── tema.json        # kimlik: ad, başlık, sürüm, açıklama
├── bolumler/        # satıcının dizdiği bölümler (giris.liquid, urun-seridi.liquid…)
├── parcalar/        # bölümlerin ortak kullandığı parçalar (urun-karti.liquid…)
└── varliklar/       # tema.css, tema.js ve diğer dosyalar
```

## Nasıl çalışır [#nasıl-çalışır]

- **Bölüm** bir `.liquid` dosyasıdır: HTML, [Liquid](/tema/liquid-nesneleri) ve dosyanın sonunda bir
  [`{% schema %}`](/tema/bolumler). Şema, satıcının düzenleyicide gördüğü ayarları ve blokları tanımlar.
- **Satıcı** mağaza düzenleyicisinde senin bölümlerini ana sayfaya, ürün sayfasına, üst ve alt kısma dizer, metin ve
  görselleri değiştirir. Senin kodun değişmez; satıcının seçimleri veri olarak saklanır.
- **Sunucuda yalnız Liquid çalışır.** Şablon yalnız ona verilen nesneleri okur (`section`, `shop`, `product`…); diske,
  ağa ya da başka mağazanın verisine ulaşamaz. Çıktı varsayılan olarak HTML'e kaçışlanır.
- **Tarayıcıda senin JS'in ve CSS'in** çalışır (`varliklar/tema.js`, `tema.css`). React dahil istediğin kitaplığı
  kullanabilirsin.
- **Sepete ekle, taksit, arama, yorumlar** gibi etkileşimli parçaları platform verir; sen yalnız nereye konacağını
  söylersin ([adalar](/tema/adalar-ve-uygulamalar)). Ödeme ve sepet mantığını yeniden yazmazsın.

## Nereden başlamalı [#nereden-başlamalı]

```bash
npx @multikolay/tema yeni benim-temam   # Liman'dan miras alan alt tema
cd benim-temam && npx @multikolay/tema gelistir
```

İki yol var:

1. **Liman'dan miras al (önerilen):** platformun temel teması Liman'ın bütün bölümleri senin temanda da olur; yalnız
   farklı olanı yazarsın. Bkz. [Tema mirası](/tema/tema-mirasi).
2. **Sıfırdan yaz:** en az bir bölüm ve bir `tema.json` yeter (`yeni --bos`).

<Cards>
  <Card title="Geliştirme akışı" href="/tema/gelistirme-akisi">Yerelde önizle, paketle, yükle, taslakta dene.</Card>
  <Card title="Bölümler ve şema" href="/tema/bolumler">Ayarlar, bloklar, hazır kurgular.</Card>
  <Card title="Liquid nesneleri" href="/tema/liquid-nesneleri">shop, product, collection, menu…</Card>
  <Card title="Adalar" href="/tema/adalar-ve-uygulamalar">Sepete ekle, taksit, arama: platformun parçaları.</Card>
</Cards>


# Liquid nesneleri (/tema/liquid-nesneleri)

Şablon yalnız bu sayfadaki nesneleri görür. Dil [LiquidJS](https://liquidjs.com) tabanlıdır: `if`, `for`, `assign`,
`capture`, `case`, `render` ve standart süzgeçler (`default`, `size`, `split`, `date`…) çalışır. MultiKolay'ın kendi
süzgeçleri: [Süzgeçler](/tema/suzgecler).

## Her sayfada [#her-sayfada]

| Nesne | Alanlar |
| --- | --- |
| `section` | Bölümün ayarları ve blokları. Bkz. [Bölümler](/tema/bolumler#section-nesnesi). |
| `shop` | `ad`, `url`, `telefon`, `eposta`, `adres` |
| `logo` | `url`, `light_url` (koyu zemin için açık logo), `height`, `text` (görsel yoksa yazı) |
| `menu` | Üst menü: `[{ title, url, links: [...] }]` |
| `menuler` | Panel → Menüler: `menuler.ana` (üst), `menuler.alt` (alt kısım), aynı biçim |
| `ana_menu` | Mega menü bilgisiyle üst menü: `{ title, url, mega, links, promo: { image, title, url } }` |
| `yollar` | `anasayfa`, `sepet`, `hesap`, `ara`, `favori` sayfalarının adresleri |
| `sepet` | `sepet.adet`: sepetteki ürün adedi |
| `kart` | Satıcının ürün kartı tercihleri (görünüm, görsel oranı, favori düğmesi…) |
| `uygulamalar` | Mağazada açık uygulamalar. Bkz. [Uygulamalar](/tema/adalar-ve-uygulamalar#uygulamalar). |
| `ozellikler` | Mağazada açık özellikler, ör. `ozellikler.iletisim_formu` |
| `kutuda` | Bölüm bir kutunun ya da sütunun içindeyse `true` (kenar boşluğu verme) |

```liquid
<a href="{{ yollar.anasayfa }}">
  {%- if logo.url != blank -%}<img src="{{ logo.url | image_url: width: 320 }}" alt="{{ shop.ad }}" style="height: {{ logo.height | default: 32 }}px">
  {%- else -%}{{ logo.text | default: shop.ad }}{%- endif -%}
</a>
<a href="{{ yollar.sepet }}">Sepet ({{ sepet.adet }})</a>
```

## Ürün sayfasında [#ürün-sayfasında]

| Nesne | Açıklama |
| --- | --- |
| `product` | Ürün (aşağıda) |
| `recommendations` | Önerilen ürünlerin kartları |
| `related` | Benzer ürünlerin kartları |

### product [#product]

Ürün kartının bütün alanları ve şunlar:

| Alan | Açıklama |
| --- | --- |
| `handle`, `subtitle` | Adresteki ad, alt başlık |
| `description` | Satıcının açıklaması, temizlenmiş HTML (`\| raw` ile bas) |
| `excerpt` | Açıklamanın kısa düz metni (220 karakter) |
| `images` | `[{ url, alt }]` |
| `options` | `[{ id, name, values: [...] }]`, ör. Renk: Krem, Lacivert |
| `variants` | `[{ id, title, sku, available, options: [...], price, compare_at_price, discount, lowest_price_30 }]` |
| `lowest_price_30` | İndirimdeyse indirimden önceki 30 günün en düşük fiyatı (İndirimli Satışlar Yönetmeliği), biçimli; bilinmiyorsa ya da indirim yoksa boş. İndirimli fiyatın yanında gösterin: `Son 30 günün en düşük fiyatı: {{ p.lowest_price_30 }}` |
| `available` | Herhangi bir varyant stokta mı |
| `categories` | `[{ title, url }]` |
| `tags` | Etiketler (metin dizisi) |
| `material`, `dimensions` | Malzeme, ölçü (`40 × 30 × 5`) |
| `specs` | `[{ label, value }]` teknik özellik satırları |
| `reviews` | Yorumlar açıksa: `average`, `count`, `items`, `can_review`; kapalıysa boş |
| `quote` | "Teklif iste" ürünüyse ayarları (`button_text`, `show_price`…), değilse boş |
| `ozel` | Ürünün [özel alanları](/tema/ozel-alanlar) |

## Ürün kartı [#ürün-kartı]

Liste sayfaları, öneriler ve `product`/`collection` ayarları ürünleri kart olarak verir:

| Alan | Açıklama |
| --- | --- |
| `id`, `title`, `url` | Kimlik, ad, ürün sayfasının adresi |
| `featured_image`, `second_image` | `{ url, alt }`; ikincisi üzerine gelince göstermek için |
| `price` | En uygun fiyat, biçimli: `1.849,90 ₺` |
| `compare_at_price` | İndirimdeyse eski fiyat, değilse boş |
| `discount`, `on_sale`, `percentage_diff` | `-%15`, indirim var mı, yüzde |
| `lowest_price_30` | Kartta her zaman boş; yalnız ürün sayfasında dolu (yukarıda) |
| `price_label` | Fiyat gizliyse yerine yazılacak metin ("Teklif ile") |
| `subtitle` | Kısa alt başlık ya da stok kodu |
| `rating` | Yorum özeti `{ average, count, average_text }`, yoksa boş |

Fiyatlar para birimi, kampanya ve "teklif iste" kuralları uygulanmış olarak gelir; şablonda hesaplama yapma.

```liquid
<a class="kart" href="{{ p.url }}">
  {%- if p.featured_image -%}<img src="{{ p.featured_image | image_url: width: 600 }}" alt="{{ p.featured_image.alt }}" loading="lazy">{%- endif -%}
  <h3>{{ p.title }}</h3>
  <span class="fiyat">{{ p.price_label | default: p.price }}</span>
  {%- if p.compare_at_price != blank -%}<s>{{ p.compare_at_price }}</s>{%- endif -%}
</a>
```

## Ürün listesi sayfasında [#ürün-listesi-sayfasında]

| Nesne | Açıklama |
| --- | --- |
| `collection` | Kategori ya da bütün ürünler sayfası (aşağıda) |
| `categories` | Kategori ağacı (süzgeç menüsü için) |

`collection`'ın alanları: `title`, `description` (HTML), `image`, `url`, `products` (kartlar), `products_count`,
`page`, `total_pages`, `next_url`, `previous_url`, `sort_options` (`[{ value, label, selected, url }]`), `filters`
(`[{ key, label, values: [{ value, count, active, url }] }]`), `active_filters_count`, `clear_url`, `price_filter`,
`parents`, `children`, `ozel`.

```liquid
{%- for p in collection.products -%}{% render 'urun-karti', p: p %}{%- endfor -%}
{%- if collection.next_url != blank -%}<a href="{{ collection.next_url }}">Sonraki sayfa</a>{%- endif -%}
```

## İçerik sayfasında [#i̇çerik-sayfasında]

`page`: `title`, `content` (temizlenmiş HTML, `\| raw` ile bas), `url`, `ozel`.

```liquid
<article>
  <h1>{{ page.title }}</h1>
  {{ page.content | raw }}
</article>
```


# Özel alanlar (/tema/ozel-alanlar)

Ürün sayfanda "bakım talimatı", "garanti süresi" ya da "kullanım kılavuzu" göstermek istiyorsan bunları
`tema.json`'da tanımla. Tema kurulunca alanlar mağazada açılır; satıcı ürün kartında doldurur.

```json title="tema.json"
{
  "ad": "konak",
  "baslik": "Konak",
  "surum": "1.0.0",
  "ozel_alanlar": {
    "urun": [
      { "kod": "garanti", "ad": "Garanti süresi", "tur": "tek_satir_metin" },
      { "kod": "kilavuz", "ad": "Kullanım kılavuzu", "tur": "dosya" },
      { "kod": "renk_kodu", "ad": "Renk kodu", "tur": "renk" }
    ],
    "kategori": [
      { "kod": "afis", "ad": "Kategori afişi metni", "tur": "zengin_metin" }
    ]
  }
}
```

- Kayıt türleri: `urun`, `kategori`, `sayfa`, `musteri`.
- `kod`: küçük harf, rakam, `_`; en çok 40 karakter, kayıt türü içinde tekil.
- Tema kurulunca açılan alanlar kilitlidir (satıcı silemez); tema değişince kilit kalkar, değerler kalır.

## Liquid'de [#liquidde]

```liquid
{%- if product.ozel.garanti != blank -%}<p>Garanti: {{ product.ozel.garanti }}</p>{%- endif -%}
{%- if product.ozel.kilavuz -%}<a href="{{ product.ozel.kilavuz | file_url }}">Kılavuzu indir</a>{%- endif -%}
{{ collection.ozel.afis | raw }}
{{ page.ozel.alt_baslik }}
```

## Alan türleri [#alan-türleri]

| Tür | Değer |
| --- | --- |
| `tek_satir_metin`, `cok_satirli_metin` | metin |
| `zengin_metin` | temizlenmiş HTML |
| `tam_sayi`, `ondalik_sayi`, `puan` | sayı |
| `boyut`, `agirlik`, `hacim` | ölçü ve birim |
| `tarih`, `tarih_saat` | tarih |
| `tutar` | para |
| `dosya` | `{ url, ad, tur }`, `\| file_url` ile adres |
| `baglanti` | adres |
| `renk` | renk değeri |
| `urun`, `varyant`, `kategori`, `sayfa`, `musteri` | bağlı kayıt |
| `evet_hayir` | `true` / `false` |
| `json` | serbest veri |


# Stil ve script (/tema/stil-ve-script)

## Kendiliğinden yüklenen dosyalar [#kendiliğinden-yüklenen-dosyalar]

- `varliklar/tema.css` temanın bir bölümü olan her sayfada `<link rel="stylesheet">` olarak gelir.
- `varliklar/tema.js` aynı sayfalarda `<script type="module" async>` olarak gelir. Yalnız tarayıcıda çalışır.

Başka bir dosyayı (`varliklar/desen.svg`, `varliklar/veri.json`) adresiyle çağır:

```liquid
<img src="{{ 'desen.svg' | asset_url }}" alt="">
```

`varliklar/`'a yalnız `.css`, `.js`, `.svg`, `.json` konabilir. Fotoğraflar satıcının medya kitaplığından gelir.

## Mağazanın tasarım değişkenleri [#mağazanın-tasarım-değişkenleri]

Satıcı panelde renklerini, yazı tiplerini ve köşe yuvarlaklığını seçer; bunlar sayfada CSS değişkeni olarak durur.
Temanı bu değişkenlerle yazarsan satıcının seçimleri senin temana da geçer.

| Değişken | Ne |
| --- | --- |
| `--mk-primary`, `--mk-on-primary` | Ana renk ve üstündeki yazı rengi (düğmeler) |
| `--mk-secondary`, `--mk-on-secondary` | İkinci renk |
| `--mk-accent`, `--mk-on-accent` | Vurgu rengi |
| `--mk-text`, `--mk-text-subtle` | Yazı ve soluk yazı |
| `--mk-background`, `--mk-surface`, `--mk-border` | Sayfa zemini, kart zemini, çizgiler |
| `--mk-danger`, `--mk-campaign`, `--mk-topbar` | Hata, kampanya, üst şerit renkleri |
| `--mk-font-heading`, `--mk-font-body` | Başlık ve metin yazı tipi |
| `--mk-radius-button`, `--mk-radius-input`, `--mk-radius-card`, `--mk-radius-image` | Köşe yuvarlaklıkları |
| `--mk-container` | İçerik genişliği |
| `--mk-space-xs` … `--mk-space-3xl` | Boşluk ölçeği |
| `--mk-text-xs` … `--mk-text-5xl` | Yazı boyutu ölçeği |

```css
.kart { background: var(--mk-surface); border: 1px solid var(--mk-border); border-radius: var(--mk-radius-card); }
.kart h3 { font-family: var(--mk-font-heading); color: var(--mk-text); }
```

## Bölüm ayarından stil [#bölüm-ayarından-stil]

Satıcının seçtiği rengi stile yazarken `| renk` süzgecinden geçir: yalnız geçerli renk değeri çıkar, başka CSS sızmaz.

```liquid
<section style="background: {{ section.settings.zemin | renk | default: 'var(--mk-surface)' }}">
```

## Tailwind ya da başka araçlar [#tailwind-ya-da-başka-araçlar]

Derleme adımı senin bilgisayarında olur: Tailwind, Sass ya da istediğin aracı kullan, çıktısını `tema.css` ve
`tema.js` olarak pakete koy. Sunucu yalnız paketteki dosyaları sunar.


# Süzgeçler (/tema/suzgecler)

`{{ değer }}` her zaman HTML'e kaçışlanır: satıcının yazdığı `<script>` sayfada yazı olarak görünür. HTML basmak
istediğin yerde bilerek `| raw` ya da aşağıdaki güvenli süzgeçleri kullan.

| Süzgeç | Örnek | Ne yapar |
| --- | --- | --- |
| `raw` | `{{ product.description \| raw }}` | Kaçışlamadan basar. Yalnız temizlenmiş HTML'de kullan (`richtext`, `description`, `page.content`). |
| `newline_to_br` | `{{ s.metin \| newline_to_br }}` | Satır sonlarını `<br>` yapar; metni önce kaçışlar. |
| `zengin_html` | `{{ s.metin \| zengin_html }}` | Metni paragraflı, temizlenmiş HTML'e çevirir. |
| `temiz_html` | `{{ s.baslik \| temiz_html }}` | Satır içi HTML'i (`<br>`, `<em>`) temizleyip basar; paragraf sarmaz. |
| `image_url` | `{{ s.gorsel \| image_url: width: 1200 }}` | Görselin adresi; mağazanın kendi görsellerinde istenen genişlikte. Geçersiz adres boş döner. |
| `file_url` | `{{ product.ozel.kilavuz \| file_url }}` | Özel alan dosyasının güvenli adresi. |
| `asset_url` | `{{ 'desen.svg' \| asset_url }}` | Temanın `varliklar/` dosyasının adresi. |
| `money` | `{{ 184990 \| money }}` | Kuruştan TL'ye: `₺1.849,90`. Ürün fiyatları zaten biçimli gelir. |
| `renk` | `{{ s.zemin \| renk \| default: 'var(--mk-surface)' }}` | Yalnız geçerli renk değeri (`#hex`, `rgb()`, `var()`), değilse boş. Stil niteliğinde kullan. |
| `buyuk_harf` | `{{ 'istanbul' \| buyuk_harf }}` | Türkçe büyük harf: `İSTANBUL`. (`upcase` "ISTANBUL" yazar.) |
| `bolum_ikonu` | `{{ kutu.icon \| bolum_ikonu: kutu.title, 'ikon' }}` | İkon adından `<svg>`. İkinci değer başlık (ikon boşsa ondan tahmin), üçüncüsü CSS sınıfı. |
| `cizgi_ikonu` | `{{ s.icon \| cizgi_ikonu: 20, 1.5, 'ikon' }}` | İnce çizgi ikon seti: boyut, çizgi kalınlığı, sınıf. Bilinmeyen ad boş. |
| `meta_doldur` | `{{ s.metin \| meta_doldur: product.meta }}` | `{meta:garanti\|2 yıl}` yer tutucularını ürünün bilgisiyle doldurur. |

Bilinmeyen süzgeç adı hatadır ve yükleme denetiminde yakalanır.


# tema.json (/tema/tema-json)

```json title="tema.json"
{
  "ad": "kadran",
  "baslik": "Kadran",
  "surum": "0.1.1",
  "yazar": "MultiKolay",
  "aciklama": "Saat ve aksesuar için editoryal, lüks bir vitrin.",
  "etiket": "Saat · Lüks",
  "ozellikler": [
    "Editoryal giriş, koyu vitrin ve yarım görselli bölümler",
    "Ürün sayfasında güven satırları ve teknik özellik tablosu"
  ],
  "notlar": ["Ürün sayfasına teknik özellik tablosu eklendi"],
  "temel": { "ad": "liman", "surum": "0.1.2" }
}
```

| Alan | Zorunlu | Açıklama |
| --- | --- | --- |
| `ad` | evet | Temanın kalıcı adı: küçük harf, rakam, `-`; en çok 48 karakter. Değiştirirsen başka bir tema olur. |
| `baslik` | evet | Tema mağazasında ve panelde görünen ad. |
| `surum` | evet | `1.2.3`. Her yüklemede artır. |
| `yazar` | hayır | Tema mağazasında görünür. |
| `aciklama` | hayır | Tema kartında ve ayrıntısında bir iki cümle. |
| `etiket` | hayır | Sektör ya da karakter, ör. `Mobilya · Ferah`. |
| `ozellikler` | hayır | Tema ayrıntısında madde madde (en çok 12). |
| `notlar` | hayır | Bu sürümde ne değişti; satıcı "Güncelleme var" dediğinde görür (en çok 20). |
| `temel` | hayır | Miras alınan tema: `{ "ad", "surum" }`. Bkz. [Tema mirası](/tema/tema-mirasi). |
| `ozel_alanlar` | hayır | Temanın ihtiyaç duyduğu ürün, kategori, sayfa alanları. Bkz. [Özel alanlar](/tema/ozel-alanlar). |
| `sayfa_kabugu` | hayır | `"platform"`: içerik sayfalarında (Hakkımızda gibi) platformun kenar boşluğu ve başlığı kullanılır. Yoksa sayfanın düzeni tamamen bölümlerinin. |
| `donusum` | hayır | Mağazanın eski (klasik) görünümündeki blokların senin hangi bölümüne karşılık geldiği: `{ "hero": "giris" }`. Satıcı temayı "İçeriğimi taşı" ile kurduğunda içeriği bu eşlemeyle taşınır. Değerler pakette olan bölüm adları olmalı. |


# Tema mirası (/tema/tema-mirasi)

Bir tema, katalogdaki onaylı bir temayı **temel** alabilir. Temelin bütün bölümleri, parçaları ve dosyaları senin
temanda da olur; sen yalnız değiştirmek ya da eklemek istediğini yazarsın.

```json title="tema.json"
{
  "ad": "kadran",
  "baslik": "Kadran",
  "surum": "0.1.1",
  "temel": { "ad": "liman", "surum": "0.1.2" }
}
```

## Kurallar [#kurallar]

- **Aynı yol, senin dosyan:** `bolumler/giris.liquid` yazarsan Liman'ın girişi yerine seninki çizilir.
- **`tema.css` ve `tema.js` eklenir:** seninki Liman'ınkinin ardına gelir, yani yalnız farkı yazarsın.
- **Künye senin:** `ad`, `baslik`, `aciklama`… alt temanın. Temelin `ozel_alanlar` ve `donusum` eşlemesi gelir;
  aynı kodu ya da anahtarı yazarsan seninki geçerli olur.
- **Sürüm sabit:** `temel.surum` tam sürümdür. Liman'ın yeni sürümünü almak için `temel.surum`'u değiştirip kendi
  temanın yeni sürümünü yüklersin; satıcı güncellemeyi panelde onaylar.
- **Tek kat:** temel teması kendisi alt tema olamaz.
- Alt temada bölüm olmak zorunda değil; yalnız CSS'le başlayabilirsin.

```css title="varliklar/tema.css"
/* Liman'ın üstüne: daha koyu, köşesiz bir görünüm */
.mk-tema { --mk-radius-button: 0; --mk-radius-card: 0; }
.mk-tema h1, .mk-tema h2 { letter-spacing: -0.02em; text-transform: uppercase; }
```

## Liman'ın kaynağı [#limanın-kaynağı]

Liman açık kaynak. Bir dosyasını ezmeden önce aslını görmek için indir:

```bash
npx @multikolay/tema indir liman
```

En yeni onaylı sürümün bütün dosyaları (`bolumler/`, `parcalar/`, `varliklar/kaynak.css` Tailwind kaynağı ve
derlenmiş `tema.css`) `liman/` klasörüne iner. Bir bölümü değiştirmek için dosyayı kendi temanın aynı yoluna kopyala
ve orada düzenle; Liman'ın kendisini değiştirip yüklemeye çalışma, katalogdaki adı başkası alamaz.

## Liman'ın bölümleri [#limanın-bölümleri]

Ezebileceğin bölüm adları (dosya `bolumler/<ad>.liquid`):

`giris`, `giris-editoryal`, `giris-kurumsal`, `banner-izgarasi`, `urun-seridi`, `urun-seridi-editoryal`,
`urun-vitrini`, `sekmeli-urunler`, `kategori-seridi`, `ikon-kutulari`, `ikon-kutulari-cerceveli`, `surec-adimlari`,
`hizmet-kartlari`, `gorsel-metin`, `yarim-gorsel`, `koyu-vitrin`, `hakkimizda-kurumsal`, `harita`,
`harita-iletisim`, `metin`, `baslik`, `gorsel-blok`, `dugme`, `baglantilar`, `ayrac`, `kampanya-seridi`,
`ust-serit`, `logo`, `ana-menu`, `konum-yolu`, `liste-baslik`, `liste-filtreler`, `liste-urunler`, `urun-galeri`,
`urun-bilgi`, `urun-aciklama`, `sepete-ekle`, `taksit-notu`, `taksit-tablosu`, `guven-rozetleri`, `urun-yorumlari`,
`urun-ayrac`, `benzer-urunler`.

Parçalar: `urun-karti`, `kategori-karosu`, `gorsel`, `logo-gorsel`, `mega-menu`, `filtre-cubugu`, `filtre-satiri`,
`guven-satiri`, `yildizlar`, `slayt-kabi-son`.


# İmzayı doğrula (/webhook/imza)

`MK-Imza` başlığı `t=<unix saniye>,v1=<imza>` biçimindedir. İmza, aboneliğin gizli anahtarıyla (`whsec_…`)
`"<t>.<ham gövde>"` metninin HMAC-SHA256'sıdır, küçük harf hex.

1. Başlıktan `t` ve `v1`'i ayır.
2. `t` 5 dakikadan eskiyse reddet (tekrar saldırısı).
3. `"<t>.<ham gövde>"` için HMAC-SHA256 hesapla; `v1` ile **sabit süreli** karşılaştır.

Gövdeyi JSON olarak çözüp yeniden yazmadan, **gelen ham haliyle** imzala; boşluk farkı imzayı bozar.

<Tabs items={['Node.js', 'PHP', 'Python']}>
<Tab value="Node.js">

```js
import { createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'

const app = express()
app.post('/multikolay/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!imzaDogru(req.body.toString('utf8'), req.get('MK-Imza') ?? '', process.env.MK_WEBHOOK_GIZLI)) return res.sendStatus(401)
  const olay = JSON.parse(req.body)
  kuyruk.ekle(olay) // ağır işi sonra yap
  res.sendStatus(200)
})

function imzaDogru(ham, baslik, gizli) {
  const p = Object.fromEntries(baslik.split(',').map((x) => x.split('=')))
  if (!p.t || !p.v1 || Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false
  const beklenen = createHmac('sha256', gizli).update(`${p.t}.${ham}`).digest('hex')
  return p.v1.length === beklenen.length && timingSafeEqual(Buffer.from(p.v1), Buffer.from(beklenen))
}
```

</Tab>
<Tab value="PHP">

```php
$ham = file_get_contents('php://input');
$baslik = $_SERVER['HTTP_MK_IMZA'] ?? '';
parse_str(str_replace(',', '&', $baslik), $p);

$taze = isset($p['t']) && abs(time() - (int) $p['t']) <= 300;
$beklenen = hash_hmac('sha256', ($p['t'] ?? '') . '.' . $ham, getenv('MK_WEBHOOK_GIZLI'));
if (!$taze || !hash_equals($beklenen, $p['v1'] ?? '')) {
  http_response_code(401);
  exit;
}
$olay = json_decode($ham, true);
http_response_code(200);
```

</Tab>
<Tab value="Python">

```python
import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/multikolay/webhook")
def webhook():
    ham = request.get_data()
    p = dict(x.split("=", 1) for x in request.headers.get("MK-Imza", "").split(",") if "=" in x)
    if abs(time.time() - int(p.get("t", 0))) > 300:
        abort(401)
    beklenen = hmac.new(os.environ["MK_WEBHOOK_GIZLI"].encode(), f"{p['t']}.".encode() + ham, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(beklenen, p.get("v1", "")):
        abort(401)
    olay = request.get_json()
    return "", 200
```

</Tab>
</Tabs>

## Sırrı yenile [#sırrı-yenile]

Sır sızdıysa [İmza sırrını yenile](/api/webhooklar/imza-sirrini-yenile) yeni bir `whsec_…` döner; eskisi hemen
geçersiz olur. Sunucundaki değeri aynı anda güncelle.


# Webhook'lar (/webhook)

Bir adres ver ve olayları seç; olay olduğunda MultiKolay o adrese `POST` atar. Siparişleri dakikada bir
sorgulamak yerine webhook kullan: hem daha hızlı hem [istek sınırına](/baslangic/istek-siniri) takılmazsın.

<Steps>
<Step>

### Aboneliği aç [#aboneliği-aç]

Panelde **Ayarlar → API anahtarları** sayfasının Webhook'lar bölümünden ya da API'yle
(`webhook:yonet` izni gerekir):

```bash
curl -X POST https://api.multikolay.com/v1/webhooklar \
  -H "Authorization: Bearer $MK_API_ANAHTARI" \
  -H "Content-Type: application/json" \
  -d '{ "adres": "https://ornek.com/multikolay/webhook", "olaylar": ["siparis.olusturuldu", "stok.degisti"] }'
```

Yanıttaki `gizli` (`whsec_…`) imza sırrıdır; sakla. Adres `https://` ile başlamalı ve bir alan adı olmalı (IP ya da
`localhost` olamaz).

</Step>
<Step>

### İsteği karşıla [#i̇steği-karşıla]

```http
POST /multikolay/webhook HTTP/1.1
Content-Type: application/json
MK-Olay: siparis.olusturuldu
MK-Teslimat: whd_01M5…
MK-Imza: t=1792344310,v1=5f2c…

{
  "id": "evt_mgx3k2a1f09c4e7b2d81a6",
  "olay": "siparis.olusturuldu",
  "magaza": "gelistirici",
  "zaman": "2026-10-19T05:16:29.894Z",
  "veri": { "id": "order_01M599DZ…", "no": "6", "durum": "hazirlaniyor", "toplam": 220000, "…": "…" }
}
```

Önce [imzayı doğrula](/webhook/imza), sonra 10 saniye içinde `2xx` dön. Ağır işi kuyruğa al.

</Step>
<Step>

### Dene [#dene]

[Test olayı gönder](/api/webhooklar/test-olayi-gonder) adresine `test.ping` olayını yollar; panelde de aynı düğme var.
Test mağazasında en çok 5 abonelik açılabilir.

</Step>
</Steps>

## Gövde [#gövde]

| Alan | Açıklama |
| --- | --- |
| `id` | Olayın kimliği (`evt_…`). Aynı olay tekrar gelirse aynıdır; tekrarları bununla ayıkla. |
| `olay` | Olay adı. Bkz. [Olaylar](/webhook/olaylar). |
| `magaza` | Mağazanın kimliği. Birden çok mağazayı tek adrese bağladıysan ayırt etmek için. |
| `zaman` | Olayın olduğu an (ISO 8601, UTC). |
| `veri` | Olay anındaki kayıt; API'nin döndüğü biçimle aynı. |
| `ek` | Bazı olaylarda olaya özgü bilgi, ör. `siparis.kargoya_verildi`'de `gonderi_id`. |


# Olaylar (/webhook/olaylar)

| Olay | Ne zaman | `veri` |
| --- | --- | --- |
| `siparis.olusturuldu` | Yeni sipariş (kartla ödenmişse ödemesi de alınmış) | [Sipariş](/api/siparisler/siparisi-getir) |
| `siparis.odeme_alindi` | Havale/EFT ödemesi onaylandı | Sipariş |
| `siparis.kargoya_verildi` | Gönderi kargoya verildi (takip numarası belli) | Sipariş; `ek.gonderi_id` |
| `siparis.teslim_edildi` | Gönderi teslim edildi | Sipariş |
| `siparis.iptal_edildi` | Sipariş iptal edildi | Sipariş |
| `siparis.para_iade_edildi` | Müşteriye para iadesi yapıldı | Sipariş |
| `iade.olusturuldu` | Ürün iadesi alındı | [İade](/api/siparisler/iadeyi-getir) |
| `urun.olusturuldu` | Ürün eklendi | [Ürün](/api/urunler/urunu-getir) |
| `urun.guncellendi` | Ürün değişti (ad, açıklama, fiyat, görsel, varyant…) | Ürün |
| `urun.silindi` | Ürün silindi | `{ id }` |
| `stok.degisti` | Bir varyantın depodaki adedi değişti (kargoya verme, iade, panel, API) | aşağıda |
| `musteri.olusturuldu` | Yeni müşteri (üyelik, sipariş, panel ya da API) | [Müşteri](/api/musteriler/musteriyi-getir) |

Olay listesini makinece almak için: [Olay türlerini listele](/api/webhooklar/olay-turlerini-listele).

## stok.degisti [#stokdegisti]

Ürünün tamamı yerine yalnız değişen varyant gelir:

```json
{
  "varyant_id": "variant_01M599DWEQRQHB8J55SXZPPWQQ",
  "urun_id": "prod_01M599DWE17C3FG9HPV9150TBF",
  "sku": "GLS-VAZO",
  "depo_id": "sloc_01M5999VZ225YBQQZ3CPWJ3CWE",
  "miktar": 7,
  "degisim": -1,
  "neden": "sevk"
}
```

`miktar` depodaki yeni adet, `degisim` farkı. `neden`:

| `neden` | Ne zaman |
| --- | --- |
| `sevk` | Sipariş kargoya verildi (adet düşer) ya da gönderi iptal edildi (geri eklenir) |
| `iade` | İade edilen ürün depoya döndü |
| `panel` | Satıcı panelden değiştirdi |
| `api` | Bir entegrasyon API'yle yazdı |

<Callout title="Sipariş anında depodaki adet değişmez">
  Sipariş gelince ürün **ayrılır**: satılabilir adet düşer ama depodaki adet kargoya verilene kadar aynı kalır, bu
  yüzden `stok.degisti` gelmez. Satılabilir adedi izlemek için `siparis.olusturuldu`'yu dinle ya da
  [Stok seviyelerini listele](/api/stok/stok-seviyelerini-listele)'deki `satilabilir` alanına bak.
</Callout>

## Sıra ve tekrar [#sıra-ve-tekrar]

- Olaylar oluş sırasıyla gönderilir ama **sırayla gelmeleri garanti değildir** (yeniden denemeler araya girer).
  Sıra önemliyse `zaman`'a bak ya da kaydı API'den taze çek.
- Aynı olay birden çok kez gelebilir. `id` ile ayıkla.


# Teslimat ve yeniden deneme (/webhook/teslimat)

## Başarılı teslimat [#başarılı-teslimat]

Adresin **10 saniye** içinde `2xx` dönerse teslimat başarılıdır. Yönlendirme (`3xx`) izlenmez, başarısız sayılır.
İşi kuyruğa alıp hemen yanıt ver.

## Yeniden deneme [#yeniden-deneme]

Başarısız teslimat 8 kez daha denenir:

| Deneme | İlkinden sonra |
| --- | --- |
| 2 | 1 dakika |
| 3 | 6 dakika |
| 4 | 21 dakika |
| 5 | 51 dakika |
| 6 | 1 saat 51 dakika |
| 7 | 4 saat 51 dakika |
| 8 | 10 saat 51 dakika |
| 9 | 22 saat 51 dakika |

Bütün denemeleri tükenen teslimat **vazgeçildi** olur. Bir abonelikte üst üste **5** teslimattan vazgeçilirse
abonelik kapanır ve mağaza sahibi panelin zilinde uyarı görür. Sorunu düzeltip aboneliği panelden ya da
[Webhook'u güncelle](/api/webhooklar/webhooku-guncelle) ile (`"aktif": true`) yeniden aç; hata sayacı sıfırlanır.

## Son teslimatlar [#son-teslimatlar]

[Teslimatları listele](/api/webhooklar/teslimatlari-listele) her teslimatın durumunu (`bekliyor`, `basarili`,
`hata`, `vazgecildi`), deneme sayısını, son HTTP kodunu ve süresini döner. Kaçırdığın bir olayı
[Teslimatı yeniden gönder](/api/webhooklar/teslimati-yeniden-gonder) ile hemen yeniden yollatabilirsin (deneme
sayacı sıfırlanır).

## Yerelde deneme [#yerelde-deneme]

Adres internetten ulaşılabilir bir `https://` alan adı olmalı. Kendi bilgisayarında denemek için bir tünel
(ör. ngrok, Cloudflare Tunnel) aç ve onun adresini abonelik adresi yap.