Documentazione per sviluppatori

Individuare le risorse

• robots.txt: istruzioni per i crawler e riferimento alla sitemap.
• sitemap.xml: indice delle sitemap nelle lingue pubblicate dal negozio.
• /.well-known/ai-catalog.json: catalogo delle risorse leggibile dalle macchine, segnalato dall’header Link con rel="ai-catalog".
• /.well-known/ard.json: alias dello stesso catalogo, accompagnato dal valore aggiuntivo rel="ard" nell’header Link, secondo la bozza ARD v0.91.
• llms.txt: panoramica sintetica dell’assortimento, dei servizi e delle fonti di dati.
• Le pagine dei prodotti e delle categorie includono JSON-LD con dati strutturati sui prodotti, sui prezzi e sulla disponibilità.

API prodotti

L’indirizzo di base dell’API pubblica è https://api.saneq.ch. L’accesso in lettura è anonimo e non richiede una chiave API. Gli endpoint GET elencati restituiscono JSON.

• GET /shop/products: ricerca e filtro dei prodotti, con risultati suddivisi in pagine.
• GET /shop/products/{titleSlug}[/{variantSlug}]: dettagli di un prodotto o di una variante specifica; la parte tra parentesi quadre è facoltativa.
• GET /shop/products/{titleSlug}/reviews: recensioni relative a un prodotto.
• GET /shop/categories/by-path/{pfad}: ricerca di una categoria tramite il suo percorso.
• GET /categories/tree: struttura ad albero delle categorie.
• GET /shop/brands: elenco delle marche.
• GET /shop/store-policy: informazioni strutturate su resi e spedizioni.

Parametri di ricerca

Per gli elenchi di prodotti, q indica il testo da cercare e categorySlug la categoria. La marca si seleziona con brand o brandId; priceMin e priceMax filtrano per prezzo. Sono disponibili anche inStock per la disponibilità a magazzino, attr per gli attributi e range per gli intervalli di valori. Utilizzi page per scegliere la pagina, pageSize per il numero di risultati, fino a un massimo di 100 per pagina, e sort per l’ordinamento.

La lingua si imposta con lang=de|fr|it|en. Se il parametro è assente, viene usato il tedesco. Per prodotti e categorie occorre utilizzare gli slug della lingua richiesta.

Esempio: https://api.saneq.ch/shop/products?q=tape&inStock=true&page=1&pageSize=20&lang=it

Interpretare i dati restituiti

I prezzi sono lordi, espressi in CHF e comprensivi d’imposta. Nei campi che terminano con Minor gli importi sono in unità minori, cioè centesimi: 1290 corrisponde a CHF 12.90. descriptionPlain contiene la descrizione senza HTML. Gli elementi di specs includono rawValue e unitCode per rappresentare valori degli attributi e unità di misura. availability descrive la disponibilità. Le risposte con i dettagli dei prodotti hanno un header Cache-Control pubblico.

Server MCP

Colleghi un client che supporta server MCP remoti, ad esempio Claude Desktop o un connettore ChatGPT compatibile, a https://api.saneq.ch/mcp. Utilizzi il trasporto Streamable HTTP senza autenticazione: il catalogo non richiede né l’accesso a un account né una chiave API.

• search_products cerca nel catalogo per testo, categoria o marca e restituisce al massimo 20 risultati per pagina, con numerazione delle pagine a partire da 0.
• get_product restituisce, a partire dallo slug di un prodotto ed eventualmente di una variante, dettagli, specifiche, prezzo IVA inclusa, disponibilità e URL del prodotto.
• check_availability verifica disponibilità, prezzo IVA inclusa e tempi di consegna per un massimo di 50 ID prodotto e segnala separatamente gli ID non trovati.
• list_categories elenca le categorie pubbliche con i relativi percorsi e il numero di prodotti nella lingua richiesta.
• get_store_policy restituisce le condizioni attuali di reso, spedizione e consegna.

Le risorse JSON saneq://store-policy e saneq://categories forniscono le condizioni commerciali e le categorie. La risorsa delle categorie è in tedesco; per le altre lingue utilizzi list_categories. Il prompt recommend_product aiuta a consigliare prodotti in base a un’esigenza, a un budget facoltativo in CHF e alla lingua.

