SiteChat için Kataloğunuzu Nasıl Yüklersiniz

Kendi web sitenizde SiteChat kullanıyorsanız (bir Shopify mağazası değilse), alışveriş yapanların SiteChat sohbetinde ve ürün aramasında bulabilmesi için Shoply’ye yapılandırılmış ürün kayıtları gönderebilirsiniz.

Bu endpoint’ler, Shoply Merchant API geri kalanında kullanılan Ayarlar → Mağaza sahibi API gizli anahtarı ile aynısını kullanır ve SiteChat yönetici Product Catalog sayfası bunları oturum açmış yönetici erişim token’ınızla çağırabilir. Shopify mağazaları katalog verilerini Shopify üzerinden senkronize etmeye devam eder; bu yükleme rotaları yalnızca halihazırda bir Magento kataloğunu senkronize etmeyen SiteChat hesapları için kullanılabilir.

SiteChat yöneticisinde Product Catalog, Products, Collections ve Inventory içeren Shopify benzeri bir alan açar. Ürün ekleyebilir veya düzenleyebilir, CSV/Excel içe aktarabilir, ürünleri manuel koleksiyonlar halinde gruplayabilir ve stok miktarlarını ayarlayabilirsiniz.

Hangi API’ler Kullanılabilir?

Başarılı ürün kayıtları, Shoply’den mağaza indeksini yeniden oluşturmasını ister. Bu yeniden oluşturma tamamlanana kadar yanıtlar index_status: "pending" bildirir. Yayımlanan ürünler daha sonra hem ürün indeksinde hem de SiteChat sohbeti tarafından kullanılan bilgide görünür.

Bu API’leri Kimler Kullanabilir?

• Mağazanız bir SiteChat hesabı olmalıdır (app_platform SiteChat’tir).
• Shopify mağaza anahtarları (herhangi bir *.myshopify.com alan adı dahil) reddedilir.
• Kimlik doğrulama, istekteki tam store_key için ya geçerli bir mağaza sahibi API gizli anahtarını ya da bir SiteChat yönetici erişim token’ını kullanmalıdır.
• Shopify Admin API token’ları bu rotaları çağıramaz.

Sahip gizli anahtarını, diğer Merchant API entegrasyonlarıyla aynı şekilde oluşturun veya döndürün: Shoply Merchant API Nasıl Kullanılır. SiteChat yönetici konsolunda, gizli anahtarı kendiniz yönetmeden ürünleri, koleksiyonları ve envanteri yönetmek veya bir CSV ya da Excel dosyası içe aktarmak için Product Catalog bölümünü açın.

Kimlik Doğrulama Nasıl Çalışır?

Bir sunucu bağlayıcısından

API’yi güvenilir bir backend’den HTTPS üzerinden çağırın. Authorization başlığına bir JSON dizesi koyun:

{
  "store_key": "YOUR_SITECHAT_STORE_KEY",
  "store_owner_api_secrete": "YOUR_STORE_OWNER_API_SECRET"
}

store_owner_api_secrete, tarihsel yazımı da dahil olmak üzere genel alan adıdır. store_owner_api_secret de kabul edilir. Bu bir Bearer token’ı değildir.

SiteChat yöneticisinden

Product Catalog sayfası bunun yerine oturum açmış yönetici oturumunuzu gönderir:

{
  "store_key": "YOUR_SITECHAT_STORE_KEY",
  "admin_auth_token": "YOUR_SITECHAT_ACCESS_TOKEN"
}

access_token, admin_auth_token için bir diğer ad olarak kabul edilir.

store_key sorgu parametresi başlıkla eşleşmelidir. Sahip gizli anahtarlarını yalnızca sunucu tarafı ortam değişkenlerinde tutun — bunları asla bir storefront betiğinde, URL’de veya herkese açık bir depoda bulundurmayın.

export SHOPLY_STORE_KEY="your-sitechat-store-key"
export SHOPLY_STORE_OWNER_API_SECRETE="shoply_owner_key_example123.secret-value"

Ürünleri Nasıl Yüklerim?

POST https://api.shoplyai.ai/merchant/products/batch?store_key=YOUR_SITECHAT_STORE_KEY

