Conas Do Chatalóg a Uaslódáil do SiteChat

Má úsáideann tú SiteChat ar do shuíomh gréasáin féin (ní siopa Shopify é), is féidir leat taifid táirge struchtúrtha a sheoladh chuig Shoply ionas gur féidir le siopadóirí iad a aimsiú i gcomhrá SiteChat agus i gcuardach táirgí.

Úsáideann na críochphointí seo an Settings → Store owner API secret céanna leis an gcuid eile den Shoply Merchant API, agus is féidir le leathanach Product Catalog i riarachán SiteChat glaoch orthu le do thócan rochtana riarthóra agus tú sínithe isteach. Leanann siopaí Shopify ag sioncronú sonraí catalóige trí Shopify; níl na bealaí uaslódála seo ar fáil ach do chuntais SiteChat nach bhfuil catalóg Magento á sioncronú acu cheana féin.

I riarachán SiteChat, osclaíonn Product Catalog limistéar i stíl Shopify le Products, Collections, agus Inventory. Is féidir leat táirgí a chur leis nó a chur in eagar, CSV/Excel a iompórtáil, táirgí a ghrúpáil i mbailiúcháin láimhe, agus cainníochtaí stoic a choigeartú.

Cad iad na hAPIanna atá ar fáil?

Iarrann sábhálacha táirge rathúla ar Shoply innéacs an tsiopa a atógáil. Go dtí go gcríochnaíonn an t-atógáil sin, tuairiscíonn freagraí index_status: "pending". Ansin feictear táirgí foilsithe san innéacs táirgí agus san eolas a úsáideann comhrá SiteChat araon.

Cé atá in ann na hAPIanna seo a úsáid?

• Caithfidh do shiopa a bheith ina chuntas SiteChat (app_platform is SiteChat).
• Diúltaítear eochracha siopa Shopify (lena n-áirítear aon fhearann *.myshopify.com).
• Caithfidh fíordheimhniú rún API úinéara siopa bailí nó tócan rochtana riarthóra SiteChat a úsáid don store_key beacht san iarratas.
• Ní féidir le tócain Shopify Admin API glaoch ar na bealaí seo.

Cruthaigh nó rothlaigh rún an úinéara ar an mbealach céanna le comhtháthuithe Merchant API eile: Conas an Shoply Merchant API a Úsáid. I gconsól riaracháin SiteChat, oscail Product Catalog chun táirgí, bailiúcháin, agus fardal a bhainistiú—nó chun comhad CSV nó Excel a iompórtáil—gan an rún a bhainistiú tú féin.

Conas a Oibríonn an Fíordheimhniú?

Ó chónascaire freastalaí

Glaoigh ar an API ó backend iontaofa thar HTTPS. Cuir teaghrán JSON sa cheanntásc Authorization:

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

Is é store_owner_api_secrete ainm an réimse phoiblí, lena n-áirítear an litriú stairiúil. Glactar le store_owner_api_secret freisin. Ní tócan Bearer é seo.

Ó riarachán SiteChat

Seolann an leathanach Product Catalog do sheisiún riarthóra sínithe isteach ina ionad:

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

Glactar le access_token mar ailias ar admin_auth_token.

Caithfidh paraiméadar ceiste store_key an cheanntáisc a mheaitseáil. Coinnigh rúin úinéara in athróga timpeallachta ar thaobh an fhreastalaí amháin—ná cuir riamh iad i script storefront, i URL, ná i stór poiblí.

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

Conas a Uaslódálaim Táirgí?

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

Réimsí riachtanacha agus rialacha

• Réimsí táirge riachtanacha: external_id, title, url, currency, price, agus available. Is é published an réamhshocrú do status.
• Fardal roghnach: socraigh tracks_inventory go true agus quantity neamh‑dhiúltach ar an táirge nó ar an variant. Ansin díorthaíonn Shoply infhaighteacht ón stoc (quantity > 0) agus stórálann sé total_inventory do liostaí riaracháin.
• Ainmníonn source an nasc catalóige (ní gá gur ardán é). Úsáid ainm cobhsaí mar woocommerce-main. Carachtair cheadaithe: litreacha beaga, uimhreacha, fo-línte, agus fleiscíní; suas le 64 carachtar. Is é admin an source réamhshocraithe do tháirgí a chruthaítear i bhfoirm sa riarachán.
• Is é comhcheangal siopa, source, agus external ID aitheantas an táirge. Is athsholáthair iomlána iad upserts POST bhaisc agus aonair, ní paistí iad: glantar réimsí roghnacha a fhágtar ar lár. Úsáid PATCH le haghaidh nuashonruithe páirteacha.
• Tá idir 1 agus 50 táirge i mbaisceanna agus uasmhéid 2,000,000 beart iarratais. Tá JSON bailíochtaithe gach táirge teoranta do 128,000 beart, le huasmhéid 250 variants.
• Is fearr teaghráin dheachúlacha do phraghsanna. Is cód trí litir i gceannlitreacha é airgeadra.
• Caithfidh URLanna táirge agus íomhá a bheith ina HTTP(S). Ní dhéanann an iompórtáil na URLanna sin a fháil duit.
• Úsáid metafields poiblí le haghaidh sonraíochtaí táirge inchuardaithe (comhfhreagrach SiteChat do Shopify product metafields). Caithfidh na luachanna a bheith ina ngnáth-theaghráin. Glactar leis an seanréimse attributes mar ailias freisin. Ní thacaítear a thuilleadh le metadata príobháideach táirge.
• Fágtar táirgí draft agus archived amach as an gcéad innéacs foilsithe eile. Fanann táirgí foilsithe atá díolta amach innéacsaithe agus faisnéis infhaighteachta ceangailte leo.
• Stórálann bailiúcháin láimhe teideal, cur síos, stádas, agus liosta de bhallraíochtaí táirge (source + external_id). Ní thacaítear le bailiúcháin chliste/bhunaithe ar rialacha sa leagan seo.

