Kendi kodunuzla vitrin (headless)

Normal yol, vitrinimizi veya sitenizdeki widget'ları kullanmaktır. Ancak siteyi geliştiriciniz veya ajansınız yazıyorsa ve tasarımın tamamen size ait olması gerekiyorsa üçüncü bir seçenek vardır: verileri ve sipariş kabulünü bizden alır, tüm ön yüzü istediğiniz teknolojiyle kendiniz geliştirirsiniz.

Verileri okumak anahtar veya kimlik doğrulama gerektirmez: vitrinde herkese açık olan her şey JSON olarak da herkese açıktır.

Nereden ayarlanır: Pazarlama → «Web sitem» → «Kendi kodunuzla vitrin» kartı. Konumunuzun manifest adresi, teknik dokümantasyon ve JSON şemalarına bağlantılar ile webhook ayarları da buradadır. Hiçbir şeyi etkinleştirmeniz gerekmez: veriler her zaman yayımlanır.

storefront.json manifesti#

Geliştiricinin bilmesi gereken tek adres:

https://cdn.cenaly.com/{ДОМЕН}/storefront.json

Diğer her şey manifesttedir:

Blok	İçeriği
`location`	Kimlik, slug, sektör (restoran, mağaza, otel, salon)
`languages`	Varsayılan dil ve etkin dillerin listesi
`currency`	Para birimi kodu ve simgesi
`cdnBase` + `data`	Menü, profil, sayfa, koleksiyon, yorum ve «birlikte satın alınanlar» önerilerinin yolları
`catalog`	Katalog modu: her şey dosyalarda veya ayrı ürün dosyaları ve katalog API'si
`images`	Görsellerin temel adresi, yol şablonları (ürün ve galeri fotoğrafları, video, kategoriler, koleksiyonlar, kapak ve logo, favicon) ve kullanılabilir boyutlar
`api`	Misafir API'si, OpenAPI belirtimi, ticaret hizmetleri, MCP uç noktası ve canlı sipariş durumları WebSocket adresleri
`publishId`, `publishedAt`	Yayın kimliği: veriler her yeniden üretildiğinde değişir

Sözleşme sürümlenir (contractVersion); yanında JSON şemaları bulunur — verileri doğrulamak ve türleri üretmek için kullanışlıdır. Bilinmeyen alanları yok sayın: sözleşme uyumluluk bozulmadan genişletilir.

Veriler ve görseller#

Vitrinin gösterdiği her şey dosya olarak kullanılabilir: dillere göre menü ve katalog, konum profili (ad, adres, çalışma saatleri, iletişim bilgileri, ayarlar), sayfalar ve makaleler, koleksiyonlar, yorumlar.

Büyük kataloglarda manifest api moduna geçer: menü dosyası hafif bir seçki içerir; tam ürün kartları ayrı dosyalardan veya filtreler ve alt kategoriler sunan katalog API'sinden alınır.

Görseller CDN'imizden, manifestteki şablona göre çeşitli boyutlarda sunulur; fotoğraf güncellendiğinde yol sürümlenir, dolayısıyla önbellek «sonsuza kadar» tutulabilir.

Tüm bu istekleri elle yazmanız gerekmez: @cenaly/storefront npm paketi; sözleşme için tür tanımlı bir istemci (manifest, profil, her iki katalog modunda menü, sipariş oluşturma), görsel URL oluşturucusu ve React hook'ları sağlar. Paketin statik derlemeler için ayrı bir giriş noktası (@cenaly/storefront/static: site adres haritası, sitemap.xml, robots.txt, görsel bağlantıları) ve cenaly-storefront konsol komutu vardır — konumun tüm verilerini bir klasöre kaydeder, adresleri listeler ve manifesti izleyip publishId değiştiği anda derlemenizi başlatan watch modunu sunar. Klonlayıp yalnızca renklerini değiştirerek kullanabileceğiniz Next.js başlangıç projesi de bu pakete dayanır.

Siparişler ve misafir API'si#

Sipariş kabulü, sipariş durumu, arama ve rezervasyonlar — misafir API'si üzerinden: yetkilendirme olmadan, adres manifestodan alınır, spesifikasyon — OpenAPI 3.1. Ayrıca ticari bir katman vardır: kuponlar, teslimat hesaplaması, formlar, abonelikler. Ayrıntılar — Yapay zekâ ajanları için Guest API, aynı arayüz.

