Site kur ve yayımla — Era Belgeleri

Siteni kendin yaz — istediğin tasarım, istediğin teknoloji — arka uç olarak Era'yı kullan: ürünler, fiyatlar, stok, ödeme, siparişler, müşteri hesapları, yazılar, formlar ve randevular. İşletme sahibinin değiştirebileceği yerleri era.theme.json'da tanımla, getera.site'de yayımla; sahip bunları Era'nın tema düzenleyicisinde değiştirir.

Site kur ve getera.site’a yayınla

Era sitenin arka ucudur, bir site oluşturucu değil. Tasarım da kod da senin: düz HTML, Astro, Next.js'in statik çıktısı ya da dosya üreten herhangi bir şey. Era masaüstünde bu kodu markaya özel olarak senin kendi Claude ya da Codex aboneliğin sıfırdan yazar. İşletme ise Era'da durur: ürünler, fiyatlar, stok ve ürün fotoğrafları, sepet ve Era'nın ödeme sayfası, siparişler, müşteri hesapları, blog ve haberler, formlar ve randevular. İşletme sahibinin koda dokunmadan değiştirebilmesi gereken her şeyi — ana başlık, çalışma saatleri, bir bölümün fotoğrafı, bölümlerin sırası — bir Shopify temasının bölümlerini tanımladığı gibi era.theme.json içinde tanımlarsın. Sahip bunları Era'nın tema düzenleyicisinde canlı önizlemenin yanında değiştirir; site değişikliği yarım dakika içinde gösterir.

siteyi yaz  →  era theme check  →  era deploy  →  sahip Era'da düzenler  →  kodu değiştirmeden önce era theme pull

İşletmene giriş yapmış era komutu ve açık bir Web sitesi modülü gerekir. Yayımlamak ve tema içe aktarmak site:manage izni ister.

İşletmeyi Era'ya koy

era sites list --json                                   # sitenin kimliği, herkese açık anahtarıdır
era run catalog.create_item --data '{"name":"Etiyopya Guji 250 g","kind":"product","fulfilment":"shipping","priceAmount":42000,"inShop":true}'
curl -s "https://app.getera.io/api/site/v1/SITE_ID/products"   # bir ziyaretçinin gördüğü

Ürünler, fiyatlar (kuruş cinsinden: 42000 = ₺420,00), stok ve ürün fotoğrafları Era'da durur; sahip bunları Ürünler'de değiştirir, siten de onu izler. Yazılar Web sitesi → Blog / Haberler'de, formlar Formlar'da yazılır.

Siteyi yaz, arka uç Era olsun

Kiti bir kez yükle — betik olarak (era-site.js, @getera/storefront/site) ya da paket olarak:

<script src="/era-site.js" data-site="SITE_ID" data-api="https://app.getera.io" defer></script>

import { createStorefront } from "@getera/storefront"
const era = createStorefront({ siteId: "SITE_ID" })
const { items } = await era.products.list({ category: "kahve" })
await era.cart.add(items[0].variantId!, 1)
await era.checkout.redirect({ returnUrl: `${location.origin}/tesekkurler` })

Ürünleri derleme sırasında da sayfaya yaz; böylece sayfa, hiçbir betik çalışmadan da eksiksiz ve dizinlenebilir olur.

Sahibin neyi değiştirebileceğini tanımla

Sitenin kökündeki era.theme.json bölümleri listeler; her bölümün türlü ayarları, isteğe bağlı tekrarlanan blokları ve isteğe bağlı canlı bir kaynağı (Era yazıları, ürünler, bir form, hizmetler) vardır:

{
  "name": "Köşe Kavurma",
  "locales": ["tr", "en"],
  "sections": [
    { "id": "hero", "label": { "tr": "Giriş", "en": "Hero" },
      "settings": [
        { "id": "title", "type": "text", "label": { "tr": "Başlık", "en": "Headline" }, "default": { "tr": "Moda'da kendi kavurduğumuz kahve", "en": "Coffee we roast ourselves, in Moda" } },
        { "id": "image", "type": "image", "label": { "tr": "Görsel", "en": "Image" }, "default": { "url": "/img/hero.avif", "alt": "Sabah kavurma makinesi" } },
        { "id": "cta", "type": "link", "label": { "tr": "Düğme", "en": "Button" }, "default": { "tr": { "label": "Kahvelerimiz", "href": "#kahve" }, "en": { "label": "Our coffee", "href": "#kahve" } } } ] },
    { "id": "hours", "label": { "tr": "Çalışma saatleri", "en": "Opening hours" },
      "blocks": { "max": 7, "settings": [ { "id": "label", "type": "text", "label": "Günler" }, { "id": "value", "type": "text", "label": "Saat" } ],
                  "default": { "tr": [ { "label": "Her gün", "value": "08:00–20:00" } ] } } },
    { "id": "news", "label": { "tr": "Haberler", "en": "News" }, "source": { "type": "posts", "kind": "news" },
      "settings": [ { "id": "count", "type": "number", "label": "Kaç yazı", "default": 3, "min": 1, "max": 6 } ] }
  ],
  "layout": { "order": ["hero", "hours", "news"] }
}

