Sut i Uwchlwytho Eich Catalog ar gyfer SiteChat

Os ydych yn defnyddio SiteChat ar eich gwefan eich hun (nid siop Shopify), gallwch anfon cofnodion cynnyrch strwythuredig at Shoply fel y gall siopwyr ddod o hyd iddynt mewn sgwrs SiteChat a chwilio am gynnyrch.

Mae’r terfynbwyntiau hyn yn defnyddio’r un Settings → Store owner API secret â gweddill y Shoply Merchant API, a gall tudalen Product Catalog gweinyddol SiteChat eu galw gyda’ch tocyn mynediad gweinyddol wedi’i lofnodi i mewn. Mae siopau Shopify yn parhau i gysoni data catalog trwy Shopify; mae’r llwybrau uwchlwytho hyn ar gael yn unig ar gyfer cyfrifon SiteChat nad ydynt eisoes yn cysoni catalog Magento.

Yn y gweinyddwr SiteChat, mae Product Catalog yn agor ardal arddull Shopify gyda Products, Collections, ac Inventory. Gallwch ychwanegu neu olygu cynhyrchion, mewnforio CSV/Excel, grwpio cynhyrchion yn gasgliadau llaw, ac addasu meintiau stoc.

Pa APIs Sydd Ar Gael?

Mae cadw cynnyrch yn llwyddiannus yn gofyn i Shoply ailadeiladu mynegai’r siop. Hyd nes y bydd yr ailadeiladu hwnnw wedi gorffen, mae ymatebion yn adrodd index_status: "pending". Yna mae cynhyrchion cyhoeddedig yn ymddangos yn y mynegai cynnyrch ac yn y wybodaeth a ddefnyddir gan sgwrs SiteChat.

Pwy All Ddefnyddio’r APIs Hyn?

• Rhaid i’ch siop fod yn gyfrif SiteChat (app_platform yw SiteChat).
• Gwrthodir allweddi siop Shopify (gan gynnwys unrhyw barth *.myshopify.com).
• Rhaid i ddilysu ddefnyddio naill ai gyfrinach API perchennog siop ddilys neu docyn mynediad gweinyddol SiteChat ar gyfer yr union store_key yn y cais.
• Ni all tocynnau Shopify Admin API alw’r llwybrau hyn.

Crëwch neu cylchdrowch gyfrinach y perchennog yn yr un modd ag integreiddiadau eraill Merchant API: How to Use the Shoply Merchant API. Yn gonsol gweinyddol SiteChat, agorwch Product Catalog i reoli cynhyrchion, casgliadau, a rhestr eiddo—neu fewnforio ffeil CSV neu Excel—heb reoli’r gyfrinach eich hun.

Sut Mae Dilysu’n Gweithio?

O gysylltydd gweinydd

Galwch yr API o gefnwaith dibynadwy dros HTTPS. Rhowch linyn JSON yn yr pennawd Authorization:

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

store_owner_api_secrete yw enw’r maes cyhoeddus, gan gynnwys y sillafiad hanesyddol. Derbynnir store_owner_api_secret hefyd. Nid tocyn Bearer yw hwn.

O weinyddwr SiteChat

Mae tudalen Product Catalog yn anfon eich sesiwn gweinyddol wedi’i lofnodi i mewn yn lle hynny:

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

Derbynnir access_token fel alias ar gyfer admin_auth_token.

Rhaid i baramedr ymholiad store_key gyd-fynd â’r pennawd. Cadwch gyfrinachau perchennog mewn newidynnau amgylchedd ochr y gweinydd yn unig—byth mewn sgript storefront, URL, na storfa gyhoeddus.

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

Sut Ydw i’n Uwchlwytho Cynhyrchion?

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

Meysydd a rheolau gofynnol

