Come caricare il tuo catalogo per SiteChat

Se utilizzi SiteChat sul tuo sito web (non su un negozio Shopify), puoi inviare record di prodotto strutturati a Shoply in modo che gli acquirenti possano trovarli nella chat di SiteChat e nella ricerca prodotti.

Questi endpoint usano lo stesso Impostazioni → Segreto API del proprietario del negozio del resto della Merchant API di Shoply, e la pagina Catalogo prodotti dell’admin di SiteChat può richiamarli con il tuo token di accesso admin autenticato. I negozi Shopify continuano a sincronizzare i dati di catalogo tramite Shopify; queste route di caricamento sono disponibili solo per gli account SiteChat che non sincronizzano già un catalogo Magento.

Nell’admin di SiteChat, Catalogo prodotti apre un’area in stile Shopify con Prodotti, Collezioni e Inventario. Puoi aggiungere o modificare prodotti, importare CSV/Excel, raggruppare prodotti in collezioni manuali e regolare le quantità di stock.

Quali API sono disponibili?

I salvataggi di prodotto riusciti chiedono a Shoply di ricostruire l’indice del negozio. Fino al completamento della ricostruzione, le risposte riportano index_status: "pending". I prodotti pubblicati appaiono quindi sia nell’indice prodotti sia nella base di conoscenza usata dalla chat di SiteChat.

Chi può usare queste API?

• Il tuo negozio deve essere un account SiteChat (app_platform è SiteChat).
• Le chiavi del negozio Shopify (incluso qualsiasi dominio *.myshopify.com) vengono rifiutate.
• L’autenticazione deve usare o un segreto API valido del proprietario del negozio oppure un token di accesso admin SiteChat per l’esatto store_key nella richiesta.
• I token Shopify Admin API non possono richiamare queste route.

Crea o ruota il segreto del proprietario nello stesso modo delle altre integrazioni Merchant API: Come usare la Merchant API di Shoply. Nella console admin di SiteChat, apri Catalogo prodotti per gestire prodotti, collezioni e inventario — oppure importare un file CSV o Excel — senza gestire direttamente il segreto.

Come funziona l’autenticazione?

Da un connettore server

Richiama l’API da un backend affidabile tramite HTTPS. Inserisci una stringa JSON nell’header Authorization:

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

store_owner_api_secrete è il nome pubblico del campo, inclusa la grafia storica. Anche store_owner_api_secret è accettato. Non è un token Bearer.

Dall’admin di SiteChat

La pagina Catalogo prodotti invia invece la tua sessione admin autenticata:

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

access_token è accettato come alias di admin_auth_token.

Il parametro di query store_key deve corrispondere all’header. Mantieni i segreti del proprietario solo nelle variabili d’ambiente lato server: mai in uno script storefront, in un URL o in un repository pubblico.

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

Come carico i prodotti?

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

Campi obbligatori e regole

• Campi obbligatori del prodotto: external_id, title, url, currency, price e available. status ha come valore predefinito published.
• Inventario facoltativo: imposta tracks_inventory su true e una quantity non negativa sul prodotto o sulla variante. Shoply ricava quindi la disponibilità dallo stock (quantity > 0) e memorizza total_inventory per gli elenchi admin.
• source identifica la connessione del catalogo (non necessariamente una piattaforma). Usa un nome stabile come woocommerce-main. Caratteri consentiti: lettere minuscole, numeri, underscore e trattini; fino a 64 caratteri. I prodotti creati tramite form nell’admin usano per impostazione predefinita la source admin.
• L’identità del prodotto è la combinazione di negozio, source ed ID esterno. Gli upsert POST batch e singoli sono sostituzioni complete, non patch: i campi facoltativi omessi vengono cancellati. Usa PATCH per aggiornamenti parziali.
• I batch contengono da 1 a 50 prodotti e al massimo 2.000.000 byte di richiesta. Il JSON validato di ciascun prodotto è limitato a 128.000 byte, con al massimo 250 varianti.
• Preferisci stringhe decimali per i prezzi. La valuta è un codice maiuscolo di tre lettere.
• Gli URL di prodotto e immagine devono essere HTTP(S). L’importazione non recupera quegli URL per te.
• Usa metafields pubblici per specifiche di prodotto ricercabili (l’equivalente in SiteChat dei metafield prodotto di Shopify). I valori devono essere semplici stringhe. Il vecchio attributes è accettato come alias. Il metadata privato del prodotto non è più supportato.
• I prodotti draft e archived vengono esclusi dal successivo indice pubblicato. I prodotti pubblicati esauriti restano indicizzati con la disponibilità associata.
• Le collezioni manuali memorizzano un titolo, una descrizione, uno stato e un elenco di appartenenze prodotto (source + external_id). Le collezioni smart/basate su regole non sono supportate in questa release.

