Cara Mengunggah Katalog Anda untuk SiteChat

Jika Anda menggunakan SiteChat di situs web Anda sendiri (bukan toko Shopify), Anda dapat mengirim data produk terstruktur ke Shoply agar pembeli dapat menemukannya di chat SiteChat dan pencarian produk.

Endpoint ini menggunakan Settings → Store owner API secret yang sama seperti Shoply Merchant API lainnya, dan halaman admin SiteChat Product Catalog dapat memanggilnya dengan token akses admin Anda yang sedang masuk. Toko Shopify akan terus menyinkronkan data katalog melalui Shopify; rute unggah ini hanya tersedia untuk akun SiteChat yang belum menyinkronkan katalog Magento.

Di admin SiteChat, Product Catalog membuka area bergaya Shopify dengan Products, Collections, dan Inventory. Anda dapat menambah atau mengedit produk, mengimpor CSV/Excel, mengelompokkan produk ke dalam koleksi manual, dan menyesuaikan jumlah stok.

API Apa Saja yang Tersedia?

Penyimpanan produk yang berhasil akan meminta Shoply membangun ulang indeks toko. Sampai pembangunan ulang itu selesai, respons akan melaporkan index_status: "pending". Produk yang dipublikasikan kemudian akan muncul baik di indeks produk maupun di pengetahuan yang digunakan oleh chat SiteChat.

Siapa yang Dapat Menggunakan API Ini?

• Toko Anda harus berupa akun SiteChat (app_platform adalah SiteChat).
• Kunci toko Shopify (termasuk domain *.myshopify.com) akan ditolak.
• Autentikasi harus menggunakan rahasia API pemilik toko yang valid atau token akses admin SiteChat untuk store_key yang sama persis dalam permintaan.
• Token Shopify Admin API tidak dapat memanggil rute ini.

Buat atau putar ulang owner secret dengan cara yang sama seperti integrasi Merchant API lainnya: How to Use the Shoply Merchant API. Di konsol admin SiteChat, buka Product Catalog untuk mengelola produk, koleksi, dan inventaris—atau mengimpor file CSV atau Excel—tanpa harus mengelola secret sendiri.

Bagaimana Cara Kerja Autentikasi?

Dari konektor server

Panggil API dari backend tepercaya melalui HTTPS. Letakkan string JSON di header Authorization:

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

store_owner_api_secrete adalah nama field publik, termasuk ejaan historis tersebut. store_owner_api_secret juga diterima. Ini bukan token Bearer.

Dari admin SiteChat

Halaman Product Catalog mengirim sesi admin Anda yang sedang masuk sebagai gantinya:

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

access_token diterima sebagai alias untuk admin_auth_token.

Parameter kueri store_key harus cocok dengan header. Simpan owner secret hanya di variabel lingkungan sisi server—jangan pernah di skrip storefront, URL, atau repositori publik.

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

Bagaimana Cara Mengunggah Produk?

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"}
        }
      ]
    }
  ]
}

Field dan aturan yang wajib

• Field produk yang wajib: external_id, title, url, currency, price, dan available. status default-nya adalah published.
• Inventaris opsional: setel tracks_inventory ke true dan quantity nonnegatif pada produk atau varian. Shoply kemudian menurunkan ketersediaan dari stok (quantity > 0) dan menyimpan total_inventory untuk daftar admin.
• source menamai koneksi katalog (tidak harus platform). Gunakan nama stabil seperti woocommerce-main. Karakter yang diizinkan: huruf kecil, angka, underscore, dan hyphen; maksimal 64 karakter. Produk yang dibuat lewat formulir di admin default ke source admin.
• Identitas produk adalah kombinasi toko, source, dan external ID. Upsert batch dan POST tunggal adalah penggantian penuh, bukan patch: field opsional yang dihilangkan akan dikosongkan. Gunakan PATCH untuk pembaruan sebagian.
• Batch berisi 1–50 produk dan maksimal 2.000.000 byte permintaan. JSON tervalidasi tiap produk dibatasi hingga 128.000 byte, dengan maksimal 250 varian.
• Gunakan string desimal untuk harga jika memungkinkan. Mata uang harus berupa kode huruf besar tiga karakter.
• URL produk dan gambar harus berupa HTTP(S). Proses impor tidak akan mengambil URL tersebut untuk Anda.
• Gunakan metafields publik untuk spesifikasi produk yang dapat dicari (padanan metafield produk Shopify di SiteChat). Nilainya harus berupa string biasa. attributes lama diterima sebagai alias. metadata produk privat tidak lagi didukung.
• Produk draft dan archived tidak disertakan dalam indeks terbit berikutnya. Produk terbit yang habis stok tetap diindeks dengan informasi ketersediaannya.
• Koleksi manual menyimpan judul, deskripsi, status, dan daftar keanggotaan produk (source + external_id). Koleksi smart/berbasis aturan belum didukung dalam rilis ini.

