Kā augšupielādēt savu katalogu SiteChat vajadzībām

Ja izmantojat SiteChat savā vietnē (nevis Shopify veikalā), varat sūtīt strukturētus produktu ierakstus uz Shoply, lai pircēji tos varētu atrast SiteChat tērzēšanā un produktu meklēšanā.

Šie galapunkti izmanto to pašu Settings → Store owner API secret kā pārējais Shoply Merchant API, un SiteChat administratora Product Catalog lapa var tos izsaukt ar jūsu pieteiktā administratora piekļuves tokenu. Shopify veikali turpina sinhronizēt kataloga datus caur Shopify; šie augšupielādes maršruti ir pieejami tikai SiteChat kontiem, kas vēl nesinhronizē Magento katalogu.

SiteChat administratora panelī Product Catalog atver Shopify stilam līdzīgu sadaļu ar Products, Collections un Inventory. Jūs varat pievienot vai rediģēt produktus, importēt CSV/Excel, grupēt produktus manuālās kolekcijās un pielāgot krājumu daudzumus.

Kādas API ir pieejamas?

Veiksmīga produktu saglabāšana liek Shoply pārbūvēt veikala indeksu. Kamēr šī pārbūve nav pabeigta, atbildes ziņo index_status: "pending". Pēc tam publicētie produkti parādās gan produktu indeksā, gan zināšanās, ko izmanto SiteChat tērzēšana.

Kas var izmantot šīs API?

• Jūsu veikalam jābūt SiteChat kontam (app_platform ir SiteChat).
• Shopify veikalu atslēgas (ieskaitot jebkuru *.myshopify.com domēnu) tiek noraidītas.
• Autentifikācijai jāizmanto vai nu derīga veikala īpašnieka API slepenā atslēga, vai SiteChat administratora piekļuves tokens tieši tam store_key, kas norādīts pieprasījumā.
• Shopify Admin API tokeni nevar izsaukt šos maršrutus.

Izveidojiet vai nomainiet īpašnieka slepeno atslēgu tāpat kā citām Merchant API integrācijām: Kā izmantot Shoply Merchant API. SiteChat administratora konsolē atveriet Product Catalog, lai pārvaldītu produktus, kolekcijas un krājumus — vai importētu CSV vai Excel failu — bez nepieciešamības pašiem pārvaldīt slepeno atslēgu.

Kā darbojas autentifikācija?

No servera savienotāja

Izsauciet API no uzticama backend caur HTTPS. Ievietojiet JSON virkni Authorization galvenē:

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

store_owner_api_secrete ir publiskais lauka nosaukums, ieskaitot vēsturisko rakstību. Tiek pieņemts arī store_owner_api_secret. Tas nav Bearer tokens.

No SiteChat administratora paneļa

Product Catalog lapa tā vietā nosūta jūsu pieteikto administratora sesiju:

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

access_token tiek pieņemts kā admin_auth_token alias.

Vaicājuma parametrs store_key jāsakrīt ar galveni. Glabājiet īpašnieka slepenās atslēgas tikai servera puses vides mainīgajos — nekad veikala frontend skriptā, URL vai publiskā repozitorijā.

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

Kā augšupielādēt produktus?

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

Obligātie lauki un noteikumi

• Obligātie produkta lauki: external_id, title, url, currency, price un available. status pēc noklusējuma ir published.
• Neobligāts krājumu atbalsts: iestatiet tracks_inventory uz true un nenegatīvu quantity produktam vai variantam. Tad Shoply atvasina pieejamību no krājuma (quantity > 0) un saglabā total_inventory administratora sarakstiem.
• source nosauc kataloga savienojumu (ne obligāti platformu). Izmantojiet stabilu nosaukumu, piemēram, woocommerce-main. Atļautās rakstzīmes: mazie burti, cipari, pasvītras un defises; līdz 64 rakstzīmēm. Administratora panelī izveidotajiem produktiem pēc noklusējuma ir source admin.
• Produkta identitāte ir veikala, source un external ID kombinācija. Batch un atsevišķi POST upsert pieprasījumi ir pilnīgas aizvietošanas, nevis ielāpi: izlaistie neobligātie lauki tiek notīrīti. Daļējiem atjauninājumiem izmantojiet PATCH.
• Batch satur 1–50 produktus un ne vairāk kā 2 000 000 pieprasījuma baitus. Katra produkta validētais JSON ir ierobežots līdz 128 000 baitiem, ar ne vairāk kā 250 variantiem.
• Cenām ieteicams izmantot decimālas virknes. Valūtai jābūt trīs burtu lielo burtu kodam.
• Produktu un attēlu URL jābūt HTTP(S). Importēšana šos URL jūsu vietā neielādē.
• Izmantojiet publiskos metafields meklējamiem produktu parametriem (SiteChat analogs Shopify produktu metafields). Vērtībām jābūt vienkāršām virknēm. Mantotais attributes tiek pieņemts kā alias. Privāts produkta metadata vairs netiek atbalstīts.
• draft un archived produkti nākamajā publicētajā indeksā netiek iekļauti. Izpārdoti publicēti produkti paliek indeksēti ar pievienotu pieejamības informāciju.
• Manuālajās kolekcijās tiek glabāts virsraksts, apraksts, statuss un produktu dalības saraksts (source + external_id). Viedās/uz noteikumiem balstītās kolekcijas šajā laidienā netiek atbalstītas.

