Cara Mengunggah Katalog Anda untuk SiteChat

Jika Anda menggunakan SiteChat di situs web Anda sendiri (bukan toko Shopify), Anda dapat mengirim catatan 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 tetap 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 menambahkan 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 meminta Shoply untuk membangun ulang indeks toko. Sampai pembangunan ulang itu selesai, respons akan melaporkan index_status: "pending". Produk yang dipublikasikan kemudian 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 di dalam permintaan.
• Token Shopify Admin API tidak dapat memanggil rute ini.

Buat atau putar ulang rahasia pemilik dengan cara yang sama seperti integrasi Merchant API lainnya: Cara Menggunakan 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 rahasia sendiri.

Bagaimana Cara Kerja Autentikasi?

Dari konektor server

Panggil API dari backend tepercaya melalui HTTPS. Tempatkan 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 publiknya, 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 rahasia pemilik 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 secara default 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 sebuah platform). Gunakan nama yang stabil seperti woocommerce-main. Karakter yang diizinkan: huruf kecil, angka, garis bawah, dan tanda hubung; hingga 64 karakter. Produk yang dibuat melalui formulir di admin secara default menggunakan source admin.
• Identitas produk adalah kombinasi toko, source, dan external ID. Upsert POST batch dan tunggal adalah penggantian penuh, bukan patch: field opsional yang dihilangkan akan dikosongkan. Gunakan PATCH untuk pembaruan parsial.
• 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.
• Sebaiknya gunakan string desimal untuk harga. Mata uang adalah kode huruf besar tiga huruf.
• 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 SiteChat untuk metafield produk Shopify). Nilainya harus berupa string biasa. attributes lama diterima sebagai alias. metadata produk privat tidak lagi didukung.
• Produk draft dan archived tidak akan dimasukkan dalam indeks terbit berikutnya. Produk published yang habis terjual tetap diindeks dengan informasi ketersediaan terlampir.
• Koleksi manual menyimpan judul, deskripsi, status, dan daftar keanggotaan produk (source + external_id). Koleksi pintar/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. HTTP 200 masih 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 pengindeksan tidak dijadwalkan—coba lagi juga produk yang sudah tersimpan.

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. Catatan yang tidak ada mengembalikan HTTP 404.

Setelah pengindeks latar belakang menerbitkan hasil pembangunan ulang, status pembacaan ulang 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"])

Bisakah Saya Mengunggah Gambar Produk?

Ya. Jika sebuah gambar sudah tersedia di URL HTTPS publik permanen, masukkan URL itu ke dalam daftar images produk atau field image pada varian. URL HTTPS S3 publik berfungsi. Path s3:// mentah dan URL bertanda tangan yang 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 data formulir multipart. JPEG, PNG, dan WebP diterima, hingga 10 MiB dan 20 juta piksel. Gambar animasi tidak didukung. Shoply mengonversi gambar ke WebP dan menghapus metadata yang 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 melampirkannya ke produk atau meminta pengindeksan. Sertakan URL yang dikembalikan dalam produk lengkap dan kirim lagi melalui /merchant/products/batch.

Gambar yang sama yang diunggah lagi untuk akun yang sama akan menggunakan kembali URL-nya. Gambar yang berubah akan menerima URL baru. Tidak ada endpoint penghapusan 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 menerbitkan indeks baru. Tidak ada jaminan waktu penyelesaian yang tetap.

• Produk yang dipublikasikan masuk ke pencarian produk dan juga 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 yang Perlu Saya Harapkan?

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

Untuk bantuan terkait integrasi, hubungi Shoply AI.