Entwickler-Dokumentation

Discovery

• robots.txt: Hinweise für Crawler und Verweis auf die Sitemap.
• sitemap.xml: Sitemap-Index für die öffentlich freigegebenen Shop-Sprachen.
• /.well-known/ai-catalog.json: maschinenlesbarer Ressourcenkatalog, angekündigt über den Link-Header mit rel="ai-catalog".
• /.well-known/ard.json: Alias mit demselben Kataloginhalt und dem zusätzlichen Link-Header-Wert rel="ard" für den ARD-Entwurf v0.91.
• llms.txt: kompakter Überblick über Sortiment, Service und Datenzugänge.
• JSON-LD auf Produkt- und Kategorieseiten: strukturierte Produktdaten mit Preisen und Verfügbarkeit.

Produkt-API

Die öffentliche API unter https://api.saneq.ch ist anonym und ohne API-Schlüssel lesbar. Die folgenden GET-Endpunkte liefern JSON.

• GET /shop/products: Produkte suchen, filtern und seitenweise abrufen.
• GET /shop/products/{titleSlug}[/{variantSlug}]: Details eines Produkttitels oder einer bestimmten Variante; der Teil in eckigen Klammern ist optional.
• GET /shop/products/{titleSlug}/reviews: Bewertungen eines Produkts abrufen.
• GET /shop/categories/by-path/{pfad}: Kategorie anhand ihres Pfads auflösen.
• GET /categories/tree: Kategoriebaum abrufen.
• GET /shop/brands: verfügbare Marken auflisten.
• GET /shop/store-policy: maschinenlesbare Rückgabe- und Versandangaben abrufen.

Parameter und Beispiel

Für Produktlisten stehen q (Suchtext), categorySlug (Kategorie), brand und brandId (Marke), priceMin und priceMax (Preisfilter), inStock (Lagerverfügbarkeit), attr (Attributfilter), range (Bereichsfilter), page (Seite), pageSize (höchstens 100 Treffer pro Seite) und sort (Sortierung) zur Verfügung.

Mit lang=de|fr|it|en wählen Sie die Sprache; ohne diesen Parameter gilt Deutsch. Nutzen Sie für Produkt- und Kategorieabfragen die Slugs der gewünschten Sprache.

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

Antwortfelder

Preise sind Bruttobeträge in CHF. Felder mit der Endung Minor enthalten Minor Units, also Rappen: 1290 entspricht CHF 12.90. descriptionPlain enthält die Beschreibung ohne HTML. In specs stehen unter anderem rawValue und unitCode für maschinenlesbare Attributwerte und Einheiten. availability beschreibt die Verfügbarkeit. Produktdetail-Antworten verwenden einen öffentlichen Cache-Control-Header.

MCP-Server

Verbinden Sie einen Client mit Unterstützung für entfernte MCP-Server, etwa Claude Desktop oder einen entsprechenden ChatGPT-Connector, mit https://api.saneq.ch/mcp. Wählen Sie Streamable HTTP als Transport und keine Authentifizierung: Für den Katalog sind weder Anmeldung noch API-Schlüssel erforderlich.

• search_products durchsucht den Katalog nach Suchtext, Kategorie oder Marke und liefert höchstens 20 Treffer pro Seite, beginnend bei Seite 0.
• get_product liefert zu einem Produkttitel-Slug und optionalen Varianten-Slug Details, Spezifikationen, Bruttopreis, Verfügbarkeit und Produkt-URL.
• check_availability prüft Verfügbarkeit, Bruttopreis und Lieferzeit für bis zu 50 Produkt-IDs und weist fehlende IDs separat aus.
• list_categories listet öffentliche Kategorien mit Pfaden und Produktanzahl in der gewünschten Sprache auf.
• get_store_policy liefert die aktuellen Rückgabe-, Versand- und Lieferbedingungen.

Die JSON-Ressourcen saneq://store-policy und saneq://categories liefern Handelsbedingungen und Kategorien; die Kategorien-Ressource ist deutsch, weitere Sprachen erhalten Sie über list_categories. Der Prompt recommend_product unterstützt Produktempfehlungen anhand von Bedarf, optionalem Budget in CHF und Sprache.

