A katalógus feltöltése a SiteChathez

Ha a SiteChat szolgáltatást a saját webhelyeden használod (nem Shopify áruházban), strukturált termékrekordokat küldhetsz a Shoplynak, hogy a vásárlók megtalálhassák őket a SiteChat chatben és a termékkeresésben.

Ezek a végpontok ugyanazt a Settings → Store owner API secret beállítást használják, mint a Shoply Merchant API többi része, és a SiteChat admin Product Catalog oldala a bejelentkezett admin hozzáférési tokeneddel is meghívhatja őket. A Shopify áruházak továbbra is Shopifyon keresztül szinkronizálják a katalógusadatokat; ezek a feltöltési útvonalak csak olyan SiteChat fiókokhoz érhetők el, amelyek nem szinkronizálnak már Magento katalógust.

A SiteChat admin felületén a Product Catalog egy Shopify-stílusú területet nyit meg, benne a Products, Collections és Inventory részekkel. Hozzáadhatsz vagy szerkeszthetsz termékeket, importálhatsz CSV/Excel fájlokat, termékeket csoportosíthatsz manuális kollekciókba, és módosíthatod a készletmennyiségeket.

Milyen API-k érhetők el?

A sikeres termékmentések után a Shoply újraépíti az áruház indexét. Amíg ez az újraépítés nem fejeződik be, a válaszok index_status: "pending" értéket adnak vissza. A közzétett termékek ezután megjelennek mind a termékindexben, mind a SiteChat chat által használt tudásbázisban.

Ki használhatja ezeket az API-kat?

• Az áruházadnak SiteChat fióknak kell lennie (app_platform értéke SiteChat).
• A Shopify áruházkulcsokat (beleértve bármely *.myshopify.com domaint) elutasítjuk.
• A hitelesítésnek vagy érvényes bolttulajdonosi API-titokkal, vagy a kérésben szereplő pontos store_key-hez tartozó SiteChat admin hozzáférési tokennel kell történnie.
• A Shopify Admin API tokenek nem hívhatják ezeket az útvonalakat.

A tulajdonosi titok létrehozása vagy cseréje ugyanúgy történik, mint más Merchant API integrációknál: A Shoply Merchant API használata. A SiteChat admin konzolban nyisd meg a Product Catalog részt a termékek, kollekciók és készlet kezeléséhez — vagy CSV- illetve Excel-fájl importálásához — anélkül, hogy magadnak kellene kezelned a titkot.

Hogyan működik a hitelesítés?

Szerveroldali összekötőből

Az API-t megbízható háttérrendszerből, HTTPS-en keresztül hívd meg. Az Authorization fejlécbe egy JSON karakterláncot kell tenni:

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

A store_owner_api_secrete a nyilvános mezőnév, beleértve a történeti elírást is. A store_owner_api_secret szintén elfogadott. Ez nem Bearer token.

A SiteChat adminból

A Product Catalog oldal helyette a bejelentkezett admin munkamenetedet küldi:

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

Az access_token elfogadott aliasa az admin_auth_token mezőnek.

A store_key lekérdezési paraméternek egyeznie kell a fejlécben szereplő értékkel. A tulajdonosi titkokat csak szerveroldali környezeti változókban tárold — soha ne bolti frontend szkriptben, URL-ben vagy nyilvános repóban.

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

Hogyan tölthetek fel termékeket?

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

Kötelező mezők és szabályok

• Kötelező termékmezők: external_id, title, url, currency, price és available. A status alapértelmezett értéke published.
• Opcionális készletkezelés: állítsd a tracks_inventory értékét true-ra, és adj meg nemnegatív quantity értéket a terméken vagy a variánson. Ekkor a Shoply a készletből vezeti le az elérhetőséget (quantity > 0), és eltárolja a total_inventory értéket az admin listákhoz.
• A source nevezi meg a katalóguskapcsolatot (nem feltétlenül platformot). Használj stabil nevet, például woocommerce-main. Engedélyezett karakterek: kisbetűk, számok, aláhúzás és kötőjel; legfeljebb 64 karakter. Az admin felületen létrehozott termékek alapértelmezett forrása az admin.
• A termékazonosság a bolt, a forrás és a külső azonosító kombinációja. A batch és az egyszeres POST upsertek teljes cserék, nem patch-ek: a kihagyott opcionális mezők törlődnek. Részleges frissítéshez használj PATCH-et.
• A batch-ek 1–50 terméket tartalmazhatnak, és legfeljebb 2 000 000 kérésbájtot. Az egyes termékek validált JSON-ja legfeljebb 128 000 bájt lehet, és maximum 250 variánst tartalmazhat.
• Az árakhoz lehetőleg decimális karakterláncokat használj. A pénznem hárombetűs nagybetűs kód.
• A termék- és kép-URL-eknek HTTP(S) típusúnak kell lenniük. Az importálás nem tölti le helyetted ezeket az URL-eket.
• Használj nyilvános metafields mezőket kereshető termékspecifikációkhoz (a SiteChat megfelelője a Shopify termék-metafieldjeinek). Az értékeknek egyszerű karakterláncoknak kell lenniük. A régi attributes szintén elfogadott alias. A privát termék-metadata már nem támogatott.
• A draft és archived termékek kimaradnak a következő közzétett indexből. Az elfogyott, de közzétett termékek indexelve maradnak, csatolt elérhetőségi adattal.
• A manuális kollekciók címet, leírást, státuszt és a terméktagságok listáját tárolják (source + external_id). Az intelligens/szabályalapú kollekciók ebben a kiadásban nem támogatottak.