L’accesso separato ai carrelli https://api.saneq.ch/mcp/cart utilizza anch’esso Streamable HTTP. Si autentichi con Authorization: Bearer sk_… e una chiave API con lo scope cart:write. Sono disponibili create_cart(items[{productId, quantity}], locale?, buyerEmail?), get_cart(cartId) e update_cart(cartId, items), oltre ai cinque strumenti di lettura di /mcp. Non esiste uno strumento di checkout: continue_url è l’unico modo per accedere alla cassa, dove la cliente o il cliente completa l’acquisto nel negozio. Citi prezzi e disponibilità esclusivamente dai risultati degli strumenti.

Chiavi API

Una chiave API con cart:write è necessaria per l’API dei carrelli per agenti e per l’accesso MCP separato ai carrelli. L’API pubblica dei prodotti, il catalogo MCP, i link diretti al carrello e l’API di trasferimento sono accessibili in forma anonima, senza chiave API.

Richieda una chiave a [email protected], descrivendo l’integrazione, gli scope necessari e il volume di richieste previsto. Il team saneq crea e gestisce le chiavi nell’amministrazione.

Invii la chiave in uno dei due header HTTP: Authorization: Bearer sk_… oppure X-Api-Key: sk_…. La conservi nell’integrazione lato server e non la includa in link pubblici.

• catalog:read identifica l’accesso in lettura al catalogo con una chiave; gli accessi anonimi al catalogo restano disponibili senza chiave.
• cart:write consente di creare, leggere, aggiornare e annullare i carrelli del relativo client API; questo scope non autorizza il completamento di un acquisto.

Per le richieste al catalogo e all’API dei carrelli per agenti si applica un limite al minuto configurato per ogni client API e la relativa chiave, pari a 600 richieste al minuto per impostazione predefinita. Fa fede il limite concordato per la Sua chiave. La rotazione della chiave non azzera questo conteggio.

Se necessario, chieda al team saneq di ruotare o revocare le chiavi nell’amministrazione. La rotazione sostituisce la chiave precedente con una nuova; aggiorni l’integrazione di conseguenza. La chiave completa viene comunicata una sola volta, al momento della creazione o della rotazione.

Preparare un carrello per i clienti

Questi accessi preparano un carrello. La cliente o il cliente verifica gli articoli, li aggiunge al proprio carrello nel negozio e completa personalmente l’acquisto. Senza questo passaggio non vengono avviati né un ordine né un pagamento. Gli articoli, i token e gli importi seguenti sono esempi illustrativi; utilizzi gli ID e gli SKU del catalogo attuale.

Link diretto: utilizzi il formato /warenkorb?add=SKU:qty,SKU:qty con un massimo di 20 righe e quantità intere da 1 a 99. Non occorre una chiave API. Esempio in italiano:

https://www.saneq.ch/it/carrello?add=ART-123:2,ART-456:1

I percorsi localizzati sono /fr/panier?add=SKU:qty,…, /it/carrello?add=SKU:qty,… e /en/cart?add=SKU:qty,…. Il link permette di verificare gli articoli proposti prima di aggiungerli al carrello.

API di trasferimento: POST /shop/cart/handoff crea in forma anonima un link di trasferimento a partire da items e locale (de, fr, it oppure en). Ogni riga contiene un productId numerico oppure uno sku, oltre a quantity. Sono ammesse da 1 a 50 righe e quantità da 1 a 999.

Esempio di richiesta:

POST https://api.saneq.ch/shop/cart/handoff Content-Type: application/json { "items": [ { "sku": "ART-123", "quantity": 2 } ], "locale": "it" }

Esempio di risposta; skipped indica le righe omesse:

HTTP/1.1 201 Created { "token": "bW9ja19oYW5kb2ZmX3Rva2VuXzMyX2J5dGVzXzAwMDA", "continueUrl": "https://www.saneq.ch/it/carrello/riprendi/bW9ja19oYW5kb2ZmX3Rva2VuXzMyX2J5dGVzXzAwMDA", "expiresAtUtc": "2026-10-14T10:00:00Z", "skipped": [] }

Trasmetta alla cliente o al cliente la continueUrl ricevuta. GET /shop/cart/handoff/{token} mostra gli articoli con prezzi e disponibilità aggiornati. Dopo la conferma, il negozio li aggiunge al carrello tramite POST /shop/cart/handoff/{token}/redeem e lo X-Cart-Key del carrello di destinazione. Riutilizzare lo stesso token nello stesso carrello non aggiunge nuovamente le quantità; i token sconosciuti o scaduti restituiscono 404.

API dei carrelli per agenti secondo ACP-Cart: l’URL di base è https://api.saneq.ch/agent/carts. Tutte le chiamate richiedono una chiave API con cart:write e riguardano i carrelli del relativo client API.