{
  "source": "woocommerce-main",
  "products": [
    {
      "external_id": "123",
      "title": "Trail shoes",
      "description": "Water-resistant hiking shoes.",
      "url": "https://example.com/products/trail-shoes",
      "currency": "USD",
      "price": "49.95",
      "original_price": "59.95",
      "available": true,
      "status": "published",
      "images": ["https://example.com/images/trail-shoes.jpg"],
      "categories": ["Footwear"],
      "metafields": {"material": "Leather"},
      "variants": [
        {
          "external_id": "124",
          "title": "Brown / 42",
          "sku": "TRAIL-BR-42",
          "price": "49.95",
          "available": true,
          "metafields": {"color": "Brown", "size": "42"}
        }
      ]
    }
  ]
}

Zorunlu alanlar ve kurallar

• Zorunlu ürün alanları: external_id, title, url, currency, price ve available. status varsayılan olarak published olur.
• İsteğe bağlı envanter: tracks_inventory değerini true olarak ve ürün ya da varyant üzerinde negatif olmayan bir quantity ayarlayın. Shoply daha sonra uygunluğu stoktan türetir (quantity > 0) ve yönetici listeleri için total_inventory saklar.
• source, katalog bağlantısını adlandırır (mutlaka bir platform olmak zorunda değildir). woocommerce-main gibi sabit bir ad kullanın. İzin verilen karakterler: küçük harfler, sayılar, alt çizgiler ve tireler; en fazla 64 karakter. Yönetici panelinde form ile oluşturulan ürünler varsayılan olarak admin kaynağını kullanır.
• Ürün kimliği; mağaza, kaynak ve harici kimlik birleşimidir. Toplu ve tekil POST upsert’leri tam değişimlerdir, yama değildir: atlanan isteğe bağlı alanlar temizlenir. Kısmi güncellemeler için PATCH kullanın.
• Toplu istekler 1–50 ürün içerir ve en fazla 2.000.000 istek baytı olabilir. Her ürünün doğrulanmış JSON’u 128.000 bayt ile sınırlıdır ve en fazla 250 varyant içerebilir.
• Fiyatlar için ondalıklı dizeleri tercih edin. Para birimi, üç harfli büyük harfli bir koddur.
• Ürün ve görsel URL’leri HTTP(S) olmalıdır. İçe aktarma bu URL’leri sizin için çekmez.
• Aranabilir ürün özellikleri için genel metafields kullanın (SiteChat’in Shopify ürün metafield’larına benzeri). Değerler düz dizeler olmalıdır. Eski attributes bir diğer ad olarak kabul edilir. Özel ürün metadata artık desteklenmez.
• draft ve archived ürünler bir sonraki yayımlanmış indekse dahil edilmez. Tükenmiş yayımlanmış ürünler, uygunluk bilgisi eklenmiş şekilde indekslenmiş kalır.
• Manuel koleksiyonlar bir başlık, açıklama, durum ve ürün üyelikleri listesi (source + external_id) saklar. Akıllı/kural tabanlı koleksiyonlar bu sürümde desteklenmez.

Örnek başarılı yanıt

{
  "results": [
    {
      "external_id": "123",
      "product_id": "sitechat_product::woocommerce-main::<sha256-of-external-id>",
      "status": "stored"
    }
  ],
  "index_status": "pending",
  "index_revision": 1
}

Shoply yazmadan önce tüm isteği doğrular. HTTP 200, yine de error: "storage_error" ile bazı failed sonuçları listeleyebilir. Her sonucu inceleyin ve başarısız ürünleri yeniden deneyin. index_status request_failed ise depolama başarılı olmuştur ancak indeksleme planlanmamıştır — kaydedilmiş ürünleri de yeniden deneyin.

Python örneği

import json
import os
import requests
 
store_key = os.environ["SHOPLY_STORE_KEY"]
headers = {
    "Authorization": json.dumps({
        "store_key": store_key,
        "store_owner_api_secrete": os.environ["SHOPLY_STORE_OWNER_API_SECRETE"],
    })
}
 
response = requests.post(
    "https://api.shoplyai.ai/merchant/products/batch",
    params={"store_key": store_key},
    headers=headers,
    json={
        "source": "custom",
        "products": [{
            "external_id": "123",
            "title": "Trail shoes",
            "url": "https://example.com/products/trail-shoes",
            "currency": "USD",
            "price": "49.95",
            "available": True,
        }],
    },
    timeout=60,
)
response.raise_for_status()
result = response.json()
failed = [item["external_id"] for item in result["results"] if item["status"] != "stored"]
if failed:
    raise RuntimeError(f"Products need retry: {failed}")
if result["index_status"] == "request_failed":
    raise RuntimeError("Products saved, but retry the batch to request indexing")