Ayar türü	Değer	Dile göre
`text`, `textarea`	metin (`textarea`: boş satır yeni paragraf başlatır)	evet
`link`	`{ "label", "href" }`	evet
`image`	`{ "url" ya da "fileId", "alt" }`	ortak
`number`, `checkbox`, `select`, `color`, `url`	sayı, `true`/`false`, bir seçenek, renk, adres	ortak
`json`	herhangi bir şey	evet

Bir ayarda "localized": true ya da false ile bunu değiştirebilirsin. Bir bölümün blocks'u, sahibin satır eklediği tek bir liste olur; layout.order sahibin değiştirebileceği (ve bölüm gizleyebileceği) başlangıç sırasıdır.

Sonra sayfayı bunlara bağla. Yazdığın metin yedektir; Era'daki değer onun yerine geçer:

<section data-era-section="hero">
  <h1 data-era="hero.title">Moda'da kendi kavurduğumuz kahve</h1>
  <img data-era="hero.image" src="/img/hero.avif" alt="Sabah kavurma makinesi">
  <a data-era="hero.cta" href="#kahve">Kahvelerimiz</a>
</section>
<ul data-era="hours.blocks">
  <template><li><span data-era-field="label"></span> <span data-era-field="value"></span></li></template>
  <li>Her gün 08:00–20:00</li>
</ul>
<div data-era-posts="news" data-era-limit="news.count" data-era-href="/haberler/{slug}">
  <template><article><h3 data-era-field="title"></h3><p data-era-field="excerpt"></p><time data-era-field="date"></time></article></template>
</div>
<meta name="description" data-era-attr="content:seo.description">
<div data-era-show="announcement.on">…</div>

Anahtarlar <bölüm>.<ayar> biçimindedir (bloklar için <bölüm>.blocks). Onları değiştirme: sahibin düzenlemeleri orada durur.

era theme check           # era.theme.json'u Era'ya göre doğrular, hiçbir şey yazmaz

Yayımla

era deploy dist --site SITE_ID          # ya da siteId'yi era.config.json'a yaz

Theme imported (version 1: 14 new settings, 0 kept as the owner set them).
Uploading 23 files…
Live: https://kose.getera.site

era deploy, era.theme.json'u (klasörden ya da üst klasörden) içe aktarır ve dosyaları POST /api/v1/sites/{siteId}/deploy ile yükler. Her yayın, Web sitesi → Yayınlar'da geri dönebileceğin bir sürümdür.

Sahip Era'da düzenler

Web sitesi → İçerik ya da Tasarım → tema düzenleyici: bölümler sitenin sırasıyla, her biri ayarları ve bloklarıyla, canlı önizlemenin yanında (bilgisayar ve telefon, her dilde). Kaydedince değerler yazılır; yayın altyapısı bunları bir sonraki istekte her sayfaya işler (en çok 30 saniye önbellek). Yeniden derleme yok, eski metin bir an bile görünmez. Ürünler, fiyatlar ve yazılar Era'da durdukları yerde değiştirilir.

Kodu sonra, sahibin düzenlemelerini kaybetmeden değiştir

era theme pull             # era.theme.values.json: sahibin ayarladıkları
# kodu dilediğin gibi değiştir; yeni ayarlara varsayılan ver; var olan anahtarları koru
era deploy dist

Yeniden içe aktarma, sahibin değiştirdiği her değeri korur ve yeni ayarları varsayılanlarıyla ekler. Bildirimden çıkardığın ayarlar raporlanır ve saklanır; yalnızca era theme import --prune derseniz silinir.

Sahibin değişiklikleri siteye nasıl ulaşır

Site nerede çalışıyor	Nasıl güncel kalır
Era yayımladı (`*.getera.site`, kendi alan adın)	Yayın altyapısı değerleri istek anında HTML'e işler — derleme yok.
Başka bir yerde, düz ya da tek sayfa uygulaması	`era-site.js` / `era.bind()`, `GET /api/site/v1/{siteId}/content`'i (önbellekli, ETag) okur ve bağlantıları doldurur.
Metni derlerken sayfaya gömen bir statik site üreticisi	Ayarlar → Webhook'lar'da `site.content_changed` için derleme kancana (Netlify, Vercel, Cloudflare Pages) giden bir webhook ekle; her kayıtta çalışır.

