Så laddar du upp din katalog för SiteChat

Om du använder SiteChat på din egen webbplats (inte en Shopify-butik) kan du skicka strukturerade produktposter till Shoply så att kunder kan hitta dem i SiteChat-chatt och produktsökning.

Dessa endpoints använder samma Settings → Store owner API secret som resten av Shoply Merchant API, och sidan Product Catalog i SiteChat-admin kan anropa dem med din inloggade admins åtkomsttoken. Shopify-butiker fortsätter att synkronisera katalogdata via Shopify; dessa uppladdningsrutter är endast tillgängliga för SiteChat-konton som inte redan synkroniserar en Magento-katalog.

I SiteChat-admin öppnar Product Catalog ett område i Shopify-stil med Products, Collections och Inventory. Du kan lägga till eller redigera produkter, importera CSV/Excel, gruppera produkter i manuella kollektioner och justera lagersaldon.

Vilka API:er finns tillgängliga?

Lyckade produktsparningar ber Shoply att bygga om butiksindexet. Tills den ombyggnaden är klar rapporterar svaren index_status: "pending". Publicerade produkter visas därefter både i produktindexet och i den kunskap som används av SiteChat-chatten.

Vem kan använda dessa API:er?

• Din butik måste vara ett SiteChat-konto (app_platform är SiteChat).
• Shopify-butikers nycklar (inklusive alla *.myshopify.com-domäner) avvisas.
• Autentisering måste använda antingen en giltig API-hemlighet för butiksägare eller en SiteChat-admins åtkomsttoken för exakt den store_key som anges i begäran.
• Shopify Admin API-tokens kan inte anropa dessa rutter.

Skapa eller rotera ägarhemligheten på samma sätt som för andra Merchant API-integrationer: Så använder du Shoply Merchant API. I SiteChat-adminpanelen kan du öppna Product Catalog för att hantera produkter, kollektioner och lager—eller importera en CSV- eller Excel-fil—utan att själv behöva hantera hemligheten.

Hur fungerar autentisering?

Från en serveranslutning

Anropa API:et från en betrodd backend över HTTPS. Lägg en JSON-sträng i headern Authorization:

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

store_owner_api_secrete är det publika fältnamnet, inklusive den historiska stavningen. store_owner_api_secret accepteras också. Detta är inte en Bearer-token.

Från SiteChat-admin

Sidan Product Catalog skickar i stället din inloggade adminsession:

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

access_token accepteras som ett alias för admin_auth_token.

Query-parametern store_key måste matcha headern. Förvara endast ägarhemligheter i server-side-miljövariabler—aldrig i ett storefront-skript, en URL eller ett publikt repository.

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

Hur laddar jag upp produkter?

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

Obligatoriska fält och regler

• Obligatoriska produktfält: external_id, title, url, currency, price och available. status har standardvärdet published.
• Valfritt lager: sätt tracks_inventory till true och en icke-negativ quantity på produkten eller varianten. Shoply härleder då tillgänglighet från lager (quantity > 0) och lagrar total_inventory för adminlistor.
• source namnger kataloganslutningen (inte nödvändigtvis en plattform). Använd ett stabilt namn som woocommerce-main. Tillåtna tecken: gemena bokstäver, siffror, understreck och bindestreck; upp till 64 tecken. Produkter som skapas i admin via formulär får som standard källan admin.
• Produktidentitet är kombinationen av butik, källa och externt ID. Batch- och enskilda POST-upserts är fullständiga ersättningar, inte patchar: utelämnade valfria fält rensas. Använd PATCH för partiella uppdateringar.
• Batchar innehåller 1–50 produkter och högst 2 000 000 byte i begäran. Varje produkts validerade JSON är begränsad till 128 000 byte, med högst 250 varianter.
• Föredra decimala strängar för priser. Valuta är en versal kod med tre bokstäver.
• Produkt- och bild-URL:er måste vara HTTP(S). Importen hämtar inte dessa URL:er åt dig.
• Använd publika metafields för sökbara produktspecifikationer (SiteChats motsvarighet till Shopifys produktmetafält). Värden måste vara vanliga strängar. Äldre attributes accepteras som alias. Privat produkt-metadata stöds inte längre.
• Produkter med draft och archived tas inte med i nästa publicerade index. Slutsålda publicerade produkter förblir indexerade med tillgänglighet bifogad.
• Manuella kollektioner lagrar en titel, beskrivning, status och en lista över produktmedlemskap (source + external_id). Smarta/reglerbaserade kollektioner stöds inte i denna version.

Exempel på lyckat svar

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

Shoply validerar hela begäran innan något skrivs. En HTTP 200 kan ändå innehålla vissa failed-resultat med error: "storage_error". Granska varje resultat och försök igen för misslyckade produkter. Om index_status är request_failed lyckades lagringen men indexeringen schemalades inte—försök igen även för de lagrade produkterna.

Python-exempel

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

Hur verifierar jag en importerad produkt?

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

Använd samma Authorization-header. Svaret innehåller schema_version, updated_at, index_status och den normaliserade product. Saknade poster returnerar HTTP 404.

Efter att bakgrundsindexeraren publicerar en ombyggnad blir status vid läsning per produkt indexed, excluded (för utkast eller arkiverade produkter) eller limit_exceeded. Använd GET /merchant/products/list för adminlistning. Mjukarkivera med DELETE /merchant/products (eller sätt status till archived / draft) för att hålla en produkt utanför nästa publicerade index; det finns ingen hård radering i denna version.

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

Kan jag ladda upp produktbilder?

Ja. Om en bild redan finns tillgänglig på en varaktig publik HTTPS-URL, lägg den URL:en i produktens images-lista eller i en variants image-fält. Publika S3 HTTPS-URL:er fungerar. Råa s3://-sökvägar och kortlivade signerade URL:er gör det inte.

Om du vill att Shoply ska hosta filen, ladda upp råa bildbytes från din backend:

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

Skicka råa filbytes, inte JSON, base64 eller multipart form-data. JPEG, PNG och WebP accepteras, upp till 10 MiB och 20 miljoner pixlar. Animerade bilder stöds inte. Shoply konverterar bilden till WebP och tar bort inbäddad metadata.

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 returnerar url, content_type, size_bytes, width och height. Att bara ladda upp en bild kopplar den inte till en produkt och begär inte indexering. Inkludera den returnerade URL:en i en fullständig produkt och skicka in den igen via /merchant/products/batch.

Samma bild som laddas upp igen för samma konto återanvänder sin URL. En ändrad bild får en ny URL. Det finns ingen endpoint för att radera bilder i denna version.

När visas produkter i chatt och sök?

Efter en lyckad batchsparning begär Shoply en ombyggnad av bakgrundsindexet. Svaren rapporterar index_status: "pending" tills arbetaren publicerar det nya indexet. Det finns ingen garanti för fast slutförandetid.

• Publicerade produkter går in i både produktsökning och den kunskap som används av SiteChat-chatten.
• Utkast och arkiverade produkter exkluderas vid nästa ombyggnad.
• Om indexering inte schemalades (index_status: "request_failed"), försök igen med batchen för de produkter som redan lagrats framgångsrikt.

Vilka fel bör jag förvänta mig?

Hemligheter löper ut efter 90 dagar. Skapa en ersättning i Settings → Store owner API secret innan utgångsdatumet, och återkalla alla hemligheter du inte längre behöver. Samma hemlighet kan också anropa analys-, konversations- och kunskaps-endpoints som dokumenteras i guiden för Merchant API.

För hjälp med en integration, kontakta Shoply AI.