{ "openapi": "3.0.3", "info": { "title": "affilinode API", "summary": "Produktdaten, Preise, Vergleiche und Auswertung für Websites und eigene Anwendungen", "description": "Mit der affilinode API liest du Produkte mit aktuellen Angeboten und Affiliate-Links, Vergleiche, Listen, Katalogdaten, Gutscheine und Auswertungen aus deinem Konto – für deine Website, eine App oder eigene Werkzeuge. Du kannst Produkte auch beauftragen, die noch nicht im Katalog stehen, und Kurzlinks anlegen.\n\n## Zugang\n\nJede Anfrage braucht einen Schlüssel aus deinem Konto (Schlüssel beginnen mit `ac_`). Es gibt zwei Arten:\n\n- **Site-Schlüssel** gehören zu einer Website. Sie dürfen alle hier beschriebenen Routen nutzen, außer dem Import von Merkmalen. Die Links in den Antworten tragen die Tracking-IDs dieser Website.\n- **API-Clients** sind für eigene Anwendungen gedacht. Du vergibst jedem Client nur die Berechtigungen, die er braucht:\n\n| Berechtigung | erlaubt |\n| --- | --- |\n| `products:read` | Produkte mit Preisen, Angeboten und Affiliate-Links, Vergleiche, Listen, Suche, Gutscheine, Banner |\n| `catalog:read` | Katalogdaten (Produktarten, Merkmale, Sichten, Änderungen, Kompatibilität, Berater) ohne Affiliate-Links |\n| `products:write` | Merkmale (Datenblattwerte) zu Produkten deines Kontos importieren |\n| `requests:write` | Produktaufträge anlegen und bearbeiten |\n| `reporting:read` | Auswertung (Klicks, Bestellungen, Umsatz) |\n\nDen Schlüssel sendest du im Kopf `Authorization: Bearer ac_…`; alternativ geht `X-API-Key: ac_…`. Jede Route nennt die Berechtigung, die ein API-Client dafür braucht.\n\n## Sprache und Land\n\nMit `locale` (z. B. `de-DE`) wählst du die Sprache der Texte, mit `country` (z. B. `DE`) das Land für Angebote, Preise und Verfügbarkeit. Beides ist unabhängig voneinander: `country=AT&locale=de-DE` liefert deutsche Texte mit österreichischen Angeboten. Ohne Angabe gelten die Standardwerte deiner Website bzw. deines Kontos. Fehlt ein Text in der gewünschten Sprache, kommt die nächstpassende; welche Sprache ein Text hat, steht in `textLocales`.\n\nMit `shops` und `prefer` kannst du die Regeln für Shops je Abruf überschreiben (siehe die Parameter der Routen).\n\n## Kennungen von Produkten\n\nWo ein Produkt angegeben wird, kannst du die Kennung von affilinode oder eine Kennung des Produkts nutzen: `asin:B0CHX1W1XY`, `gtin:4006381333931` oder `mpn:bosch/06019H5202` (Marke und Modellnummer). Mehrere Kennungen trennst du mit Komma (höchstens 50).\n\n## Tarif\n\nManche Funktionen gehören nicht zu jedem Tarif. Welche dein Tarif enthält, zeigt `GET /v1/me` im Feld `planFeatures`. Ruft ein Schlüssel eine Funktion auf, die der Tarif nicht enthält, antwortet die API mit Status 402 oder 403.\n\n## Fehler\n\nFehler kommen mit passendem HTTP-Status und diesem Aufbau:\n\n```json\n{ \"error\": { \"code\": \"validation_failed\", \"message\": \"Die Anfrage ist ungültig\", \"details\": [] } }\n```\n\nWerte am besten den `code` aus; die `message` ist für Menschen gedacht und auf Deutsch.\n\n## Ratenbegrenzung\n\nJe Schlüssel ist die Zahl der Anfragen pro Minute begrenzt. Die Antworten tragen die Köpfe `X-RateLimit-Limit`, `X-RateLimit-Remaining` und `X-RateLimit-Reset`. Bei Überschreitung antwortet die API mit Status 429 und dem Kopf `Retry-After` (Sekunden bis zum nächsten Versuch).\n\n## Zwischenspeicher\n\nAntworten auf GET-Anfragen tragen einen `ETag`. Sendest du ihn beim nächsten Abruf als `If-None-Match`, antwortet die API bei unveränderten Daten mit Status 304 ohne Inhalt. Antworten enthalten Links mit deinen Tracking-IDs und dürfen deshalb nur privat zwischengespeichert werden.\n\n## Mehrere Unterseiten (WordPress-Multisite)\n\nEin Netzwerk aus mehreren WordPress-Seiten nutzt einen Site-Schlüssel. Mit den optionalen Köpfen `X-AC-Blog`, `X-AC-Blog-Name` und `X-AC-Blog-Url` sagst du, welche Unterseite fragt, damit deren Tracking-IDs in die Links kommen.\n\n## Ausprobieren im Browser\n\nDie Dokumentation auf affilinode.com kann lesende Routen (GET) direkt mit deinem Schlüssel aufrufen. Der Schlüssel bleibt dabei in deinem Browser.", "version": "1.0.2", "contact": { "name": "affilinode Support", "url": "https://affilinode.com", "email": "support@affilinode.com" } }, "servers": [ { "url": "https://api.affilinode.com", "description": "Öffentliche API" } ], "tags": [ { "name": "Konto", "description": "Verbindungstest: zu welchem Konto gehört der Schlüssel und was darf er?" }, { "name": "Produkte", "description": "Produkte mit Angeboten, Preisen und Affiliate-Links. Dazu Ersatzteile, Zubehör, Tarife, Vertragsangebote und der Preisverlauf eines Produkts." }, { "name": "Vergleiche", "description": "Produkte nebeneinander vergleichen: Vergleich, A-gegen-B, gespeicherte Vergleichstabellen und Vergleichsdaten." }, { "name": "Listen", "description": "Redaktionelle und automatische Produktlisten (Bestenlisten, Bestseller)." }, { "name": "Deals und Gutscheine", "description": "Preissenkungen, Gutscheine und Rabattcodes sowie die Rückmeldung, dass ein Code kopiert wurde." }, { "name": "Suche", "description": "Produktsuche über Titel, Marke und Kennungen sowie die Suche mit Filtern." }, { "name": "Katalog", "description": "Katalogdaten ohne Affiliate-Links: Produktarten mit Merkmalen, Produkte einer Produktart, Sichten, Änderungen seit einem Zeitpunkt, Produktpaare und Kompatibilität." }, { "name": "Beratung und Empfehlungen", "description": "Alternativen, ähnliche Produkte, Stärken, Bestenlisten je Produktart, Preis-Leistungs-Diagramme und der Produktberater (Kaufberater-Quiz)." }, { "name": "Banner, Looks und Warenkorb", "description": "Werbebanner aus Partnerprogrammen, Shop-my-Look-Bilder und Warenkorb-Links für mehrere Produkte." }, { "name": "Produktaufträge", "description": "Produkte beauftragen, die noch nicht im Katalog stehen. Der Auftrag wird im Hintergrund bearbeitet; du fragst den Stand ab oder wartest kurz auf das Ergebnis." }, { "name": "Auswertung", "description": "Klicks, Einblendungen, Bestellungen und Umsatz aus deinen Partnerprogrammen." }, { "name": "Kurzlinks", "description": "Kurzlinks für Social Media und Messenger anlegen." } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "paths": { "/v1/me": { "get": { "tags": [ "Konto" ], "summary": "Verbindung prüfen", "description": "Liefert zu deinem Schlüssel das Konto, die Art des Schlüssels (Site oder API-Client mit seinen Berechtigungen), die Fähigkeiten deines Tarifs und das Guthaben für KI-Funktionen. Gut für einen ersten Test, ob der Schlüssel funktioniert.\n\nDiese Route steht jedem gültigen Schlüssel offen.", "operationId": "getMe", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "slug", "name" ], "additionalProperties": false }, "features": { "type": "array", "items": { "type": "string" } }, "principal": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "site" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "defaultCountry": { "type": "string" }, "defaultLocale": { "type": "string" } }, "required": [ "type", "id", "name", "defaultCountry", "defaultLocale" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_client" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "products:read", "requests:write", "catalog:read", "reporting:read", "products:write" ] } } }, "required": [ "type", "id", "name", "scopes" ], "additionalProperties": false } ] }, "policies": { "default": { "amazonAssociate": false }, "type": "object", "properties": { "amazonAssociate": { "type": "boolean" } }, "required": [ "amazonAssociate" ], "additionalProperties": false }, "planFeatures": { "default": null, "nullable": true, "type": "array", "items": { "type": "string" } }, "staleShops": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "offers": { "type": "integer" }, "stale": { "type": "integer" }, "newestCheck": { "nullable": true, "type": "string" }, "stuck": { "type": "boolean" } }, "required": [ "name", "type", "offers", "stale", "newestCheck", "stuck" ], "additionalProperties": false } }, "credits": { "default": null, "nullable": true, "type": "object", "properties": { "unmetered": { "type": "boolean" }, "available": { "type": "integer" }, "lowBalance": { "type": "boolean" } }, "required": [ "unmetered", "available", "lowBalance" ], "additionalProperties": false }, "poweredBy": { "default": false, "type": "boolean" } }, "required": [ "tenant", "features", "principal", "policies", "planFeatures", "staleShops", "credits", "poweredBy" ], "additionalProperties": false }, "example": { "tenant": { "id": "2f6c8e1a-3b4d-4c5e-9a0b-1c2d3e4f5a6b", "slug": "mein-blog", "name": "Mein Blog" }, "features": [ "products", "compare", "lists", "search" ], "principal": { "type": "site", "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "name": "meinblog.example", "defaultCountry": "DE", "defaultLocale": "de-DE", "fallbackRouting": null, "geoRouting": null, "allowedCountries": null }, "policies": { "amazonAssociate": false }, "planFeatures": null, "staleShops": [], "credits": { "unmetered": false, "available": 120, "lowBalance": false }, "poweredBy": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products": { "get": { "tags": [ "Produkte" ], "summary": "Produkte abrufen", "description": "Liefert Produkte zu den angegebenen Kennungen: Titel, Bilder, Merkmale, Texte und die Angebote der Shops mit Preisen und Affiliate-Links (inklusive deiner Tracking-IDs). Das ist die Route für Kaufbuttons, Preisvergleiche und Produktboxen.\n\nIn `resolved` steht, welche angefragte Kennung zu welchem Produkt gehört; Kennungen ohne Treffer stehen in `missing`. Fragst du ein Produkt an, das noch Angebote braucht, sucht affilinode im Hintergrund danach – ein späterer Abruf liefert sie dann.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "ids", "required": true, "description": "Produkt-Kennungen, kommagetrennt (höchstens 50): die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`. Doppelte werden zusammengefasst.", "example": "asin:B0CHX1W1XY,gtin:4006381333931" }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "activate", "required": false, "description": "Bei `false` werden die Produkte nur abgefragt und nicht für die laufende Preisaktualisierung vorgemerkt. Gedacht für den Abgleich sehr vieler Kennungen auf einmal (Massenabgleich). Standard: `true`." }, { "schema": { "type": "string", "enum": [ "queue" ] }, "in": "query", "name": "search", "required": false, "description": "Nur zusammen mit `activate=false`: `queue` reiht die Produkte für eine gelegentliche, langsame Angebotssuche ein." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos.", "example": "de-DE" }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland.", "example": "DE" }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Die Produkte mit Angeboten", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductWithReplacement" } }, "resolved": { "type": "object", "additionalProperties": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "string" } } }, "required": [ "products", "resolved", "missing" ], "additionalProperties": false }, "example": { "products": [ { "id": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "title": "Nova X5 128 GB schwarz", "detailedTitle": null, "brand": "Nova", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null } ], "resolved": { "asin:B0CHX1W1XY": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "gtin:4006381333931": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42" }, "missing": [] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/spare-parts": { "get": { "tags": [ "Produkte" ], "summary": "Ersatzteile eines Produkts", "description": "Liefert die Ersatzteile, die zu einem Gerät passen, nach Gruppen geordnet. `fitsProductIds` nennt die Geräte, zu denen das Produkt selbst als Ersatzteil passt.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductSpareParts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produkts: die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "productIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "label", "productIds" ], "additionalProperties": false } }, "fitsProductIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "productId", "groups", "fitsProductIds" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/accessories": { "get": { "tags": [ "Produkte" ], "summary": "Zubehör eines Produkts", "description": "Liefert passendes Zubehör zu einem Produkt, nach Gruppen geordnet. `accessoryForProductIds` nennt die Produkte, zu denen das Produkt selbst als Zubehör passt.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductAccessories", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produkts: die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "productIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "note": { "nullable": true, "type": "string" } }, "required": [ "productId", "note" ], "additionalProperties": false } } }, "required": [ "label", "productIds", "items" ], "additionalProperties": false } }, "accessoryForProductIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "productId", "groups", "accessoryForProductIds" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/tariffs": { "get": { "tags": [ "Produkte" ], "summary": "Tarife zu einem Gerät", "description": "Liefert zu einem Gerät (z. B. Smartphone) die Mobilfunktarife mit Laufzeit, monatlichen und einmaligen Kosten sowie den effektiven Kosten über die Laufzeit.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductTariffs", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Geräts: die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Tarife (1 bis 20). Standard: 10." }, { "schema": { "default": "effective", "type": "string", "enum": [ "effective", "monthly", "upfront" ] }, "in": "query", "name": "sort", "required": false, "description": "Sortierung: `effective` (effektive Kosten, Standard), `monthly` (monatlicher Preis) oder `upfront` (einmalige Kosten)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 60 }, "in": "query", "name": "provider", "required": false, "description": "Nur Tarife dieses Anbieters, z. B. `Telekom`." }, { "schema": { "type": "string", "enum": [ "telekom", "vodafone", "o2", "1und1" ] }, "in": "query", "name": "network", "required": false, "description": "Nur Tarife in diesem Netz: `telekom`, `vodafone`, `o2` oder `1und1`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductWithReplacement" }, "tariffs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "shop": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "type", "name" ], "additionalProperties": false }, "url": { "type": "string" }, "title": { "nullable": true, "type": "string" }, "provider": { "nullable": true, "type": "string" }, "providerInfo": { "default": null, "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "slug": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "network_operator", "brand", "discounter", "reseller", "mvno" ] }, "logoUrl": { "nullable": true, "type": "string" }, "website": { "nullable": true, "type": "string" }, "parentCompany": { "nullable": true, "type": "string" } }, "required": [ "id", "slug", "name", "kind", "logoUrl", "website", "parentCompany" ], "additionalProperties": false }, "network": { "nullable": true, "type": "string", "enum": [ "telekom", "vodafone", "o2", "1und1" ] }, "promo": { "default": null, "nullable": true, "type": "object", "properties": { "price": { "$ref": "#/components/schemas/Money" }, "months": { "nullable": true, "type": "integer" }, "validUntil": { "nullable": true, "type": "string" } }, "required": [ "price", "months", "validUntil" ], "additionalProperties": false }, "smsPrice": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "throttleNote": { "default": null, "nullable": true, "type": "string" }, "lte": { "default": null, "nullable": true, "type": "boolean" }, "maxDownloadMbit": { "default": null, "nullable": true, "type": "integer" }, "maxUploadMbit": { "default": null, "nullable": true, "type": "integer" }, "euRoaming": { "default": null, "nullable": true, "type": "boolean" }, "euRoamingGb": { "default": null, "nullable": true, "type": "number" }, "wifiCalling": { "default": null, "nullable": true, "type": "boolean" }, "volte": { "default": null, "nullable": true, "type": "boolean" }, "esim": { "default": null, "nullable": true, "type": "boolean" }, "multiSim": { "default": null, "nullable": true, "type": "boolean" }, "hotspot": { "default": null, "nullable": true, "type": "boolean" }, "streamingNote": { "default": null, "nullable": true, "type": "string" }, "bonus": { "default": null, "nullable": true, "type": "object", "properties": { "amount": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "note": { "nullable": true, "type": "string" } }, "required": [ "amount", "note" ], "additionalProperties": false }, "cancellationNote": { "default": null, "nullable": true, "type": "string" }, "providerNote": { "default": null, "nullable": true, "type": "string" }, "source": { "default": "feed", "type": "string", "enum": [ "feed", "manual" ] }, "tariffName": { "nullable": true, "type": "string" }, "dataGb": { "nullable": true, "type": "number" }, "unlimitedData": { "type": "boolean" }, "allnetFlat": { "nullable": true, "type": "boolean" }, "smsFlat": { "nullable": true, "type": "boolean" }, "fiveG": { "nullable": true, "type": "boolean" }, "contractMonths": { "nullable": true, "type": "integer" }, "upfrontPrice": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "monthlyPrice": { "$ref": "#/components/schemas/Money" }, "connectionFee": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "totalCost": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "effectiveMonthly": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "checkedAt": { "nullable": true, "type": "string" } }, "required": [ "id", "shop", "url", "title", "provider", "providerInfo", "network", "promo", "smsPrice", "throttleNote", "lte", "maxDownloadMbit", "maxUploadMbit", "euRoaming", "euRoamingGb", "wifiCalling", "volte", "esim", "multiSim", "hotspot", "streamingNote", "bonus", "cancellationNote", "providerNote", "source", "tariffName", "dataGb", "unlimitedData", "allnetFlat", "smsFlat", "fiveG", "contractMonths", "upfrontPrice", "monthlyPrice", "connectionFee", "totalCost", "effectiveMonthly", "checkedAt" ], "additionalProperties": false } } }, "required": [ "product", "tariffs" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/contract-offers": { "get": { "tags": [ "Produkte" ], "summary": "Vertragsangebote zu einem Produkt", "description": "Liefert zu einem Vertragsprodukt (Internet, Strom, Gas, Streaming-Abo) die Angebote der Anbieter mit Laufzeit, Preisen und den effektiven Kosten.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductContractOffers", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Vertragsprodukts: die ID von affilinode oder `gtin:…`, `mpn:marke/modell`." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Angebote (1 bis 20). Standard: 10." }, { "schema": { "default": "effective", "type": "string", "enum": [ "effective", "monthly", "total" ] }, "in": "query", "name": "sort", "required": false, "description": "Sortierung: `effective` (effektive Kosten, Standard), `monthly` (monatlicher Preis) oder `total` (Gesamtkosten über die Laufzeit)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "in": "query", "name": "provider", "required": false, "description": "Nur Angebote dieses Anbieters." }, { "schema": { "type": "integer", "minimum": 0, "maximum": 60 }, "in": "query", "name": "maxTermMonths", "required": false, "description": "Höchste Vertragslaufzeit in Monaten (0 bis 60)." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 10000 }, "in": "query", "name": "minMbit", "required": false, "description": "Mindestgeschwindigkeit in Mbit/s (bei Internetverträgen)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductWithReplacement" }, "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "family": { "type": "string", "enum": [ "internet_dsl", "strom", "gas", "streaming_abo" ] }, "provider": { "nullable": true, "type": "string" }, "title": { "nullable": true, "type": "string" }, "url": { "type": "string" }, "priceKind": { "type": "string", "enum": [ "monthly", "yearly", "one_time" ] }, "amount": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "setupFee": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "termMonths": { "nullable": true, "type": "integer" }, "promo": { "nullable": true, "type": "object", "properties": { "phases": { "type": "array", "items": { "type": "object", "properties": { "months": { "type": "integer" }, "amount": { "$ref": "#/components/schemas/Money" } }, "required": [ "months", "amount" ], "additionalProperties": false } }, "validUntil": { "nullable": true, "type": "string" }, "bonus": { "nullable": true, "type": "object", "properties": { "amount": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "note": { "nullable": true, "type": "string" } }, "required": [ "amount", "note" ], "additionalProperties": false } }, "required": [ "phases", "validUntil", "bonus" ], "additionalProperties": false }, "kind": { "type": "string", "enum": [ "offer", "compare" ] }, "totalCost": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "totalCostWithBonus": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "effectiveMonthly": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "effectiveMonthlyWithBonus": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "bonusAmount": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "horizonMonths": { "nullable": true, "type": "integer" }, "regularMonthly": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "attributes": { "type": "object", "additionalProperties": {} }, "facts": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "label", "value" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "feed", "manual" ] }, "checkedAt": { "nullable": true, "type": "string" } }, "required": [ "id", "family", "provider", "title", "url", "priceKind", "amount", "setupFee", "termMonths", "promo", "kind", "totalCost", "totalCostWithBonus", "effectiveMonthly", "effectiveMonthlyWithBonus", "bonusAmount", "horizonMonths", "regularMonthly", "attributes", "facts", "source", "checkedAt" ], "additionalProperties": false } }, "bonusDefault": { "default": false, "type": "boolean" } }, "required": [ "product", "offers", "bonusDefault" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/price-history": { "get": { "tags": [ "Produkte" ], "summary": "Preisverlauf eines Produkts", "description": "Liefert den Preisverlauf der letzten Tage mit dem Verlauf je Tag, dem günstigsten Preis je Shop und einer Zusammenfassung (aktuell, niedrigster, höchster und durchschnittlicher Preis). Shops, deren Preise nicht verwendet werden dürfen, fehlen und stehen in `excludedShopTypes`.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductPriceHistory", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produkts: die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`." }, { "schema": { "default": 90, "type": "integer", "minimum": 7, "maximum": 365 }, "in": "query", "name": "days", "required": false, "description": "Zeitraum in Tagen (7 bis 365). Standard: 90." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "detailedTitle": { "default": null, "nullable": true, "type": "string" } }, "required": [ "id", "title", "detailedTitle" ], "additionalProperties": false }, "country": { "type": "string" }, "locale": { "type": "string" }, "currency": { "nullable": true, "type": "string" }, "days": { "type": "integer" }, "from": { "type": "string" }, "to": { "type": "string" }, "series": { "type": "array", "items": { "type": "object", "properties": { "shop": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ] }, "name": { "type": "string" }, "logoUrl": { "nullable": true, "type": "string" }, "own": { "type": "boolean" } }, "required": [ "id", "type", "name", "logoUrl", "own" ], "additionalProperties": false }, "current": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "price": { "type": "number" }, "total": { "type": "number" }, "availability": { "type": "string", "enum": [ "in_stock", "limited", "preorder", "out_of_stock", "unknown" ] } }, "required": [ "date", "price", "total", "availability" ], "additionalProperties": false } } }, "required": [ "shop", "current", "points" ], "additionalProperties": false } }, "best": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "total": { "type": "number" }, "shopId": { "type": "string" } }, "required": [ "date", "total", "shopId" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "current": { "nullable": true, "type": "object", "properties": { "total": { "$ref": "#/components/schemas/Money" }, "shopId": { "type": "string" }, "shopName": { "type": "string" }, "checkedAt": { "type": "string" } }, "required": [ "total", "shopId", "shopName", "checkedAt" ], "additionalProperties": false }, "lowest": { "nullable": true, "type": "object", "properties": { "total": { "$ref": "#/components/schemas/Money" }, "date": { "type": "string" }, "shopId": { "type": "string" }, "shopName": { "type": "string" } }, "required": [ "total", "date", "shopId", "shopName" ], "additionalProperties": false }, "highest": { "nullable": true, "type": "object", "properties": { "total": { "$ref": "#/components/schemas/Money" }, "date": { "type": "string" }, "shopId": { "type": "string" }, "shopName": { "type": "string" } }, "required": [ "total", "date", "shopId", "shopName" ], "additionalProperties": false }, "average": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "since": { "nullable": true, "type": "string" }, "dayCount": { "type": "integer" } }, "required": [ "current", "lowest", "highest", "average", "since", "dayCount" ], "additionalProperties": false }, "excludedShopTypes": { "type": "array", "items": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ] } } }, "required": [ "product", "country", "locale", "currency", "days", "from", "to", "series", "best", "summary", "excludedShopTypes" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/specs": { "put": { "tags": [ "Produkte" ], "summary": "Merkmale eines Produkts importieren", "description": "Trägt Merkmale (Datenblattwerte) für ein Produkt deines Kontos ein, etwa aus einer Herstellerdatenbank. Die Werte werden wie bei der Pflege im Dashboard geprüft (Feld der Produktart, Typ, Auswahlwert, Einheit). Auswahlfelder nehmen auch die Bezeichnung oder gängige Schreibweisen an, z. B. `wi-fi` für WLAN.\n\nDer Import füllt nur leere Merkmale und aktualisiert Werte, die aus derselben `source` stammen. Von Hand gepflegte Werte und Werte aus der Datenblatt-Auslese oder Anreicherung überschreibt er nie; sie dürfen umgekehrt die importierten Werte jederzeit ersetzen. Wiederholte Aufrufe mit denselben Daten ändern nichts. Titel, Preise, Bilder und Kennungen sind nicht Teil des Imports.\n\nDie Antwort nennt je Merkmal: `applied` (eingetragen), `unchanged` (schon so vorhanden), `skipped_existing` (anderer Wert vorhanden, nicht überschrieben) oder `invalid` (mit Grund). Ist das Produkt unbekannt, antwortet die Route mit Status 404.\n\nNur mit einem API-Client, der die Berechtigung `products:write` hat. Mit einem Site-Schlüssel antwortet die Route mit Status 403.", "operationId": "putProductSpecs", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:write" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produkts: ID von affilinode oder `asin:`, `gtin:`, `mpn:/`.", "example": "mpn:beispielmarke/BM-100" }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" }, { "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 100 } }, { "type": "object", "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 40 } ] } } ] }, "description": "Merkmale als Objekt `{ \"feldschlüssel\": wert }` (höchstens 60). Die Schlüssel stehen in den Daten der Produktart (`getCategory`). Wert je nach Feld: Text, Zahl (oder `{ \"value\": 6.1, \"unit\": \"in\" }`), `true`/`false`, Auswahlwert, Liste bei Mehrfachauswahl." }, "source": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,39}$", "description": "Name deiner Quelle, z. B. `csa-dcl-import` (2 bis 40 Zeichen: a–z, 0–9, Punkt, Binde- und Unterstrich). Nur Werte derselben Quelle aktualisiert ein späterer Import." }, "sourceNote": { "type": "string", "maxLength": 200, "description": "Herkunftshinweis zu den Werten, z. B. „CSA DCL, Stand 2026-10-27“ (höchstens 200 Zeichen)." }, "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Stand der Daten als Datum `JJJJ-MM-TT`; ersetzt den Hinweis, wenn dieser fehlt." } }, "required": [ "values", "source" ] }, "example": { "values": { "radio_protocols": [ "thread", "wi-fi" ], "matter_version": "1.4", "matter_device_type": 266, "matter_certificate": "CSA00000AAA00000-24", "matter_certified_since": "2024-03-15", "matter_firmware": "1.2.3" }, "source": "csa-dcl-import", "sourceNote": "CSA DCL, Stand 2026-10-27" } } }, "description": "Die Merkmale und woher sie stammen." }, "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "productId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identifier": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "applied", "unchanged", "skipped_existing", "invalid", "not_found" ] }, "reason": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "status": { "type": "string", "enum": [ "applied", "unchanged", "skipped_existing", "invalid" ] }, "reason": { "type": "string" } }, "required": [ "field", "status" ], "additionalProperties": false } } }, "required": [ "index", "productId", "identifier", "status", "fields" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "items": { "type": "object", "properties": { "applied": { "type": "integer" }, "unchanged": { "type": "integer" }, "skipped_existing": { "type": "integer" }, "invalid": { "type": "integer" }, "not_found": { "type": "integer" } }, "required": [ "applied", "unchanged", "skipped_existing", "invalid", "not_found" ], "additionalProperties": false }, "fields": { "type": "object", "properties": { "applied": { "type": "integer" }, "unchanged": { "type": "integer" }, "skipped_existing": { "type": "integer" }, "invalid": { "type": "integer" } }, "required": [ "applied", "unchanged", "skipped_existing", "invalid" ], "additionalProperties": false } }, "required": [ "items", "fields" ], "additionalProperties": false } }, "required": [ "results", "summary" ], "additionalProperties": false }, "example": { "results": [ { "index": 0, "productId": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "identifier": "mpn:beispielmarke/BM-100", "status": "applied", "fields": [ { "field": "radio_protocols", "status": "applied" }, { "field": "matter_version", "status": "applied" }, { "field": "matter_device_type", "status": "applied" }, { "field": "matter_certificate", "status": "unchanged" }, { "field": "matter_certified_since", "status": "skipped_existing", "reason": "Wert ist von Hand gepflegt und gesperrt" }, { "field": "matter_firmware", "status": "applied" } ] } ], "summary": { "items": { "applied": 1, "unchanged": 0, "skipped_existing": 0, "invalid": 0, "not_found": 0 }, "fields": { "applied": 4, "unchanged": 1, "skipped_existing": 1, "invalid": 0 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/specs/batch": { "post": { "tags": [ "Produkte" ], "summary": "Merkmale mehrerer Produkte importieren", "description": "Wie `putProductSpecs`, aber für bis zu 100 Produkte in einem Aufruf. Jeder Eintrag nennt sein Produkt mit `productId` oder `identifier` (z. B. `mpn:ikea/E2201`). Die Antwort enthält je Eintrag ein Ergebnis in derselben Reihenfolge (`applied`, `unchanged`, `skipped_existing`, `invalid` oder `not_found`, mit Grund) und Zähler für alle Einträge. Ein fehlerhafter Eintrag hindert die anderen nicht. Der Aufruf lässt sich gefahrlos wiederholen.\n\nNur mit einem API-Client, der die Berechtigung `products:write` hat. Mit einem Site-Schlüssel antwortet die Route mit Status 403.", "operationId": "importProductSpecs", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:write" ], "parameters": [ { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "ID des Produkts bei affilinode (alternativ `identifier`)." }, "identifier": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$", "description": "Kennung des Produkts, z. B. `mpn:ikea/E2201` oder `gtin:…` (alternativ `productId`)." }, "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" }, { "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 100 } }, { "type": "object", "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 40 } ] } } ] }, "description": "Merkmale als Objekt `{ \"feldschlüssel\": wert }` (höchstens 60), wie bei `putProductSpecs`." }, "source": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,39}$", "description": "Name deiner Quelle, z. B. `csa-dcl-import`." }, "sourceNote": { "type": "string", "maxLength": 200, "description": "Herkunftshinweis, z. B. „CSA DCL, Stand 2026-10-27“." }, "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Stand der Daten als Datum `JJJJ-MM-TT`." } }, "required": [ "values", "source" ] }, "description": "Einträge, je einer pro Produkt." } }, "required": [ "items" ] }, "example": { "items": [ { "identifier": "mpn:beispielmarke/BM-100", "values": { "matter_version": "1.4", "matter_device_type": 266 }, "source": "csa-dcl-import", "sourceNote": "CSA DCL, Stand 2026-10-27" }, { "productId": "9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60", "values": { "matter_version": "1.2" }, "source": "csa-dcl-import", "asOf": "2026-10-27" } ] } } }, "description": "Die Einträge, höchstens 100." }, "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "productId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identifier": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "applied", "unchanged", "skipped_existing", "invalid", "not_found" ] }, "reason": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "status": { "type": "string", "enum": [ "applied", "unchanged", "skipped_existing", "invalid" ] }, "reason": { "type": "string" } }, "required": [ "field", "status" ], "additionalProperties": false } } }, "required": [ "index", "productId", "identifier", "status", "fields" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "items": { "type": "object", "properties": { "applied": { "type": "integer" }, "unchanged": { "type": "integer" }, "skipped_existing": { "type": "integer" }, "invalid": { "type": "integer" }, "not_found": { "type": "integer" } }, "required": [ "applied", "unchanged", "skipped_existing", "invalid", "not_found" ], "additionalProperties": false }, "fields": { "type": "object", "properties": { "applied": { "type": "integer" }, "unchanged": { "type": "integer" }, "skipped_existing": { "type": "integer" }, "invalid": { "type": "integer" } }, "required": [ "applied", "unchanged", "skipped_existing", "invalid" ], "additionalProperties": false } }, "required": [ "items", "fields" ], "additionalProperties": false } }, "required": [ "results", "summary" ], "additionalProperties": false }, "example": { "results": [ { "index": 0, "productId": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "identifier": "mpn:beispielmarke/BM-100", "status": "applied", "fields": [ { "field": "matter_version", "status": "applied" }, { "field": "matter_device_type", "status": "applied" } ] }, { "index": 1, "productId": null, "identifier": null, "status": "not_found", "reason": "Produkt nicht gefunden (nur Produkte des eigenen Kontos)", "fields": [] } ], "summary": { "items": { "applied": 1, "unchanged": 0, "skipped_existing": 0, "invalid": 0, "not_found": 1 }, "fields": { "applied": 2, "unchanged": 0, "skipped_existing": 0, "invalid": 0 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/compare": { "get": { "tags": [ "Vergleiche" ], "summary": "Produkte vergleichen", "description": "Stellt mehrere Produkte nebeneinander: die Produkte mit ihren Angeboten und eine Tabelle der Merkmale (`rows`) mit Bestwerten und Unterschieden. `comparisonText` enthält, falls vorhanden, einen fertigen Vergleichstext.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "compareProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "ids", "required": true, "description": "Produkt-Kennungen, kommagetrennt (höchstens 50): die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`. Doppelte werden zusammengefasst.", "example": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42,9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60" }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "replace", "required": false, "description": "Bei `true` erscheint statt eines nicht mehr verfügbaren Produkts dessen Nachfolger bzw. Ersatz (Feld `replacement`)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland.", "example": "DE" }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductWithReplacement" } }, "resolved": { "type": "object", "additionalProperties": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "nullable": true, "type": "string" } }, "best": { "type": "array", "items": { "type": "integer" } }, "differs": { "type": "boolean" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] } }, "required": [ "group", "key", "label", "values", "best", "differs", "compare", "importance" ], "additionalProperties": false } }, "comparisonText": { "default": null, "nullable": true, "type": "string" } }, "required": [ "products", "resolved", "missing", "rows", "comparisonText" ], "additionalProperties": false }, "example": { "products": [ { "id": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "title": "Nova X5 128 GB schwarz", "detailedTitle": null, "brand": "Nova", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null }, { "id": "9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60", "title": "Lumen S3 128 GB blau", "detailedTitle": null, "brand": "Lumen", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "349.00", "currency": "EUR", "formatted": "349,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "349.00", "currency": "EUR", "formatted": "349,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null } ], "resolved": { "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60": "9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60" }, "missing": [], "rows": [ { "group": "Display", "key": "display_size", "label": "Bildschirmdiagonale", "values": [ "6,6 Zoll", "6,3 Zoll" ], "best": [ 0 ], "differs": true, "compare": "higher", "importance": "key" } ], "comparisonText": null } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/compare/data": { "get": { "tags": [ "Vergleiche" ], "summary": "Vergleichsdaten (ohne Affiliate-Links)", "description": "Liefert die Merkmalsdaten für den Vergleich von 2 bis 10 Produkten der gleichen Produktart, ohne Angebote und Affiliate-Links. Für Seiten, die die Darstellung selbst bauen.\n\nBerechtigung für API-Clients: `catalog:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getComparisonData", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "ids", "required": true, "description": "Produkt-Kennungen, kommagetrennt (2 bis 10): die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProduct" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "unit": { "nullable": true, "type": "string" }, "unitSymbol": { "nullable": true, "type": "string" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] }, "values": { "type": "array", "items": { "nullable": true, "type": "object", "properties": { "display": { "type": "string" }, "raw": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ] }, "source": { "type": "string" }, "sourceUrl": { "nullable": true, "type": "string" }, "confidence": { "nullable": true, "type": "number" }, "locked": { "type": "boolean" }, "updatedAt": { "type": "string" } }, "required": [ "display", "raw", "source", "sourceUrl", "confidence", "locked", "updatedAt" ], "additionalProperties": false } }, "best": { "type": "array", "items": { "type": "integer" } }, "differs": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "integer" } } }, "required": [ "group", "key", "label", "type", "unit", "unitSymbol", "compare", "importance", "values", "best", "differs", "missing" ], "additionalProperties": false } }, "facts": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "fieldKey": { "type": "string" }, "label": { "type": "string" }, "rank": { "type": "integer" }, "of": { "type": "integer" }, "percentile": { "type": "integer" }, "kind": { "type": "string", "enum": [ "best_in_category", "top_10", "typical", "bottom_10" ] } }, "required": [ "productId", "fieldKey", "label", "rank", "of", "percentile", "kind" ], "additionalProperties": false } } }, "required": [ "productType", "products", "rows", "facts" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/versus": { "get": { "tags": [ "Vergleiche" ], "summary": "A gegen B", "description": "Stellt zwei oder drei Produkte gegenüber: Unterschiede nach Bereichen, Gesamturteil, für wen welches Produkt passt und häufige Fragen. Dazu dieselben Daten wie beim Vergleich.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getVersus", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "ids", "required": true, "description": "Zwei bis drei Produkt-Kennungen, kommagetrennt." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "replace", "required": false, "description": "Bei `true` erscheint statt eines nicht mehr verfügbaren Produkts dessen Nachfolger bzw. Ersatz (Feld `replacement`)." }, { "schema": { "default": 6, "type": "integer", "minimum": 0, "maximum": 10 }, "in": "query", "name": "faq", "required": false, "description": "Anzahl der häufigen Fragen (0 bis 10). Standard: 6." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "amazonPrices", "required": false, "description": "Bei `true` darf der Vergleich Preise von Amazon in seine Aussagen einbeziehen. Standard: nein." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductWithReplacement" } }, "resolved": { "type": "object", "additionalProperties": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "nullable": true, "type": "string" } }, "best": { "type": "array", "items": { "type": "integer" } }, "differs": { "type": "boolean" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] } }, "required": [ "group", "key", "label", "values", "best", "differs", "compare", "importance" ], "additionalProperties": false } }, "comparisonText": { "default": null, "nullable": true, "type": "string" }, "versus": { "type": "object", "properties": { "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" } }, "required": [ "key", "label", "labelPlural" ], "additionalProperties": false }, "title": { "type": "string" }, "areas": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string", "enum": [ "display", "chip", "storage", "camera", "battery", "power", "wireless", "sound", "size", "shield", "climate", "light", "spec" ] }, "winner": { "nullable": true, "type": "integer" }, "scores": { "type": "array", "items": { "type": "number" } }, "summary": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "nullable": true, "type": "string" } }, "winners": { "type": "array", "items": { "type": "integer" } }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] }, "text": { "nullable": true, "type": "string" } }, "required": [ "key", "label", "values", "winners", "compare", "importance", "text" ], "additionalProperties": false } } }, "required": [ "key", "label", "icon", "winner", "scores", "summary", "fields" ], "additionalProperties": false } }, "differences": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "nullable": true, "type": "string" } }, "winners": { "type": "array", "items": { "type": "integer" } }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] }, "text": { "nullable": true, "type": "string" } }, "required": [ "key", "label", "values", "winners", "compare", "importance", "text" ], "additionalProperties": false } }, "overall": { "type": "object", "properties": { "winner": { "nullable": true, "type": "integer" }, "wins": { "type": "array", "items": { "type": "integer" } }, "summary": { "type": "string" } }, "required": [ "winner", "wins", "summary" ], "additionalProperties": false }, "buyers": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "title": { "type": "string" }, "areas": { "type": "array", "items": { "type": "string" } }, "points": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" } }, "required": [ "productId", "title", "areas", "points", "text" ], "additionalProperties": false } }, "faq": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "key", "question", "answer" ], "additionalProperties": false } }, "basis": { "type": "string" }, "pricesOmitted": { "type": "boolean" } }, "required": [ "productType", "title", "areas", "differences", "overall", "buyers", "faq", "basis", "pricesOmitted" ], "additionalProperties": false } }, "required": [ "products", "resolved", "missing", "rows", "comparisonText", "versus" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/versus/suggestions": { "get": { "tags": [ "Vergleiche" ], "summary": "Vorschläge für Vergleiche", "description": "Schlägt Produktpaare vor, die sich zum Gegenüberstellen eignen – zu einem Produkt oder zu einer Produktart.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getVersusSuggestions", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "query", "name": "product", "required": false, "description": "Kennung des Produkts, zu dem Gegenspieler vorgeschlagen werden sollen." }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Schlüssel einer Produktart, z. B. `smartphone`. Liefert Paare aus dieser Produktart." }, { "schema": { "default": 6, "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Vorschläge (1 bis 20). Standard: 6." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (Standard) betrachtet alle Produkte deines Kontos, `site` nur die Produkte, die deine Website schon zeigt. `site` geht nur mit einem Site-Schlüssel (sonst Status 403)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brand": { "nullable": true, "type": "string" }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "required": [ "id", "title", "brand", "productType" ], "additionalProperties": false } }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "same_type", "similar_price", "similar_specs", "same_series", "same_brand", "compared_together", "popular", "successor", "alternative" ] } } }, "required": [ "key", "products", "score", "reasons" ], "additionalProperties": false } } }, "required": [ "suggestions" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/compare-tables/{id}": { "get": { "tags": [ "Vergleiche" ], "summary": "Gespeicherte Vergleichstabelle", "description": "Liefert eine im Dashboard angelegte Vergleichstabelle mit ihren Produkten, Zeilen und Hervorhebungen. Tabellen aus der Produktsuche aktualisieren sich selbst.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCompareTable", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kennung der Vergleichstabelle (aus dem Dashboard)." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "replace", "required": false, "description": "Bei `true` erscheint statt eines nicht mehr verfügbaren Produkts dessen Nachfolger bzw. Ersatz (Feld `replacement`)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "table": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "updatedAt": { "type": "string" }, "onlyDifferences": { "type": "boolean" }, "highlight": { "nullable": true, "type": "object", "properties": { "productId": { "type": "string" }, "badge": { "type": "string" } }, "required": [ "productId", "badge" ], "additionalProperties": false } }, "required": [ "id", "name", "updatedAt", "onlyDifferences", "highlight" ], "additionalProperties": false }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductWithReplacement" } }, "rows": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "standard" ] }, "key": { "type": "string", "enum": [ "image", "title", "rating", "review", "price", "button", "pros", "cons", "highlights" ] }, "label": { "nullable": true, "type": "string" } }, "required": [ "type", "key", "label" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "field" ] }, "key": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "string" }, "values": { "type": "array", "items": { "nullable": true, "type": "string" } }, "best": { "type": "array", "items": { "type": "integer" } }, "differs": { "type": "boolean" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] } }, "required": [ "type", "key", "label", "group", "values", "best", "differs", "compare", "importance" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "yesno" ] }, "values": { "type": "array", "items": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "boolean" } ] } }, "differs": { "type": "boolean" } }, "required": [ "type", "key", "label", "kind", "values", "differs" ], "additionalProperties": false } ] } }, "missing": { "type": "array", "items": { "type": "string" } }, "comparisonText": { "default": null, "nullable": true, "type": "string" } }, "required": [ "table", "products", "rows", "missing", "comparisonText" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/lists": { "get": { "tags": [ "Listen" ], "summary": "Listen auflisten", "description": "Liefert die Produktlisten deines Kontos mit Typ, Titel, Anzahl der Einträge und letzter Änderung.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getLists", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "q", "required": false, "description": "Suchbegriff im Titel der Liste." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "lists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "manual", "dynamic", "shop" ] }, "title": { "nullable": true, "type": "string" }, "itemCount": { "type": "integer" }, "updatedAt": { "type": "string" } }, "required": [ "id", "type", "title", "itemCount", "updatedAt" ], "additionalProperties": false } } }, "required": [ "lists" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/lists/amazon": { "get": { "tags": [ "Listen" ], "summary": "Amazon-Bestseller zu einem Stichwort", "description": "Liefert eine automatische Liste mit Bestsellern oder Neuerscheinungen zu einem Stichwort. Die Produkte werden beim ersten Abruf angelegt; `list.source.status` zeigt, ob die Liste noch aufgebaut wird (`building`).\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getAmazonList", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 2, "maxLength": 100 }, "in": "query", "name": "keyword", "required": true, "description": "Stichwort, nach dem gesucht wird." }, { "schema": { "default": "bestseller", "type": "string", "enum": [ "bestseller", "new" ] }, "in": "query", "name": "sort", "required": false, "description": "`bestseller` (Standard) oder `new` (Neuerscheinungen)." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 10 }, "in": "query", "name": "limit", "required": false, "description": "Anzahl der Produkte (1 bis 10). Standard: 10." }, { "schema": { "type": "string", "pattern": "^\\d{1,20}$" }, "in": "query", "name": "node", "required": false, "description": "Optional: Nummer der Amazon-Kategorie (BrowseNode), um die Liste einzugrenzen." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "replace", "required": false, "description": "Bei `true` erscheint statt eines nicht mehr verfügbaren Produkts dessen Nachfolger bzw. Ersatz (Feld `replacement`)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "manual", "dynamic", "shop" ] }, "title": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "updatedAt": { "type": "string" }, "source": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "amazon_search" ] }, "keyword": { "type": "string" }, "sort": { "type": "string", "enum": [ "bestseller", "new" ] }, "status": { "type": "string", "enum": [ "building", "ready", "error" ] }, "refreshedAt": { "nullable": true, "type": "string" } }, "required": [ "type", "keyword", "sort", "status", "refreshedAt" ], "additionalProperties": false } }, "required": [ "id", "type", "title", "description", "updatedAt" ], "additionalProperties": false }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListItem" } }, "total": { "type": "integer" } }, "required": [ "list", "items", "total" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/lists/{id}": { "get": { "tags": [ "Listen" ], "summary": "Liste abrufen", "description": "Liefert eine Produktliste mit ihren Einträgen in der festgelegten Reihenfolge – jeweils mit Produkt, Angeboten, redaktionellem Hinweis und Badge (z. B. „Testsieger“).\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getList", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung der Liste (aus dem Dashboard oder von `getLists`).", "example": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8" }, { "schema": { "default": 24, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Anzahl der Einträge je Seite (1 bis 100). Standard: 24.", "example": 10 }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 10000 }, "in": "query", "name": "offset", "required": false, "description": "Anzahl der Einträge, die übersprungen werden (für die nächste Seite). Standard: 0." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "replace", "required": false, "description": "Bei `true` erscheint statt eines nicht mehr verfügbaren Produkts dessen Nachfolger bzw. Ersatz (Feld `replacement`)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "manual", "dynamic", "shop" ] }, "title": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "updatedAt": { "type": "string" }, "source": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "amazon_search" ] }, "keyword": { "type": "string" }, "sort": { "type": "string", "enum": [ "bestseller", "new" ] }, "status": { "type": "string", "enum": [ "building", "ready", "error" ] }, "refreshedAt": { "nullable": true, "type": "string" } }, "required": [ "type", "keyword", "sort", "status", "refreshedAt" ], "additionalProperties": false } }, "required": [ "id", "type", "title", "description", "updatedAt" ], "additionalProperties": false }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListItem" } }, "total": { "type": "integer" } }, "required": [ "list", "items", "total" ], "additionalProperties": false }, "example": { "list": { "id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8", "type": "manual", "title": "Die besten Smartphones bis 400 Euro", "description": null, "updatedAt": "2026-10-18T12:00:00.000Z" }, "items": [ { "position": 1, "badge": "Testsieger", "note": "Bester Allrounder", "product": { "id": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "title": "Nova X5 128 GB schwarz", "detailedTitle": null, "brand": "Nova", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null } }, { "position": 2, "badge": null, "note": null, "product": { "id": "9e3a7c52-61b8-4d0f-a2c4-35f7d8e19b60", "title": "Lumen S3 128 GB blau", "detailedTitle": null, "brand": "Lumen", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "349.00", "currency": "EUR", "formatted": "349,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "349.00", "currency": "EUR", "formatted": "349,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null } } ], "total": 2 } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/deals": { "get": { "tags": [ "Deals und Gutscheine" ], "summary": "Aktuelle Preissenkungen", "description": "Liefert Produkte, deren bester Preis nachweislich gefallen ist, mit dem Rückgang in Prozent gegenüber dem niedrigsten Preis der 30 Tage davor und dem Tag der Senkung. Je nach Tarif verfügbar.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getDeals", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 400, "pattern": "^[a-z0-9_,]*$" }, "in": "query", "name": "type", "required": false, "description": "Nur Produkte dieser Produktarten, Schlüssel kommagetrennt, z. B. `smartphone,tablet`.", "example": "smartphone" }, { "schema": { "type": "integer", "minimum": 3, "maximum": 80 }, "in": "query", "name": "minDrop", "required": false, "description": "Mindestrückgang in Prozent (3 bis 80).", "example": 10 }, { "schema": { "type": "string", "maxLength": 400, "pattern": "^[\\p{L}\\p{N}_ .+/()\\-,;=]*$" }, "in": "query", "name": "filter", "required": false, "description": "Merkmalsfilter `feld=wert1,wert2;feld2=wert`: mehrere Werte eines Merkmals mit Komma (ODER), mehrere Merkmale mit Strichpunkt (UND), höchstens 5 Merkmale und 20 Werte je Merkmal. Produkte ohne das Merkmal werden nicht geliefert. Unbekannte Merkmale oder Werte ergeben 400." }, { "schema": { "type": "integer", "minimum": 7, "maximum": 365 }, "in": "query", "name": "best", "required": false, "description": "Nur Deals, deren aktueller Bestpreis der niedrigste der letzten N Tage ist (7 bis 365). Gilt nur, wenn die Preisaufzeichnung den Zeitraum ganz abdeckt." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 10 }, "in": "query", "name": "minOffers", "required": false, "description": "Mindestzahl Shops mit aktuellem, lieferbarem Preis für Neuware (1 bis 10)." }, { "schema": { "default": 12, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Einträge (1 bis 50). Standard: 12.", "example": 12 }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "badge": { "nullable": true, "type": "string" }, "note": { "nullable": true, "type": "string" }, "product": { "$ref": "#/components/schemas/ProductWithReplacement" }, "deal": { "type": "object", "properties": { "dropPercent": { "type": "integer" }, "since": { "nullable": true, "type": "string" }, "lowestDays": { "default": null, "nullable": true, "type": "integer" }, "belowAverage": { "default": null, "nullable": true, "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "shops": { "type": "integer" } }, "required": [ "amount", "shops" ], "additionalProperties": false }, "comparableShops": { "default": 0, "type": "integer" } }, "required": [ "dropPercent", "since", "lowestDays", "belowAverage", "comparableShops" ], "additionalProperties": false } }, "required": [ "position", "badge", "note", "product", "deal" ], "additionalProperties": false } }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "additionalProperties": false }, "example": { "items": [ { "position": 1, "badge": null, "note": null, "product": { "id": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "title": "Nova X5 128 GB schwarz", "detailedTitle": null, "brand": "Nova", "mpn": "NX5-128-BK", "gtins": [ "4006381333931" ], "productClass": "goods", "productType": { "key": "smartphone", "label": "Smartphone", "path": [ "product", "smartphone" ] }, "category": null, "locale": "de-DE", "textLocales": null, "country": "DE", "images": [ { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null } ], "badge": null, "highlights": [ "6,6 Zoll AMOLED-Display", "5.000 mAh Akku" ], "texts": { "short": "Solides Smartphone mit starkem Akku.", "long": null, "verdict": null, "social": null }, "aiTexts": null, "prosCons": null, "review": null, "specs": [ { "group": "Display", "items": [ { "key": "display_size", "label": "Bildschirmdiagonale", "value": "6,6 Zoll", "raw": 6.6, "unit": "inch", "compare": "higher", "importance": "key" } ] } ], "attributions": [], "profile": null, "completeness": { "filled": 12, "required": 14, "missing": [ "weight", "ip_rating" ] }, "offers": [ { "id": "0b6f2d1a-7c3e-4a58-9d41-2e8f6a0c5b13", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "feed", "name": "Beispiel-Shop", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/0b6f2d1a", "cartUrl": null, "price": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": true, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null }, { "id": "3d9a1e7b-5f02-4c86-b1a3-6c4e8d2f0a97", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null, "own": false }, "country": "DE", "title": "Nova X5 128 GB schwarz", "url": "https://www.beispiel-shop.example/angebot/3d9a1e7b", "cartUrl": null, "price": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "oldPrice": null, "shipping": { "amount": "0.00", "currency": "EUR", "formatted": "0,00 €" }, "total": { "amount": "329.00", "currency": "EUR", "formatted": "329,00 €" }, "savings": null, "availability": "in_stock", "availabilityText": "Auf Lager", "delivery": { "text": "1–2 Werktage", "minDays": 1, "maxDays": 2, "fast": true }, "condition": "new", "checkedAt": "2026-10-19T06:30:00.000Z", "priceAgeHours": 2, "priceStale": false, "isBest": false, "packQuantity": 1, "unitPrice": null, "priceInsight": null, "salesRank": null } ], "linkOffers": [], "ebayOffers": [], "documents": [], "status": "available", "activityState": "active", "offersStatus": "available", "updatedAt": "2026-10-19T06:30:00.000Z", "variantOf": null, "variantLabel": null, "variants": [], "lowestVariant": null, "isModel": false, "variantAxes": [], "priceRange": null, "replacement": null }, "deal": { "dropPercent": 14, "since": "2026-10-17" } } ], "total": 1 } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/coupons": { "get": { "tags": [ "Deals und Gutscheine" ], "summary": "Gutscheine und Aktionen", "description": "Liefert Gutscheincodes, Rabattaktionen und Gratisversand-Angebote der Händler, optional zu einem Shop, Händler oder Produkt.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCoupons", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "shop", "required": false, "description": "Nur Gutscheine dieses Shops (Shop-ID aus dem Dashboard)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "merchant", "required": false, "description": "Nur Gutscheine dieses Händlers (Name)." }, { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "query", "name": "product", "required": false, "description": "Kennung des Produkts: die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`." }, { "schema": { "type": "string" }, "in": "query", "name": "kind", "required": false, "description": "Nur diese Arten, kommagetrennt: `code` (Gutscheincode), `offer` (Aktion), `free_shipping` (Gratisversand).", "example": "code,free_shipping" }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Einträge (1 bis 50). Standard: 10.", "example": 10 }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "shop": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "logoUrl": { "nullable": true, "type": "string" } }, "required": [ "id", "type", "name", "logoUrl" ], "additionalProperties": false }, "merchant": { "type": "object", "properties": { "id": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "kind": { "type": "string", "enum": [ "code", "offer", "free_shipping" ] }, "code": { "nullable": true, "type": "string" }, "title": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "terms": { "nullable": true, "type": "string" }, "discount": { "nullable": true, "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "enum": [ "percent", "amount" ] }, "currency": { "nullable": true, "type": "string" }, "formatted": { "type": "string" } }, "required": [ "value", "type", "currency", "formatted" ], "additionalProperties": false }, "minOrderValue": { "nullable": true, "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" }, "formatted": { "type": "string" } }, "required": [ "amount", "currency", "formatted" ], "additionalProperties": false }, "startsAt": { "nullable": true, "type": "string" }, "endsAt": { "nullable": true, "type": "string" }, "url": { "nullable": true, "type": "string" }, "exclusive": { "type": "boolean" }, "revealOpensLink": { "type": "boolean" }, "source": { "type": "string", "enum": [ "awin", "tradedoubler", "webgains", "manual", "creator" ] } }, "required": [ "id", "shop", "merchant", "kind", "code", "title", "description", "terms", "discount", "minOrderValue", "startsAt", "endsAt", "url", "exclusive", "revealOpensLink", "source" ], "additionalProperties": false } }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "additionalProperties": false }, "example": { "items": [ { "id": "a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d", "shop": { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "type": "awin", "name": "Elektro-Markt", "logoUrl": null }, "merchant": { "id": "12345", "name": "Elektro-Markt" }, "kind": "code", "code": "HERBST10", "title": "10 % auf alle Haushaltsgeräte", "description": null, "terms": "Mindestbestellwert 50 €", "discount": { "type": "percent", "value": "10", "currency": null, "formatted": "10 %" }, "minOrderValue": { "amount": "50.00", "currency": "EUR", "formatted": "50,00 €" }, "startsAt": "2026-10-01T00:00:00.000Z", "endsAt": "2026-10-31T23:59:59.000Z", "url": "https://www.elektro-markt.example/gutschein?ref=ab12cd34", "exclusive": false, "revealOpensLink": false, "source": "awin" } ], "total": 1 } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/creator-codes/{id}/copied": { "post": { "tags": [ "Deals und Gutscheine" ], "summary": "Rückmeldung: Rabattcode kopiert", "description": "Meldet, dass ein Besucher einen eigenen Rabattcode kopiert hat. Gezählt wird nur die Summe je Tag und Ort, keine Person. Unbekannte oder abgelaufene Codes werden stillschweigend ignoriert; die Antwort ist immer leer.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "reportCreatorCodeCopied", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Rabattcodes (aus dem Dashboard)." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "default": "api", "type": "string", "enum": [ "embed", "plugin", "api" ], "description": "Ort: `embed` (eingebettete Box), `plugin` (WordPress) oder `api` (eigene Anwendung). Standard: `api`." } } } } }, "description": "Wo der Code kopiert wurde." }, "responses": { "204": { "description": "Erfolgreich, keine Antwortdaten", "content": { "application/json": { "schema": { "type": "string", "nullable": true, "enum": [ null ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/search": { "get": { "tags": [ "Suche" ], "summary": "Produkte suchen", "description": "Sucht Produkte nach Titel, Marke, ASIN, EAN oder Modellnummer und liefert kompakte Treffer mit Bild und bestem Preis.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "searchProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "in": "query", "name": "q", "required": true, "description": "Suchbegriff oder Kennung.", "example": "nova x5" }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Nur Treffer dieser Produktart (Schlüssel), z. B. `smartphone`." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Treffer (1 bis 50). Standard: 20.", "example": 5 }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHit" } }, "total": { "type": "integer" } }, "required": [ "hits", "total" ], "additionalProperties": false }, "example": { "hits": [ { "id": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "title": "Nova X5 128 GB schwarz", "brand": "Nova", "productType": { "key": "smartphone", "label": "Smartphone" }, "image": { "url": "https://bilder.beispiel-shop.example/nova-x5.webp", "width": 800, "height": 800, "alt": "Nova X5 in Schwarz", "srcset": null, "source": "origin", "imageRights": "hotlink", "editRights": "none", "cutout": null }, "bestPrice": { "amount": "319.00", "currency": "EUR", "formatted": "319,00 €" }, "offerCount": 2, "status": "available", "identifiers": [ { "type": "asin", "value": "B0CHX1W1XY" }, { "type": "gtin", "value": "4006381333931" } ] } ], "total": 1 } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/search": { "get": { "tags": [ "Suche" ], "summary": "Produktsuche mit Filtern", "description": "Sucht Produkte einer Produktart mit Filtern und Facetten (Auswahlmöglichkeiten mit Trefferzahlen) und blättert seitenweise. Gedacht für Kategorieseiten mit Filterleiste. Die Produkte kommen ohne Angebote und Affiliate-Links.\n\nFilter gibst du als `filter[]` an: `filter[brand]=Bosch,Makita`, `filter[price]=50..200` (auch `..100` oder `150..`), `filter[availability]=available` und für Merkmale der Produktart `filter[voltage]=18..`, `filter[chuck_type]=a,b` oder `filter[brushless_motor]=true`. Merkmalsfilter brauchen den Parameter `type`. Höchstens 20 Filter.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "searchProductsFaceted", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "q", "required": false, "description": "Suchbegriff." }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Schlüssel der Produktart, z. B. `smartphone`." }, { "schema": { "type": "string", "maxLength": 1000 }, "in": "query", "name": "facets", "required": false, "description": "Facetten (Auswahlmöglichkeiten mit Trefferzahlen), kommagetrennt und in dieser Reihenfolge, höchstens 12, z. B. `brand,price,availability,field:voltage`. Ohne Angabe gelten die Standardfacetten." }, { "schema": { "type": "string", "pattern": "^(relevance|popular|title|updated|-?price|-?field:[a-z0-9_]{1,64})$" }, "in": "query", "name": "sort", "required": false, "description": "Sortierung: `relevance` (Standard mit Suchbegriff), `popular` (Standard sonst), `title`, `updated`, `price`, `-price`, `field:` oder `-field:` (nur Zahlenmerkmale)." }, { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "page", "required": false, "description": "Seite (ab 1). Standard: 1." }, { "schema": { "default": 12, "type": "integer", "minimum": 1, "maximum": 48 }, "in": "query", "name": "perPage", "required": false, "description": "Treffer je Seite (1 bis 48). Standard: 12." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (Standard) betrachtet alle Produkte deines Kontos, `site` nur die Produkte, die deine Website schon zeigt. `site` geht nur mit einem Site-Schlüssel (sonst Status 403)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProduct" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" }, "pages": { "type": "integer" }, "sort": { "type": "string" }, "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "facets": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "brand", "availability", "field" ] }, "type": { "type": "string", "enum": [ "values" ] }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "selected": { "type": "boolean" } }, "required": [ "value", "label", "count", "selected" ], "additionalProperties": false } } }, "required": [ "key", "kind", "type", "label", "values" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "price", "field" ] }, "type": { "type": "string", "enum": [ "range" ] }, "label": { "type": "string" }, "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" }, "count": { "type": "integer" }, "unit": { "nullable": true, "type": "string" }, "unitSymbol": { "nullable": true, "type": "string" }, "currency": { "nullable": true, "type": "string" }, "selected": { "nullable": true, "type": "object", "properties": { "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" } }, "required": [ "min", "max" ], "additionalProperties": false } }, "required": [ "key", "kind", "type", "label", "min", "max", "count", "unit", "unitSymbol", "currency", "selected" ], "additionalProperties": false } ] } } }, "required": [ "items", "total", "page", "perPage", "pages", "sort", "productType", "facets" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/categories": { "get": { "tags": [ "Katalog" ], "summary": "Produktarten auflisten", "description": "Liefert alle Produktarten des Katalogs (z. B. Smartphone, Akkuschrauber) mit Anzahl der Produkte.\n\nBerechtigung für API-Clients: `catalog:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCategories", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "links", "required": false, "description": "Bei `true` kommen Querverweise auf verwandte Produktarten mit." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "parentKey": { "nullable": true, "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" }, "abstract": { "type": "boolean" }, "productCount": { "type": "integer" }, "totalProductCount": { "type": "integer" }, "link": { "type": "boolean" }, "canonicalKey": { "type": "string" }, "canonicalParentKey": { "nullable": true, "type": "string" }, "canonicalPath": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "parentKey", "label", "labelPlural", "abstract", "productCount", "totalProductCount" ], "additionalProperties": false } } }, "required": [ "categories" ], "additionalProperties": false }, "example": { "categories": [ { "key": "smartphone", "parentKey": "mobile_device", "label": "Smartphone", "labelPlural": "Smartphones", "abstract": false, "productCount": 412, "totalProductCount": 412 } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/categories/{type}": { "get": { "tags": [ "Katalog" ], "summary": "Produktart mit Merkmalen", "description": "Liefert eine Produktart mit ihren Merkmalen: Gruppen, Bezeichnungen, Einheiten, Auswahlwerte und wie Werte bewertet werden (höher oder niedriger ist besser). Die Merkmale sind die Grundlage für Filter und Vergleiche.\n\nBerechtigung für API-Clients: `catalog:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCategory", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "path", "name": "type", "required": true, "description": "Schlüssel der Produktart, z. B. `smartphone` (aus `getCategories`)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "parentKey": { "nullable": true, "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" }, "abstract": { "type": "boolean" }, "path": { "type": "array", "items": { "type": "string" } }, "googleProductCategory": { "nullable": true, "type": "object", "properties": { "id": { "type": "integer" }, "path": { "type": "string" } }, "required": [ "id", "path" ], "additionalProperties": false }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "string" }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] }, "required": { "type": "boolean" }, "filterable": { "type": "boolean" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "unit": { "nullable": true, "type": "string" }, "unitSymbol": { "nullable": true, "type": "string" }, "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" }, "options": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } }, "variantAxis": { "type": "boolean" } }, "required": [ "key", "type", "label", "group", "importance", "required", "filterable", "compare", "unit", "unitSymbol", "min", "max", "options", "variantAxis" ], "additionalProperties": false } } }, "required": [ "key", "parentKey", "label", "labelPlural", "abstract", "path", "googleProductCategory", "groups", "fields" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/categories/{type}/products": { "get": { "tags": [ "Katalog" ], "summary": "Produkte einer Produktart", "description": "Liefert die Produkte einer Produktart ohne Angebote und Affiliate-Links, mit Filtern, Facetten und Fortsetzung über `nextCursor`.\n\nFilter nach Merkmalen der Produktart gibst du als `f.` an: Zahlenbereiche als `f.leistung=18..36`, Optionen als `f.farbe=schwarz,weiss`, Ja/Nein als `f.wlan=true`. Welche Merkmale es gibt, liefert `getCategory`.\n\nSortierung: `popular` (Standard), `title`, `updated`, `price`, `-price` (absteigend), `field:` oder `-field:`.\n\nBerechtigung für API-Clients: `catalog:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCategoryProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "path", "name": "type", "required": true, "description": "Schlüssel der Produktart, z. B. `smartphone`." }, { "schema": { "type": "string", "maxLength": 500 }, "in": "query", "name": "brand", "required": false, "description": "Nur diese Marken, kommagetrennt, z. B. `Bosch,Makita`." }, { "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "in": "query", "name": "q", "required": false, "description": "Suchbegriff im Titel oder in der Marke (mindestens 2 Zeichen)." }, { "schema": { "default": "popular", "type": "string", "pattern": "^(popular|title|updated|-?price|-?field:[a-z0-9_]{1,64})$" }, "in": "query", "name": "sort", "required": false, "description": "Sortierung, siehe Beschreibung. Standard: `popular`." }, { "schema": { "default": 24, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Einträge in der Antwort. Die erlaubten Werte stehen im Schema." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false, "description": "Fortsetzung: der Wert `nextCursor` aus der vorigen Antwort. Ohne Angabe beginnt die Liste von vorn." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProduct" } }, "total": { "type": "integer" }, "facets": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogFacet" } }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "items", "total", "facets", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/views": { "get": { "tags": [ "Katalog" ], "summary": "Sichten auflisten", "description": "Liefert die vorbereiteten Sichten auf den Katalog – feste Kombinationen aus Produktart und Filtern, z. B. „Akkuschrauber bis 18 V“.\n\nBerechtigung für API-Clients: `catalog:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getViews", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Nur Sichten dieser Produktart (Schlüssel)." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "views": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "productTypeKey": { "type": "string" }, "label": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "filters": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "key", "productTypeKey", "label", "description", "filters" ], "additionalProperties": false } } }, "required": [ "views" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/views/{key}/products": { "get": { "tags": [ "Katalog" ], "summary": "Produkte einer Sicht", "description": "Liefert die Produkte einer Sicht ohne Angebote und Affiliate-Links. Zusätzliche Filter wirken zusätzlich zu den Filtern der Sicht.\n\nFilter nach Merkmalen der Produktart gibst du als `f.` an: Zahlenbereiche als `f.leistung=18..36`, Optionen als `f.farbe=schwarz,weiss`, Ja/Nein als `f.wlan=true`. Welche Merkmale es gibt, liefert `getCategory`.\n\nSortierung: `popular` (Standard), `title`, `updated`, `price`, `-price` (absteigend), `field:` oder `-field:`.\n\nBerechtigung für API-Clients: `catalog:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getViewProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "path", "name": "key", "required": true, "description": "Schlüssel der Sicht (aus `getViews`)." }, { "schema": { "type": "string", "maxLength": 500 }, "in": "query", "name": "brand", "required": false, "description": "Nur diese Marken, kommagetrennt." }, { "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "in": "query", "name": "q", "required": false, "description": "Suchbegriff im Titel oder in der Marke (mindestens 2 Zeichen)." }, { "schema": { "default": "popular", "type": "string", "pattern": "^(popular|title|updated|-?price|-?field:[a-z0-9_]{1,64})$" }, "in": "query", "name": "sort", "required": false, "description": "Sortierung, siehe Beschreibung. Standard: `popular`." }, { "schema": { "default": 24, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Einträge in der Antwort. Die erlaubten Werte stehen im Schema." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false, "description": "Fortsetzung: der Wert `nextCursor` aus der vorigen Antwort. Ohne Angabe beginnt die Liste von vorn." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProduct" } }, "total": { "type": "integer" }, "facets": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogFacet" } }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "items", "total", "facets", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/catalog/changes": { "get": { "tags": [ "Katalog" ], "summary": "Änderungen seit einem Zeitpunkt", "description": "Liefert die Produkte, die sich seit einem Zeitpunkt geändert haben (neu, aktualisiert oder entfernt). Damit hältst du eine eigene Datenbank aktuell, ohne alles neu zu laden. Lies so lange mit `cursor` weiter, bis `nextCursor` leer ist.\n\nBerechtigung für API-Clients: `catalog:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCatalogChanges", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "since", "required": true, "description": "Zeitpunkt als Datum mit Uhrzeit nach ISO 8601, z. B. `2026-10-01T00:00:00Z`." }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Nur Änderungen dieser Produktart (Schlüssel)." }, { "schema": { "type": "string", "maxLength": 300 }, "in": "query", "name": "cursor", "required": false, "description": "Fortsetzung: der Wert `nextCursor` aus der vorigen Antwort. Ohne Angabe beginnt die Liste von vorn." }, { "schema": { "default": 500, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Einträge (1 bis 1000). Standard: 500." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productTypeKey": { "type": "string" }, "activityState": { "nullable": true, "type": "string" }, "status": { "nullable": true, "type": "string" }, "deleted": { "type": "boolean" }, "updatedAt": { "type": "string" } }, "required": [ "id", "productTypeKey", "activityState", "status", "deleted", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "items", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/pairs": { "get": { "tags": [ "Katalog" ], "summary": "Passende Produktpaare", "description": "Schlägt für eine Produktart Paare von Produkten vor, die sich gut gegenüberstellen lassen, mit einer Bewertung von 0 bis 1 und den Gründen.\n\nBerechtigung für API-Clients: `catalog:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductPairs", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": true, "description": "Schlüssel der Produktart, z. B. `smartphone`." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false, "description": "Fortsetzung: der Wert `nextCursor` aus der vorigen Antwort. Ohne Angabe beginnt die Liste von vorn." }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Anzahl der Ausgangsprodukte je Seite (1 bis 100). Standard: 50." }, { "schema": { "default": 3, "type": "integer", "minimum": 1, "maximum": 10 }, "in": "query", "name": "perProduct", "required": false, "description": "Vorschläge je Ausgangsprodukt (1 bis 10). Standard: 3." }, { "schema": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "in": "query", "name": "minScore", "required": false, "description": "Mindestbewertung eines Paares von 0 bis 1. Standard: 0,5." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "pairs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "productIds": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "string" } ] }, "minItems": 2, "maxItems": 2 }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "productIds", "score", "reasons" ], "additionalProperties": false } }, "productCount": { "type": "integer" }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "pairs", "productCount", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/compatibility/systems": { "get": { "tags": [ "Katalog" ], "summary": "Systeme für den Kompatibilitätscheck", "description": "Liefert die Systeme, für die es Kompatibilitätsangaben gibt (z. B. Akku-Plattformen oder Smart-Home-Standards), mit der Zahl der passenden Produkte.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCompatibilitySystems", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Nur Systeme, die für diese Produktart gelten (Schlüssel)." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "kind", "required": false, "description": "Nur Systeme dieser Arten, kommagetrennt: `hub`, `ecosystem`, `radio`, `battery`, `socket` oder `lens_mount`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "systems": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "hub", "ecosystem", "radio", "battery", "socket", "lens_mount" ] }, "kindLabel": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "key", "kind", "kindLabel", "label", "count" ], "additionalProperties": false } } }, "required": [ "systems" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/compatibility": { "get": { "tags": [ "Katalog" ], "summary": "Produkte, die zu einem System passen", "description": "Beantwortet „Passt das zu meinem …?“: Liefert die Produkte (ohne Affiliate-Links), die mit einem System kompatibel sind, jeweils mit den Belegen dafür – oder prüft ein einzelnes Produkt gegen das System.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCompatibleProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 80 }, "in": "query", "name": "system", "required": true, "description": "Schlüssel des Systems in der Form `:`, z. B. `hub:zha` oder `battery:makitalxt18v` (aus `getCompatibilitySystems`)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "product", "required": false, "description": "Optional: Kennung eines Produkts, das gegen das System geprüft werden soll." }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "type", "required": false, "description": "Nur Produkte dieser Produktart (Schlüssel)." }, { "schema": { "default": "popular", "type": "string", "enum": [ "popular", "price", "-price", "title" ] }, "in": "query", "name": "sort", "required": false, "description": "Sortierung: `popular` (Standard), `price`, `-price` oder `title`." }, { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "page", "required": false, "description": "Seite (ab 1). Standard: 1." }, { "schema": { "default": 12, "type": "integer", "minimum": 1, "maximum": 48 }, "in": "query", "name": "perPage", "required": false, "description": "Treffer je Seite (1 bis 48). Standard: 12." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "list" ] }, "system": { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "hub", "ecosystem", "radio", "battery", "socket", "lens_mount" ] }, "kindLabel": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "kind", "kindLabel", "label" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brand": { "nullable": true, "type": "string" }, "model": { "nullable": true, "type": "string" }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "activityState": { "type": "string", "enum": [ "catalog", "active", "paused" ] }, "status": { "type": "string", "enum": [ "available", "unavailable", "discontinued" ] }, "image": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "keySpecs": { "type": "array", "items": { "$ref": "#/components/schemas/SpecItem" } }, "specCount": { "type": "integer" }, "completeness": { "$ref": "#/components/schemas/SpecCompleteness" }, "bestPrice": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "offerCount": { "type": "integer" }, "popularity": { "type": "object", "properties": { "clicks30d": { "type": "integer" }, "impressions30d": { "type": "integer" }, "orders30d": { "type": "integer" }, "sites": { "type": "integer" }, "lastRequestedAt": { "nullable": true, "type": "string" } }, "required": [ "clicks30d", "impressions30d", "orders30d", "sites", "lastRequestedAt" ], "additionalProperties": false }, "updatedAt": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "sourceLabel": { "type": "string" }, "sourceUrl": { "nullable": true, "type": "string" }, "basis": { "type": "string", "enum": [ "spec", "listing" ] }, "field": { "nullable": true, "type": "string" } }, "required": [ "source", "sourceLabel", "sourceUrl", "basis", "field" ], "additionalProperties": false } } }, "required": [ "id", "title", "brand", "model", "productType", "activityState", "status", "image", "keySpecs", "specCount", "completeness", "bestPrice", "offerCount", "popularity", "updatedAt", "evidence" ], "additionalProperties": false } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" }, "pages": { "type": "integer" }, "sort": { "type": "string" }, "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "required": [ "mode", "system", "items", "total", "page", "perPage", "pages", "sort", "productType" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "check" ] }, "system": { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "hub", "ecosystem", "radio", "battery", "socket", "lens_mount" ] }, "kindLabel": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "kind", "kindLabel", "label" ], "additionalProperties": false }, "product": { "$ref": "#/components/schemas/CatalogProduct" }, "verdict": { "type": "string", "enum": [ "yes", "no", "unknown" ] }, "reason": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "sourceLabel": { "type": "string" }, "sourceUrl": { "nullable": true, "type": "string" }, "basis": { "type": "string", "enum": [ "spec", "listing" ] }, "field": { "nullable": true, "type": "string" } }, "required": [ "source", "sourceLabel", "sourceUrl", "basis", "field" ], "additionalProperties": false } } }, "required": [ "mode", "system", "product", "verdict", "reason", "evidence" ], "additionalProperties": false } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/alternatives": { "get": { "tags": [ "Beratung und Empfehlungen" ], "summary": "Alternativen zu einem Produkt", "description": "Liefert Alternativen zu einem Produkt: günstigere, besser ausgestattete oder Nachfolger – jeweils mit dem Grund. In `settings` steht, mit welchen Schwellen gesucht wurde.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductAlternatives", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produkts: die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`." }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "kinds", "required": false, "description": "Gewünschte Arten, kommagetrennt: `cheaper`, `better`, `successor`. Standard: alle." }, { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 6 }, "in": "query", "name": "limit", "required": false, "description": "Anzahl der Vorschläge je Art (1 bis 6). Standard: 1." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 90 }, "in": "query", "name": "cheaperBy", "required": false, "description": "Mindestersparnis in Prozent für „günstiger“ (1 bis 90). Standard: 10." }, { "schema": { "default": 20, "type": "integer", "minimum": 0, "maximum": 200 }, "in": "query", "name": "maxPremium", "required": false, "description": "Höchster Aufpreis in Prozent für „besser ausgestattet“ (0 bis 200). Standard: 20." }, { "schema": { "default": 60, "type": "integer", "minimum": 10, "maximum": 100 }, "in": "query", "name": "minSimilarity", "required": false, "description": "Mindestähnlichkeit in Prozent (10 bis 100). Standard: 60." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (Standard) betrachtet alle Produkte deines Kontos, `site` nur die Produkte, die deine Website schon zeigt. `site` geht nur mit einem Site-Schlüssel (sonst Status 403)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cheaper", "better", "successor" ] }, "label": { "type": "string" }, "neutralLabel": { "type": "string" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "similarity": { "nullable": true, "type": "integer" }, "reasons": { "type": "array", "items": { "type": "string" } }, "tradeOffs": { "type": "array", "items": { "type": "string" } }, "amazonPrice": { "type": "boolean" }, "product": { "$ref": "#/components/schemas/CatalogProduct" } }, "required": [ "kind", "label", "neutralLabel", "productId", "similarity", "reasons", "tradeOffs", "amazonPrice", "product" ], "additionalProperties": false } }, "settings": { "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "string", "enum": [ "cheaper", "better", "successor" ] } }, "limit": { "type": "integer" }, "cheaperBy": { "type": "integer" }, "maxPremium": { "type": "integer" }, "minSimilarity": { "type": "integer" } }, "required": [ "kinds", "limit", "cheaperBy", "maxPremium", "minSimilarity" ], "additionalProperties": false } }, "required": [ "productId", "productType", "items", "settings" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/complements": { "get": { "tags": [ "Beratung und Empfehlungen" ], "summary": "Dazu passt auch", "description": "Liefert andere Geräte, die man zu einem Produkt oft zusätzlich kauft (zum Beispiel ein Türsensor zum Wassersensor derselben Marke) – weder Zubehör noch Alternative. Es erscheinen nur Beziehungen, die bestätigt sind.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductComplements", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produkts: die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`." }, { "schema": { "default": 4, "type": "integer", "minimum": 1, "maximum": 6 }, "in": "query", "name": "limit", "required": false, "description": "Anzahl der Produkte (1 bis 6). Standard: 4." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (Standard) betrachtet alle Produkte deines Kontos, `site` nur die Produkte, die deine Website schon zeigt. `site` geht nur mit einem Site-Schlüssel (sonst Status 403)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reason": { "nullable": true, "type": "string" }, "product": { "$ref": "#/components/schemas/CatalogProduct" } }, "required": [ "productId", "reason", "product" ], "additionalProperties": false } } }, "required": [ "productId", "items" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/similar": { "get": { "tags": [ "Beratung und Empfehlungen" ], "summary": "Ähnliche Produkte", "description": "Liefert Produkte der gleichen Produktart, die dem angegebenen Produkt in den Merkmalen ähneln, ohne Affiliate-Links.\n\nBerechtigung für API-Clients: `catalog:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getSimilarProducts", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produkts: die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Produkte (1 bis 50). Standard: 10." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/CatalogProduct" }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "product", "score", "reasons" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/products/{id}/highlights": { "get": { "tags": [ "Beratung und Empfehlungen" ], "summary": "Stärken eines Produkts „auf einen Blick“", "description": "Liefert die wichtigsten Kennwerte eines Produkts mit Einordnung in seine Produktart: Wo liegt es im Vergleich zu den anderen (z. B. „besser als 80 % der Smartphones“)?\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductHighlights", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 120, "pattern": "^(?:[0-9a-f-]{36}|(?:asin|gtin|mpn):[\\p{L}\\p{N}][\\p{L}\\p{N}._/+#&()'\" -]{0,99})$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produkts: die ID von affilinode oder `asin:…`, `gtin:…`, `mpn:marke/modell`." }, { "schema": { "default": 6, "type": "integer", "minimum": 1, "maximum": 12 }, "in": "query", "name": "count", "required": false, "description": "Anzahl der Kennwerte (1 bis 12). Standard: 6." }, { "schema": { "type": "string", "maxLength": 600 }, "in": "query", "name": "fields", "required": false, "description": "Nur diese Merkmale, Schlüssel kommagetrennt. Ohne Angabe wählt affilinode die wichtigsten." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productType": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" } }, "required": [ "key", "label", "labelPlural" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "nullable": true, "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "icon": { "type": "string", "enum": [ "display", "chip", "storage", "camera", "battery", "power", "wireless", "sound", "size", "shield", "climate", "light", "spec" ] }, "value": { "type": "string" }, "raw": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ] }, "unit": { "nullable": true, "type": "string" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] }, "sample": { "nullable": true, "type": "integer" }, "rating": { "nullable": true, "type": "object", "properties": { "percentile": { "type": "integer" }, "betterThan": { "type": "integer" }, "sameAs": { "type": "integer" }, "worseThan": { "type": "integer" }, "tier": { "type": "integer" }, "summary": { "type": "string" }, "text": { "type": "string" } }, "required": [ "percentile", "betterThan", "sameAs", "worseThan", "tier", "summary", "text" ], "additionalProperties": false } }, "required": [ "key", "label", "group", "icon", "value", "raw", "unit", "compare", "importance", "sample", "rating" ], "additionalProperties": false } }, "minSample": { "type": "integer" } }, "required": [ "productId", "productType", "items", "minSample" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/categories/{type}/top": { "get": { "tags": [ "Beratung und Empfehlungen" ], "summary": "Beste Produkte einer Produktart", "description": "Liefert die besten Produkte einer Produktart nach Bewertung, Preis-Leistung oder einem Merkmal – mit Titel und Badge für eine Bestenliste.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCategoryTop", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "path", "name": "type", "required": true, "description": "Schlüssel der Produktart, z. B. `smartphone`." }, { "schema": { "default": "rating", "type": "string", "pattern": "^(rating|value|value:[a-z0-9_]{1,64}|field:[a-z0-9_]{1,64})$" }, "in": "query", "name": "by", "required": false, "description": "Rangfolge: `rating` (Testnote, Standard), `value` (Preis-Leistung), `value:` (Merkmalswert je Euro) oder `field:` (Wert eines Merkmals)." }, { "schema": { "default": 3, "type": "integer", "minimum": 1, "maximum": 10 }, "in": "query", "name": "limit", "required": false, "description": "Anzahl der Produkte (1 bis 10). Standard: 3." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (Standard) betrachtet alle Produkte deines Kontos, `site` nur die Produkte, die deine Website schon zeigt. `site` geht nur mit einem Site-Schlüssel (sonst Status 403)." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] }, "in": "query", "name": "available", "required": false, "description": "Bei `false` kommen auch Produkte ohne aktuellen Preis in die Liste (nicht bei `by=value`)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" } }, "required": [ "key", "label", "labelPlural" ], "additionalProperties": false }, "by": { "type": "string", "enum": [ "rating", "value", "field" ] }, "field": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "unit": { "nullable": true, "type": "string" }, "unitSymbol": { "nullable": true, "type": "string" }, "direction": { "type": "string", "enum": [ "higher", "lower" ] } }, "required": [ "key", "label", "unit", "unitSymbol", "direction" ], "additionalProperties": false }, "coreFields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string", "enum": [ "higher", "lower" ] } }, "required": [ "key", "label", "direction" ], "additionalProperties": false } }, "title": { "type": "string" }, "badge": { "type": "string" }, "currency": { "nullable": true, "type": "string" }, "total": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "value": { "type": "number" }, "valueText": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "badge": { "nullable": true, "type": "string" }, "product": { "$ref": "#/components/schemas/CatalogProduct" } }, "required": [ "rank", "productId", "value", "valueText", "reasons", "badge", "product" ], "additionalProperties": false } }, "generatedAt": { "type": "string" } }, "required": [ "productType", "by", "field", "coreFields", "title", "badge", "currency", "total", "items", "generatedAt" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/categories/{type}/scatter": { "get": { "tags": [ "Beratung und Empfehlungen" ], "summary": "Preis-Leistungs-Diagramm", "description": "Liefert die Daten für ein Diagramm, das Preis und ein Merkmal gegenüberstellt: je Produkt ein Punkt, dazu die Achsen und Wertebereiche.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCategoryScatter", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "path", "name": "type", "required": true, "description": "Schlüssel der Produktart, z. B. `smartphone`." }, { "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "in": "query", "name": "field", "required": true, "description": "Schlüssel des Merkmals für die senkrechte Achse (aus `getCategory`)." }, { "schema": { "default": 60, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Anzahl der Punkte (1 bis 100). Standard: 60." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (Standard) betrachtet alle Produkte deines Kontos, `site` nur die Produkte, die deine Website schon zeigt. `site` geht nur mit einem Site-Schlüssel (sonst Status 403)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "highlight", "required": false, "description": "Kennung eines Produkts, das im Diagramm hervorgehoben werden soll." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "labelPlural": { "type": "string" } }, "required": [ "key", "label", "labelPlural" ], "additionalProperties": false }, "x": { "type": "object", "properties": { "label": { "type": "string" }, "currency": { "nullable": true, "type": "string" }, "direction": { "type": "string", "enum": [ "lower" ] }, "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" } }, "required": [ "label", "currency", "direction", "min", "max" ], "additionalProperties": false }, "y": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "unit": { "nullable": true, "type": "string" }, "unitSymbol": { "nullable": true, "type": "string" }, "direction": { "nullable": true, "type": "string", "enum": [ "higher", "lower" ] }, "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" } }, "required": [ "key", "label", "unit", "unitSymbol", "direction", "min", "max" ], "additionalProperties": false }, "title": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "price": { "type": "number" }, "priceText": { "type": "string" }, "value": { "type": "number" }, "valueText": { "type": "string" }, "image": { "nullable": true, "type": "object", "properties": { "url": { "type": "string" }, "width": { "nullable": true, "type": "integer" }, "height": { "nullable": true, "type": "integer" } }, "required": [ "url", "width", "height" ], "additionalProperties": false }, "shop": { "nullable": true, "type": "string" }, "highlight": { "type": "boolean" } }, "required": [ "productId", "title", "price", "priceText", "value", "valueText", "image", "shop", "highlight" ], "additionalProperties": false } }, "total": { "type": "integer" }, "outliers": { "type": "integer" }, "highlight": { "nullable": true, "type": "object", "properties": { "productId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "shown", "not_found", "other_type", "no_price", "no_value" ] } }, "required": [ "productId", "state" ], "additionalProperties": false }, "amazonPrice": { "type": "boolean" }, "generatedAt": { "type": "string" } }, "required": [ "productType", "x", "y", "title", "points", "total", "outliers", "highlight", "amazonPrice", "generatedAt" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/advisors/{id}": { "get": { "tags": [ "Beratung und Empfehlungen" ], "summary": "Produktberater abrufen", "description": "Liefert einen im Dashboard angelegten Produktberater (Kaufberater-Quiz) mit Einleitung, Fragen und Antwortmöglichkeiten.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getAdvisor", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produktberaters (aus dem Dashboard)." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "locale": { "type": "string" }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "intro": { "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "single", "multi", "yesno", "range" ] }, "title": { "type": "string" }, "help": { "type": "string" }, "showIf": { "nullable": true, "type": "object", "properties": { "question": { "type": "string", "pattern": "^[a-z0-9]{1,16}$" }, "answers": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]{1,16}$" } } }, "required": [ "question", "answers" ], "additionalProperties": false }, "any": { "nullable": true, "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false } }, "range": { "nullable": true, "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "step": { "type": "number" }, "default": { "type": "number" }, "unitSymbol": { "nullable": true, "type": "string" }, "currency": { "nullable": true, "type": "string" }, "op": { "type": "string", "enum": [ "max", "min" ] } }, "required": [ "min", "max", "step", "default", "unitSymbol", "currency", "op" ], "additionalProperties": false } }, "required": [ "id", "type", "title", "help", "showIf", "any", "answers", "range" ], "additionalProperties": false } }, "result": { "type": "object", "properties": { "count": { "type": "integer" }, "bestBadge": { "nullable": true, "type": "string" }, "showPrices": { "type": "boolean" } }, "required": [ "count", "bestBadge", "showPrices" ], "additionalProperties": false }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "locale", "productType", "intro", "questions", "result", "updatedAt" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/advisors/{id}/result": { "get": { "tags": [ "Beratung und Empfehlungen" ], "summary": "Ergebnis des Produktberaters (Antworten in der Adresse)", "description": "Wertet die Antworten eines Besuchers aus und liefert die passenden Produkte mit Rangfolge, Punkten und Gründen. Die Antworten stehen in der Adresse als `a[]=`, z. B. `?a[q1]=250&a[q2]=bl&a[q3]=bosch,makita`. Unbekannte Fragen und Antworten werden ignoriert, Schieberegler in ihren Bereich gesetzt. Gibt es keinen perfekten Treffer, steht in `relaxed`, welche Wünsche gelockert wurden. Dasselbe geht mit `postAdvisorResult` und den Antworten im Body.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getAdvisorResult", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produktberaters." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (Standard) betrachtet alle Produkte deines Kontos, `site` nur die Produkte, die deine Website schon zeigt. `site` geht nur mit einem Site-Schlüssel (sonst Status 403)." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] }, "in": "query", "name": "count", "required": false, "description": "Bei `true` werden die Antworten in der Statistik des Beraters mitgezählt." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "advisor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "updatedAt" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rank": { "type": "integer" }, "score": { "type": "integer" }, "points": { "type": "number" }, "best": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "product": { "$ref": "#/components/schemas/CatalogProduct" } }, "required": [ "productId", "rank", "score", "points", "best", "reasons", "product" ], "additionalProperties": false } }, "total": { "type": "integer" }, "relaxed": { "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "questionId", "question", "answer" ], "additionalProperties": false } }, "message": { "nullable": true, "type": "string" }, "bestBadge": { "nullable": true, "type": "string" }, "answers": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" } ] } } }, "required": [ "advisor", "items", "total", "relaxed", "message", "bestBadge", "answers" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Beratung und Empfehlungen" ], "summary": "Ergebnis des Produktberaters auswerten", "description": "Wertet die Antworten eines Besuchers aus und liefert die passenden Produkte mit Rangfolge, Punkten und Gründen. Gibt es keinen perfekten Treffer, steht in `relaxed`, welche Wünsche gelockert wurden.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "postAdvisorResult", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produktberaters." }, { "schema": { "default": "tenant", "type": "string", "enum": [ "tenant", "site" ] }, "in": "query", "name": "scope", "required": false, "description": "`tenant` (Standard) betrachtet alle Produkte deines Kontos, `site` nur die Produkte, die deine Website schon zeigt. `site` geht nur mit einem Site-Schlüssel (sonst Status 403)." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] }, "in": "query", "name": "count", "required": false, "description": "Bei `true` werden die Antworten in der Statistik des Beraters mitgezählt." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "default": {}, "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "maxItems": 12, "type": "array", "items": { "type": "string", "maxLength": 16 } }, { "type": "number" } ] }, "description": "Antworten je Frage: Kennung der Frage → gewählte Option, Liste von Optionen oder Zahl (Schieberegler)." } } } } }, "description": "Die Antworten des Besuchers." }, "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "advisor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "updatedAt" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rank": { "type": "integer" }, "score": { "type": "integer" }, "points": { "type": "number" }, "best": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "product": { "$ref": "#/components/schemas/CatalogProduct" } }, "required": [ "productId", "rank", "score", "points", "best", "reasons", "product" ], "additionalProperties": false } }, "total": { "type": "integer" }, "relaxed": { "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "questionId", "question", "answer" ], "additionalProperties": false } }, "message": { "nullable": true, "type": "string" }, "bestBadge": { "nullable": true, "type": "string" }, "answers": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" } ] } } }, "required": [ "advisor", "items", "total", "relaxed", "message", "bestBadge", "answers" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/advisors/{id}/events": { "post": { "tags": [ "Beratung und Empfehlungen" ], "summary": "Statistik des Produktberaters melden", "description": "Meldet Ereignisse eines Besuchers am Produktberater (z. B. gestartet, Frage beantwortet, Ergebnis gesehen). Die Antwort ist leer.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "reportAdvisorEvents", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kennung des Produktberaters." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "minItems": 1, "maxItems": 28, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reach", "next", "click" ] }, "question": { "type": "string", "pattern": "^[a-z0-9]{1,16}$" } }, "required": [ "type" ] }, "description": "Liste der Ereignisse." } }, "required": [ "events" ] } } }, "description": "Die Ereignisse." }, "responses": { "204": { "description": "Erfolgreich, keine Antwortdaten", "content": { "application/json": { "schema": { "type": "string", "nullable": true, "enum": [ null ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/banners": { "get": { "tags": [ "Banner, Looks und Warenkorb" ], "summary": "Werbebanner abrufen", "description": "Liefert Werbebanner aus deinen Partnerprogrammen – bestimmte Banner, die Banner eines Programms oder die Auswahl einer Banner-Platzierung aus dem Dashboard. Je nach Tarif verfügbar.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getBanners", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "maxLength": 800 }, "in": "query", "name": "id", "required": false, "description": "Banner-IDs, kommagetrennt." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "shop", "required": false, "description": "Nur Banner dieses Shops (Shop-ID)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "program", "required": false, "description": "Nur Banner dieses Partnerprogramms (Name)." }, { "schema": { "type": "string", "enum": [ "adcell", "webgains", "awin", "tradedoubler", "ebay", "other" ] }, "in": "query", "name": "network", "required": false, "description": "Nur Banner dieses Netzwerks: `adcell`, `webgains`, `awin`, `tradedoubler`, `ebay` oder `other`." }, { "schema": { "default": 5, "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Banner (1 bis 20). Standard: 5." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "placement", "required": false, "description": "ID einer Platzierung aus dem Dashboard; ihre Regeln bestimmen die Auswahl." }, { "schema": { "type": "integer", "minimum": 0, "maximum": 4000 }, "in": "query", "name": "width", "required": false, "description": "Breite des freien Platzes in Pixeln. Bevorzugt werden Formate, die hineinpassen." }, { "schema": { "type": "string", "pattern": "^(\\d{2,4}x\\d{2,4}|horizontal|vertical|square)$" }, "in": "query", "name": "format", "required": false, "description": "Nur Banner in diesem Format, z. B. `300x250`." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "network": { "type": "string", "enum": [ "adcell", "webgains", "awin", "tradedoubler", "ebay", "other" ] }, "shop": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "type", "name" ], "additionalProperties": false }, "program": { "nullable": true, "type": "string" }, "delivery": { "type": "string", "enum": [ "cdn", "network" ] }, "language": { "nullable": true, "type": "string" }, "countries": { "type": "array", "items": { "type": "string" } }, "startsAt": { "nullable": true, "type": "string" }, "endsAt": { "nullable": true, "type": "string" }, "score": { "default": null, "nullable": true, "type": "number" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "kind": { "type": "string", "enum": [ "image", "html" ] }, "url": { "nullable": true, "type": "string" }, "originalUrl": { "nullable": true, "type": "string" }, "code": { "nullable": true, "type": "string" }, "clickUrl": { "nullable": true, "type": "string" } }, "required": [ "id", "width", "height", "kind", "url", "originalUrl", "code", "clickUrl" ], "additionalProperties": false } } }, "required": [ "id", "name", "network", "shop", "program", "delivery", "language", "countries", "startsAt", "endsAt", "score", "variants" ], "additionalProperties": false } }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/banners/stats": { "post": { "tags": [ "Banner, Looks und Warenkorb" ], "summary": "Banner-Aufrufe und -Klicks melden", "description": "Meldet Einblendungen und Klicks auf Banner, wenn du Banner selbst darstellst. Gezählt wird je Banner und Tag.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "reportBannerStats", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "v": { "default": 0, "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100 }, "p": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ] }, "description": "Liste der Zeilen mit Banner, Ereignis und Anzahl." } }, "required": [ "rows" ] } } }, "description": "Die Zahlen je Banner." }, "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "recorded": { "type": "integer" } }, "required": [ "recorded" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/looks/{code}": { "get": { "tags": [ "Banner, Looks und Warenkorb" ], "summary": "Shop-my-Look abrufen", "description": "Liefert einen „Look“: ein Bild mit markierten Produkten, die per Klick zum Shop führen. Je nach Tarif verfügbar.\n\nBerechtigung für API-Clients: eine von `catalog:read` oder `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getLook", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes-any-of": [ "catalog:read", "products:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9]{10}$" }, "in": "path", "name": "code", "required": true, "description": "Code des Looks (10 Zeichen, Kleinbuchstaben und Ziffern) aus dem Dashboard." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "default": "api", "type": "string", "enum": [ "wordpress", "api" ] }, "in": "query", "name": "src", "required": false, "description": "Woher die Klicks in der Auswertung stammen sollen: `api` (Standard) oder `wordpress`." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "country": { "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "width": { "nullable": true, "type": "integer" }, "height": { "nullable": true, "type": "integer" }, "alt": { "type": "string" }, "caption": { "nullable": true, "type": "string" }, "hotspots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "x": { "type": "number" }, "y": { "type": "number" }, "label": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "id", "number", "x", "y", "label", "available" ], "additionalProperties": false } } }, "required": [ "id", "url", "width", "height", "alt", "caption", "hotspots" ], "additionalProperties": false } }, "items": { "type": "array", "items": { "type": "object", "properties": { "hotspotId": { "type": "string" }, "imageId": { "type": "string" }, "number": { "type": "integer" }, "label": { "type": "string" }, "title": { "type": "string" }, "image": { "nullable": true, "type": "object", "properties": { "url": { "type": "string" }, "alt": { "type": "string" } }, "required": [ "url", "alt" ], "additionalProperties": false }, "price": { "nullable": true, "type": "string" }, "oldPrice": { "nullable": true, "type": "string" }, "priceCheckedAt": { "nullable": true, "type": "string" }, "shop": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ], "additionalProperties": false }, "target": { "type": "string", "enum": [ "offer", "search", "link", "none" ] }, "url": { "nullable": true, "type": "string" }, "amazon": { "type": "boolean" } }, "required": [ "hotspotId", "imageId", "number", "label", "title", "image", "price", "oldPrice", "priceCheckedAt", "shop", "target", "url", "amazon" ], "additionalProperties": false } }, "amazon": { "type": "boolean" }, "associates": { "type": "boolean" }, "publisher": { "type": "string" } }, "required": [ "code", "title", "description", "url", "country", "images", "items", "amazon", "associates", "publisher" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/cart": { "get": { "tags": [ "Banner, Looks und Warenkorb" ], "summary": "Warenkorb-Link für mehrere Produkte", "description": "Erzeugt einen Link, der mehrere Produkte auf einmal in den Amazon-Warenkorb legt. Produkte ohne passendes Amazon-Angebot stehen in `skipped`.\n\nBerechtigung für API-Clients: `products:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getCart", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "products:read" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "ids", "required": true, "description": "Produkt-Kennungen, kommagetrennt (höchstens 10)." }, { "schema": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$" }, "in": "query", "name": "locale", "required": false, "description": "Sprache der Texte, z. B. `de-DE` oder `en-GB`. Ohne Angabe gilt die Standardsprache deiner Website bzw. deines Kontos." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Land für Angebote, Preise und Verfügbarkeit als Ländercode, z. B. `DE`, `AT` oder `CH`. Ohne Angabe gilt das Standardland." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "shops", "required": false, "description": "Nur diese Shops berücksichtigen: Shop-Typen oder Shop-IDs, kommagetrennt, z. B. `amazon,awin`. Überschreibt die Regel deiner Website." }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "prefer", "required": false, "description": "Bevorzugter Shop: Shop-Typ oder Shop-ID, mehrere in Reihenfolge, kommagetrennt. Der bevorzugte Shop gilt als bestes Angebot, sofern er das Produkt lieferbar hat." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "marketplace": { "nullable": true, "type": "string" }, "url": { "nullable": true, "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "title": { "type": "string" }, "asin": { "type": "string" }, "cartUrl": { "type": "string" } }, "required": [ "productId", "title", "asin", "cartUrl" ], "additionalProperties": false } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "reason": { "type": "string", "enum": [ "no_cart_offer", "other_marketplace", "limit" ] } }, "required": [ "productId", "reason" ], "additionalProperties": false } }, "missing": { "type": "array", "items": { "type": "string" } }, "maxItems": { "type": "number", "enum": [ 10 ] } }, "required": [ "marketplace", "url", "items", "skipped", "missing", "maxItems" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-requests": { "post": { "tags": [ "Produktaufträge" ], "summary": "Produkt beauftragen", "description": "Beauftragt ein Produkt, das noch nicht im Katalog steht (oder das du sicher zuordnen willst). Du gibst an, wonach gesucht wird – Suchbegriff, EAN, ASIN, Adresse, Marke oder Modellnummer. Bekannte Produkte werden sofort erkannt, sonst sucht affilinode in den Shops.\n\nDie Antwort hat den Status 200, wenn der Auftrag abgeschlossen ist, sonst 202 mit der Auftragsnummer: Frage den Stand mit `getProductRequest` ab oder warte mit `wait` bis zu 15 Sekunden auf das Ergebnis. Mit dem Kopf `Idempotency-Key` wird ein wiederholter Aufruf nicht doppelt ausgeführt. Pro Tag ist die Zahl der Aufträge begrenzt.\n\nBerechtigung für API-Clients: `requests:write`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "createProductRequest", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "requests:write" ], "parameters": [ { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 15 }, "in": "query", "name": "wait", "required": false, "description": "Sekunden, die die Anfrage auf den Abschluss wartet (0 bis 15). Standard: 0.", "example": 10 }, { "schema": { "type": "string", "minLength": 8, "maxLength": 100 }, "in": "header", "name": "idempotency-key", "required": false, "description": "Eindeutiger Wert (8 bis 100 Zeichen) für diesen Auftrag. Wiederholst du den Aufruf mit demselben Wert, bekommst du den bestehenden Auftrag zurück." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "allOf": [ { "$ref": "#/components/schemas/ProductRequestTargetInput" } ], "description": "Wonach gesucht wird. Mindestens eine Angabe ist nötig." }, "constraints": { "type": "object", "properties": { "productType": { "type": "string", "maxLength": 64, "description": "Schlüssel der Produktart, z. B. `smartphone`." }, "condition": { "type": "string", "enum": [ "new", "any" ], "description": "`new` (nur neue Ware) oder `any` (auch gebraucht)." }, "priceMax": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000, "description": "Höchstpreis." } }, "description": "Einschränkungen für die Suche." }, "countries": { "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "Ländercodes, in denen Angebote gesucht werden, z. B. `[\"DE\",\"AT\"]` (höchstens 20). Standard: das Land deiner Website bzw. deines Kontos." }, "locales": { "maxItems": 10, "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" }, "description": "Sprachen für die Produkttexte, z. B. `[\"de-DE\"]`." }, "selection": { "default": "auto", "type": "string", "enum": [ "auto", "best_effort", "manual" ], "description": "Auswahl bei mehreren Treffern: `auto` (nur eindeutige Treffer anlegen, Standard), `best_effort` (den besten Treffer nehmen) oder `manual` (du wählst immer selbst mit `selectProductRequestCandidate`)." }, "callbackUrl": { "type": "string", "maxLength": 2048, "format": "uri", "description": "HTTPS-Adresse, die nach Abschluss benachrichtigt wird." }, "callbackSecret": { "type": "string", "minLength": 16, "maxLength": 200, "description": "Gemeinsames Geheimnis (16 bis 200 Zeichen), mit dem die Benachrichtigung signiert wird. Ohne Angabe wird sie unsigniert gesendet. Das Geheimnis wird nie zurückgegeben." } }, "required": [ "input" ] }, "example": { "input": { "query": "Nova X5 128 GB", "brand": "Nova" }, "constraints": { "productType": "smartphone", "condition": "new" }, "countries": [ "DE" ], "selection": "auto" } } }, "description": "Was gesucht wird und wie die Auswahl erfolgen soll." }, "responses": { "200": { "description": "Der Auftrag ist abgeschlossen (oder war schon bekannt).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "id": "c1f2a3b4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "input": { "query": "Nova X5 128 GB" }, "status": "completed", "productId": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "match": { "method": "search", "confidence": 0.97, "notes": [] }, "candidates": [], "llmCheck": null, "error": null, "createdAt": "2026-10-19T08:00:00.000Z", "completedAt": "2026-10-19T08:00:06.000Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "202": { "description": "Der Auftrag wurde angenommen und wird bearbeitet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "id": "c1f2a3b4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "input": { "query": "Nova X5 128 GB" }, "status": "searching", "productId": null, "match": null, "candidates": [], "llmCheck": null, "error": null, "createdAt": "2026-10-19T08:00:00.000Z", "completedAt": null } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "Produktaufträge" ], "summary": "Produktaufträge auflisten", "description": "Liefert deine Produktaufträge, neueste zuerst.\n\nBerechtigung für API-Clients: `requests:write`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductRequests", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "requests:write" ], "parameters": [ { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "status", "required": false, "description": "Nur Aufträge mit diesem Status, kommagetrennt: `queued`, `searching`, `selecting`, `completed`, `needs_selection`, `not_found`, `failed`, `rejected`." }, { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Aufträge (1 bis 100). Standard: 25." }, { "schema": { "type": "string", "maxLength": 60 }, "in": "query", "name": "cursor", "required": false, "description": "Fortsetzung: der Wert `nextCursor` aus der vorigen Antwort. Ohne Angabe beginnt die Liste von vorn." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRequest" } }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "requests", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-requests/{id}": { "get": { "tags": [ "Produktaufträge" ], "summary": "Produktauftrag abrufen", "description": "Liefert den Stand eines Auftrags. Mit `wait` wartest du bis zu 15 Sekunden auf den Abschluss. Status 200 heißt abgeschlossen, 202 heißt in Bearbeitung. Bei `needs_selection` stehen die Kandidaten in `candidates`.\n\nBerechtigung für API-Clients: `requests:write`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getProductRequest", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "requests:write" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Auftragsnummer aus `createProductRequest`.", "example": "c1f2a3b4-5d6e-4f70-8a9b-0c1d2e3f4a5b" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 15 }, "in": "query", "name": "wait", "required": false, "description": "Sekunden, die die Anfrage auf den Abschluss wartet (0 bis 15). Standard: 0.", "example": 5 }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Der Auftrag ist abgeschlossen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "id": "c1f2a3b4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "input": { "query": "Nova X5 128 GB" }, "status": "completed", "productId": "5b0c4f1e-2a7d-4c63-9f0e-8d1a6b3c7e42", "match": { "method": "search", "confidence": 0.97, "notes": [] }, "candidates": [], "llmCheck": null, "error": null, "createdAt": "2026-10-19T08:00:00.000Z", "completedAt": "2026-10-19T08:00:06.000Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "202": { "description": "Der Auftrag wird noch bearbeitet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "id": "c1f2a3b4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "input": { "query": "Nova X5 128 GB" }, "status": "searching", "productId": null, "match": null, "candidates": [], "llmCheck": null, "error": null, "createdAt": "2026-10-19T08:00:00.000Z", "completedAt": null } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-requests/{id}/reject": { "post": { "tags": [ "Produktaufträge" ], "summary": "Produktauftrag ablehnen", "description": "Beendet einen Auftrag, dessen Kandidaten nicht passen. Es wird kein Produkt zugeordnet.\n\nBerechtigung für API-Clients: `requests:write`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "rejectProductRequest", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "requests:write" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Auftragsnummer." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 300, "description": "Kurze Begründung (höchstens 300 Zeichen)." } } } } }, "description": "Optionaler Grund." }, "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/product-requests/{id}/select": { "post": { "tags": [ "Produktaufträge" ], "summary": "Kandidaten für einen Produktauftrag wählen", "description": "Wählt bei einem Auftrag im Status `needs_selection` den passenden Kandidaten aus. Danach wird das Produkt angelegt bzw. zugeordnet.\n\nBerechtigung für API-Clients: `requests:write`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "selectProductRequestCandidate", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "requests:write" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Auftragsnummer." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "candidate": { "type": "string", "maxLength": 200, "description": "Kennung des Kandidaten (`ref` aus der Liste `candidates`)." }, "productType": { "type": "string", "maxLength": 64, "description": "Optional: Schlüssel der Produktart, wenn sie festgelegt werden soll." }, "singleCandidate": { "type": "string", "maxLength": 200, "description": "Optional: Kennung des Einzelprodukts, wenn der Kandidat ein Mehrfachpack ist." } }, "required": [ "candidate" ] } } }, "description": "Der gewählte Kandidat." }, "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/reporting/summary": { "get": { "tags": [ "Auswertung" ], "summary": "Auswertung: Zusammenfassung", "description": "Liefert Klicks, Einblendungen, Bestellungen, Umsatz und Provision (bestätigt und offen) für einen Zeitraum, gruppiert nach Tag, Website, Shop, Produkt, Artikel oder anderem. Ein Site-Schlüssel sieht nur die Zahlen der eigenen Website.\n\nBerechtigung für API-Clients: `reporting:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getReportingSummary", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "reporting:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": true, "description": "Beginn des Zeitraums als Datum `JJJJ-MM-TT`." }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": true, "description": "Ende des Zeitraums als Datum `JJJJ-MM-TT` (einschließlich)." }, { "schema": { "default": "day", "type": "string", "enum": [ "day", "site", "subsite", "shop", "advertiser", "product", "article", "box", "account", "source", "country" ] }, "in": "query", "name": "groupBy", "required": false, "description": "Gruppierung der Zeilen: `day`, `site`, `subsite`, `shop`, `advertiser`, `product`, `article`, `box`, `account`, `source` oder `country`." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "accountId", "required": false, "description": "Nur dieses Partnerkonto." }, { "schema": { "type": "string", "enum": [ "awin", "amazon", "ebay", "adsense", "matomo", "ga4", "tradedoubler", "adcell", "webgains", "levanta", "partnerboost", "impact", "archer" ] }, "in": "query", "name": "source", "required": false, "description": "Nur diese Quelle, z. B. `awin` oder `amazon`." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "siteId", "required": false, "description": "Nur diese Website." }, { "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "in": "query", "name": "blogId", "required": false, "description": "Nur diese Unterseite eines WordPress-Netzwerks." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "shopId", "required": false, "description": "Nur dieser Shop." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Nur dieses Produkt." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "articleKey", "required": false, "description": "Nur dieser Artikel (Kennung aus dem WordPress-Plugin)." }, { "schema": { "type": "string", "pattern": "^[a-z_]{1,20}$" }, "in": "query", "name": "boxKind", "required": false, "description": "Nur diese Art von Box." }, { "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "in": "query", "name": "currency", "required": false, "description": "Währung, in der die Summen ausgewiesen werden, z. B. `EUR`." }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Zeilen (1 bis 500). Standard: 100." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "groupBy": { "type": "string", "enum": [ "day", "site", "subsite", "shop", "advertiser", "product", "article", "box", "account", "source", "country" ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "orders": { "type": "integer" }, "items": { "type": "integer" }, "revenue": { "type": "string" }, "commission": { "type": "string" }, "pendingRevenue": { "type": "string" }, "pendingCommission": { "type": "string" }, "declinedRevenue": { "type": "string" }, "declinedCommission": { "type": "string" }, "key": { "nullable": true, "type": "string" }, "label": { "type": "string" }, "currency": { "type": "string" }, "blogId": { "nullable": true, "type": "integer" } }, "required": [ "clicks", "impressions", "orders", "items", "revenue", "commission", "pendingRevenue", "pendingCommission", "declinedRevenue", "declinedCommission", "key", "label", "currency", "blogId" ], "additionalProperties": false } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "orders": { "type": "integer" }, "items": { "type": "integer" }, "revenue": { "type": "string" }, "commission": { "type": "string" }, "pendingRevenue": { "type": "string" }, "pendingCommission": { "type": "string" }, "declinedRevenue": { "type": "string" }, "declinedCommission": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "clicks", "impressions", "orders", "items", "revenue", "commission", "pendingRevenue", "pendingCommission", "declinedRevenue", "declinedCommission", "currency" ], "additionalProperties": false } }, "unmatched": { "type": "object", "properties": { "rows": { "type": "integer" }, "clicks": { "type": "integer" }, "orders": { "type": "integer" }, "revenue": { "type": "string" }, "commission": { "type": "string" } }, "required": [ "rows", "clicks", "orders", "revenue", "commission" ], "additionalProperties": false }, "truncated": { "type": "boolean" } }, "required": [ "from", "to", "groupBy", "rows", "totals", "unmatched", "truncated" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/reporting/revenue": { "get": { "tags": [ "Auswertung" ], "summary": "Auswertung: Umsatz", "description": "Liefert den Umsatz für einen Zeitraum, gruppiert z. B. nach Artikel, Box, Produkt oder Shop, mit Seitenaufrufen. `truncated` zeigt, ob die Zeilen gekürzt wurden.\n\nBerechtigung für API-Clients: `reporting:read`. Site-Schlüssel dürfen diese Route immer nutzen.", "operationId": "getReportingRevenue", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "x-required-scopes": [ "reporting:read" ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": true, "description": "Beginn des Zeitraums als Datum `JJJJ-MM-TT`." }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": true, "description": "Ende des Zeitraums als Datum `JJJJ-MM-TT` (einschließlich)." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "siteId", "required": false, "description": "Nur diese Website." }, { "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "in": "query", "name": "blogId", "required": false, "description": "Nur diese Unterseite eines WordPress-Netzwerks." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "shopId", "required": false, "description": "Nur dieser Shop." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Nur dieses Produkt." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "articleKey", "required": false, "description": "Nur dieser Artikel (Kennung aus dem WordPress-Plugin)." }, { "schema": { "type": "string", "pattern": "^[a-z_]{1,20}$" }, "in": "query", "name": "boxKind", "required": false, "description": "Nur diese Art von Box." }, { "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "in": "query", "name": "currency", "required": false, "description": "Währung, z. B. `EUR`." }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false, "description": "Höchste Anzahl der Zeilen (1 bis 500). Standard: 100." }, { "schema": { "default": "article", "type": "string", "enum": [ "article", "box", "product", "shop", "source", "advertiser", "country", "site", "day" ] }, "in": "query", "name": "groupBy", "required": false, "description": "Gruppierung: `article`, `box`, `product`, `shop`, `source`, `advertiser`, `country`, `site` oder `day`." }, { "schema": { "type": "string", "enum": [ "awin", "amazon", "ebay", "tradedoubler", "adcell", "webgains", "impact", "levanta", "partnerboost", "archer" ] }, "in": "query", "name": "source", "required": false, "description": "Nur diese Quelle, z. B. `awin` oder `amazon`." }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "Nur dieses Land (Ländercode)." }, { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "responses": { "200": { "description": "Erfolgreich", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "groupBy": { "type": "string", "enum": [ "article", "box", "product", "shop", "source", "advertiser", "country", "site", "day" ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "integer" }, "orders": { "type": "integer" }, "revenue": { "type": "string" }, "commission": { "type": "string" }, "pendingCommission": { "type": "string" }, "approvedCommission": { "type": "string" }, "declinedCommission": { "type": "string" }, "epc": { "nullable": true, "type": "string" }, "conversionRate": { "nullable": true, "type": "number" }, "pageviews": { "nullable": true, "type": "integer" }, "commissionPer1000": { "nullable": true, "type": "string" }, "key": { "nullable": true, "type": "string" }, "label": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "clicks", "orders", "revenue", "commission", "pendingCommission", "approvedCommission", "declinedCommission", "epc", "conversionRate", "pageviews", "commissionPer1000", "key", "label", "currency" ], "additionalProperties": false } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "integer" }, "orders": { "type": "integer" }, "revenue": { "type": "string" }, "commission": { "type": "string" }, "pendingCommission": { "type": "string" }, "approvedCommission": { "type": "string" }, "declinedCommission": { "type": "string" }, "epc": { "nullable": true, "type": "string" }, "conversionRate": { "nullable": true, "type": "number" }, "pageviews": { "nullable": true, "type": "integer" }, "commissionPer1000": { "nullable": true, "type": "string" }, "currency": { "type": "string" } }, "required": [ "clicks", "orders", "revenue", "commission", "pendingCommission", "approvedCommission", "declinedCommission", "epc", "conversionRate", "pageviews", "commissionPer1000", "currency" ], "additionalProperties": false } }, "pageviews": { "nullable": true, "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "from", "to", "groupBy", "rows", "totals", "pageviews", "truncated" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/short-links": { "post": { "tags": [ "Kurzlinks" ], "summary": "Kurzlink anlegen", "description": "Legt einen Kurzlink für ein Produkt (`product`, Ziel je Land des Besuchers nach deinen Regeln) oder für eine Adresse (`url`) an. Wunsch-Kürzel, Gruppe, Notiz und UTM-Werte sind optional. Je nach Tarif verfügbar.\n\nNur mit Site-Schlüssel, weil ein Kurzlink zu einer Website gehört. Mit einem API-Client antwortet die Route mit Status 403.", "operationId": "createShortLink", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcBlog" }, { "$ref": "#/components/parameters/AcBlogName" }, { "$ref": "#/components/parameters/AcBlogUrl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Kennung des Produkts (Link mit Ziel je Land)." }, "url": { "type": "string", "maxLength": 2000, "description": "Adresse, auf die der Link zeigt." }, "channel": { "type": "string", "pattern": "^[a-z0-9_]{1,32}$", "description": "Kanal für die Auswertung, z. B. `instagram`." }, "title": { "type": "string", "maxLength": 200, "description": "Titel des Links in der Übersicht." }, "overview": { "type": "boolean", "description": "Bei `true` zeigt der Link eine Übersicht aller Angebote statt direkt zum besten." }, "slug": { "type": "string", "description": "Wunsch-Kürzel für die Adresse des Kurzlinks." }, "group": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Name der Gruppe, in der der Link erscheint (wird bei Bedarf angelegt)." }, "note": { "type": "string", "maxLength": 1000, "description": "Interne Notiz." }, "utm": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 100, "description": "utm_source" }, "medium": { "type": "string", "minLength": 1, "maxLength": 100, "description": "utm_medium" }, "campaign": { "type": "string", "minLength": 1, "maxLength": 100, "description": "utm_campaign" }, "content": { "type": "string", "minLength": 1, "maxLength": 100, "description": "utm_content" } }, "description": "UTM-Werte, die an die Ziel-Adresse angehängt werden." }, "routing": { "type": "object", "properties": { "rules": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{1,12}$" }, "label": { "default": "", "type": "string", "maxLength": 80 }, "active": { "default": true, "type": "boolean" }, "when": { "type": "object", "properties": { "countries": { "default": [], "maxItems": 60, "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "devices": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "mobile", "tablet", "desktop" ] } }, "os": { "default": [], "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux" ] } }, "languages": { "default": [], "maxItems": 30, "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}$" } }, "days": { "default": [], "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "timeFrom": { "default": null, "nullable": true, "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "timeTo": { "default": null, "nullable": true, "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "default", "url", "offer", "overview" ] }, "url": { "default": null, "nullable": true, "type": "string", "maxLength": 2000 }, "offerId": { "default": null, "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind" ] } }, "required": [ "id", "when", "target" ] } }, "ab": { "default": null, "nullable": true, "type": "object", "properties": { "variants": { "minItems": 2, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{1,12}$" }, "label": { "default": "", "type": "string", "maxLength": 80 }, "weight": { "type": "integer", "minimum": 0, "maximum": 100 }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "default", "url", "offer", "overview" ] }, "url": { "default": null, "nullable": true, "type": "string", "maxLength": 2000 }, "offerId": { "default": null, "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind" ] } }, "required": [ "id", "weight", "target" ] } }, "winner": { "default": null, "nullable": true, "type": "string", "pattern": "^[a-z0-9]{1,12}$" }, "startedAt": { "default": null, "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "variants" ] } }, "description": "Regeln für das Ziel je Besucherland und A/B-Test." } }, "required": [ "channel" ] } } }, "description": "Ziel und Angaben zum Link. Angegeben sein muss `product` oder `url`." }, "responses": { "201": { "description": "Angelegt", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "code": { "type": "string" }, "shortUrl": { "type": "string" }, "title": { "type": "string" }, "targetUrl": { "default": "", "type": "string" }, "mode": { "default": "redirect", "type": "string", "enum": [ "redirect", "direct" ] }, "notes": { "type": "array", "items": { "type": "string" } }, "codes": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sponsor": { "type": "string" }, "code": { "type": "string" }, "discountText": { "nullable": true, "type": "string" }, "endsAt": { "nullable": true, "type": "string" }, "text": { "type": "string" } }, "required": [ "id", "sponsor", "code", "discountText", "endsAt", "text" ], "additionalProperties": false } } }, "required": [ "id", "code", "shortUrl", "title", "targetUrl", "mode", "notes", "codes" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "schemas": { "CatalogFacet": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "values" ] }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "value", "label", "count" ], "additionalProperties": false } } }, "required": [ "key", "type", "label", "values" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "range" ] }, "label": { "type": "string" }, "min": { "nullable": true, "type": "number" }, "max": { "nullable": true, "type": "number" }, "count": { "type": "integer" }, "unit": { "nullable": true, "type": "string" } }, "required": [ "key", "type", "label", "min", "max", "count", "unit" ], "additionalProperties": false } ] }, "CatalogProduct": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brand": { "nullable": true, "type": "string" }, "model": { "nullable": true, "type": "string" }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "activityState": { "type": "string", "enum": [ "catalog", "active", "paused" ] }, "status": { "type": "string", "enum": [ "available", "unavailable", "discontinued" ] }, "image": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "keySpecs": { "type": "array", "items": { "$ref": "#/components/schemas/SpecItem" } }, "specCount": { "type": "integer" }, "completeness": { "$ref": "#/components/schemas/SpecCompleteness" }, "bestPrice": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "offerCount": { "type": "integer" }, "popularity": { "type": "object", "properties": { "clicks30d": { "type": "integer" }, "impressions30d": { "type": "integer" }, "orders30d": { "type": "integer" }, "sites": { "type": "integer" }, "lastRequestedAt": { "nullable": true, "type": "string" } }, "required": [ "clicks30d", "impressions30d", "orders30d", "sites", "lastRequestedAt" ], "additionalProperties": false }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "brand", "model", "productType", "activityState", "status", "image", "keySpecs", "specCount", "completeness", "bestPrice", "offerCount", "popularity", "updatedAt" ], "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Maschinenlesbarer Code, z. B. `validation_failed`, `unauthorized`, `forbidden`, `not_found`." }, "message": { "type": "string", "description": "Erklärung für Menschen (auf Deutsch)." }, "details": { "description": "Weitere Angaben, z. B. die fehlerhaften Felder bei `validation_failed`." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Der Fehler." } }, "required": [ "error" ], "additionalProperties": false, "description": "Aufbau aller Fehlerantworten." }, "Image": { "type": "object", "properties": { "url": { "type": "string", "description": "Adresse des Bildes in Standardgröße." }, "width": { "nullable": true, "type": "integer", "description": "Breite in Pixeln." }, "height": { "nullable": true, "type": "integer", "description": "Höhe in Pixeln." }, "alt": { "type": "string", "description": "Alternativtext für Barrierefreiheit." }, "srcset": { "nullable": true, "type": "string", "description": "Fertiger `srcset`-Wert mit Größenvarianten, falls vorhanden." }, "source": { "type": "string", "enum": [ "cdn", "origin" ] }, "imageRights": { "type": "string", "enum": [ "rehost", "hotlink", "none" ] }, "editRights": { "type": "string", "enum": [ "edit", "none" ] }, "cutout": { "nullable": true, "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "url", "width", "height" ], "additionalProperties": false } }, "required": [ "url", "width", "height", "alt", "srcset", "source", "imageRights", "editRights", "cutout" ], "additionalProperties": false, "description": "Ein Produktbild." }, "ListItem": { "type": "object", "properties": { "position": { "type": "integer" }, "badge": { "nullable": true, "type": "string" }, "note": { "nullable": true, "type": "string" }, "product": { "$ref": "#/components/schemas/ProductWithReplacement" } }, "required": [ "position", "badge", "note", "product" ], "additionalProperties": false }, "Money": { "type": "object", "properties": { "amount": { "type": "string", "description": "Betrag als Dezimalzahl in Textform, z. B. `399.00`." }, "currency": { "type": "string", "description": "Währung als ISO-Code, z. B. `EUR`." }, "formatted": { "type": "string", "description": "Fertig formatiert für die Anzeige, z. B. `399,00 €`." } }, "required": [ "amount", "currency", "formatted" ], "additionalProperties": false, "description": "Ein Geldbetrag." }, "Offer": { "type": "object", "properties": { "id": { "type": "string", "description": "Kennung des Angebots." }, "shop": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ], "description": "Art des Shops bzw. Netzwerks." }, "name": { "type": "string", "description": "Name des Shops." }, "logoUrl": { "nullable": true, "type": "string", "description": "Adresse des Shop-Logos, falls vorhanden." }, "own": { "type": "boolean", "description": "Ist `true` bei deinem eigenen Shop (kein Partnerprogramm)." } }, "required": [ "id", "type", "name", "logoUrl", "own" ], "additionalProperties": false, "description": "Der Shop, der das Angebot macht." }, "country": { "type": "string", "description": "Land, für das das Angebot gilt." }, "title": { "nullable": true, "type": "string", "description": "Titel des Angebots im Shop." }, "url": { "type": "string", "description": "Affiliate-Link zum Angebot mit deinen Tracking-IDs." }, "cartUrl": { "default": null, "nullable": true, "type": "string", "description": "Link, der das Produkt direkt in den Warenkorb legt (nur bei Shops, die das anbieten)." }, "price": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Preis ohne Versand." }, "oldPrice": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Durchgestrichener früherer Preis, falls der Shop einen nennt." }, "shipping": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Versandkosten, falls bekannt." }, "total": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Preis inklusive Versand." }, "savings": { "nullable": true, "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "percent": { "type": "integer" } }, "required": [ "amount", "percent" ], "additionalProperties": false, "description": "Ersparnis gegenüber dem früheren Preis." }, "availability": { "type": "string", "enum": [ "in_stock", "limited", "preorder", "out_of_stock", "unknown" ], "description": "Verfügbarkeit: `in_stock`, `limited`, `preorder`, `out_of_stock` oder `unknown`." }, "availabilityText": { "nullable": true, "type": "string", "description": "Verfügbarkeit als Text des Shops." }, "delivery": { "nullable": true, "type": "object", "properties": { "text": { "type": "string" }, "minDays": { "nullable": true, "type": "integer" }, "maxDays": { "nullable": true, "type": "integer" }, "fast": { "type": "boolean" } }, "required": [ "text", "minDays", "maxDays", "fast" ], "additionalProperties": false, "description": "Lieferzeit." }, "condition": { "type": "string", "enum": [ "new", "used", "refurbished" ], "description": "Zustand: `new`, `used` oder `refurbished`." }, "conditionDetail": { "default": null, "nullable": true, "type": "string", "enum": [ "open_box", "b_stock", "returned", "demo", "like_new", "very_good", "good", "acceptable", "for_parts" ], "description": "Feinstufe bei nicht neuer Ware: `open_box`, `b_stock`, `returned`, `demo`, `like_new`, `very_good`, `good`, `acceptable` oder `for_parts`; sonst `null`." }, "checkedAt": { "type": "string", "description": "Zeitpunkt der letzten Preisprüfung." }, "priceAgeHours": { "default": null, "nullable": true, "type": "integer", "minimum": 0, "description": "Alter des Preises in ganzen Stunden, `null` ohne Prüfzeitpunkt. Ein älterer Preis bleibt mit dieser Angabe sichtbar; Amazon- und eBay-Preise blendet die Anzeige nach 24 bzw. 6 Stunden aus." }, "priceStale": { "default": false, "type": "boolean", "description": "`true`, wenn der Preis älter ist als die Schwelle der Shop-Art. Solche Angebote sind nie das beste Angebot, ihre Verfügbarkeit ist `unknown`." }, "isBest": { "type": "boolean", "description": "Ist `true` beim besten Angebot für das Land." }, "packQuantity": { "default": 1, "type": "integer", "minimum": 1, "description": "Stückzahl der Packung." }, "unitPrice": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Preis je Einheit (z. B. je Stück), falls berechenbar." }, "priceInsight": { "default": null, "nullable": true, "type": "object", "properties": { "lowestInDays": { "nullable": true, "type": "integer" }, "dropPercent": { "nullable": true, "type": "integer" }, "dropSince": { "nullable": true, "type": "string" } }, "required": [ "lowestInDays", "dropPercent", "dropSince" ], "additionalProperties": false, "description": "Einordnung des Preises gegenüber dem bisherigen Verlauf." }, "salesRank": { "default": null, "nullable": true, "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1 }, "category": { "nullable": true, "type": "string" } }, "required": [ "rank", "category" ], "additionalProperties": false } }, "required": [ "id", "shop", "country", "title", "url", "cartUrl", "price", "oldPrice", "shipping", "total", "savings", "availability", "availabilityText", "delivery", "condition", "conditionDetail", "checkedAt", "priceAgeHours", "priceStale", "isBest", "packQuantity", "unitPrice", "priceInsight", "salesRank" ], "additionalProperties": false, "description": "Das Angebot eines Shops für ein Produkt, mit Preis und Affiliate-Link." }, "Product": { "type": "object", "properties": { "id": { "type": "string", "description": "Kennung des Produkts bei affilinode." }, "title": { "type": "string", "description": "Anzeigetitel des Produkts." }, "detailedTitle": { "default": null, "nullable": true, "type": "string", "description": "Ausführlicher Titel mit Marke, Modell, Produktart und wichtigsten Merkmalen." }, "brand": { "nullable": true, "type": "string", "description": "Marke." }, "mpn": { "nullable": true, "type": "string", "description": "Modellnummer des Herstellers." }, "gtins": { "type": "array", "items": { "type": "string" }, "description": "EAN- bzw. UPC-Nummern." }, "productClass": { "type": "string", "enum": [ "goods", "service", "tariff" ], "description": "Art des Produkts: `goods` (Ware), `service` oder `tariff`." }, "productType": { "type": "object", "properties": { "key": { "type": "string", "description": "Schlüssel der Produktart." }, "label": { "type": "string", "description": "Name der Produktart." }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "path" ], "additionalProperties": false, "description": "Standardisierte Produktart, z. B. Smartphone." }, "category": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false, "description": "Deine eigene Kategorie für das Produkt, falls zugeordnet." }, "locale": { "type": "string", "description": "Sprache der ausgelieferten Texte." }, "textLocales": { "default": null, "nullable": true, "type": "object", "properties": { "title": { "nullable": true, "type": "string" }, "detailedTitle": { "nullable": true, "type": "string" }, "short": { "nullable": true, "type": "string" }, "long": { "nullable": true, "type": "string" } }, "required": [ "title", "detailedTitle", "short", "long" ], "additionalProperties": false, "description": "Sprache der einzelnen Texte, falls sie von `locale` abweicht (dann fehlte die Übersetzung)." }, "country": { "type": "string", "description": "Land, für das Angebote und Preise gelten." }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/Image" }, "description": "Produktbilder." }, "badge": { "nullable": true, "type": "string", "description": "Redaktionelles Badge, z. B. „Testsieger“." }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "Kurze Stichpunkte zu den wichtigsten Eigenschaften." }, "texts": { "type": "object", "properties": { "short": { "nullable": true, "type": "string" }, "long": { "nullable": true, "type": "string" }, "verdict": { "default": null, "nullable": true, "type": "string" }, "social": { "default": null, "nullable": true, "type": "string" } }, "required": [ "short", "long", "verdict", "social" ], "additionalProperties": false, "description": "Beschreibungstexte: Kurztext, Langtext, Fazit und Social-Media-Text." }, "aiTexts": { "default": null, "nullable": true, "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string", "enum": [ "short", "long", "prosCons", "verdict", "social" ] } }, "label": { "type": "boolean" } }, "required": [ "fields", "label" ], "additionalProperties": false, "description": "Angabe, welche Texte mit KI erstellt wurden und ob der Hinweis „KI-generiert“ angezeigt werden soll." }, "prosCons": { "nullable": true, "type": "object", "properties": { "pros": { "type": "array", "items": { "type": "string" } }, "cons": { "type": "array", "items": { "type": "string" } } }, "required": [ "pros", "cons" ], "additionalProperties": false, "description": "Vor- und Nachteile." }, "review": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Review" } ] }, "specs": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SpecItem" } } }, "required": [ "group", "items" ], "additionalProperties": false }, "description": "Technische Merkmale in Gruppen." }, "attributions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "license": { "nullable": true, "type": "string" }, "licenseUrl": { "nullable": true, "type": "string" }, "notice": { "nullable": true, "type": "string" } }, "required": [ "source", "name", "url", "license", "licenseUrl", "notice" ], "additionalProperties": false } }, "profile": { "nullable": true, "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "partial" ] }, "locale": { "type": "string" }, "strengths": { "type": "array", "items": { "type": "string" } }, "weaknesses": { "type": "array", "items": { "type": "string" } }, "audience": { "nullable": true, "type": "string" }, "specials": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "llm", "manual" ] }, "updatedAt": { "type": "string" } }, "required": [ "status", "locale", "strengths", "weaknesses", "audience", "specials", "source", "updatedAt" ], "additionalProperties": false, "description": "Produktprofil mit Stärken, Schwächen und Zielgruppe." }, "completeness": { "allOf": [ { "$ref": "#/components/schemas/SpecCompleteness" } ], "description": "Wie vollständig die wichtigen Merkmale ausgefüllt sind." }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" }, "description": "Angebote der Shops, das beste zuerst." }, "usedOffers": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Offer" }, "description": "Gebrauchte, generalüberholte, B-Ware- und Open-Box-Angebote, getrennt von `offers`: günstigster Gesamtpreis zuerst, nie `isBest`, ohne Ersparnis und Preissignale. `offers` enthält nur Neuware." }, "linkOffers": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "shop": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ] }, "name": { "type": "string" }, "logoUrl": { "nullable": true, "type": "string" }, "own": { "type": "boolean" } }, "required": [ "id", "type", "name", "logoUrl", "own" ], "additionalProperties": false }, "country": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "shop", "country", "url" ], "additionalProperties": false }, "description": "Amazon nur als Link: Eintrag ohne Preis, Bild, Titel und Bestand, getrennt von den Angeboten. Er zählt nie für den Bestpreis." }, "ebayOffers": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Offer" }, "description": "Angebote von eBay (gesondert, da sie anders dargestellt werden)." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "language": { "nullable": true, "type": "string" }, "url": { "type": "string" }, "sizeBytes": { "nullable": true, "type": "integer" }, "pageCount": { "default": null, "nullable": true, "type": "integer" }, "eprelUrl": { "default": null, "nullable": true, "type": "string" } }, "required": [ "type", "title", "language", "url", "sizeBytes", "pageCount", "eprelUrl" ], "additionalProperties": false }, "description": "Dokumente wie Datenblatt oder Anleitung." }, "status": { "type": "string", "enum": [ "available", "unavailable", "discontinued" ], "description": "Verfügbarkeit des Produkts am Markt: `available`, `unavailable` oder `discontinued`." }, "activityState": { "type": "string", "enum": [ "catalog", "active", "paused" ], "description": "Ob Preise laufend aktualisiert werden: `active`, `paused` oder nur Katalogeintrag (`catalog`)." }, "offersStatus": { "type": "string", "enum": [ "available", "pending", "none" ], "description": "Stand der Angebotssuche: `available` (Angebote vorhanden), `pending` (wird gesucht) oder `none` (keine gefunden)." }, "updatedAt": { "type": "string", "description": "Zeitpunkt der letzten Änderung." }, "variantOf": { "default": null, "nullable": true, "type": "string", "description": "Kennung des Modellprodukts, wenn dies eine Variante ist." }, "variantLabel": { "default": null, "nullable": true, "type": "string", "description": "Bezeichnung der Variante, z. B. „Schwarz, 256 GB“." }, "variants": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "label": { "nullable": true, "type": "string" }, "price": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "available": { "type": "boolean" }, "url": { "default": null, "nullable": true, "type": "string" }, "shopName": { "default": null, "nullable": true, "type": "string" }, "shopType": { "default": null, "nullable": true, "type": "string" }, "axes": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "color": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false } }, "required": [ "key", "label", "value" ], "additionalProperties": false } }, "color": { "default": null, "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false }, "image": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "bestOffer": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Offer" } ] }, "isDefault": { "default": false, "type": "boolean" } }, "required": [ "id", "title", "label", "price", "available", "url", "shopName", "shopType", "axes", "color", "image", "bestOffer", "isDefault" ], "additionalProperties": false }, "description": "Varianten des Produkts." }, "lowestVariant": { "default": null, "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "label": { "nullable": true, "type": "string" }, "price": { "$ref": "#/components/schemas/Money" } }, "required": [ "id", "label", "price" ], "additionalProperties": false }, "isModel": { "default": false, "type": "boolean", "description": "Ist `true`, wenn dies ein Modellprodukt mit mehreren Varianten ist." }, "variantAxes": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "variantIds": { "type": "array", "items": { "type": "string" } }, "color": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false } }, "required": [ "value", "variantIds" ], "additionalProperties": false } } }, "required": [ "key", "label", "values" ], "additionalProperties": false } }, "priceRange": { "default": null, "nullable": true, "type": "object", "properties": { "min": { "$ref": "#/components/schemas/Money" }, "max": { "$ref": "#/components/schemas/Money" } }, "required": [ "min", "max" ], "additionalProperties": false, "description": "Preisspanne über alle Varianten." } }, "required": [ "id", "title", "detailedTitle", "brand", "mpn", "gtins", "productClass", "productType", "category", "locale", "textLocales", "country", "images", "badge", "highlights", "texts", "aiTexts", "prosCons", "review", "specs", "attributions", "profile", "completeness", "offers", "usedOffers", "linkOffers", "ebayOffers", "documents", "status", "activityState", "offersStatus", "updatedAt", "variantOf", "variantLabel", "variants", "lowestVariant", "isModel", "variantAxes", "priceRange" ], "additionalProperties": false, "description": "Ein Produkt mit Texten, Bildern, Merkmalen und den aktuellen Angeboten der Shops. Felder ohne Wert sind `null` oder leere Listen." }, "ProductRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Auftragsnummer." }, "input": { "allOf": [ { "$ref": "#/components/schemas/ProductRequestTarget" } ], "description": "Wonach gesucht wurde." }, "status": { "type": "string", "enum": [ "queued", "searching", "selecting", "completed", "needs_selection", "not_found", "failed", "rejected" ], "description": "Stand: `queued` (wartet), `searching` (Suche läuft), `selecting` (Auswahl läuft), `completed` (fertig), `needs_selection` (Auswahl durch dich nötig), `not_found` (nichts gefunden), `failed` (fehlgeschlagen), `rejected` (abgelehnt)." }, "productId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Kennung des zugeordneten Produkts, sobald der Auftrag abgeschlossen ist." }, "match": { "nullable": true, "type": "object", "properties": { "method": { "type": "string", "enum": [ "gtin", "asin", "mpn", "previous_request", "search", "manual", "llm", "pack", "tariff", "manual_link" ] }, "confidence": { "type": "number" }, "notes": { "type": "array", "items": { "type": "string" } }, "packCount": { "nullable": true, "type": "integer" }, "tariffOffers": { "type": "integer" }, "tariffName": { "nullable": true, "type": "string" } }, "required": [ "method", "confidence", "notes" ], "additionalProperties": false, "description": "Wie das Produkt gefunden wurde." }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRequestCandidate" }, "description": "Kandidaten, aus denen gewählt werden kann (Status `needs_selection`)." }, "llmCheck": { "nullable": true, "type": "object", "properties": { "choice": { "nullable": true, "type": "string" }, "confidence": { "type": "number" }, "reason": { "type": "string" }, "checkedAt": { "type": "string" } }, "required": [ "choice", "confidence", "reason", "checkedAt" ], "additionalProperties": false }, "error": { "nullable": true, "type": "string", "description": "Fehlermeldung, falls der Auftrag fehlgeschlagen ist." }, "createdAt": { "type": "string", "description": "Zeitpunkt, zu dem der Auftrag angelegt wurde." }, "completedAt": { "nullable": true, "type": "string", "description": "Zeitpunkt des Abschlusses; solange der Auftrag läuft, `null`." } }, "required": [ "id", "input", "status", "productId", "match", "candidates", "llmCheck", "error", "createdAt", "completedAt" ], "additionalProperties": false, "description": "Ein Produktauftrag mit Eingabe, Stand und Ergebnis." }, "ProductRequestCandidate": { "type": "object", "properties": { "ref": { "type": "string" }, "shop": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ] }, "name": { "type": "string" } }, "required": [ "id", "type", "name" ], "additionalProperties": false }, "externalId": { "type": "string" }, "url": { "type": "string", "maxLength": 2048 }, "title": { "type": "string" }, "brand": { "nullable": true, "type": "string" }, "gtins": { "type": "array", "items": { "type": "string" } }, "mpn": { "nullable": true, "type": "string" }, "productType": { "nullable": true, "type": "string" }, "categoryPath": { "maxItems": 6, "type": "array", "items": { "type": "string" } }, "price": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } }, "packCount": { "nullable": true, "type": "integer" }, "tariff": { "type": "boolean" } }, "required": [ "ref", "shop", "externalId", "title", "brand", "gtins", "mpn", "productType", "price", "score", "reasons" ], "additionalProperties": false }, "ProductRequestTarget": { "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 200 }, "gtin": { "type": "string", "maxLength": 20 }, "asin": { "type": "string", "maxLength": 20 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "brand": { "type": "string", "maxLength": 80 }, "mpn": { "type": "string", "maxLength": 80 } }, "additionalProperties": false }, "ProductRequestTargetInput": { "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Freier Suchbegriff, z. B. „Bosch GSR 12V-15“." }, "gtin": { "type": "string", "maxLength": 20, "description": "EAN oder UPC." }, "asin": { "type": "string", "maxLength": 20, "description": "ASIN von Amazon." }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Adresse einer Produktseite im Shop." }, "brand": { "type": "string", "maxLength": 80, "description": "Marke." }, "mpn": { "type": "string", "maxLength": 80, "description": "Modellnummer des Herstellers." } } }, "ProductWithReplacement": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "detailedTitle": { "default": null, "nullable": true, "type": "string" }, "brand": { "nullable": true, "type": "string" }, "mpn": { "nullable": true, "type": "string" }, "gtins": { "type": "array", "items": { "type": "string" } }, "productClass": { "type": "string", "enum": [ "goods", "service", "tariff" ] }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "path" ], "additionalProperties": false }, "category": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, "locale": { "type": "string" }, "textLocales": { "default": null, "nullable": true, "type": "object", "properties": { "title": { "nullable": true, "type": "string" }, "detailedTitle": { "nullable": true, "type": "string" }, "short": { "nullable": true, "type": "string" }, "long": { "nullable": true, "type": "string" } }, "required": [ "title", "detailedTitle", "short", "long" ], "additionalProperties": false }, "country": { "type": "string" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "badge": { "nullable": true, "type": "string" }, "highlights": { "type": "array", "items": { "type": "string" } }, "texts": { "type": "object", "properties": { "short": { "nullable": true, "type": "string" }, "long": { "nullable": true, "type": "string" }, "verdict": { "default": null, "nullable": true, "type": "string" }, "social": { "default": null, "nullable": true, "type": "string" } }, "required": [ "short", "long", "verdict", "social" ], "additionalProperties": false }, "aiTexts": { "default": null, "nullable": true, "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string", "enum": [ "short", "long", "prosCons", "verdict", "social" ] } }, "label": { "type": "boolean" } }, "required": [ "fields", "label" ], "additionalProperties": false }, "prosCons": { "nullable": true, "type": "object", "properties": { "pros": { "type": "array", "items": { "type": "string" } }, "cons": { "type": "array", "items": { "type": "string" } } }, "required": [ "pros", "cons" ], "additionalProperties": false }, "review": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Review" } ] }, "specs": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SpecItem" } } }, "required": [ "group", "items" ], "additionalProperties": false } }, "attributions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "license": { "nullable": true, "type": "string" }, "licenseUrl": { "nullable": true, "type": "string" }, "notice": { "nullable": true, "type": "string" } }, "required": [ "source", "name", "url", "license", "licenseUrl", "notice" ], "additionalProperties": false } }, "profile": { "nullable": true, "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "partial" ] }, "locale": { "type": "string" }, "strengths": { "type": "array", "items": { "type": "string" } }, "weaknesses": { "type": "array", "items": { "type": "string" } }, "audience": { "nullable": true, "type": "string" }, "specials": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "llm", "manual" ] }, "updatedAt": { "type": "string" } }, "required": [ "status", "locale", "strengths", "weaknesses", "audience", "specials", "source", "updatedAt" ], "additionalProperties": false }, "completeness": { "$ref": "#/components/schemas/SpecCompleteness" }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "usedOffers": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "linkOffers": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "shop": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "amazon", "awin", "ebay", "woocommerce", "tradedoubler", "adcell", "aliexpress", "feed", "webgains", "adtraction" ] }, "name": { "type": "string" }, "logoUrl": { "nullable": true, "type": "string" }, "own": { "type": "boolean" } }, "required": [ "id", "type", "name", "logoUrl", "own" ], "additionalProperties": false }, "country": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "shop", "country", "url" ], "additionalProperties": false } }, "ebayOffers": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "language": { "nullable": true, "type": "string" }, "url": { "type": "string" }, "sizeBytes": { "nullable": true, "type": "integer" }, "pageCount": { "default": null, "nullable": true, "type": "integer" }, "eprelUrl": { "default": null, "nullable": true, "type": "string" } }, "required": [ "type", "title", "language", "url", "sizeBytes", "pageCount", "eprelUrl" ], "additionalProperties": false } }, "status": { "type": "string", "enum": [ "available", "unavailable", "discontinued" ] }, "activityState": { "type": "string", "enum": [ "catalog", "active", "paused" ] }, "offersStatus": { "type": "string", "enum": [ "available", "pending", "none" ] }, "updatedAt": { "type": "string" }, "variantOf": { "default": null, "nullable": true, "type": "string" }, "variantLabel": { "default": null, "nullable": true, "type": "string" }, "variants": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "label": { "nullable": true, "type": "string" }, "price": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "available": { "type": "boolean" }, "url": { "default": null, "nullable": true, "type": "string" }, "shopName": { "default": null, "nullable": true, "type": "string" }, "shopType": { "default": null, "nullable": true, "type": "string" }, "axes": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "color": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false } }, "required": [ "key", "label", "value" ], "additionalProperties": false } }, "color": { "default": null, "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false }, "image": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "bestOffer": { "default": null, "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Offer" } ] }, "isDefault": { "default": false, "type": "boolean" } }, "required": [ "id", "title", "label", "price", "available", "url", "shopName", "shopType", "axes", "color", "image", "bestOffer", "isDefault" ], "additionalProperties": false } }, "lowestVariant": { "default": null, "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "label": { "nullable": true, "type": "string" }, "price": { "$ref": "#/components/schemas/Money" } }, "required": [ "id", "label", "price" ], "additionalProperties": false }, "isModel": { "default": false, "type": "boolean" }, "variantAxes": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "variantIds": { "type": "array", "items": { "type": "string" } }, "color": { "nullable": true, "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "hex": { "nullable": true, "type": "string" }, "hexes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "hex" ], "additionalProperties": false } }, "required": [ "value", "variantIds" ], "additionalProperties": false } } }, "required": [ "key", "label", "values" ], "additionalProperties": false } }, "priceRange": { "default": null, "nullable": true, "type": "object", "properties": { "min": { "$ref": "#/components/schemas/Money" }, "max": { "$ref": "#/components/schemas/Money" } }, "required": [ "min", "max" ], "additionalProperties": false }, "replacement": { "nullable": true, "type": "object", "properties": { "relation": { "type": "string", "enum": [ "successor", "alternative" ] }, "reason": { "type": "string", "enum": [ "unavailable", "discontinued" ] }, "origin": { "default": "central", "type": "string", "enum": [ "site", "own", "central" ] }, "notice": { "default": "", "type": "string" }, "product": { "$ref": "#/components/schemas/Product" } }, "required": [ "relation", "reason", "origin", "notice", "product" ], "additionalProperties": false } }, "required": [ "id", "title", "detailedTitle", "brand", "mpn", "gtins", "productClass", "productType", "category", "locale", "textLocales", "country", "images", "badge", "highlights", "texts", "aiTexts", "prosCons", "review", "specs", "attributions", "profile", "completeness", "offers", "usedOffers", "linkOffers", "ebayOffers", "documents", "status", "activityState", "offersStatus", "updatedAt", "variantOf", "variantLabel", "variants", "lowestVariant", "isModel", "variantAxes", "priceRange", "replacement" ], "additionalProperties": false }, "Review": { "type": "object", "properties": { "scale": { "type": "string", "enum": [ "grade", "points10", "points100", "stars5" ] }, "score": { "type": "number" }, "best": { "type": "number" }, "worst": { "type": "number" }, "normalized": { "type": "number" }, "level": { "type": "integer", "minimum": 1, "maximum": 5 }, "verdict": { "type": "string" }, "scoreText": { "type": "string" }, "testedAt": { "nullable": true, "type": "string" }, "summary": { "nullable": true, "type": "string" }, "criteria": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "number" }, "normalized": { "type": "number" }, "scoreText": { "type": "string" } }, "required": [ "name", "score", "normalized", "scoreText" ], "additionalProperties": false } }, "locale": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "scale", "score", "best", "worst", "normalized", "level", "verdict", "scoreText", "testedAt", "summary", "criteria", "locale", "updatedAt" ], "additionalProperties": false }, "SearchHit": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brand": { "nullable": true, "type": "string" }, "productType": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false }, "image": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "bestPrice": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "offerCount": { "type": "integer" }, "status": { "type": "string", "enum": [ "available", "unavailable", "discontinued" ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asin", "gtin", "mpn" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false } } }, "required": [ "id", "title", "brand", "productType", "image", "bestPrice", "offerCount", "status", "identifiers" ], "additionalProperties": false }, "SpecCompleteness": { "type": "object", "properties": { "filled": { "type": "integer" }, "required": { "type": "integer" }, "missing": { "type": "array", "items": { "type": "string" } } }, "required": [ "filled", "required", "missing" ], "additionalProperties": false }, "SpecItem": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "raw": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ] }, "unit": { "nullable": true, "type": "string" }, "compare": { "type": "string", "enum": [ "higher", "lower", "none" ] }, "importance": { "type": "string", "enum": [ "key", "standard", "detail" ] } }, "required": [ "key", "label", "value", "raw", "unit", "compare", "importance" ], "additionalProperties": false } }, "responses": { "BadRequest": { "description": "Die Anfrage ist ungültig (fehlende oder falsche Parameter). Die Einzelheiten stehen in `error.details`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig", "details": [ { "path": "ids", "message": "Ungültige Kennungen: abc" } ] } } } } }, "Unauthorized": { "description": "Der Schlüssel fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "Gültiger API-Key erforderlich" } } } } }, "PaymentRequired": { "description": "Das Konto ist gesperrt. Bitte Tarif und Zahlung im Konto prüfen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "payment_required", "message": "Dein Konto ist gesperrt" } } } } }, "Forbidden": { "description": "Dem Schlüssel fehlt die Berechtigung für diese Route, oder die Website bzw. der API-Client ist deaktiviert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "forbidden", "message": "Dem API-Client fehlt die Berechtigung \"products:read\"" } } } } }, "NotFound": { "description": "Nicht gefunden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "Produkt nicht gefunden" } } } } }, "TooManyRequests": { "description": "Zu viele Anfragen. Nach der Zeit aus dem Kopf `Retry-After` erneut versuchen.", "headers": { "Retry-After": { "description": "Sekunden, nach denen du es erneut versuchen kannst", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen" } } } } } }, "parameters": { "AcBlog": { "name": "X-AC-Blog", "in": "header", "required": false, "description": "Nur für Site-Schlüssel von WordPress-Netzwerken: Nummer der Unterseite (`get_current_blog_id()`). Bestimmt, welche Tracking-IDs in die Links kommen. Ungültige Werte werden ignoriert.", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "AcBlogName": { "name": "X-AC-Blog-Name", "in": "header", "required": false, "description": "Name der Unterseite, prozentkodiert (UTF-8). Nur zusammen mit `X-AC-Blog`.", "schema": { "type": "string", "maxLength": 200 } }, "AcBlogUrl": { "name": "X-AC-Blog-Url", "in": "header", "required": false, "description": "Adresse der Unterseite, prozentkodiert (UTF-8). Nur zusammen mit `X-AC-Blog`.", "schema": { "type": "string", "maxLength": 500 } } }, "headers": { "RateLimitLimit": { "description": "Erlaubte Anfragen pro Minute für diesen Schlüssel", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Noch verbleibende Anfragen im laufenden Zeitfenster", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Sekunden bis zum Ende des laufenden Zeitfensters", "schema": { "type": "integer" } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ac_…", "description": "Schlüssel aus deinem Konto (beginnt mit `ac_`) im Kopf `Authorization: Bearer ac_…`. Site-Schlüssel gehören zu einer Website, API-Clients zu einer eigenen Anwendung." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternative zu `Authorization`: derselbe Schlüssel im Kopf `X-API-Key`." } } } }