geliştirici belgeleri

CLI

biticaret CLI'ı kurmak, tema ve uygulama başlatmak, giriş yapmak, uygulamayı yüklemek ve kodlama asistanlarına MCP sunucusu vermek.

biticaret CLI temaları ve uygulamaları başlatır, denetler, derler ve yükler.

Kurulum

Şimdilik CLI kaynağından derlenir (Go gerekir):

cd cli
go build -o biticaret ./cmd/biticaret

Tema başlatmak

biticaret theme init my-theme

./my-theme klasörünü (ad verilmezse ./skeleton-theme) Biticaret'in iskelet temasından yazar: her sayfa türü sade bir işaretleme ve biraz CSS ile, MIT lisanslı, yapay zekâ ajanları için bir AGENTS.md ile. Tema CLI sürümünün etiketinden (v<sürüm>) klonlanır; --clone-url <git adresi> başka bir deponun varsayılan dalını klonlar. Dolu bir klasör reddedilir, --force içine yazar.

Sonra biticaret theme check çalıştırın, tema klasörlerini ZIP yapın ve yönetim panelinde Online mağaza > Temalar altından yükleyin.

Temayı denetlemek ve taşımak

biticaret theme check my-theme [--strict] [--json]
biticaret theme convert their-theme [--out <klasör>] [--dry-run] [--json] [--report <dosya>]

Uygulama başlatmak

biticaret app init my-app
biticaret app init my-blocks --template theme-blocks

./my-app klasörünü bir başlangıç projesinden yazar: varsayılan olarak uygulama SDK'sı üzerinde küçük bir Go uygulaması (OAuth ile kurulum, KVKK webhook'ları, App Bridge ile yönetim panelinde bir sayfa), ya da --template ile bir örnek uygulama: theme-blocks, functions veya ui-extensions. --clone-url <git adresi> başka bir deponun varsayılan dalını klonlar; dolu bir klasör reddedilir, --force içine yazar. Ardından yeni klasörde app check çalıştırır ve sonraki adımları yazar.

Giriş yapmak

biticaret auth login [--platform <yönetim paneli adresi>] [--no-browser]
biticaret auth status
biticaret auth logout [--org <id|ad>] [--all]

auth login bir kod gösterir ve iş ortağı portalının onay sayfasını açar; organizasyonunuzda uygulamalar üzerinde çalışan bir üye orada onaylar. Giriş onaylayan üyenin organizasyonuna bağlıdır; CLI her organizasyon için bir giriş tutar. Jetonlar sistemin anahtar zincirinde saklanır ve CLI onları hiç yazdırmaz. auth status girişleri organizasyon, e-posta, rol ve bitiş zamanıyla listeler. --no-browser onay sayfasını açmaz, yalnızca adresini yazar. Platform --platform, yoksa $BITICARET_PLATFORM, yoksa https://admin.biticaret.com.tr olur; uygulama komutları son girişin platformunu kullanır.

Uygulamayla çalışmak

biticaret app check [klasör] [--config <ortam>] [--json]
biticaret app build [klasör] [--config <ortam>] [--out <klasör>] [--skip-build]
biticaret app generate extension --type function --name tier-discount
biticaret app config use staging
biticaret app config link [--client-id <id> | --name <ad> [--handle <handle>]] [--org <id|ad>] [--force]
biticaret app deploy [--version <ad>] [--message <değişiklikler>] [--submit] [--skip-build] [--org <id|ad>] [--json]
biticaret app versions list [--org <id|ad>] [--json]

Klasör verilmezse komut bulunduğunuz klasörde çalışır; --config <ortam> biticaret.app.<ortam>.toml dosyasını seçer.

Uygulama komutları dosyadaki client_id değerinin organizasyonuna ait girişi kullanır; --org başkasını seçer. check, build, generate ve config use çevrimdışı çalışır; config link, deploy ve versions list için auth login gerekir. .biticaret/ klasörünü git dışında tutun.

Mağazanın temalarını listelemek

biticaret theme list --store <mağaza handle> [--platform <yönetim paneli adresi>] [--org <id|ad>] [--json]