const content = await era.content()               // { version, entries: { "hero.title": { kind, value, values } } }
const title = await era.content("hero.title")     // sayfanın dilindeki değer
const settings = await era.settings()             // şirket, iletişim, sosyal hesaplar, logo, diller

Vitrin kiti

Tarayıcıda site Era ile @getera/storefront üzerinden konuşur. Anahtarı sitenin kendi kimliğidir: yalnızca yayımlanmış sitenin bir ziyaretçisinin yapabileceklerini yapabilir — sitenin gösterdiğini okumak, sepeti doldurmak, ödemeye geçmek, form göndermek, randevu almak — ve yalnızca sitenin kendi adreslerine yanıt verir (*.getera.site adresi, doğrulanmış alan adları ve geliştirirken localhost). Bir siteye asla API anahtarı koyma.

Alan	Çağrılar
Katalog	`products.list({ q, category, collection, brand, sort, page, pageSize })`, `products.get(slug)`, `search(q)`, `categories()`, `collections()`
Sepet	`cart.add(variantId, adet)`, `cart.set(…)`, `cart.remove(variantId)`, `cart.get()`, `cart.clear()`
Ödeme	`checkout.url({ returnUrl })`, `checkout.redirect(…)`, `checkout.result()`, `orders.get(token)`, `paymentMethods()`
Sahibin içeriği	`content()`, `content(key)`, `settings()`, `bind(root)`
Yazılar ve sayfalar	`posts.list({ kind: "blog" \| "news" })`, `posts.get(slug)`, `pages()`
Formlar	`forms.get(slug)`, `forms.submit(slug, values, { honeypot, startedAt })`
Randevu	`booking.services()`, `booking.slots(serviceId, date)`, `booking.book(input)` (giriş yapmış müşteri)
Müşteri hesapları	`customer.requestCode(email)`, `customer.verify(email, code)`, `customer.orders()`, `customer.bookings()`, `customer.signOut()`

Kit hiçbir zaman tutar göndermez: fiyatları, indirimleri ve toplamları her zaman Era hesaplar.

Era'nın ödeme sayfası

await era.checkout.redirect({ returnUrl: `${location.origin}/tesekkurler` })
// /tesekkurler sayfasında:
const done = era.checkout.result()                 // { orderToken, number, status, paid }
const order = done && (await era.orders.get(done.orderToken))

Era'nın ödeme sayfası bilgileri, teslimatı ve bağlı ödeme uygulamanla ödemeyi alır, siparişi oluşturur (Siparişler nasıl işler) ve alışverişçiyi returnUrl?order=…&number=…&status=… adresine geri gönderir. Dönüş adresi sitenin kendi adreslerinden biri olmalı.

Kendi alan adın

era domains add magaza.ornek.com --site SITE_ID

Era, eklenecek DNS kayıtlarını Web sitesi → Alan adları'nda gösterir; DNS Era'yı gösterdiğinde alan adı kendiliğinden doğrulanır ve yayındaki sürümü sunar.

Şablonlar

era templates, Era'nın 31 kod şablonunu listeler; era init --template <ad> birini bir klasöre kopyalar — esin kaynağı olarak ya da biri şablon istediğinde işe yarar. Varsayılan, markaya özel sıfırdan yazılmış bir sitedir.

API'den de

Çağrı	Yaptığı
`POST /api/v1/actions/site.import_theme`	`era.theme.json`'u kaydeder (`dryRun`, `prune`)
`POST /api/v1/actions/site.set_content`	Bir içeriği değiştirir (`{ siteId, key, value: { "tr": … } }`)
`GET /api/v1/site_contents?site_id=…`	Sahibin şu anki değerleri
`GET /api/site/v1/{siteId}/content` · `/content/{key}` · `/settings`	Ziyaretçinin sayfasının okuduğu (herkese açık, önbellekli)
`POST /api/v1/sites/{siteId}/deploy`	Derlenmiş bir siteyi yayımlar: `{ files: [{ path, content (base64) }] }`
`GET /api/v1/sites/{siteId}/deploys` · `POST …/deploys/{id}/rollback` · `DELETE /api/v1/sites/{siteId}/deploy`	Sürümler, geri alma, yayından kaldırma

Bir ziyaretçinin yapmaması gereken her iş için — tedarikçiden stok eşitlemek, siparişleri dışa aktarmak — @getera/sdk'yı bir sunucuda API anahtarıyla kullan, asla sitenin tarayıcı kodunda değil.