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 bunları SiteChat sohbetinde ve ürün aramasında bulabilmesi için yapılandırılmış ürün kayıtlarını Shoply’ye gönderebilirsiniz.

Bu uç noktalar, Shoply Merchant API geri kalanıyla aynı Settings → Store owner API secret değerini kullanır ve SiteChat yönetici Product Catalog sayfası bunları oturum açmış yönetici erişim jetonunuzla çağırabilir. Shopify mağazaları katalog verilerini Shopify üzerinden senkronize etmeye devam eder; bu yükleme rotaları yalnızca hâlihazırda bir Magento kataloğunu senkronize etmeyen SiteChat hesapları için kullanılabilir.

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

Hangi API’ler Mevcut?

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ınlanmış ü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 değeri SiteChat).
• Shopify mağaza anahtarları (herhangi bir *.myshopify.com alan adı dâhil) 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 jetonunu kullanmalıdır.
• Shopify Admin API jetonları bu rotaları çağıramaz.

Sahip gizli anahtarını diğer Merchant API entegrasyonlarıyla aynı şekilde oluşturun veya döndürün: How to Use the Shoply Merchant API. SiteChat yönetici konsolunda, ü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—gizli anahtarı kendiniz yönetmeden.

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 üstbilgisine 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ıyla birlikte herkese açık alan adıdır. store_owner_api_secret da kabul edilir. Bu bir Bearer jetonu 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 takma ad olarak kabul edilir.

store_key sorgu parametresi üstbilgiyle eşleşmelidir. Sahip gizli anahtarlarını yalnızca sunucu tarafı ortam değişkenlerinde tutun—bunları asla bir vitrin betiğine, URL’ye veya herkese açık depoya koymayı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"}
        }
      ]
    }
  ]
}

Gerekli alanlar ve kurallar

• Gerekli ü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 yapın ve ürün veya varyant üzerinde negatif olmayan bir quantity verin. 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 olması gerekmez). woocommerce-main gibi sabit bir ad kullanın. İzin verilen karakterler: küçük harfler, sayılar, alt çizgiler ve kısa çizgiler; en fazla 64 karakter. Yönetici panelinde form ile oluşturulan ürünlerde varsayılan source değeri admin olur.
• Ürün kimliği; mağaza, source ve external ID birleşimidir. Toplu ve tekil POST upsert işlemleri tam değiştirme yapar, yama uygulamaz: 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ık dizeler tercih edin. Para birimi üç harfli büyük harf kodudur.
• Ürün ve görsel URL’leri HTTP(S) olmalıdır. İçe aktarma bu URL’leri sizin için getirmez.
• Aranabilir ürün özellikleri için herkese açık metafields kullanın (SiteChat’in Shopify ürün metafield’larına karşılığı). Değerler düz dizeler olmalıdır. Eski attributes alanı da takma ad olarak kabul edilir. Özel ürün metadata desteği artık yoktur.
• draft ve archived ürünler bir sonraki yayınlanmış indekse alınmaz. Tükenmiş ancak yayınlanmış ü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 değeri request_failed ise, depolama başarılı olmuştur ancak indeksleme zamanlanmamıştır—kaydedilen ü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 üstbilgisini kullanın. Yanıt; schema_version, updated_at, index_status ve normalize edilmiş product alanlarını içerir. Eksik kayıtlar HTTP 404 döndürür.

Arka plan indeksleyicisi bir yeniden oluşturmayı yayınladı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ınlanmış indeksin dışında tutmak için DELETE /merchant/products ile yumuşak arşivleme yapın (veya status değerini archived / draft yapı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"])

Varyantları veya Metafield’ları Güvenli Şekilde Nasıl Güncellerim?

PATCH içinde variants, metafields veya eski attributes alanı varsa, önce ürünü GET ile okuyun. Düzenlemeyi bu yanıttan oluşturun ve üst düzey updated_at değerini PATCH gövdesinde expected_updated_at olarak ekleyin. Bu, varyantları veya metafield’ları temizlerken de geçerlidir.

current_response = requests.get(
    "https://api.shoplyai.ai/merchant/products",
    params={"store_key": store_key, "source": "woocommerce-main", "external_id": "123"},
    headers=headers,
    timeout=30,
)
current_response.raise_for_status()
current = current_response.json()
updated_metafields = {**current["product"].get("metafields", {}), "material": "Leather"}
response = requests.patch(
    "https://api.shoplyai.ai/merchant/products",
    params={"store_key": store_key},
    headers=headers,
    json={
        "source": "woocommerce-main",
        "external_id": "123",
        "expected_updated_at": current["updated_at"],
        "metafields": updated_metafields,
    },
    timeout=30,
)
response.raise_for_status()

HTTP 409, sürümün eksik olduğu ya da başka bir güncellemenin ürünü değiştirdiği anlamına gelir. En son ürünü tekrar okuyun ve yeniden denemeden önce yapmak istediğiniz değişiklikleri tekrar birleştirin. Eski bir varyant listesine yeni bir sürüm eklemeyin: bu, daha yeni stok değerlerinin üzerine yazabilir.

Bu alanları sürüm olmadan PATCH eden mevcut entegrasyonlar güncellenmelidir. Yalnızca skaler alanları içeren PATCH istekleri, özel envanter ayarlamaları ve POST veya toplu içe aktarma yoluyla yapılan tam değiştirmeler bu alanı gerektirmez. Tam değiştirmeler yine de ürünün tamamını değiştirir.

Ü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 koyun. 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; üst sınır 10 MiB ve 20 milyon pikseldir. 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 görsel yüklemek, onu bir ürüne bağlamaz veya indeksleme istemez. Dönen URL’yi tam bir ürüne ekleyin ve ürünü tekrar /merchant/products/batch üzerinden gönderin.

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

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

Başarılı bir toplu kayıttan sonra Shoply arka planda bir indeks yeniden oluşturma isteği gönderir. Çalışan yeni indeksi yayınlayana kadar yanıtlar index_status: "pending" bildirir. Tamamlanma süresi için sabit bir garanti yoktur.

• Yayınlanmış ürünler hem ürün aramasına hem de SiteChat sohbetinin kullandığı bilgiye girer.
• Taslak ve arşivlenmiş ürünler bir sonraki yeniden oluşturma işleminde hariç tutulur.
• İndeksleme zamanlanmadı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 Settings → Store owner API secret içinde bir yedek oluşturun ve artık ihtiyacınız olmayan tüm gizli anahtarları iptal edin. Aynı gizli anahtar, Merchant API guide içinde belgelenen analiz, konuşma ve bilgi uç noktalarını da çağırabilir.

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