Organizasyonunuzun bir geliştirme mağazasındaki temaları listeler: kimlik (önizleme bağlantısının ?preview_theme_id= değeri), ad, yayında olup olmadığı (published veya unpublished) ve önizleme bağlantısı. --json aynı bilgileri updated_at ile birlikte JSON olarak verir. auth login gerekir; komut mağazaya sahip organizasyonun girişini kullanır, --org başkasını seçer. Yalnızca geliştirme mağazaları listelenir: müşteriye devredilecek bir mağaza, başka bir organizasyonun mağazası ve olmayan bir handle aynı "bulunamadı" hatasını verir.

Yapay zekâ kodlama asistanıyla çalışmak

biticaret mcp

Claude Code, Cursor gibi kodlama asistanları için stdio üzerinden bir MCP sunucusu çalıştırır. Sunucuyu asistan kendisi başlatır; siz yalnızca projenin .mcp.json (Claude Code) veya .cursor/mcp.json (Cursor) dosyasına eklersiniz:

{
  "mcpServers": {
    "biticaret": {
      "command": "biticaret",
      "args": ["mcp"]
    }
  }
}

Claude Code'da claude mcp add biticaret -- biticaret mcp de aynı işi görür. biticaret PATH üzerinde olmalıdır; değilse command olarak tam yolunu verin. Asistan sunucuyu projenin klasöründe başlatır ve araçların varsayılan dir değeri o klasördür.

Araçlar yalnızca okur ve denetler: projeye yazmaz, fonksiyonların [build] command komutunu çalıştırmaz, girişlerinizi okumaz ve platformu çağırmaz. Yani asistan bu sunucu üzerinden yükleme yapamaz, mağazayı değiştiremez; app deploy sizin çalıştırdığınız bir komut olarak kalır.

Araç Ne verir
docs_search Bu belgelerin query ile en çok eşleşen sayfaları (limit, varsayılan 5, en çok 20); sorgu yoksa bütün sayfalar.
docs_read Bir sayfanın (page) Markdown metni.
config_schema biticaret.app.toml ve her uzantı türünün biticaret.extension.toml anahtarları, türleriyle (file: app, theme, function, ui_extension, web_pixel).
manifest_schema manifest.json dosyasının her alanı, türüyle.
reference_lists Uygulamanın kullanabileceği adlar: izinler, webhook konuları, uzantı hedefleri, fonksiyon ve uzantı türleri; temanın Liquid filtreleri, etiketleri, genel adları ve nesneleri (list ile biri seçilir).
app_api_routes Uygulama API'sinin yolları: yöntem, yol, gereken izin ve sayfalı olup olmadığı (scope ile o izni gerektirenler).
theme_check theme check --json raporu (dir, strict).
app_check app check --json sonucu (dir, config).
liquid_render Temanın bir şablonunu (template) düzeniyle ya da bir Liquid parçasını (source) örnek bir mağazayla işler; çıktıyı, işlemeden önce bulunan Liquid sorunlarını ve varsa işleme hatasını verir. Hiçbir şey kaydedilmez.

Belge araçları https://dev.biticaret.com.tr/llms-full.txt dosyasını giriş bilgisi göndermeden indirir ve kullanıcı önbellek klasöründe bir gün tutar. Çevrimdışıyken son kopya kullanılır ve sonuç hangi güne ait olduğunu söyler; hiç kopya yoksa belge araçları hata verir, diğerleri çalışır. BITICARET_DOCS başka bir kaynak gösterir: bir belge sitesinin adresi veya llms-full.txt içeren derlenmiş bir belge klasörü.

mcp girdisi kapandığında 0 ile, yanlış kullanımda veya çıktısını yazamadığında 2 ile çıkar; araçların bulduğu sorunlar çıkış kodunda değil, sonuçtadır.

Çıkış kodları

Kod Anlamı
0 Tamam: tema veya uygulama denetimden geçti, dosyalar yazıldı veya sürüm yüklendi.
1 Tema veya uygulamanın düzeltilmesi gerekiyor: denetim hata buldu, platform yüklemeyi veya incelemeye göndermeyi reddetti; auth status için giriş yapılmamış.
2 Yanlış kullanım veya komut çalışamadı: klasör boş değil, klonlama başarısız, dosya zaten var, giriş yapılmamış, platforma ulaşılamıyor veya dosyadaki client_id ile bir uygulama yok.