• Meysydd cynnyrch gofynnol: external_id, title, url, currency, price, ac available. Mae status yn ddiofyn i published.
• Rhestr eiddo ddewisol: gosodwch tracks_inventory i true a quantity annegyddol ar y cynnyrch neu’r amrywiad. Yna mae Shoply yn deillio argaeledd o’r stoc (quantity > 0) ac yn storio total_inventory ar gyfer rhestrau gweinyddol.
• Mae source yn enwi’r cysylltiad catalog (nid llwyfan o reidrwydd). Defnyddiwch enw sefydlog fel woocommerce-main. Nodau a ganiateir: llythrennau bach, rhifau, tanlinellau, a chysylltnodau; hyd at 64 nod. Mae cynhyrchion a grëwyd drwy ffurflen yn y gweinyddwr yn ddiofyn i ffynhonnell admin.
• Hunaniaeth cynnyrch yw’r cyfuniad o siop, ffynhonnell, ac ID allanol. Mae upserts POST swp ac unigol yn amnewidiadau llawn, nid patches: caiff meysydd dewisol a hepgorwyd eu clirio. Defnyddiwch PATCH ar gyfer diweddariadau rhannol.
• Mae sypiau’n cynnwys 1–50 o gynhyrchion ac uchafswm o 2,000,000 o bytes cais. Mae JSON dilysedig pob cynnyrch wedi’i gyfyngu i 128,000 bytes, gydag uchafswm o 250 amrywiad.
• Mae’n well defnyddio llinynnau degol ar gyfer prisiau. Mae arian cyfred yn god tri llythyren priflythrennol.
• Rhaid i URLau cynnyrch a delwedd fod yn HTTP(S). Nid yw mewnforio yn nôl y URLau hynny i chi.
• Defnyddiwch metafields cyhoeddus ar gyfer manylebau cynnyrch chwiliadwy (cyfatebiaeth SiteChat i Shopify product metafields). Rhaid i werthoedd fod yn llinynnau plaen. Derbynnir attributes etifeddol fel alias hefyd. Nid yw metadata cynnyrch preifat yn cael ei gefnogi mwyach.
• Mae cynhyrchion draft ac archived yn cael eu hepgor o’r mynegai cyhoeddedig nesaf. Mae cynhyrchion cyhoeddedig sydd wedi gwerthu allan yn aros wedi’u mynegeio gyda gwybodaeth argaeledd ynghlwm.
• Mae casgliadau llaw yn storio teitl, disgrifiad, statws, a rhestr o aelodaeth cynnyrch (source + external_id). Nid yw casgliadau smart/seiliedig ar reolau yn cael eu cefnogi yn y fersiwn hon.

Ymateb llwyddiant enghreifftiol

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

Mae Shoply yn dilysu’r cais cyfan cyn ysgrifennu. Gall HTTP 200 restru rhai canlyniadau failed o hyd gyda error: "storage_error". Archwiliwch bob canlyniad ac ailgeisiwch gynhyrchion a fethodd. Os yw index_status yn request_failed, llwyddodd storio ond ni chafodd mynegeio ei drefnu—ailgeisiwch y cynhyrchion a storiwyd hefyd.

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

Sut Ydw i’n Dilysu Cynnyrch a Fewnforiwyd?

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

Defnyddiwch yr un pennawd Authorization. Mae’r ymateb yn cynnwys schema_version, updated_at, index_status, a’r product wedi’i normaleiddio. Mae cofnodion coll yn dychwelyd HTTP 404.

Ar ôl i’r mynegydd cefndir gyhoeddi ailadeiladu, daw statws darllen yn ôl fesul cynnyrch yn indexed, excluded (ar gyfer cynhyrchion drafft neu wedi’u harchifo), neu limit_exceeded. Defnyddiwch GET /merchant/products/list ar gyfer rhestru gweinyddol. Archifiwch yn feddal gyda DELETE /merchant/products (neu gosodwch status i archived / draft) i gadw cynnyrch allan o’r mynegai cyhoeddedig nesaf; nid oes dileu caled yn y fersiwn hon.

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

Sut Ydw i’n Diweddaru Amrywiadau neu Metafields yn Ddiogel?

Ar gyfer PATCH sy’n cynnwys variants, metafields, neu’r maes etifeddol attributes, darllenwch y cynnyrch yn gyntaf gyda GET. Adeiladwch y golygiad o’r ymateb hwnnw a chynhwyswch ei werth updated_at lefel uchaf fel expected_updated_at yng nghorff y PATCH. Mae hyn hefyd yn berthnasol wrth glirio amrywiadau neu 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()