Veiksmīgas atbildes piemērs

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

Shoply validē visu pieprasījumu pirms ierakstīšanas. HTTP 200 joprojām var uzrādīt dažus failed rezultātus ar error: "storage_error". Pārbaudiet katru rezultātu un atkārtoti mēģiniet neveiksmīgos produktus. Ja index_status ir request_failed, glabāšana izdevās, bet indeksēšana netika ieplānota — atkārtoti mēģiniet arī jau saglabātos produktus.

Python piemērs

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

Kā pārbaudīt importētu produktu?

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

Izmantojiet to pašu Authorization galveni. Atbilde ietver schema_version, updated_at, index_status un normalizēto product. Trūkstoši ieraksti atgriež HTTP 404.

Pēc tam, kad fona indeksētājs publicē pārbūvi, katra produkta nolasīšanas statuss kļūst par indexed, excluded (draft vai archived produktiem) vai limit_exceeded. Administratora sarakstam izmantojiet GET /merchant/products/list. Mīksti arhivējiet ar DELETE /merchant/products (vai iestatiet status uz archived / draft), lai produkts neparādītos nākamajā publicētajā indeksā; šajā laidienā cietā dzēšana nav pieejama.

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

Kā droši atjaunināt variantus vai metafields?

Ja PATCH satur variants, metafields vai mantoto attributes lauku, vispirms nolasiet produktu ar GET. Izveidojiet labojumu no šīs atbildes un iekļaujiet tās augšējā līmeņa updated_at vērtību kā expected_updated_at PATCH pamattekstā. Tas attiecas arī uz variantu vai metafields notīrīšanu.

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 nozīmē, ka versija trūka vai cits atjauninājums izmainīja produktu. Nolasiet jaunāko produktu un pirms atkārtota mēģinājuma vēlreiz apvienojiet savas paredzētās izmaiņas. Nepievienojiet jaunu versiju vecam variantu sarakstam: tas var pārrakstīt jaunākas krājumu vērtības.

Esošās integrācijas, kas veic PATCH šiem laukiem bez versijas, ir jāatjaunina. PATCH pieprasījumiem tikai ar skalāriem laukiem, īpašām krājumu korekcijām un pilnīgām aizvietošanām caur POST vai batch importu šis lauks nav vajadzīgs. Pilnīgas aizvietošanas joprojām aizvieto visu produktu.

Vai varu augšupielādēt produktu attēlus?

Jā. Ja attēls jau ir pieejams pastāvīgā publiskā HTTPS URL, ievietojiet šo URL produkta images sarakstā vai varianta image laukā. Publiski S3 HTTPS URL darbojas. Neapstrādāti s3:// ceļi un īslaicīgi parakstīti URL neder.

Lai Shoply mitinātu failu, augšupielādējiet neapstrādātus attēla baitus no sava backend:

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

Sūtiet neapstrādātus faila baitus, nevis JSON, base64 vai multipart form datus. Tiek pieņemti JPEG, PNG un WebP formāti, līdz 10 MiB un 20 miljoniem pikseļu. Animēti attēli netiek atbalstīti. Shoply pārveido attēlu uz WebP un noņem iegultos metadatus.

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 atgriež url, content_type, size_bytes, width un height. Tikai attēla augšupielāde to nepiesaista produktam un nepieprasa indeksēšanu. Iekļaujiet atgriezto URL pilnā produktā un iesniedziet to vēlreiz caur /merchant/products/batch.

Tas pats attēls, augšupielādēts vēlreiz tam pašam kontam, atkārtoti izmanto savu URL. Izmainīts attēls saņem jaunu URL. Šajā laidienā nav attēlu dzēšanas galapunkta.

Kad produkti parādās tērzēšanā un meklēšanā?

Pēc veiksmīgas batch saglabāšanas Shoply pieprasa fona indeksa pārbūvi. Atbildes ziņo index_status: "pending", līdz darbinieks publicē jauno indeksu. Nav fiksētas pabeigšanas laika garantijas.

• Publicētie produkti nonāk gan produktu meklēšanā, gan zināšanās, ko izmanto SiteChat tērzēšana.
• Draft un archived produkti nākamajā pārbūvē tiek izslēgti.
• Ja indeksēšana netika ieplānota (index_status: "request_failed"), atkārtoti mēģiniet batch pieprasījumu tiem produktiem, kas jau tika veiksmīgi saglabāti.

Kādas kļūdas man sagaidīt?

Slepeno atslēgu derīguma termiņš beidzas pēc 90 dienām. Izveidojiet aizstājēju sadaļā Settings → Store owner API secret pirms termiņa beigām un atsauciet jebkuru slepeno atslēgu, kas jums vairs nav vajadzīga. Tā pati slepenā atslēga var izsaukt arī analītikas, sarunu un zināšanu galapunktus, kas dokumentēti Merchant API ceļvedī.

Ja nepieciešama palīdzība ar integrāciju, sazinieties ar Shoply AI.