Sizin siteniz tarafından oluşturulan sipariş, genel "Siparişler" bölümüne düşer ve normal kurallara göre yaşar: durumlar, mutfak, kuryeler, fişler, bildirimler.

Değişiklik webhook'ları#

CDN'yi sürekli sorgulamak yerine olaylara abone olun:

menu.updated — menü veya katalog yeniden üretildi;
profile.updated — konum profili değişti;
pages.updated — sayfalar ve makaleler değişti.

Olay gövdesindeki publishId, statik sayfaları yeniden derlemek veya ISR önbelleğini temizlemek için kullanışlıdır. Bir gizli anahtar belirlediyseniz istek HMAC-SHA256 ile imzalanır ve X-Meni-Signature başlığıyla gelir — herhangi bir yeniden derleme yapmadan önce imzayı doğrulayın; Vercel/Netlify deploy hook'u için gizli anahtar tanımlamayabilirsiniz. Konum başına en fazla beş adres eklenebilir; art arda on başarısızlıktan sonra abonelik otomatik olarak kapanır (panelde son teslimat ve hata sayacı görünür; ayarları yeniden kaydetmek aboneliği tekrar açar).

Sunucu hangi adresi kabul eder? Yalnızca https://; URL'nin içinde kullanıcı adı veya parola bulunamaz ve sunucu herkese açık olmalıdır: yerel, dahili ve hizmet adresleri (localhost, 10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12, 100.64.0.0/10, 169.254.169.254) kaydetme sırasında reddedilir. Kendi bilgisayarınızda hata ayıklamak için herkese açık bir https adresi sağlayan tünel açın.

Ne zaman yeniden denenir? Zaman aşımları ile 5xx, 408, 429 yanıtları, yani geçici arızaya benzeyen durumlar yeniden denenir. Diğer tüm 4xx yanıtları kalıcı hata sayılır: yeniden deneme yapılmaz ve girişim doğrudan başarısızlık sayacına eklenir.

Webhook'lar «Kendi kodunuzla vitrin» kartında ayarlanır ve ücretli planlarda kullanılabilir; verileri okumak her zaman mümkündür.

Nereden başlamalı#

Pazarlama → «Web sitem» → «Kendi kodunuzla vitrin» bölümünü açıp manifest adresini kopyalayın.
Manifesti, ardından onun üzerinden menü ve profil verilerini yükleyin (veya @cenaly/storefront paketini kurup konum slug'ını iletin). Bu adımda hiçbir anahtar gerekmez.
Sayfaları kendi framework'ünüzle oluşturun; siparişler için misafir API'sini kullanın.
Değişiklik olduğunda siteyi yeniden derlemek için webhook ekleyin; olayları alacak herkese açık bir adresiniz yoksa cenaly-storefront watch çalıştırın: manifestteki publishId değerini izler ve derlemenizi kendisi başlatır.

Tam teknik açıklama aynı karttaki «Geliştirici dokümantasyonu» bağlantısındadır; yanında statik site için ayrı kılavuz ve JSON şemalarına bağlantılar bulunur. Hazır bir Next.js başlangıç projesi vardır; ayrıca tüm dokümantasyon, geliştiricinin AI asistanları için llms.txt biçiminde de sunulur — konumunuzun CDN'deki kişisel llms.txt dosyası da buna dahildir.

İlgili bölümler#

Sitem — sitenin tamamını yeniden yazmanıza gerek yoksa widget'lar
Yapay zeka ajanları için Guest API — aynı misafir API'si
Telefon API ve MCP — yapay zeka ajanlarının ve CRM'in telefona erişimi
İnternet Mağazası — katalog verilerinde tam olarak neler geldiği

Sık sorulan sorular#

Veri okumak için ödeme yapmam gerekiyor mu? Hayır. Herkese açık JSON'lar her pakette kullanılabilir — bunlar bizim vitrinimizin de kullandığı aynı dosyalardır. Ücretli olan webhook'lardır.

SEO durumu ne olacak? Tamamen sizin tarafınızda: sayfaları kendiniz oluşturur ve işaretlemeyi kendiniz yönetirsiniz. Sözleşmede mikro işaretleme (JSON-LD) için veriler mevcuttur.

Kendi vitrinimle birlikte kullanabilir miyim? Evet. Bizim vitrinimiz, widget'lar ve kendi siteniz aynı verilerle ve aynı sipariş sepetiyle çalışır.