Hvernig á að hlaða vörulistanum þínum upp fyrir SiteChat

Ef þú notar SiteChat á þinni eigin vefsíðu (ekki Shopify-verslun) geturðu sent skipulagðar vörufærslur til Shoply svo viðskiptavinir geti fundið þær í SiteChat-spjalli og vöruleit.

Þessir endapunktar nota sama Settings → Store owner API secret og restin af Shoply Merchant API, og Product Catalog-síðan í SiteChat-stjórnun getur kallað á þá með innskráða stjórnandaaðgangslyklinum þínum. Shopify-verslanir halda áfram að samstilla vörulistagögn í gegnum Shopify; þessar upphleðsluleiðir eru aðeins í boði fyrir SiteChat-reikninga sem samstilla ekki nú þegar Magento-vörulista.

Í SiteChat-stjórnun opnar Product Catalog svæði í Shopify-stíl með Products, Collections og Inventory. Þú getur bætt við eða breytt vörum, flutt inn CSV/Excel, flokkað vörur í handvirk söfn og stillt birgðamagn.

Hvaða API eru í boði?

Þegar vörur vistast með árangri biður Shoply um að endurbyggja vísitölu verslunarinnar. Þar til þeirri endurbyggingu lýkur munu svör skila index_status: "pending". Birtaðar vörur birtast þá bæði í vörulista og í þeirri þekkingu sem SiteChat-spjallið notar.

Hverjir geta notað þessi API?

• Verslunin þín verður að vera SiteChat-reikningur (app_platform er SiteChat).
• Shopify-verslunarlyklum (þar á meðal hvaða *.myshopify.com léni sem er) er hafnað.
• Auðkenning verður að nota annaðhvort gildan API-leyndarlykil verslunareiganda eða SiteChat-aðgangslykil stjórnanda fyrir nákvæmlega þann store_key sem er í beiðninni.
• Shopify Admin API-lyklar geta ekki kallað á þessar leiðir.

Búðu til eða endurnýjaðu eigandalykilinn á sama hátt og fyrir aðrar Merchant API-samþættingar: How to Use the Shoply Merchant API. Í SiteChat-stjórnborðinu skaltu opna Product Catalog til að stýra vörum, söfnum og birgðum — eða flytja inn CSV- eða Excel-skrá — án þess að þurfa sjálf/ur að stýra leyndarlyklinum.

Hvernig virkar auðkenning?

Frá netþjónstengingu

Kallaðu á API frá traustum bakenda yfir HTTPS. Settu JSON-streng í Authorization-hausinn:

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

store_owner_api_secrete er opinbera heiti reitsins, þar á meðal sögulega stafsetningin. store_owner_api_secret er einnig samþykkt. Þetta er ekki Bearer-lykill.

Frá SiteChat-stjórnun

Product Catalog-síðan sendir í staðinn innskráða stjórnandalotuna þína:

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

access_token er samþykkt sem samheiti fyrir admin_auth_token.

Fyrirspurnarbreytan store_key verður að samsvara hausnum. Geymdu eigandalykla aðeins í umhverfisbreytum á netþjónshlið — aldrei í skriftu í verslunarglugga, slóð eða opinni kóðageymslu.

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

Hvernig hleð ég upp vörum?

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

Nauðsynlegir reitir og reglur

• Nauðsynlegir vörureitir: external_id, title, url, currency, price og available. status er sjálfgefið published.
• Valfrjáls birgðaskráning: stilltu tracks_inventory á true og óneikvætt quantity á vörunni eða afbrigði. Shoply leiðir þá framboð af birgðum (quantity > 0) og geymir total_inventory fyrir stjórnendalista.
• source nefnir tengingu vörulistans (ekki endilega kerfisvettvang). Notaðu stöðugt heiti eins og woocommerce-main. Leyfðir stafir: lágstafir, tölur, undirstrik og bandstrik; allt að 64 stafir. Vörur sem eru búnar til í stjórnun fá sjálfgefið source admin.
• Auðkenni vöru er samsetning verslunar, source og external ID. Batch- og stök POST upsert eru fullar yfirskriftir, ekki plástrar: slepptir valfrjálsir reitir eru hreinsaðir. Notaðu PATCH fyrir hlutauppfærslur.
• Hver batch inniheldur 1–50 vörur og mest 2.000.000 beiðnibæti. Staðfest JSON fyrir hverja vöru er takmarkað við 128.000 bæti, með mest 250 afbrigðum.
• Best er að nota tugabrotastrengi fyrir verð. Gjaldmiðill er þriggja stafa kóði með hástöfum.
• Vöru- og myndaslóðir verða að vera HTTP(S). Innflutningur sækir þessar slóðir ekki fyrir þig.
• Notaðu opinber metafields fyrir leitarhæfar vörulýsingar (hliðstæða SiteChat við Shopify product metafields). Gildi verða að vera venjulegir strengir. Eldri attributes er samþykkt sem samheiti. Einka-metadata á vöru er ekki lengur stutt.
• draft og archived vörur eru skildar eftir úr næstu birtu vísitölu. Uppseldar birtaðar vörur haldast í vísitölu með framboðsupplýsingum.
• Handvirk söfn geyma titil, lýsingu, stöðu og lista yfir aðild vara (source + external_id). Snjöll söfn / reglubundin söfn eru ekki studd í þessari útgáfu.