Der separate Warenkorb-Zugang https://api.saneq.ch/mcp/cart verwendet ebenfalls Streamable HTTP. Authentifizieren Sie sich mit Authorization: Bearer sk_… und einem API-Schlüssel mit Scope cart:write. Er bietet create_cart(items[{productId, quantity}], locale?, buyerEmail?), get_cart(cartId) und update_cart(cartId, items) sowie die fünf Lesetools von /mcp. Es gibt kein Checkout-Tool: continue_url ist der einzige Weg zur Kasse, wo die Kundin oder der Kunde den Kauf im Shop abschliesst. Zitieren Sie Preise und Verfügbarkeit ausschliesslich aus Tool-Ergebnissen.

API-Schlüssel

Ein API-Schlüssel mit cart:write ist für die Agenten-Warenkorb-API und den separaten MCP-Warenkorb-Zugang erforderlich. Die öffentliche Produkt-API, der MCP-Katalog, Warenkorb-Deep-Links und die Handoff-API können anonym ohne API-Schlüssel genutzt werden.

Beantragen Sie einen Schlüssel über [email protected] und beschreiben Sie Ihre Integration, die benötigten Scopes und das erwartete Anfragevolumen. Das saneq-Team erstellt und verwaltet die Schlüssel im Admin.

Übermitteln Sie den Schlüssel in einem der beiden HTTP-Header: Authorization: Bearer sk_… oder X-Api-Key: sk_…. Bewahren Sie ihn in Ihrer serverseitigen Integration auf und geben Sie ihn nicht in öffentlichen Links weiter.

• catalog:read steht für lesenden Katalogzugriff mit Schlüssel; die anonymen Katalogzugänge bleiben ohne Schlüssel nutzbar.
• cart:write erlaubt das Erstellen, Lesen, Aktualisieren und Abbrechen eigener Agenten-Warenkörbe; der Scope erlaubt keinen Kaufabschluss.

Bei Katalogabfragen und der Agenten-Warenkorb-API gilt ein separat konfiguriertes Minutenlimit je API-Client bzw. Schlüssel, standardmässig 600 Anfragen pro Minute. Massgeblich ist das für Ihren Schlüssel vereinbarte Limit. Eine Rotation setzt dieses Limit nicht zurück.

Lassen Sie Schlüssel bei Bedarf über das saneq-Team im Admin rotieren oder widerrufen. Bei der Rotation ersetzt ein neuer Schlüssel den bisherigen; aktualisieren Sie Ihre Integration entsprechend. Der vollständige Schlüssel wird nur bei Erstellung oder Rotation einmal ausgegeben.

Warenkorb für Kunden vorbereiten

Diese Zugänge bereiten einen Warenkorb vor. Die Kundin oder der Kunde prüft und übernimmt die Artikel im Shop und schliesst den Kauf selbst ab. Ohne diesen Schritt werden weder eine Bestellung noch eine Zahlung ausgelöst. Die folgenden Artikel, Token und Beträge sind illustrative Beispiele; verwenden Sie die IDs und SKUs aus dem aktuellen Katalog.

Deep-Link: Verwenden Sie das Format /warenkorb?add=SKU:qty,SKU:qty mit höchstens 20 Positionen und ganzzahligen Mengen von 1–99. Ein API-Schlüssel ist nicht nötig. Beispiel:

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

Die lokalisierten Pfade sind /fr/panier?add=SKU:qty,…, /it/carrello?add=SKU:qty,… und /en/cart?add=SKU:qty,…. Der Link führt zur Prüfung und Übernahme der vorgeschlagenen Artikel.

Handoff-API: POST /shop/cart/handoff erstellt anonym einen Übergabelink aus items und locale (de, fr, it oder en). Jede Position enthält entweder eine numerische productId oder eine sku sowie quantity; zulässig sind 1–50 Positionen und Mengen von 1–999.

Beispiel-Request:

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

Beispiel-Response; skipped nennt ausgelassene Positionen:

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

Geben Sie die zurückgegebene continueUrl an die Kundin oder den Kunden weiter. GET /shop/cart/handoff/{token} zeigt die Positionen mit aktuellen Preisen und Verfügbarkeit. Nach Bestätigung übernimmt der Shop sie mit POST /shop/cart/handoff/{token}/redeem und dem X-Cart-Key des Zielwarenkorbs. Wiederholtes Einlösen in denselben Warenkorb addiert die Mengen nicht erneut; unbekannte oder abgelaufene Token liefern 404.

