Für Entwickler & KI-Agenten

Agenten-Integration

Mia x Klausi bietet eine öffentliche REST-API und einen MCP-Server, damit KI-Agenten Produkte finden, einen Warenkorb vorbereiten und einen sicheren Stripe-Checkout-Link erstellen können. Es werden nur Einzelstücke verkauft — jedes Produkt gibt es genau einmal.

Was Agenten können

🟢 Nur lesend: Produkte suchen, Details/Kategorien lesen, Empfehlungen, Bestellstatus (mit Token).

🟠 Datenverändernd: Warenkorb erstellen/ändern.

🔴 Kostenrelevant + bestätigungspflichtig: Checkout-Link erstellen. Nur nach ausdrücklicher Nutzerbestätigung. Es wird ausschließlich ein Stripe-Link erzeugt — der Nutzer zahlt direkt bei Stripe.

Endpunkte & Discovery

REST-Basis: https://www.miaxklausi.ch/api/agent/v1

OpenAPI: /openapi.json

MCP-Endpunkt: https://www.miaxklausi.ch/mcp (Streamable HTTP)

Health-Check: /api/agent/health

Capabilities: /.well-known/agent.json

llms.txt: /llms.txt

Authentifizierung

Lesende Produkt-Endpunkte sind öffentlich (rate-limited).

Geschützte Aktionen nutzen kurzlebige, signierte Bearer-Tokens:

• cartToken (aus POST /carts) → Warenkorb ändern, Checkout erstellen.

• orderAccessToken (aus POST /checkouts) → Bestellstatus lesen.

Ablauf eines Kaufs

Produkte suchen (search_products / GET /products).
Dem Nutzer Produkt, Preis, Zustand und Versand zeigen.
Nutzer bestätigt den Artikel.
Warenkorb erstellen (POST /carts).
Vollständige Kostenübersicht zeigen (GET /carts/:id).
Nutzer bestätigt den Checkout ausdrücklich.
Checkout-Link erstellen (POST /checkouts, userConfirmed: true).
Nutzer zahlt direkt bei Stripe.
Stripe bestätigt die Zahlung per Webhook — erst dann gilt der Verkauf.

Beispiele

Produktsuche (curl)

curl "https://www.miaxklausi.ch/api/agent/v1/products?availableOnly=true&sort=price_asc&limit=5"

Warenkorb & Checkout (JavaScript)

// 1) Warenkorb anlegen
const cart = await fetch("https://www.miaxklausi.ch/api/agent/v1/carts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ productId: "prod_xxx" }),
}).then(r => r.json());

// 2) Nutzer bestätigt -> Checkout-Link erstellen
const checkout = await fetch("https://www.miaxklausi.ch/api/agent/v1/checkouts", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + cart.cartToken,
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    cartId: cart.cartId,
    userConfirmed: true,
    successUrl: "https://www.miaxklausi.ch/erfolg",
    cancelUrl: "https://www.miaxklausi.ch/",
  }),
}).then(r => r.json());

// checkout.checkoutUrl -> Nutzer zahlt bei Stripe
// checkout.orderId + checkout.orderAccessToken -> Status abfragen

MCP-Verbindung

{
  "mcpServers": {
    "miaxklausi": {
      "url": "https://www.miaxklausi.ch/mcp"
    }
  }
}

Fehlercodes

Code	Bedeutung
INVALID_REQUEST	Ungültige Eingabe (400)
UNAUTHORIZED	Token fehlt/ungültig (401)
FORBIDDEN	Token passt nicht (403)
PRODUCT_NOT_FOUND	Produkt existiert nicht (404)
PRODUCT_NOT_AVAILABLE	Bereits verkauft/reserviert (409)
CART_NOT_FOUND / CART_EXPIRED	Warenkorb weg/abgelaufen (404/410)
CONFIRMATION_REQUIRED	Nutzerbestätigung fehlt (428)
RATE_LIMITED	Zu viele Anfragen (429)
ORDER_NOT_FOUND / PAYMENT_PENDING	Bestellung offen (404/409)
INTERNAL_ERROR	Serverfehler (500)

Format: { "error": { "code", "message", "retryable", "requestId" } }

Rate-Limit, Einzelstücke & Datenschutz

Rate-Limit: pro IP begrenzt; bei Überschreitung kommt RATE_LIMITED (429).

Einzelstücke: Menge ist immer 1. Verfügbarkeit wird vor dem Checkout erneut geprüft; der Verkauf gilt erst nach verifizierter Stripe-Zahlung.

Idempotenz: Sende einen Idempotency-Key-Header bei POST /carts und POST /checkouts, um Doppelaktionen zu vermeiden.

Datenschutz: Die API gibt keine personenbezogenen Kundendaten aus. Details in der Datenschutzerklärung.

Kontakt

Fragen zur Integration? Über das Kontaktformular.

Hinweis: Ein MCP-Server wird nicht automatisch von allen Agenten gefunden — Nutzer oder Plattformen müssen ihn verbinden. OpenAPI, strukturierte Daten, Sitemap und llms.txt ergänzen die Auffindbarkeit, garantieren sie aber nicht.