Minta sikeres válasz

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

A Shoply az egész kérést validálja, mielőtt írna. Egy HTTP 200 válasz továbbra is tartalmazhat néhány failed eredményt error: "storage_error" értékkel. Vizsgáld meg az összes eredményt, és próbáld újra a sikertelen termékeket. Ha az index_status értéke request_failed, a tárolás sikerült, de az indexelés ütemezése nem történt meg — ilyenkor a már eltárolt termékeket is küldd be újra.

Python-példa

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

Hogyan ellenőrizhetek egy importált terméket?

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

Ugyanazt az Authorization fejlécet használd. A válasz tartalmazza a schema_version, updated_at, index_status és a normalizált product mezőket. Hiányzó rekordok esetén HTTP 404 érkezik.

Miután a háttérben futó indexelő közzéteszi az újraépítést, a termékenkénti visszaolvasási státusz indexed, excluded (piszkozat vagy archivált termékeknél), vagy limit_exceeded lesz. Admin listázáshoz használd a GET /merchant/products/list végpontot. Soft archiváláshoz használd a DELETE /merchant/products hívást (vagy állítsd a status értékét archived / draft értékre), hogy a termék kimaradjon a következő közzétett indexből; ebben a kiadásban nincs hard delete.

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

Hogyan frissíthetem biztonságosan a variánsokat vagy metafield-eket?

Ha a PATCH kérés variants, metafields vagy a régi attributes mezőt tartalmazza, először olvasd be a terméket GET-tel. Az abból kapott válasz alapján építsd fel a módosítást, és a válasz felső szintű updated_at értékét add meg expected_updated_at néven a PATCH törzsében. Ez akkor is érvényes, amikor variánsokat vagy metafield-eket törölsz.

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

A HTTP 409 azt jelenti, hogy a verzió hiányzott, vagy egy másik frissítés módosította a terméket. Olvasd be a legfrissebb terméket, és újra egyesítsd a kívánt módosításokat, mielőtt ismét próbálkozol. Ne csatolj új verziót egy régi variánslistához: ez felülírhatja az újabb készletértékeket.

A meglévő integrációkat, amelyek verzió nélkül küldenek PATCH-et ezekre a mezőkre, frissíteni kell. A csak skalár mezőket érintő PATCH kérésekhez, a dedikált készletmódosításokhoz, valamint a POST-tal vagy batch importtal végzett teljes cserékhez nincs szükség erre a mezőre. A teljes cserék továbbra is az egész terméket lecserélik.

Feltölthetek termékképeket?

Igen. Ha egy kép már elérhető tartós, nyilvános HTTPS URL-en, tedd ezt az URL-t a termék images listájába vagy egy variáns image mezőjébe. A nyilvános S3 HTTPS URL-ek működnek. A nyers s3:// útvonalak és a rövid élettartamú aláírt URL-ek nem.

Ha azt szeretnéd, hogy a Shoply tárolja a fájlt, tölts fel nyers képbájtokat a backendből:

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

A nyers fájlbájtokat küldd, ne JSON-t, base64-et vagy multipart form adatot. A JPEG, PNG és WebP támogatott, legfeljebb 10 MiB méretig és 20 millió pixelig. Az animált képek nem támogatottak. A Shoply WebP-vé alakítja a képet, és eltávolítja a beágyazott metaadatokat.

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

A HTTP 201 válasz visszaadja a url, content_type, size_bytes, width és height mezőket. Egy kép önmagában történő feltöltése nem csatolja azt termékhez, és nem kér indexelést. Tedd bele a visszakapott URL-t egy teljes termékbe, majd küldd be újra a /merchant/products/batch végponton keresztül.

Ha ugyanazt a képet ugyanahhoz a fiókhoz újra feltöltöd, ugyanaz az URL lesz újrahasznosítva. A módosított kép új URL-t kap. Ebben a kiadásban nincs képtörlő végpont.

Mikor jelennek meg a termékek a chatben és a keresésben?

A sikeres batch mentés után a Shoply háttérben index-újraépítést kér. A válaszok index_status: "pending" értéket adnak vissza addig, amíg a worker közzé nem teszi az új indexet. Nincs garantált, fix befejezési idő.

• A közzétett termékek bekerülnek mind a termékkeresésbe, mind a SiteChat chat által használt tudásbázisba.
• A piszkozat és archivált termékek a következő újraépítéskor kizárásra kerülnek.
• Ha az indexelés ütemezése nem történt meg (index_status: "request_failed"), ismételd meg a batch kérést azoknál a termékeknél, amelyek már sikeresen eltárolódtak.

Milyen hibákra számíthatok?

A titkok 90 nap után lejárnak. Lejárat előtt hozz létre csereértéket a Settings → Store owner API secret részen, és vond vissza azokat a titkokat, amelyekre már nincs szükséged. Ugyanezzel a titokkal meghívhatók a Merchant API útmutatóban dokumentált analitikai, beszélgetési és tudásvégpontok is.

Ha segítségre van szükséged egy integrációval kapcsolatban, lépj kapcsolatba a Shoply AI-jal.