Mae HTTP 409 yn golygu bod y fersiwn ar goll neu fod diweddariad arall wedi newid y cynnyrch. Darllenwch y cynnyrch diweddaraf ac uno’r newidiadau a fwriadwyd gennych eto cyn ailgeisio. Peidiwch ag atodi fersiwn newydd i hen restr amrywiadau: gallai hynny drosysgrifo gwerthoedd stoc mwy newydd.

Rhaid diweddaru integreiddiadau presennol sy’n PATCHio’r meysydd hyn heb fersiwn. Nid yw ceisiadau PATCH sy’n cynnwys sgalarau yn unig, addasiadau rhestr eiddo pwrpasol, ac amnewidiadau llawn trwy POST neu fewnforio swp yn gofyn am y maes hwn. Mae amnewidiadau llawn yn dal i amnewid y cynnyrch cyfan.

A Allaf Uwchlwytho Delweddau Cynnyrch?

Gallwch. Os yw delwedd eisoes ar gael mewn URL HTTPS cyhoeddus parhaol, rhowch y URL hwnnw yn rhestr images y cynnyrch neu faes image amrywiad. Mae URLau HTTPS S3 cyhoeddus yn gweithio. Nid yw llwybrau amrwd s3:// na URLau llofnodedig byrhoedlog yn gweithio.

I gael Shoply i letya’r ffeil, uwchlwythwch bytes delwedd amrwd o’ch backend:

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

Anfonwch bytes amrwd y ffeil, nid JSON, base64, na data ffurflen multipart. Derbynnir JPEG, PNG, a WebP, hyd at 10 MiB a 20 miliwn picsel. Nid yw delweddau animeiddiedig yn cael eu cefnogi. Mae Shoply yn trosi’r ddelwedd i WebP ac yn tynnu metadata wedi’i fewnosod.

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

Mae HTTP 201 yn dychwelyd url, content_type, size_bytes, width, ac height. Nid yw uwchlwytho delwedd ar ei phen ei hun yn ei hatodi at gynnyrch nac yn gofyn am fynegeio. Cynhwyswch y URL a ddychwelwyd mewn cynnyrch cyflawn a’i gyflwyno eto trwy /merchant/products/batch.

Mae’r un ddelwedd a uwchlwythir eto ar gyfer yr un cyfrif yn ailddefnyddio ei URL. Mae delwedd wedi’i newid yn derbyn URL newydd. Nid oes terfynbwynt dileu delwedd yn y fersiwn hon.

Pryd Mae Cynhyrchion yn Ymddangos mewn Sgwrs a Chwilio?

Ar ôl cadw swp yn llwyddiannus, mae Shoply yn gofyn am ailadeiladu mynegai cefndir. Mae ymatebion yn adrodd index_status: "pending" hyd nes y bydd y gweithiwr yn cyhoeddi’r mynegai newydd. Nid oes gwarant amser cwblhau sefydlog.

• Mae cynhyrchion cyhoeddedig yn mynd i mewn i chwiliad cynnyrch ac i’r wybodaeth a ddefnyddir gan sgwrs SiteChat.
• Caiff cynhyrchion drafft ac wedi’u harchifo eu heithrio yn yr ailadeiladu nesaf.
• Os na chafodd mynegeio ei drefnu (index_status: "request_failed"), ailgeisiwch y swp ar gyfer y cynhyrchion a storiwyd yn llwyddiannus eisoes.

Pa Wallau Ddylwn i’w Disgwyl?

Mae cyfrinachau’n dod i ben ar ôl 90 diwrnod. Crëwch un newydd yn Settings → Store owner API secret cyn iddo ddod i ben, a dirymwch unrhyw gyfrinach nad oes ei hangen arnoch mwyach. Gall yr un gyfrinach hefyd alw terfynbwyntiau dadansoddeg, sgwrs, a gwybodaeth a ddogfennir yn y Merchant API guide.

Am help gydag integreiddiad, cysylltwch â Shoply AI.