Contoh respons berhasil

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

Shoply memvalidasi seluruh permintaan sebelum menulis data. HTTP 200 tetap dapat mencantumkan beberapa hasil failed dengan error: "storage_error". Periksa setiap hasil dan coba lagi produk yang gagal. Jika index_status adalah request_failed, penyimpanan berhasil tetapi penjadwalan pengindeksan tidak dilakukan—coba lagi produk yang sudah tersimpan juga.

Contoh Python

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")

Bagaimana Cara Memverifikasi Produk yang Diimpor?

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

Gunakan header Authorization yang sama. Respons mencakup schema_version, updated_at, index_status, dan product yang telah dinormalisasi. Data yang tidak ditemukan mengembalikan HTTP 404.

Setelah pengindeks latar belakang memublikasikan hasil pembangunan ulang, status pembacaan balik per produk menjadi indexed, excluded (untuk produk draft atau archived), atau limit_exceeded. Gunakan GET /merchant/products/list untuk daftar admin. Arsipkan sementara dengan DELETE /merchant/products (atau setel status ke archived / draft) agar produk tidak masuk ke indeks terbit berikutnya; tidak ada hard-delete dalam rilis ini.

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"])

Bagaimana Cara Memperbarui Varian atau Metafield dengan Aman?

Untuk PATCH yang berisi variants, metafields, atau field lama attributes, pertama baca produknya dengan GET. Bangun edit dari respons tersebut dan sertakan nilai updated_at tingkat atasnya sebagai expected_updated_at di body PATCH. Ini juga berlaku saat mengosongkan varian atau metafield.

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 berarti versinya tidak ada atau pembaruan lain telah mengubah produk. Baca produk terbaru dan gabungkan kembali perubahan yang Anda inginkan sebelum mencoba lagi. Jangan lampirkan versi baru ke daftar varian lama: itu bisa menimpa nilai stok yang lebih baru.

Integrasi yang sudah ada dan melakukan PATCH pada field ini tanpa versi harus diperbarui. Permintaan PATCH yang hanya berisi skalar, penyesuaian inventaris khusus, dan penggantian penuh melalui POST atau impor batch tidak memerlukan field ini. Penggantian penuh tetap mengganti seluruh produk.

Bisakah Saya Mengunggah Gambar Produk?

Ya. Jika gambar sudah tersedia di URL HTTPS publik yang permanen, letakkan URL tersebut di daftar images produk atau field image pada varian. URL HTTPS S3 publik berfungsi. Path s3:// mentah dan signed URL berumur pendek tidak didukung.

Agar Shoply meng-host file tersebut, unggah byte gambar mentah dari backend Anda:

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

Kirim byte file mentah, bukan JSON, base64, atau multipart form data. JPEG, PNG, dan WebP diterima, hingga 10 MiB dan 20 juta piksel. Gambar animasi tidak didukung. Shoply mengonversi gambar ke WebP dan menghapus metadata tertanam.

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 mengembalikan url, content_type, size_bytes, width, dan height. Mengunggah gambar saja tidak akan menempelkannya ke produk atau meminta pengindeksan. Sertakan URL yang dikembalikan dalam produk lengkap dan kirim ulang melalui /merchant/products/batch.

Gambar yang sama yang diunggah lagi untuk akun yang sama akan menggunakan ulang URL-nya. Gambar yang berubah akan menerima URL baru. Tidak ada endpoint hapus gambar dalam rilis ini.

Kapan Produk Muncul di Chat dan Pencarian?

Setelah batch berhasil disimpan, Shoply meminta pembangunan ulang indeks latar belakang. Respons melaporkan index_status: "pending" sampai worker memublikasikan indeks baru. Tidak ada jaminan waktu penyelesaian yang tetap.

• Produk yang dipublikasikan masuk ke pencarian produk dan pengetahuan yang digunakan oleh chat SiteChat.
• Produk draft dan archived dikecualikan pada pembangunan ulang berikutnya.
• Jika pengindeksan tidak dijadwalkan (index_status: "request_failed"), coba lagi batch untuk produk yang sudah berhasil disimpan.

Error Apa Saja yang Perlu Saya Harapkan?

Secret kedaluwarsa setelah 90 hari. Buat pengganti di Settings → Store owner API secret sebelum kedaluwarsa, dan cabut secret yang tidak lagi Anda perlukan. Secret yang sama juga dapat memanggil endpoint analitik, percakapan, dan pengetahuan yang didokumentasikan dalam Merchant API guide.

Untuk bantuan terkait integrasi, hubungi Shoply AI.