Fruga
Türkçe
Dokümantasyon

FrugalDomain entegrasyon dokümanları

Platform için teknik rehber: mağaza bağlama, mobil uygulama entegrasyonu, kendi uygulamalarınızı yayımlama ve REST API.

Platforma Genel Bakış

FrugalDomain; katalog, stok, içerik ve sipariş işlemlerini tek bir sistemde toplayan bir platformdur.

  • Mağaza verilerinizi tek bir kontrol panelinden yönetin.
  • Tek bir ticaret motorunu doğruluk kaynağı olarak tutun.
  • Web ve Flutter mobil uygulamaları için temiz API'ler sunun.

FrugalDomain Neden Önemli

Platform, tek bir yönetim panelinden hızlı günlük operasyon yürütmesi gereken ekipler için tasarlanmıştır.

  • Günlük çalışanlar için daha hızlı ürün ve stok işlemleri.
  • İzleme ve yeniden deneme desteği olan yapılandırılmış senkronizasyon hatları.
  • Ön yüz, mobil ve entegrasyonlar için yeniden kullanılabilir API sözleşmeleri.
  • Mağaza düzeyinde yalıtım; her mağaza yalnızca kendi verisini görür.

Temel İş Akışları

Katalog Yönetimi

  • Ürünler, varyantlar, koleksiyonlar, etiketler, tedarikçiler, ürün türleri.
  • Kanal segmentasyonu için depoya duyarlı ürün görünürlüğü.

Stok ve Fiyatlandırma

  • Varyant düzeyinde stok ve bulunabilirlik yönetimi.
  • Senkronizasyon gönderimiyle toplu ve hedefli fiyat güncellemeleri.

Siparişler ve Ödeme

  • Sepet toplamlarını arka uçtan hesaplayın.
  • Ödeme öncesi adım olarak taslak siparişler oluşturun.
  • Etkinleştirildiğinde, yapılandırılmış ödeme URL'sine yönlendirerek ödeme aşamasını tamamlayın.

Mağaza Nasıl Bağlanır

  1. 1. Sisteminizde mağaza kaydını oluşturun ve etkinleştirin.
  2. 2. Mağaza alan adını ve erişim token'ını güvenli biçimde kaydedin.
  3. 3. Ürünler, varyantlar, içerik ve müşteriler için ilk tam senkronizasyonu çalıştırın.
  4. 4. Sürekli senkronizasyon işlerini ve webhook aboneliklerini etkinleştirin.
  5. 5. Mağaza çalışanlarına erişim açmadan önce panodaki senkronizasyon durumunu doğrulayın.

Her mağaza için tek bir mağaza kimliği kullanın. Token'ları mağazalar arasında asla tekrar kullanmayın.

Flutter Mobil Entegrasyonu

Mobil uygulama uç noktaları /mobile altındadır ve mağaza bağlamı gerektirir. Her zaman store_id gönderin; kanala özel ürün akışları için isteğe bağlı olarak warehouse_name de gönderin.

  • warehouse_name filtrelemesi, eşleşen depo ürünlerini ve genel ürünleri (null/empty/all) kapsar.
  • Mağaza markasını, öne çıkan ürünleri ve ödeme yöntemlerini önceden yüklemek için önce bootstrap uç noktasını kullanın.
  • Kesin toplamları göstermek için taslak sipariş oluşturmadan önce quote uç noktasını kullanın.
Kod
GET /mobile/bootstrap?store_id={uuid}&warehouse_name=BRAND VIP WEB
GET /mobile/products?store_id={uuid}&warehouse_name=BRAND VIP WEB&per_page=20
GET /mobile/collections?store_id={uuid}&warehouse_name=BRAND VIP WEB
GET /mobile/search?store_id={uuid}&warehouse_name=BRAND VIP WEB&q=lip
POST /mobile/checkout/quote
POST /mobile/checkout/place-draft-order

Sitedeki Araçlar

Panonun ötesinde site, tarayıcıda çalışan bir araç seti sunar. Tamamen ziyaretçinin cihazında çalışır, hiçbir şey yüklenmez; bu yüzden sayfa yüklendikten sonra çevrimdışı da çalışır.

Simge kütüphanesi

  • CDN üzerinden sunulan, SVG ve PNG biçiminde 324 simge.
  • Bir sınıf adını kopyalayın, tek bir dosya indirin veya koleksiyon oluşturun.
  • İki satırla kullanılır: stil dosyasını bağlayın, ardından simge sınıfını kullanın.

Dönüştürücüler

  • Yaygın raster biçimleri arasında resim dönüştürme.
  • Tarayıcıda WebAssembly ile çalışan ses ve belge dönüştürme.
  • Dosyalar cihazdan hiç çıkmaz; bu yüzden büyük girdileri yalnızca kullanılabilir bellek sınırlar.

Çizim tahtası ve simülatör

  • Katmanlar, geri alma ve yineleme destekli bir vektör çizim tahtası.
  • Hareket vuruşlarını kaydeden ve Arapça karakterleri tanıyan bir dokunmatik simülatör.