Agenten-Warenkorb-API nach ACP-Cart: Die Basis-URL lautet https://api.saneq.ch/agent/carts. Alle Aufrufe benötigen einen API-Schlüssel mit cart:write und beziehen sich auf die Warenkörbe dieses API-Clients.

• POST /agent/carts erstellt einen Warenkorb und liefert 201.
• GET /agent/carts/{id} liest den Warenkorb mit aktuellen Preisen und Verfügbarkeit.
• PUT /agent/carts/{id} ersetzt sämtliche Positionen durch die mitgelieferte Liste.
• POST /agent/carts/{id}/cancel bricht den Agenten-Warenkorb ab; bereits ausgegebene Übergabelinks bleiben bis zu ihrem Ablauf gültig.

Senden Sie bei allen vier Operationen API-Version: 2026-04-17. Create und Cancel benötigen zusätzlich einen Idempotency-Key mit 1–128 druckbaren ASCII-Zeichen: Verwenden Sie pro neuer Operation einen neuen Wert und bei Wiederholungen desselben Requests denselben Wert. PUT benötigt diesen Header nicht. line_items enthält 1–50 Positionen mit id im Format v{productId} und quantity von 1–999.

Beispiel zum Erstellen; ersetzen Sie den Beispielschlüssel durch Ihren eigenen:

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": "de" }

Auszug aus einer Beispiel-Response:

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": "Beispielprodukt", "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/warenkorb/uebernehmen/bW9ja19oYW5kb2ZmX3Rva2VuXzMyX2J5dGVzXzAwMDA" }

unit_amount und totals[].amount sind ganzzahlige Minor Units: Bei currency: "chf" entspricht 1290 CHF 12.90. Produktpreise enthalten die Mehrwertsteuer; Versandbeträge sind Schätzungen. Prüfen Sie die Antwortmeldungen in messages und übergeben Sie die aktuelle continue_url an die Kundin oder den Kunden. Diese API bietet keinen Checkout.

Handelsbedingungen

GET /shop/store-policy liefert Rückgabe- und Versandangaben maschinenlesbar, darunter Rückgabefrist, Rücksendemethode, Kosten und Lieferzeiten. Verwenden Sie diese Daten für Ihre Integration und berücksichtigen Sie produktspezifische Rückgabeausnahmen.

Fair Use

• Anonyme Katalogabfragen unterliegen dem Limit catalog-read von 300 Anfragen pro Minute je IP-Adresse. Vermeiden Sie unnötige Wiederholungen und Lastspitzen; mit API-Schlüssel gilt das individuelle Minutenlimit.
• Bei Überschreitung erhalten Sie HTTP 429. Warten Sie die im Header Retry-After angegebene Anzahl Sekunden ab, bevor Sie erneut anfragen.
• Beachten Sie die Cache-Control-Header und verwenden Sie Antworten während ihrer Gültigkeitsdauer wieder. Produktdetails verwenden beispielsweise public, max-age=300, stale-while-revalidate=3600. Antworten mit private, no-store, insbesondere Warenkorb-Übergaben, dürfen nicht zwischengespeichert werden.
• Geben Sie bei der Verwendung der Daten «saneq.ch» als Quelle an.
• Preise und Verfügbarkeit können sich ändern. Für Preisangaben ausserhalb des Shops übernehmen wir keine Preis-Garantie; massgeblich sind die Angaben im Shop.
• Kontakt für Fragen und Integrationen: [email protected].

Für wiederholte Bestellversuche im Kunden-Checkout unterstützt POST /shop/checkout/orders den Header Idempotency-Key (1–128 druckbare ASCII-Zeichen). Verwenden Sie für denselben Warenkorb und denselben Request-Body denselben Schlüssel, etwa nach einem Verbindungsabbruch.

• Ein Replay liefert die gespeicherte Antwort mit Idempotent-Replayed: true.
• Wird der Schlüssel für einen anderen Warenkorb oder Request verwendet, folgt HTTP 422 mit checkout.idempotency-mismatch.
• Wird der erste Versuch noch verarbeitet, folgt HTTP 409 mit checkout.idempotency-in-progress und Retry-After: 2; wiederholen Sie den identischen Request nach der Wartezeit.

Checkout-Idempotenz verhindert doppelte Bestellversuche; sie erteilt Agenten keine Berechtigung, ohne die Kundin oder den Kunden einen Kauf abzuschliessen.