İçe Aktarılan Bir Ürünü Nasıl Doğrularım?

GET https://api.shoplyai.ai/merchant/products?store_key=YOUR_SITECHAT_STORE_KEY&source=woocommerce-main&external_id=123

Aynı Authorization başlığını kullanın. Yanıt schema_version, updated_at, index_status ve normalize edilmiş product içerir. Eksik kayıtlar HTTP 404 döndürür.

Arka plan indeksleyici bir yeniden oluşturmayı yayımladıktan sonra, ürün başına geri okuma durumu indexed, excluded (taslak veya arşivlenmiş ürünler için) ya da limit_exceeded olur. Yönetici listesi için GET /merchant/products/list kullanın. Bir ürünü bir sonraki yayımlanmış indeksin dışında tutmak için DELETE /merchant/products ile yumuşak arşivleme yapın (veya status değerini archived / draft olarak ayarlayın); bu sürümde kalıcı silme yoktur.

record = requests.get(
    "https://api.shoplyai.ai/merchant/products",
    params={
        "store_key": store_key,
        "source": "woocommerce-main",
        "external_id": "123",
    },
    headers=headers,
    timeout=30,
)
record.raise_for_status()
print(record.json()["index_status"], record.json()["product"]["title"])

Ürün Görselleri Yükleyebilir miyim?

Evet. Bir görsel zaten kalıcı herkese açık bir HTTPS URL’sinde bulunuyorsa, bu URL’yi ürün images listesine veya bir varyantın image alanına ekleyin. Herkese açık S3 HTTPS URL’leri çalışır. Ham s3:// yolları ve kısa ömürlü imzalı URL’ler çalışmaz.

Dosyanın Shoply tarafından barındırılmasını istiyorsanız, backend’inizden ham görsel baytlarını yükleyin:

POST https://api.shoplyai.ai/merchant/products/images?store_key=YOUR_SITECHAT_STORE_KEY
Content-Type: image/png

JSON, base64 veya multipart form verisi değil, ham dosya baytlarını gönderin. JPEG, PNG ve WebP kabul edilir; en fazla 10 MiB ve 20 milyon piksel olabilir. Animasyonlu görseller desteklenmez. Shoply görseli WebP’ye dönüştürür ve gömülü meta verileri kaldırır.

with open("trail-shoes.png", "rb") as image_file:
    response = requests.post(
        "https://api.shoplyai.ai/merchant/products/images",
        params={"store_key": store_key},
        headers={**headers, "Content-Type": "image/png"},
        data=image_file,
        timeout=60,
    )
response.raise_for_status()
image_url = response.json()["url"]

HTTP 201, url, content_type, size_bytes, width ve height döndürür. Yalnızca bir görsel yüklemek onu bir ürüne eklemez veya indeksleme isteğinde bulunmaz. Döndürülen URL’yi eksiksiz bir ürüne dahil edin ve /merchant/products/batch üzerinden yeniden gönderin.

Aynı görsel aynı hesap için yeniden yüklenirse URL’si yeniden kullanılır. Değiştirilmiş bir görsel yeni bir URL alır. Bu sürümde görsel silme endpoint’i yoktur.

Ürünler Ne Zaman Sohbette ve Aramada Görünür?

Başarılı bir toplu kayıttan sonra Shoply arka planda bir indeks yeniden oluşturma ister. Worker yeni indeksi yayımlayana kadar yanıtlar index_status: "pending" bildirir. Tamamlanma süresi için sabit bir garanti yoktur.

• Yayımlanmış ürünler hem ürün aramasına hem de SiteChat sohbeti tarafından kullanılan bilgiye girer.
• Taslak ve arşivlenmiş ürünler bir sonraki yeniden oluşturmada hariç tutulur.
• İndeksleme planlanmadıysa (index_status: "request_failed"), zaten başarıyla kaydedilmiş ürünler için toplu isteği yeniden deneyin.

Hangi Hataları Beklemeliyim?

Gizli anahtarların süresi 90 gün sonra dolar. Süresi dolmadan önce Ayarlar → Mağaza sahibi API gizli anahtarı bölümünde bir yenisini oluşturun ve artık ihtiyacınız olmayan tüm gizli anahtarları iptal edin. Aynı gizli anahtar, Merchant API kılavuzu içinde belgelenen analiz, konuşma ve bilgi endpoint’lerini de çağırabilir.

Bir entegrasyonla ilgili yardım için Shoply AI ile iletişime geçin.