Kā augšupielādēt savu katalogu SiteChat

Ja izmantojat SiteChat savā vietnē (nevis Shopify veikalā), varat nosū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ējā Shoply Merchant API, un SiteChat administratora Product Catalog lapa var tos izsaukt ar jūsu pieteiktā administratora piekļuves marķieri. 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 failus, 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, atbildēs tiek norādīts index_status: "pending". Publicētie produkti pēc tam parādās gan produktu indeksā, gan zināšanu bāzē, 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 marķieris tieši tam store_key, kas norādīts pieprasījumā.
• Shopify Admin API marķieri nevar izsaukt šos maršrutus.

Izveidojiet vai nomainiet īpašnieka slepeno atslēgu tāpat kā citām Merchant API integrācijām: How to Use the 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 — pašiem nepārvaldot slepeno atslēgu.

Kā darbojas autentifikācija?

No servera savienotāja

Izsauciet API no uzticama backend servera 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 marķieris.

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 aizstājvārds.

store_key vaicājuma parametram jāsakrīt ar galvenē norādīto vērtību. Glabājiet īpašnieka slepenās atslēgas tikai servera puses vides mainīgajos — nekad veikala skatloga 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 noklusēti ir published.
• Neobligātie krājumi: iestatiet tracks_inventory uz true un nenegatīvu quantity produktam vai variantam. Tad Shoply nosaka pieejamību no krājuma (quantity > 0) un saglabā total_inventory administratora sarakstiem.
• source nosauc kataloga savienojumu (ne vienmēr 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 source ir admin.
• Produkta identitāte ir veikala, source un external ID kombinācija. Batch un viena produkta POST upsert darbības ir pilnīgas aizvietošanas, nevis labojumi: izlaistie neobligātie lauki tiek notīrīti. Daļējiem atjauninājumiem izmantojiet PATCH.
• Pakotnēs ir 1–50 produkti un ne vairāk kā 2,000,000 pieprasījuma baitu. 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ūta ir trīs burtu kods ar lielajiem burtiem.
• 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 metafieldiem). Vērtībām jābūt vienkāršām virknēm. Mantotais attributes arī tiek pieņemts kā aizstājvārds. Privāts produkta metadata vairs netiek atbalstīts.
• draft un archived produkti netiek iekļauti nākamajā publicētajā indeksā. Izpārdoti publicēti produkti paliek indeksēti ar pievienotu pieejamības informāciju.
• Manuālās kolekcijas glabā nosaukumu, aprakstu, statusu un produktu piederību sarakstu (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 neizdevušos produktus. Ja index_status ir request_failed, saglabāšana bija veiksmīga, bet indeksēšana netika ieplānota — atkārtoti iesniedziet arī 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 (melnraksta vai arhivētiem produktiem) vai limit_exceeded. Administratora sarakstiem 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ā nav pilnīgas dzēšanas.

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

Vai es 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 servera:

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

Sūtiet neapstrādātos faila baitus, nevis JSON, base64 vai multipart form data. 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 iegulto metadatu informāciju.

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, atkārtoti augšupielādēts tam pašam kontam, atkārtoti izmanto savu URL. Mainī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 pakotnes saglabāšanas Shoply pieprasa fona indeksa pārbūvi. Atbildēs tiek ziņots 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āšanu bāzē, ko izmanto SiteChat tērzēšana.
• Melnraksti un arhivētie produkti tiek izslēgti nākamajā pārbūvē.
• Ja indeksēšana netika ieplānota (index_status: "request_failed"), atkārtoti mēģiniet pakotni produktiem, kas jau tika veiksmīgi saglabāti.

Kādas kļūdas man vajadzētu 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. To pašu slepeno atslēgu var izmantot arī analytics, conversation un knowledge galapunktu izsaukšanai, kas dokumentēti Merchant API guide.

Lai saņemtu palīdzību ar integrāciju, sazinieties ar Shoply AI.