Ürün Listeleme API Entegrasyonu

Ürünlerini kendi web sitende listelemek istersen, bunu ürün liteleme API entegrasyonu ile sağlayabilirsin. Bu entegrasyonun çalışabilmesi için API Key'e ihtiyacın var. API Key'ini öğrenmek için bize talep oluşturman yeterli. En kısa sürede sana ileteceğiz.

API Key'ini edindikten sonra, ShopProductsResource (/api/v1/shop/products) endpoint'ini kullanarak bunu kolayca yapabilirsin. Bu dokümanda, ürünlerini kendi frontend'ine nasıl çekeceğini adım adım anlattık.

Genel Bakış

• Kimlik Doğrulama: İsteklerinde X-API-Key header'ını göndermen gerekiyor. Eğer kullandığın anahtar geçerli bir mağaza ile eşleşmezse 403 hatası alırsın.
• Parametreler: Listeleme yaparken sadece sayfalama (page, per_page) parametrelerini kullanabilirsin. Varsayılan olarak page=1 ve per_page=50 değerleri geçerlidir.
• Sonuç: İstek sonucunda sana ürünlerin listesiyle birlikte sayfalama bilgileri (count, total_pages) döner.

Örnek İstek

Aşağıdaki komutu kullanarak API'yi hızlıca test edebilirsin:

curl -X GET "https://api.voxvil.com/api/v1/shop/products?page=1&per_page=50" \
  -H "Accept: application/json" \
  -H "X-API-Key: SHOP_API_KEY"

Yanıt Yapısı (Özet)

API'den dönecek yanıtın yapısı şuna benzer olacaktır:

{
  "meta": {
    "count": 123,
    "total_pages": 3
  },
  "data": [
    {
      "title": "Ürün Adı",
      "price": {
        "amount": 199.9,
        "currency": "TRY",
        "formatted": "199,90 TRY"
      },
      "product_images": {
        "list_images": [
          /* ... */
        ],
        "detail_images": [
          /* ... */
        ]
      },
      "design_images": {
        "list_images": [
          /* ... */
        ],
        "detail_images": [
          /* ... */
        ]
      },
      "url": "https://www.voxvil.com/path/to/product",
      "product_categories": [
        /* ... */
      ]
    }
  ]
}

Frontend'de Kullanım İpuçları

• Sayfalama: Kullanıcılarına ürünlerini parça parça göstermek için page ve per_page parametrelerini kullanabilirsin. Toplam sayfa sayısını total_pages değerinden öğrenebilirsin.
• Fiyat Gösterimi: Fiyatı direkt göstermek için price.formatted alanını kullanabilirsin. Eğer farklı bir format istiyorsan amount ve currency değerleriyle kendi gösterimini oluşturabilirsin.
• Görseller: Ürün listesi sayfanda product_images.list_images, ürün detay sayfasında ise product_images.detail_images veya design_images.detail_images alanlarını kullanman daha doğru olacaktır.
• Link: Ürünün Voxvil üzerindeki sayfasına yönlendirmek istersen url alanındaki bağlantıyı kullanabilirsin.

Hata Durumları

• 401/403: Gönderdiğin X-API-Key eksik veya hatalı olabilir. Anahtarını kontrol etmelisin.
• 500: Sunucu tarafında beklenmedik bir hata oluştu. Eğer bu hatayı alırsan, dönen hata mesajını bize iletebilirsin.