• POST /agent/carts crea un carrello e restituisce 201.
• GET /agent/carts/{id} legge il carrello con prezzi e disponibilità aggiornati.
• PUT /agent/carts/{id} sostituisce tutte le righe con l’elenco fornito.
• POST /agent/carts/{id}/cancel annulla il carrello dell’agente; i link di trasferimento già emessi restano validi fino alla scadenza.

Invii API-Version: 2026-04-17 per tutte e quattro le operazioni. La creazione e l’annullamento richiedono anche un Idempotency-Key composto da 1 a 128 caratteri ASCII stampabili: usi un nuovo valore per ogni nuova operazione e lo stesso valore quando ripete la medesima richiesta. PUT non richiede questo header. line_items contiene da 1 a 50 righe con un id nel formato v{productId} e una quantity da 1 a 999.

Esempio di creazione; sostituisca la chiave illustrativa con la propria:

POST https://api.saneq.ch/agent/carts Authorization: Bearer sk_… API-Version: 2026-04-17 Idempotency-Key: cart-demo-001 Content-Type: application/json { "line_items": [ { "id": "v12345", "quantity": 2 } ], "locale": "it" }

Estratto di una risposta di esempio:

HTTP/1.1 201 Created API-Version: 2026-04-17 { "id": "f268c6ea-89af-4183-a426-b75bdcaa32c5", "line_items": [ { "id": "line_12345", "item": { "id": "v12345", "name": "Prodotto di esempio", "unit_amount": 1290 }, "quantity": 2, "totals": [ { "type": "subtotal", "amount": 2580 } ] } ], "currency": "chf", "totals": [ { "type": "subtotal", "amount": 2580 }, { "type": "shipping", "amount": 790 }, { "type": "total", "amount": 3370 } ], "continue_url": "https://www.saneq.ch/it/carrello/riprendi/bW9ja19oYW5kb2ZmX3Rva2VuXzMyX2J5dGVzXzAwMDA" }

unit_amount e totals[].amount sono numeri interi in unità minori: con currency: "chf", 1290 corrisponde a CHF 12.90. I prezzi dei prodotti includono l’IVA; le spese di spedizione sono stime. Controlli le informazioni in messages e trasmetta alla cliente o al cliente la continue_url attuale. Questa API non consente di completare un acquisto.

Condizioni commerciali

Con GET /shop/store-policy può leggere in formato strutturato le informazioni su resi e spedizioni, inclusi termini e modalità di restituzione, costi e tempi di consegna. Utilizzi questi dati nell’integrazione e consideri le eventuali esclusioni dal reso indicate per i singoli prodotti.

Uso corretto (Fair Use)

• Le richieste anonime al catalogo sono soggette al limite catalog-read di 300 richieste al minuto per indirizzo IP. Eviti ripetizioni inutili e picchi di carico; con una chiave API si applica il limite individuale al minuto.
• Se il limite viene superato, riceve HTTP 429. Attenda il numero di secondi indicato nell’header Retry-After prima di riprovare.
• Rispetti gli header Cache-Control e riutilizzi le risposte durante il loro periodo di validità. I dettagli dei prodotti utilizzano ad esempio public, max-age=300, stale-while-revalidate=3600. Le risposte con private, no-store, in particolare i trasferimenti del carrello, non devono essere memorizzate nella cache.
• Quando utilizza i dati, citi «saneq.ch» come fonte.
• Prezzi e disponibilità possono cambiare. Non garantiamo i prezzi riportati al di fuori del negozio; fanno fede le informazioni presenti nel negozio.
• Per domande o integrazioni, contatti [email protected].

Per ripetere un tentativo d’ordine durante il checkout del cliente, POST /shop/checkout/orders supporta l’header Idempotency-Key composto da 1 a 128 caratteri ASCII stampabili. Utilizzi la stessa chiave per lo stesso carrello e lo stesso corpo della richiesta, ad esempio dopo un’interruzione della connessione.

• La ripetizione restituisce la risposta memorizzata con Idempotent-Replayed: true.
• Se la chiave viene riutilizzata per un carrello o una richiesta diversi, la risposta è HTTP 422 con checkout.idempotency-mismatch.
• Se il primo tentativo è ancora in corso, la risposta è HTTP 409 con checkout.idempotency-in-progress e Retry-After: 2; ripeta la richiesta identica dopo il tempo di attesa.

L’idempotenza al checkout evita tentativi d’ordine duplicati; non autorizza gli agenti a completare un acquisto senza la cliente o il cliente.