Esempio di risposta di successo

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

Shoply valida l’intera richiesta prima della scrittura. Un HTTP 200 può comunque elencare alcuni risultati failed con error: "storage_error". Controlla ogni risultato e ritenta i prodotti non riusciti. Se index_status è request_failed, l’archiviazione è riuscita ma l’indicizzazione non è stata pianificata: ritenta anche i prodotti memorizzati.

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

Come verifico un prodotto importato?

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

Usa lo stesso header Authorization. La risposta include schema_version, updated_at, index_status e il product normalizzato. I record mancanti restituiscono HTTP 404.

Dopo che l’indicizzatore in background pubblica una ricostruzione, lo stato di rilettura per prodotto diventa indexed, excluded (per prodotti draft o archived) oppure limit_exceeded. Usa GET /merchant/products/list per l’elenco admin. Archivia in modo soft con DELETE /merchant/products (o imposta status su archived / draft) per tenere un prodotto fuori dal successivo indice pubblicato; in questa release non esiste l’eliminazione definitiva.

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

Posso caricare immagini di prodotto?

Sì. Se un’immagine è già disponibile a un URL HTTPS pubblico stabile, inserisci quell’URL nell’elenco images del prodotto o nel campo image di una variante. Gli URL HTTPS pubblici di S3 funzionano. I percorsi s3:// grezzi e gli URL firmati di breve durata no.

Per fare in modo che Shoply ospiti il file, carica i byte grezzi dell’immagine dal tuo backend:

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

Invia i byte grezzi del file, non JSON, base64 o dati multipart form. Sono accettati JPEG, PNG e WebP, fino a 10 MiB e 20 milioni di pixel. Le immagini animate non sono supportate. Shoply converte l’immagine in WebP e rimuove i metadati incorporati.

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 restituisce url, content_type, size_bytes, width e height. Caricare un’immagine da sola non la collega a un prodotto né richiede l’indicizzazione. Includi l’URL restituito in un prodotto completo e invialo di nuovo tramite /merchant/products/batch.

La stessa immagine caricata di nuovo per lo stesso account riutilizza il proprio URL. Un’immagine modificata riceve un nuovo URL. In questa release non esiste un endpoint per eliminare immagini.

Quando i prodotti compaiono nella chat e nella ricerca?

Dopo un salvataggio batch riuscito, Shoply richiede una ricostruzione dell’indice in background. Le risposte riportano index_status: "pending" finché il worker non pubblica il nuovo indice. Non esiste una garanzia fissa sui tempi di completamento.

• I prodotti pubblicati entrano sia nella ricerca prodotti sia nella base di conoscenza usata dalla chat di SiteChat.
• I prodotti draft e archived vengono esclusi alla successiva ricostruzione.
• Se l’indicizzazione non è stata pianificata (index_status: "request_failed"), ritenta il batch per i prodotti che erano già stati memorizzati con successo.

Quali errori devo aspettarmi?

I segreti scadono dopo 90 giorni. Crea un sostituto in Impostazioni → Segreto API del proprietario del negozio prima della scadenza e revoca qualsiasi segreto che non ti serve più. Lo stesso segreto può anche richiamare gli endpoint di analytics, conversazioni e knowledge documentati nella guida Merchant API.

Per assistenza con un’integrazione, contatta Shoply AI.