{"openapi":"3.1.0","info":{"title":"Mia x Klausi — Agenten-API","version":"1.0.0","description":"Öffentliche API für KI-Agenten: Produkte suchen, Details abrufen, Warenkorb vorbereiten und einen sicheren Stripe-Checkout-Link erstellen. Einzelstücke: jedes Produkt gibt es genau einmal. Ein Kauf gilt erst nach verifizierter Stripe-Zahlung. Fehlerformat: { error: { code, message, retryable, requestId } }. Rate-Limit pro IP (Header konfigurierbar). Idempotency-Key wird bei carts/checkouts unterstützt.","contact":{"name":"Mia x Klausi","url":"https://www.miaxklausi.ch/developers/agents"}},"servers":[{"url":"https://www.miaxklausi.ch/api/agent/v1"}],"security":[{}],"components":{"securitySchemes":{"cartToken":{"type":"http","scheme":"bearer","description":"Cart-Token aus POST /carts (Scopes: carts:write, checkout:create)."},"orderToken":{"type":"http","scheme":"bearer","description":"Order-Token aus POST /checkouts (Scope: orders:read)."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"requestId":{"type":"string"}},"required":["code","message"]}}},"ProductSummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"shortDescription":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"brand":{"type":"string"},"color":{"type":"string"},"condition":{"type":"string"},"size":{"type":"string"},"price":{"type":"number"},"compareAtPrice":{"type":"number"},"currency":{"type":"string","enum":["CHF"]},"availability":{"type":"string","enum":["available","reserved","sold","unavailable"]},"quantity":{"type":"integer"},"images":{"type":"array","items":{"type":"string","format":"uri"}},"productUrl":{"type":"string","format":"uri"},"updatedAt":{"type":"string","format":"date-time"}}},"Cart":{"type":"object","properties":{"cartId":{"type":"string"},"items":{"type":"array","items":{"type":"object"}},"subtotal":{"type":"number"},"shipping":{"type":"number"},"total":{"type":"number"},"currency":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"checkoutAvailable":{"type":"boolean"},"cartToken":{"type":"string","description":"Nur bei POST /carts enthalten."}}},"Checkout":{"type":"object","properties":{"checkoutId":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"},"status":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"orderId":{"type":"string"},"orderAccessToken":{"type":"string"},"currency":{"type":"string"}}},"OrderStatus":{"type":"object","properties":{"orderId":{"type":"string"},"status":{"type":"string","enum":["paid","processing","refunded","expired"]},"total":{"type":"number"},"currency":{"type":"string"},"items":{"type":"array","items":{"type":"object"}}}}}},"paths":{"/products":{"get":{"summary":"Produkte suchen/filtern/sortieren","parameters":[{"name":"query","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"minPrice","in":"query","schema":{"type":"number"},"description":"in CHF"},{"name":"maxPrice","in":"query","schema":{"type":"number"},"description":"in CHF"},{"name":"availableOnly","in":"query","schema":{"type":"boolean"}},{"name":"condition","in":"query","schema":{"type":"string"}},{"name":"brand","in":"query","schema":{"type":"string"}},{"name":"size","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","price_asc","price_desc","relevance"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination-Cursor"}],"responses":{"200":{"description":"Trefferliste","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"}},"nextCursor":{"type":["string","null"]},"total":{"type":"integer"}}}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT / PRODUCT_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"CART_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}":{"get":{"summary":"Produktdetails (id oder slug)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Produktdetails","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSummary"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT / PRODUCT_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"CART_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories":{"get":{"summary":"Rubriken","responses":{"200":{"description":"Rubriken"},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT / PRODUCT_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"CART_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/carts":{"post":{"summary":"Warenkorb erstellen","description":"Unterstützt Idempotency-Key-Header. Gibt cartToken zurück (für weitere Aktionen nötig).","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"quantity":{"type":"integer","enum":[1]}},"required":["productId"]}}}},"responses":{"201":{"description":"Warenkorb","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT / PRODUCT_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"CART_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/carts/{cartId}":{"get":{"summary":"Warenkorb abrufen","security":[{"cartToken":[]}],"parameters":[{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Warenkorb","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT / PRODUCT_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"CART_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/carts/{cartId}/items":{"post":{"summary":"Produkt zum Warenkorb hinzufügen","security":[{"cartToken":[]}],"parameters":[{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"quantity":{"type":"integer","enum":[1]}},"required":["productId"]}}}},"responses":{"200":{"description":"Warenkorb","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT / PRODUCT_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"CART_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/carts/{cartId}/items/{productId}":{"delete":{"summary":"Produkt aus Warenkorb entfernen","security":[{"cartToken":[]}],"parameters":[{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Warenkorb","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT / PRODUCT_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"CART_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkouts":{"post":{"summary":"Sicheren Stripe-Checkout-Link erstellen","description":"Erzeugt AUSSCHLIESSLICH einen Checkout-Link (keine Zahlungsdaten). Erfordert userConfirmed=true (ausdrückliche Nutzerbestätigung). successUrl/cancelUrl werden gegen eine Domain-Allowlist geprüft. Unterstützt Idempotency-Key.","security":[{"cartToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cartId":{"type":"string"},"successUrl":{"type":"string","format":"uri"},"cancelUrl":{"type":"string","format":"uri"},"userConfirmed":{"type":"boolean"},"confirmationToken":{"type":"string"}},"required":["cartId","successUrl","cancelUrl"]}}}},"responses":{"201":{"description":"Checkout-Link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT / PRODUCT_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"CART_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{orderId}":{"get":{"summary":"Bestellstatus (tokengebunden, keine PII)","security":[{"orderToken":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}},{"name":"access_token","in":"query","schema":{"type":"string"},"description":"Alternativ zum Bearer-Header."}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderStatus"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT / PRODUCT_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"CART_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}