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

Ef þú notar SiteChat á eigin vefsíðu (ekki í Shopify-verslun) geturðu sent skipulögð vörugögn til Shoply svo kaupendur geti fundið þau í 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órnborðinu getur kallað á þá með innskráðu aðgangsauðkenni stjórnanda. Shopify-verslanir halda áfram að samstilla vörulistagögn í gegnum Shopify; þessar upphleðsluleiðir eru aðeins í boði fyrir SiteChat-aðganga sem samstilla ekki nú þegar Magento-vörulista.

Í SiteChat-stjórnborðinu 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 breytt birgðamagni.

Hvaða API eru í boði?

Þegar vara vistast með góðum á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 síðan bæði í vörulistavísitölunni og í þekkingunni sem SiteChat-spjallið notar.

Hverjir geta notað þessi API?

• Verslunin þín verður að vera SiteChat-aðgangur (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ðgangsauðkenni stjórnanda fyrir nákvæmlega það store_key sem er í beiðninni.
• Shopify Admin API-auðkenni geta ekki kallað á þessar leiðir.

Búðu til eða endurnýjaðu eigandalykilorðið á sama hátt og fyrir aðrar Merchant API-tengingar: How to Use the Shoply Merchant API. Í SiteChat-stjórnborðinu geturðu opnað Product Catalog til að stjórna vörum, söfnum og birgðum—eða flutt inn CSV- eða Excel-skrá—án þess að þurfa sjálf(ur) að stjórna leyndarlyklinum.

Hvernig virkar auðkenning?

Frá bakendaþjónustu

Kallaðu á API-ið 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ð talið söguleg stafsetning. store_owner_api_secret er einnig samþykkt. Þetta er ekki Bearer-auðkenni.

Frá SiteChat-stjórnborðinu

Síðan Product Catalog 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ð passa við hausinn. Geymdu eigandalykla aðeins í umhverfisbreytum á netþjóni—aldrei í skriftu á verslunarsíðu, slóð eða opinberu kóðasafni.

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álsar birgðir: stilltu tracks_inventory á true og ótöluneikvætt quantity á vörunni eða afbrigði hennar. Þá leiðir Shoply framboð af birgðum (quantity > 0) og geymir total_inventory fyrir stjórnendalista.
• source nefnir tengingu vörulista (ekki endilega vettvang). Notaðu stöðugt heiti eins og woocommerce-main. Leyfilegir stafir: lágstafir, tölur, undirstrik og bandstrik; allt að 64 stafir. Vörur sem eru búnar til í stjórnborðinu fá sjálfgefið source gildið admin.
• Auðkenni vöru er samsetning af verslun, source og external ID. Batch- og stök POST upsert eru algjörar skiptingar út, ekki plástranir: valfrjálsir reitir sem vantar eru hreinsaðir. Notaðu PATCH fyrir hlutauppfærslur.
• Hópar innihalda 1–50 vörur og mest 2.000.000 bæti í beiðni. Staðfest JSON fyrir hverja vöru er takmarkað við 128.000 bæti, með að hámarki 250 afbrigðum.
• Best er að nota tugastrengi fyrir verð. Gjaldmiðill er þriggja stafa hástafakóði.
• Slóðir fyrir vörur og myndir verða að vera HTTP(S). Innflutningur sækir þessar slóðir ekki sjálfkrafa fyrir þig.
• Notaðu opinber metafields fyrir leitarhæfar vörulýsingar (samsvörun SiteChat við Shopify product metafields). Gildi verða að vera einfaldir strengir. Eldra attributes er samþykkt sem samheiti. Einka metadata fyrir vörur er ekki lengur stutt.
• draft og archived vörur eru skildar út úr næstu birtu vísitölu. Uppseldar birtaðar vörur haldast í vísitölunni með upplýsingum um framboð.
• Handvirk söfn geyma titil, lýsingu, stöðu og lista yfir aðild vara (source + external_id). Snjöll söfn/safnreglur 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 innihaldið einhverjar failed niðurstöður með error: "storage_error". Skoðaðu hverja niðurstöðu og reyndu aftur fyrir vörur sem mistókust. Ef index_status er request_failed tókst vistun en tímasetning á vísitölun var ekki sett af stað—reyndu einnig aftur fyrir vörurnar 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. Vantar færslur skila HTTP 404.

Eftir að bakgrunnsvísitölun birtir endurbyggingu verður staða upplestrar fyrir hverja vöru indexed, excluded (fyrir drög eða geymsluvörur) eða limit_exceeded. Notaðu GET /merchant/products/list fyrir stjórnendalista. Mjúk-setsafnaðu 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"])

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

Já. Ef mynd er þegar aðgengileg á varanlegri opinberri HTTPS-slóð skaltu setja þá slóð í images lista vörunnar eða í image reit afbrigðis. Opinberar S3 HTTPS-slóðir virka. Hráar 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 myndbætum úr 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ð eitt að hlaða upp mynd tengir hana ekki við vöru né biður um vísitölun. Settu skilaða slóð inn í fullbúna vöru og sendu hana aftur í gegnum /merchant/products/batch.

Sama mynd sem er hlaðið upp aftur fyrir sama aðgang endurnýtir slóðina sína. 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 að hópvistun tekst biður Shoply um endurbyggingu vísitölu í bakgrunni. Svör skila index_status: "pending" þar til vinnsluferlið 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 í þekkinguna sem SiteChat-spjallið notar.
• Drög og geymsluvörur eru útilokaðar í næstu endurbyggingu.
• Ef vísitölun var ekki tímasett (index_status: "request_failed"), reyndu aftur hópinn fyrir vörurnar sem höfðu þegar vistast með góðum árangri.

Hvaða villur má ég búast við?

Leyndarlyklar renna út eftir 90 daga. Búðu til nýjan lykil í Settings → Store owner API secret áður en gildistími rennur út, og afturkallaðu alla lykla sem þú þarft ekki lengur. Sami lykill getur einnig kallað á greiningar-, samtals- og þekkingarendapunkta sem skjalfestir eru í Merchant API guide.

Fyrir aðstoð við tengingu, hafðu samband við Shoply AI.