Sampla freagartha ratha

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

Bailíochtaíonn Shoply an t-iarratas iomlán sula scríobhann sé. Is féidir le HTTP 200 roinnt torthaí failed a liostú fós le error: "storage_error". Scrúdaigh gach toradh agus déan iarracht eile ar na táirgí ar theip orthu. Más é request_failed atá in index_status, d’éirigh leis an stóráil ach níor sceidealaíodh an t-innéacsú—déan iarracht eile ar na táirgí stóráilte sin freisin.

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

Conas a Fhíoraím Táirge Iompórtáilte?

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

Úsáid an ceanntásc Authorization céanna. Áirítear sa fhreagra schema_version, updated_at, index_status, agus an product normalaithe. Filleann taifid atá ar iarraidh HTTP 404.

Tar éis don innéacsóir cúlra atógáil a fhoilsiú, éiríonn stádas in aghaidh an táirge sa léamh siar mar indexed, excluded (do tháirgí draft nó archived), nó limit_exceeded. Úsáid GET /merchant/products/list le haghaidh liostú riaracháin. Cuir i gcartlann bhog le DELETE /merchant/products (nó socraigh status go archived / draft) chun táirge a choinneáil amach as an gcéad innéacs foilsithe eile; níl aon scriosadh crua sa leagan seo.

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

Conas is Féidir Liom Variants nó Metafields a Nuashonrú go Sábháilte?

Le haghaidh PATCH ina bhfuil variants, metafields, nó an seanréimse attributes, léigh an táirge ar dtús le GET. Tóg an t-athrú ón bhfreagra sin agus cuir a luach barrleibhéil updated_at san áireamh mar expected_updated_at i gcorp an PATCH. Baineann sé seo freisin le variants nó metafields a ghlanadh.

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

Ciallaíonn HTTP 409 go raibh an leagan ar iarraidh nó gur athraigh nuashonrú eile an táirge. Léigh an táirge is déanaí agus cumaisc na hathruithe a bhí beartaithe agat arís sula ndéanann tú iarracht eile. Ná ceangail leagan nua le seanliosta variants: d’fhéadfadh sé sin luachanna stoic níos nuaí a fhorscríobh.

Ní mór comhtháthuithe atá ann cheana a dhéanann PATCH ar na réimsí seo gan leagan a nuashonrú. Ní theastaíonn an réimse seo ó iarratais PATCH ar scálairí amháin, ó choigeartuithe fardail tiomnaithe, ná ó athsholáthair iomlána trí POST nó iompórtáil bhaisc. Cuireann athsholáthair iomlána an táirge iomlán in ionad fós.

An Féidir Liom Íomhánna Táirge a Uaslódáil?

Is féidir. Má tá íomhá ar fáil cheana ag URL HTTPS poiblí marthanach, cuir an URL sin i liosta images an táirge nó i réimse image variant. Oibríonn URLanna HTTPS poiblí S3. Ní oibríonn cosáin amh s3:// ná URLanna sínithe gearrshaolacha.

Chun go n-óstálfaidh Shoply an comhad, uaslódáil bearta amh na híomhá ó do backend:

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

Seol bearta amh an chomhaid, ní JSON, base64, ná sonraí foirme multipart. Glactar le JPEG, PNG, agus WebP, suas le 10 MiB agus 20 milliún picteilín. Ní thacaítear le híomhánna beoite. Tiontaíonn Shoply an íomhá go WebP agus baineann sé meiteashonraí leabaithe.

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

Filleann HTTP 201 url, content_type, size_bytes, width, agus height. Ní cheanglaíonn uaslódáil íomhá amháin í le táirge ná ní iarrann sí innéacsú. Cuir an URL a filleadh san áireamh i dtáirge iomlán agus cuir isteach arís é trí /merchant/products/batch.

Má uaslódáiltear an íomhá chéanna arís don chuntas céanna, athúsáidtear a URL. Faigheann íomhá athraithe URL nua. Níl críochphointe scriosta íomhá sa leagan seo.

Cathain a Fheictear Táirgí i gComhrá agus i gCuardach?

Tar éis sábháil bhaisc rathúil, iarrann Shoply atógáil innéacs cúlra. Tuairiscíonn freagraí index_status: "pending" go dtí go bhfoilseoidh an worker an t-innéacs nua. Níl aon ráthaíocht ama chríochnaithe sheasta ann.

• Téann táirgí foilsithe isteach i gcuardach táirgí agus san eolas a úsáideann comhrá SiteChat araon.
• Fágtar táirgí draft agus archived ar lár ag an gcéad atógáil eile.
• Murar sceidealaíodh an t-innéacsú (index_status: "request_failed"), déan iarracht eile ar an mbaisc do na táirgí a stóráladh go rathúil cheana féin.

Cad iad na hEarráidí ar Chóir Dom a Bheith ag Súil Leo?

Téann rúin in éag tar éis 90 lá. Cruthaigh ceann athsholáthair in Settings → Store owner API secret sula rachaidh sé in éag, agus cúlghair aon rún nach bhfuil uait a thuilleadh. Is féidir leis an rún céanna glaoch freisin ar chríochphointí anailíse, comhráite, agus eolais atá doiciméadaithe sa treoir Merchant API.

Le cúnamh maidir le comhtháthú, déan teagmháil le Shoply AI.