Uygulama Yayımlama

Uygulamalar sitenin yanında yayımlanabilir. Her biri bir galeri kartı, kendi dokümantasyon sayfası ve gömülü bir canlı önizleme alır; kendi klasöründen sunulduğu için kendi yönlendirmesini ve varlıklarını korur.

  1. 1. Girişi panodan (Apps) ekleyin; türü ve önizleme modunu seçin.
  2. 2. Uygulamanın sayfasında görünen dokümantasyon bölümlerini yazın.
  3. 3. Uygulamayı klasörüyle eşleşen bir temel yolla derleyin, örn. --base=/apps/my-app/
  4. 4. Derleme çıktısının içeriğini sunucudaki apps/<slug>/ klasörüne yükleyin.
  5. 5. Girişi Yayımlandı olarak ayarlayın, kataloğu kaydedin ve ön yüzü yeniden derleyin.

Önizleme modları

  • Alt klasör: /apps/<slug> adresinde sunulur. Yalnızca yükleme, barındırma yapılandırması gerekmez.
  • Alt alan adı: bir alt alan adının belge kökünü uygulama klasörüne yönlendirin ve temel yol "/" ile derleyin.
  • Harici: uygulama başka bir yerde barındırılır ve galeri ona bağlantı verir.

Yönlendirme

  • Sitenin yeniden yazma kuralı /apps/<slug>/... yollarını dışarıda bırakır; böylece derin bağlantılar uygulamanın içinde çözümlenir.
  • Kendi istemci tarafı yönlendiricisi olan bir uygulamanın klasöründe, kendi index.html dosyasına işaret eden bir .htaccess bulunmalıdır.

Alt klasörden sunulan bir React veya Vue derlemesi, eşleşen bir temel yolla derlenmelidir. Varsayılan temel yolla derlenirse varlıklarını site kökünden ister, hepsi 404 döndürür ve önizleme boş görünür.

REST API Rehberi (Güncel Genel Entegrasyon Seti)

JSON istekleri ve yanıtları kullanın. Rota korumalı bağlam gerektiriyorsa Authorization token'ı gönderin. Mobil vitrin rotalarında istekte store_id zorunludur.

  • GET/mobile/bootstrap

    Mağaza profilini, öne çıkan katalog bloklarını ve ödeme yöntemi referanslarını döndürür.

  • GET/mobile/products

    İsteğe bağlı arama ve depo filtresi olan sayfalanmış ürün listesi.

  • GET/mobile/products/{id}

    Varyantları, koleksiyonları ve etiketleriyle ürün ayrıntıları.

  • GET/mobile/collections

    Geçerli mağaza bağlamındaki koleksiyonları listeler.

  • GET/mobile/collections/{id}

    Koleksiyon ayrıntıları ve koleksiyondaki ürünler.

  • GET/mobile/pages

    Vitrin uygulaması için yayımlanmış statik sayfalar.

  • GET/mobile/blogs

    Yayımlanmış bloglar.

  • GET/mobile/blogs/{blogId}/articles

    İçerik ekranları için blog yazıları listesi.

  • GET/mobile/payment-methods

    Etkin yerel ödeme seçeneklerini ve desteklenen yöntem referanslarını döndürür.

  • POST/mobile/checkout/quote

    Varyant satırlarından teklif toplamlarını hesaplar.

  • POST/mobile/checkout/place-draft-order

    Ödeme öncesi adım olarak yerel taslak sipariş oluşturur.

Örnek istek
{
  "store_id": "your-store-uuid",
  "warehouse_name": "BRAND VIP WEB",
  "lines": [
    { "variant_id": 1201, "quantity": 2 },
    { "variant_id": 1202, "quantity": 1 }
  ]
}
Örnek yanıt
{
  "status": "success",
  "data": {
    "totals": {
      "subtotal": 45.0,
      "tax": 0,
      "shipping": 0,
      "discount": 0,
      "grand_total": 45.0
    }
  }
}

Güvenlik ve En İyi Uygulamalar

  • store_id değerini doğrulayın ve istemci tarafından gelen kiracı kapsamına asla güvenmeyin.
  • Üretimde yalnızca HTTPS kullanın ve kimlik bilgilerini düzenli olarak yenileyin.
  • Erişim token'larını yalnızca sunucu tarafında tutun.
  • Kritik oluşturma/güncelleme işlemlerinde idempotency kullanın.
  • Tanılama için senkronizasyon hatalarını korelasyon kimlikleriyle kaydedin.

Sorun Giderme

Bir mobil kanalda ürünler eksik.

Uygulamanın gönderdiği warehouse_name değerini kontrol edin ve products tablosundaki warehouse_location değerlerini doğrulayın.

Quote uç noktası boş satırlar döndürüyor.

Varyant kimliklerinin aynı mağazaya ait olduğundan ve seçilen deponun görünürlük kurallarıyla eşleştiğinden emin olun.

Senkronizasyon sayaçları eski görünüyor.

Ortak panosunu yenileyin ve arka plandaki kuyruk işçilerinin çalıştığını doğrulayın.