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 eu canfod mewn sgwrs SiteChat ac wrth chwilio am gynhyrchion.

Mae’r pwyntiau terfyn 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 pan fyddwch wedi mewngofnodi. Mae siopau Shopify yn parhau i gydamseru data catalog drwy Shopify; mae’r llwybrau uwchlwytho hyn ar gael yn unig ar gyfer cyfrifon SiteChat nad ydynt eisoes yn cydamseru catalog Magento.

Yn y gweinyddiaeth 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 cadwadau cynnyrch llwyddiannus yn gofyn i Shoply ailadeiladu mynegai’r siop. Hyd nes y bydd yr ailadeiladu hwnnw wedi gorffen, mae’r 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 ffordd ag integreiddiadau Merchant API eraill: How to Use the Shoply Merchant API. Yn nghonsol gweinyddol SiteChat, agorwch Product Catalog i reoli cynhyrchion, casgliadau, a rhestr stoc—neu fewnforio ffeil CSV neu Excel—heb orfod rheoli’r gyfrinach eich hun.

Sut Mae Dilysu’n Gweithio?

O gysylltydd gweinydd

Galwch yr API o ôl-ben dibynadwy dros HTTPS. Rhowch linyn JSON yn y 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 weinyddiaeth SiteChat

Mae tudalen Product Catalog yn anfon eich sesiwn gweinyddol mewngofnodedig 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’r paramedr ymholiad store_key gyd-fynd â’r pennawd. Cadwch gyfrinachau perchennog mewn newidynnau amgylchedd ochr-gweinydd yn unig—byth mewn sgript siop flaen, URL, neu gadwrfa 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 rhagosod i published.
• Rhestr stoc ddewisol: gosodwch tracks_inventory i true a quantity nad yw’n negatif 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 o reidrwydd platfform). Defnyddiwch enw sefydlog fel woocommerce-main. Nodau a ganiateir: llythrennau bach, rhifau, tanlinellau, a chysylltnodau; hyd at 64 nod. Mae cynhyrchion a grëir drwy ffurflen yn y weinyddiaeth yn rhagosod i source admin.
• Hunaniaeth cynnyrch yw’r cyfuniad o siop, source, ac ID allanol. Mae upsert POST sengl a swp yn ddisodliadau llawn, nid patsys: mae meysydd dewisol a hepgorir yn cael eu clirio. Defnyddiwch PATCH ar gyfer diweddariadau rhannol.
• Mae swpiau’n cynnwys 1–50 cynnyrch ac ar y mwyaf 2,000,000 beit cais. Mae JSON dilysedig pob cynnyrch wedi’i gyfyngu i 128,000 beit, gydag uchafswm o 250 amrywiad.
• Ffafriwch linynnau degol ar gyfer prisiau. Mae arian cyfred yn god priflythyren tair llythyren.
• Rhaid i URLau cynnyrch a delweddau 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 fetafields cynnyrch Shopify). 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 gadael allan 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 clyfar/seiliedig ar reolau yn cael eu cefnogi yn y datganiad hwn.

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 ddal i restru rhai canlyniadau failed gyda error: "storage_error". Archwiliwch bob canlyniad ac ailgeisiwch y cynhyrchion a fethodd. Os yw index_status yn request_failed, llwyddodd y storio ond ni drefnwyd mynegeio—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 Gwirio 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 mynegeiwr 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. Archifwch yn feddal gyda DELETE /merchant/products (neu gosod status i archived / draft) i gadw cynnyrch allan o’r mynegai cyhoeddedig nesaf; nid oes dileu caled yn y datganiad hwn.

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

A Allaf Uwchlwytho Delweddau Cynnyrch?

Gallwch. Os yw delwedd eisoes ar gael ar URL HTTPS cyhoeddus parhaol, rhowch y URL hwnnw yn rhestr images y cynnyrch neu ym maes image amrywiad. Mae URLau HTTPS S3 cyhoeddus yn gweithio. Nid yw llwybrau amrwd s3:// a URLau wedi’u llofnodi byrhoedlog yn gweithio.

Er mwyn i Shoply gynnal y ffeil, uwchlwythwch feitiau delwedd amrwd o’ch ôl-ben:

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

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

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 i gynnyrch nac yn gofyn am fynegeio. Cynhwyswch y URL a ddychwelwyd mewn cynnyrch cyflawn a’i gyflwyno eto drwy /merchant/products/batch.

Mae’r un ddelwedd a uwchlwythir eto ar gyfer yr un cyfrif yn ailddefnyddio ei URL. Mae delwedd a newidiwyd yn derbyn URL newydd. Nid oes pwynt terfyn dileu delwedd yn y datganiad hwn.

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" nes i’r gweithiwr gyhoeddi’r mynegai newydd. Nid oes gwarant amser cwblhau sefydlog.

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

Pa Wallau Ddylwn i eu Disgwyl?

Mae cyfrinachau’n dod i ben ar ôl 90 diwrnod. Crëwch ddisodlydd 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 pwyntiau terfyn dadansoddeg, sgyrsiau, a gwybodaeth sydd wedi’u dogfennu yn y Merchant API guide.

Am gymorth gydag integreiddiad, cysylltwch â Shoply AI.