Dæmi um árangursríkt svar

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

Shoply staðfestir alla beiðnina áður en skrifað er. HTTP 200 getur samt talið upp einhverjar failed niðurstöður með error: "storage_error". Skoðaðu hverja niðurstöðu og reyndu aftur fyrir misheppnaðar vörur. Ef index_status er request_failed tókst geymslan en tímasetning fyrir vísitölusetningu var ekki sett upp — reyndu einnig aftur fyrir þær vörur sem voru vistaðar.

Python-dæmi

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

Hvernig staðfesti ég innflutta vöru?

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

Notaðu sama Authorization-haus. Svarið inniheldur schema_version, updated_at, index_status og staðlaða product. Færslur sem vantar skila HTTP 404.

Eftir að bakgrunnsvísitölusetjari birtir endurbyggingu verður staða lestrar á hverri vöru indexed, excluded (fyrir draft eða archived vörur) eða limit_exceeded. Notaðu GET /merchant/products/list fyrir stjórnendalista. Notaðu mjúka vörslu með DELETE /merchant/products (eða stilltu status á archived / draft) til að halda vöru utan næstu birtu vísitölu; hörð eyðing er ekki í boði í þessari útgáfu.

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

Hvernig uppfæri ég afbrigði eða metafields á öruggan hátt?

Fyrir PATCH sem inniheldur variants, metafields eða gamla attributes-reitinn skaltu fyrst lesa vöruna með GET. Byggðu breytinguna út frá því svari og láttu efsta updated_at-gildi þess fylgja sem expected_updated_at í PATCH-meginmálinu. Þetta á einnig við þegar verið er að hreinsa afbrigði eða metafields.

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 þýðir að útgáfuna vantaði eða að önnur uppfærsla breytti vörunni. Lestu nýjustu vöruna og sameinaðu fyrirhugaðar breytingar aftur áður en þú reynir á ný. Ekki hengja nýja útgáfu við gamlan afbrigðalista: það gæti yfirskrifað nýrri birgðagildi.

Núverandi samþættingar sem PATCH-a þessa reiti án útgáfu þurfa að vera uppfærðar. PATCH-beiðnir sem aðeins breyta scalar-gildum, sértækar birgðaleiðréttingar og fullar yfirskriftir í gegnum POST eða batch-innflutning krefjast ekki þessa reits. Fullar yfirskriftir skipta þó samt út allri vörunni.

Get ég hlaðið upp vörumyndum?

Já. Ef mynd er þegar tiltæk á varanlegri opinberri HTTPS-slóð skaltu setja þá slóð í images-lista vörunnar eða image-reit afbrigðis. Opinberar S3 HTTPS-slóðir virka. Hreinar s3://-slóðir og skammlífar undirritaðar slóðir gera það ekki.

Til að láta Shoply hýsa skrána skaltu hlaða upp hráum myndabætum frá bakendanum þínum:

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

Sendu hrá skráarbæti, ekki JSON, base64 eða multipart form data. JPEG, PNG og WebP eru samþykkt, allt að 10 MiB og 20 milljón pixlar. Hreyfimyndir eru ekki studdar. Shoply umbreytir myndinni í WebP og fjarlægir innfelld lýsigögn.

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 skilar url, content_type, size_bytes, width og height. Að hlaða upp mynd einni og sér tengir hana ekki við vöru né biður um vísitölusetningu. Settu skilaða slóð inn í fullkomna vöru og sendu hana aftur í gegnum /merchant/products/batch.

Ef sama mynd er hlaðin upp aftur fyrir sama reikning er sama slóð endurnotuð. Breytt mynd fær nýja slóð. Það er enginn endapunktur til að eyða myndum í þessari útgáfu.

Hvenær birtast vörur í spjalli og leit?

Eftir árangursríka batch-vistun biður Shoply um endurbyggingu vísitölu í bakgrunni. Svör skila index_status: "pending" þar til vinnsluþráðurinn birtir nýju vísitöluna. Það er engin föst trygging fyrir lokatíma.

• Birtaðar vörur fara bæði í vöruleit og í þá þekkingu sem SiteChat-spjallið notar.
• Draft og archived vörur eru útilokaðar við næstu endurbyggingu.
• Ef vísitölusetning var ekki tímasett (index_status: "request_failed") skaltu reyna batch aftur fyrir þær vörur sem þegar voru vistaðar með árangri.

Hvaða villum ætti ég að búast við?

Leyndarlyklar renna út eftir 90 daga. Búðu til nýjan í Settings → Store owner API secret áður en gildistíminn rennur út og afturkallaðu alla lykla sem þú þarft ekki lengur. Sami leyndarlykill getur einnig kallað á endapunkta fyrir greiningar, samtöl og þekkingu sem skráðir eru í Merchant API guide.

Til að fá hjálp með samþættingu, hafðu samband við Shoply AI.