Tecof’ta iki tür şey geliştirirsiniz: mağazanın ziyaretçiye görünen teması (Next.js + Tecof Studio) ve mağaza panelinde çalışan uygulamalar (partner uygulamaları). İkisi de @tecof/cli ile terminalden geliştirilir, numaralı sürümlerle yayınlanır ve anında geri alınabilir. Bu doküman sitesi bu işlerin tamamının tek kaynağıdır; içerik kaynak koda göre yazılır ve her sayfa AI araçları için Markdown olarak da sunulur.

Nereden başlamalı#

Yapmak istediğiniz	Başlangıç	Sonra
Mağazanın temasını kodla değiştirmek	Tema hızlı başlangıç	Tema mimarisi, Tecof Studio
Temaya Studio’da düzenlenebilir bileşen eklemek	Bileşen yapılandırması	Alanlar, Slotlar, Stil editörü
Mağazalara kurulan bir uygulama yazmak	Uygulama hızlı başlangıç	Tasarım kimliği, Webhook’lar, App Bridge
Vitrin verisini kendi önyüzünüzde kullanmak	Public API	Headless CMS
Bir AI ajanını Tecof’a bağlamak	Tecof MCP	Dokümanı AI ile kullanın, Alışveriş ajanları
CI’dan yayın yapmak	Güvenlik ve CI	CLI başvurusu
Paket sürümlerini görmek	Paketler	—

Platform yüzeyleri#

Tema ve vitrin#

Temalar Next.js App Router projeleridir. Sayfa verisini, CMS içeriğini, mağaza ayarlarını ve e-ticaret verisini backend’in /api/store/* katmanından vitrin anahtarıyla (x-secret-key) okur; sayfaları @tecof/theme-editor’ün TecofRender’ı ile çizer. Panel aynı sayfaları temanın editör rotasında Tecof Studio ile düzenletir. Özel temanın kodu bir Space’te yaşar: tecof theme push yalnız değişen dosyaları yükleyip staged bir sürüm açar, tecof theme promote onu yeniden derlemeden canlıya alır (Spaces).

Partner uygulamaları#

Uygulamalar mağazaya kurulur; istemci kimliği + sırrıyla alınan kurulum token’ı (tcfi_…) ile /api/v1’i kullanır, imzalı webhook’lar ve panel aksiyonları alır, panelde iframe içinde @tecof/app-ui ile Tecof görünümünde çalışır, ayarlarını Vault ve metafield’larda tutar ve ücretli planlar sunabilir (Uygulama geliştirme).

Vitrin ve CMS API’leri#

Canlı mağazanın güvenli API yüzeyi /api/store/* altındadır: ürün listesi, sepet doğrulama, checkout, müşteri hesabı, CMS okuma, bülten ve tema render verisi (Public API). Panel (yönetim) uçları /api/merchant/* altında JWT ile korunur ve panel içindir; üçüncü taraflar /api/v1 kullanır.

AI ve MCP#

Tecof’un uzak MCP sunucusu (https://api.tecof.com/mcp) mağaza verisini, sayfaları, CMS’i, ürünleri ve tema kodunu kapsamlı yetkilerle ajanlara açar; @tecof/mcp aynı araçları tema reposunun içinden sunar (Tecof MCP). Mağazalar ayrıca AI arama motorları için llms.txt ve /ai/*.json dosyaları yayınlar (GEO: AI Storefront).

Kimlik doğrulama modeli#

Katman	Kullanım	Kimlik doğrulama
Vitrin (okuma ve güvenli yazma)	Canlı tema, ürün, CMS, checkout	`x-secret-key`
Müşteri hesabı	Profil, adres, siparişler, yorum/favori	`x-secret-key` + müşteri `Authorization`
Tema editörü yazma	Sayfa kaydetme, yükleme, ortak bileşen	`x-secret-key` + mağaza/ekip JWT’si
Panel (yönetim)	Satıcı paneli ve yönetim API’leri	JWT, rol/ekip yetkisi
Analytics toplama	Vitrin olayları	Public `merchantId`
Partner uygulaması (sunucu)	Kurulu uygulamanın `/api/v1` çağrıları	`Authorization: Bearer tcfi_…` (kurulum token’ı)
Partner uygulaması (iframe)	Panel içindeki uygulama arayüzü → uygulama sunucusu	60 sn’lik oturum JWT’si (App Bridge)
CLI ve CI	Spaces, push, promote, rollback	Cihaz akışı token’ı (`tcfd_…`) ya da kapsamlı CI token’ı (`TECOF_TOKEN`)
MCP	Ajanların mağaza araçları	OAuth 2.1 ya da kişisel erişim anahtarı (`tcf_…`)

NEXT_PUBLIC_MERCHANT_SECRET_KEY temanın public bundle’ında bulunur. Bu yüzden backend, yazma yetkisi gerektiren editör işlemlerinde ayrıca JWT ister; taslak önizleme de imzalı previewToken ister.

Ortam değişkenleri#

Tema projelerinin temel değişkenleri (tecof theme dev bunları .env.local dosyasına yazar):

.env.local

NEXT_PUBLIC_BASE_URL=https://api.tecof.com
NEXT_PUBLIC_CDN_URL=https://cdn.tecof.com
NEXT_PUBLIC_MERCHANT_SECRET_KEY=merchant_secret_key
NEXT_PUBLIC_THEME_ID=merchant_theme_id

tecof-theme-core bu değerlerle /api/store/render, /api/store/merchant-info, /api/store/pages ve /api/store/ecommerce/* uçlarını çağırır. Uygulama projelerinin değişkenleri (TECOF_CLIENT_ID, TECOF_CLIENT_SECRET, TECOF_API_URL) uygulama hızlı başlangıçta.

Doğruluk notu#

Bu belgeler kaynak koda göre yazılır: tecof-app-backend (API sözleşmeleri), tecof-theme-core (tema runtime’ı), tecof-theme-editor (Studio ve renderer), tecof-app-sdk (CLI, uygulama paketleri) ve tecof-mcp. Mevcut kodda doğrulanan yol REST tabanlı /api/store/*, /api/v1 ve MCP sözleşmeleridir; GraphQL ya da ayrı bir storefront SDK’sı birincil yol değildir. Henüz kodda olmayan özellikler “plan” olarak belirtilir. Bir çelişki görürseniz paketlerin gerçek tip tanımları ve API yanıtları son doğruluk kaynağıdır.