{"openapi":"3.1.0","info":{"title":"Fakeshop AI Shop-Check API","version":"2026-11-16","description":"Prüft Online-Shops und Websites auf Betrugsmerkmale. Authentifizierung per Header X-Api-Key, Abrechnung über Prepaid-Credits (1 gelieferte Prüfung = 1 Credit). Ohne Schlüssel gilt ein knappes Tageslimit je IP. Ausführliche Beschreibung: docu/api-reference.md bzw. https://fakeshop.ai/entwickler.","contact":{"name":"Fakeshop AI","url":"https://fakeshop.ai/entwickler"}},"servers":[{"url":"https://api.fakeshop.ai","description":"Produktion (direkt, ohne Cloudflare)"},{"url":"https://fakeshop.ai","description":"Produktion (über die Website-Domain)"}],"security":[{"ApiKey":[]},{}],"tags":[{"name":"Prüfung","description":"Shop-/Website-Prüfung und Abfrage eingereihter Prüfungen"},{"name":"Meta"}],"paths":{"/api/check":{"post":{"tags":["Prüfung"],"operationId":"checkShop","summary":"Shop oder Website prüfen","description":"Liefert ein gespeichertes Ergebnis sofort (200, cached:true) oder prüft neu. Ist die Warteschlange aktiv, wird eine neue Prüfung angenommen (202) und das Ergebnis über GET /api/check/status/{jobId} abgefragt. Mit Schlüssel kostet jede Antwort 200 oder 202 einen Credit; scheitert die Prüfung (500, 504, Job-Status failed), wird er erstattet. Eingabefehler (400) kosten nichts. IBAN, E-Mail-Adresse, Telefonnummer und Krypto-Adresse werden im Feld url ebenfalls erkannt und gegen Meldungen geprüft (entityType im Ergebnis).","parameters":[{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["de","en"]},"description":"Sprache der Texte. Vorrang vor body.lang und Accept-Language. Default de."},{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckRequest"},"examples":{"shop":{"value":{"url":"https://beispiel-shop.de"}},"website":{"value":{"url":"beispiel.de","checkType":"website"}}}}}},"responses":{"200":{"description":"Ergebnis (gespeichert oder frisch geprüft)","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"202":{"description":"Prüfung angenommen, Ergebnis per Status-Abfrage holen","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Queued"}}}},"400":{"description":"Ungültige Eingabe (kein Credit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"url_required":{"value":{"error":"…","errorCode":"url_required"}},"invalid_url":{"value":{"error":"…","errorCode":"invalid_url"}},"invalid_check_type":{"value":{"error":"…","errorCode":"invalid_check_type"}},"invalid_json":{"value":{"error":"…","errorCode":"invalid_json"}}}}}},"401":{"description":"Schlüssel unbekannt, gesperrt oder gelöscht","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_key":{"value":{"error":"…","errorCode":"invalid_api_key"}}}}}},"402":{"description":"Guthaben aufgebraucht","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_credits":{"value":{"error":"…","errorCode":"insufficient_credits"}}}}}},"403":{"description":"Browser-Aufruf von fremder Origin (CORS). Die API ist für Server-Aufrufe gedacht.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"origin_not_allowed":{"value":{"error":"…","errorCode":"origin_not_allowed"}}}}}},"429":{"description":"Burst-Limit (je IP, Minute) oder Tageslimit erreicht","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"too_many_requests":{"value":{"error":"…","errorCode":"too_many_requests"}},"quota_exceeded":{"value":{"error":"…","errorCode":"quota_exceeded"}}}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Prüfung gescheitert (Credit erstattet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scan_failed":{"value":{"error":"…","errorCode":"scan_failed"}},"internal_error":{"value":{"error":"…","errorCode":"internal_error"}}}}}},"504":{"description":"Zeitlimit der synchronen Prüfung überschritten (Credit erstattet). Später erneut anfragen, das Ergebnis liegt dann meist im Cache.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scan_timeout":{"value":{"error":"…","errorCode":"scan_timeout"}}}}}}}}},"/api/check/status/{jobId}":{"get":{"tags":["Prüfung"],"operationId":"getCheckStatus","summary":"Status einer eingereihten Prüfung","description":"Kostenlos, kein Schlüssel nötig. Eigenes Burst-Limit (Default 120 Abfragen je Minute und IP). Empfohlenes Polling: alle 2 bis 5 Sekunden, Abbruch nach etwa 4 Minuten. Fertige und gescheiterte Aufträge werden eine Stunde aufbewahrt; danach 404. Die Texte im Ergebnis stehen in der Sprache der ursprünglichen Anfrage.","security":[{}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","pattern":"^scan-[A-Za-z0-9._-]{1,300}$"},"example":"scan-shop-de-beispiel-shop.de"}],"responses":{"200":{"description":"Status oder Ergebnis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatus"}}}},"404":{"description":"Auftrag unbekannt oder abgelaufen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"job_not_found":{"value":{"error":"…","errorCode":"job_not_found"}}}}}},"429":{"description":"Zu viele Status-Abfragen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"too_many_requests":{"value":{"error":"…","errorCode":"too_many_requests"}}}}}},"503":{"description":"Warteschlange nicht verfügbar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"queue_unavailable":{"value":{"error":"…","errorCode":"queue_unavailable"}},"job_status_failed":{"value":{"error":"…","errorCode":"job_status_failed"}}}}}}}}},"/api/openapi.json":{"get":{"tags":["Meta"],"operationId":"getOpenApi","summary":"Diese OpenAPI-Beschreibung","security":[{}],"responses":{"200":{"description":"OpenAPI 3.1","content":{"application/json":{}}}}}},"/api/shop-marks/{file}":{"get":{"tags":["Meta"],"operationId":"getShopMark","summary":"Favicon oder Logo eines geprüften Shops","description":"Bild aus shopProfile.mark. Bei uns abgelegt, validiert, auf höchstens 64 x 64 (Favicon) bzw. 240 x 80 (Logo) verkleinert und als PNG neu kodiert. Dateiname ist der Inhalts-Hash, der Inhalt ändert sich nie: Cache-Control public, max-age=31536000, immutable. Kostenlos, kein Schlüssel nötig.","security":[{}],"parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{32}\\.png$"}}],"responses":{"200":{"description":"PNG","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Unbekannte Datei"}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"fsk_live_ + 64 Hex-Zeichen. Im Portal unter Entwickler > API-Schlüssel erzeugen; wird nur einmal angezeigt."}},"headers":{"XRateLimitLimit":{"description":"Nur ohne Schlüssel: Tageslimit je IP (Website 500, sonst 50). Mit Schlüssel nur bei 429 durch das Tageslimit des Schlüssels.","schema":{"type":"integer"}},"XRateLimitRemaining":{"description":"Ohne Schlüssel: verbleibende Anfragen heute. Mit Schlüssel: Credit-Guthaben nach dieser Anfrage.","schema":{"type":"integer"}},"XRateLimitReset":{"description":"Sekunden bis 00:00 UTC (Tageslimit).","schema":{"type":"integer"}},"RateLimit":{"description":"Burst-Limiter nach IETF-Entwurf (Limit, Rest, Reset der laufenden Minute).","schema":{"type":"string"}},"RateLimitPolicy":{"description":"Burst-Policy, z. B. 20;w=60.","schema":{"type":"string"}},"RetryAfter":{"description":"Sekunden bis zum nächsten erlaubten Versuch.","schema":{"type":"integer"}}},"schemas":{"Error":{"type":"object","required":["error","errorCode"],"properties":{"error":{"type":"string","description":"Lokalisierter Text, nicht parsen"},"errorCode":{"type":"string","description":"Stabiler Code (englisch, snake_case)"}}},"CheckRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","maxLength":2048,"description":"Domain oder URL (Schema optional, IDN erlaubt). Keine IP-Adressen, keine lokalen oder reservierten Namen. Alternativ IBAN, E-Mail-Adresse, Telefonnummer oder Krypto-Adresse."},"checkType":{"type":"string","enum":["shop","website"],"default":"shop","description":"website = Seriositätsprüfung für Seiten ohne Shop"},"lang":{"type":"string","enum":["de","en"]},"force":{"type":"boolean","description":"Cache umgehen und synchron neu prüfen (bis 55 s). Kostet wie jede Prüfung einen Credit."}}},"Queued":{"type":"object","required":["status","jobId","domain"],"properties":{"status":{"const":"queued"},"jobId":{"type":"string"},"domain":{"type":"string"}}},"JobStatus":{"oneOf":[{"type":"object","required":["status"],"properties":{"status":{"enum":["queued","processing"]},"progress":{"$ref":"#/components/schemas/ScanProgress"}},"description":"Bei status processing optional der Zwischenstand der laufenden Prüfung (progress). Fehlt er, liegt keiner vor."},{"type":"object","required":["status","result"],"properties":{"status":{"const":"completed"},"result":{"$ref":"#/components/schemas/CheckResult"}}},{"type":"object","required":["status","errorCode"],"properties":{"status":{"const":"failed"},"error":{"type":"string"},"errorCode":{"const":"scan_failed"}}}]},"Factor":{"type":"object","properties":{"id":{"type":"string","example":"impressum"},"label":{"type":"string"},"status":{"type":"string","enum":["ok","warn","fail","unknown"]},"impact":{"type":"string","enum":["positive","neutral","negative"]},"reasons":{"type":"array","items":{"type":"string"}},"unknownKind":{"type":"string"},"aiGenerated":{"type":"boolean"},"display":{"type":"object"}}},"CheckResult":{"type":"object","description":"Öffentliche Projektion. Felder können je nach Ergebnis fehlen; unbekannte Felder ignorieren.","required":["domain","verdict"],"properties":{"domain":{"type":"string","description":"Registrierte Domain ohne www, IDN als Punycode"},"score":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"0 = sehr riskant, 100 = unauffällig; null bei not_a_shop/unreachable"},"verdict":{"type":"string","enum":["safe","suspicious","danger","not_a_shop","unreachable"]},"checkType":{"type":"string","enum":["shop","website"]},"entityType":{"type":"string","enum":["website","iban","crypto","email","phone"]},"cached":{"type":"boolean"},"checkedAt":{"type":"string","format":"date-time"},"factors":{"type":"array","items":{"$ref":"#/components/schemas/Factor"}},"trustLevel":{"type":"object","properties":{"level":{"type":"integer","minimum":1,"maximum":5},"label":{"type":"string"}}},"confidenceBand":{"type":"string","enum":["low","medium","high"]},"summary":{"type":"string"},"recommendation":{"type":"string"},"topSignals":{"type":"array","items":{"type":"object"}},"keyFindings":{"type":"array","items":{"type":"object"}},"isShop":{"type":["boolean","null"]},"shopDetection":{"type":"object"},"category":{"type":["string","null"]},"fakeshopStatus":{"type":["string","null"]},"brand":{"type":["object","null"]},"faviconUrl":{"type":["string","null"]},"previewImage":{"type":["string","null"]},"previewCapturedAt":{"type":["string","null"],"format":"date-time"},"shopProfile":{"$ref":"#/components/schemas/ShopProfile"},"aiSummary":{"type":["string","null"]},"aiContent":{"type":"object","description":"Kennzeichnung KI-erzeugter Texte (Art. 50 KI-VO): regulation, digitalSourceType, label, fields, translated"},"notice":{"type":["object","string","null"]}},"additionalProperties":true},"ScanProgress":{"type":"object","description":"Zwischenstand einer laufenden Prüfung: was gerade getan wird und wie viel schon getan ist, ohne Befund. Stufen in fester Reihenfolge: connect (Seite aufrufen), structure (Aufbau erfassen), pages (Seiten lesen), sources (Quellen abgleichen), assemble (Ergebnis zusammenstellen). pages und sources laufen gleichzeitig. Gedrosselt aktualisiert (höchstens alle 0,5 s).","required":["stage","stages","counts","pages"],"properties":{"stage":{"type":["string","null"],"enum":["connect","structure","pages","sources","assemble",null],"description":"Erste laufende Stufe, null zwischen zwei Stufen"},"stages":{"type":"array","minItems":5,"maxItems":5,"items":{"type":"object","required":["id","startedMs","endedMs"],"properties":{"id":{"enum":["connect","structure","pages","sources","assemble"]},"startedMs":{"type":["integer","null"],"description":"Beginn der Stufe in Millisekunden seit Start des Auftrags, null solange nicht begonnen"},"endedMs":{"type":["integer","null"],"description":"Ende der Stufe in Millisekunden seit Start des Auftrags, null solange sie läuft oder nicht begonnen hat"}}}},"counts":{"type":"object","required":["pagesFound","pagesRead","checksDone","checksTotal"],"properties":{"pagesFound":{"type":["integer","null"],"description":"Seiten der Domain, die die Startseite verlinkt, vereinigt mit den gelesenen; null solange unbekannt"},"pagesRead":{"type":"integer","description":"Gelesene Adressen der Domain (Startseite, Unterseiten, robots.txt, Sitemaps)"},"checksDone":{"type":"integer","description":"Abgeschlossene Prüfpunkte"},"checksTotal":{"type":["integer","null"],"description":"Prüfpunkte dieser Prüfung, null bis sie feststehen"}}},"pages":{"type":"array","maxItems":8,"description":"Zuletzt gelesene Pfade der geprüften Domain, ohne Abfrageteil. Keine Adressen Dritter.","items":{"type":"object","required":["path","state","stage"],"properties":{"path":{"type":"string","example":"/impressum"},"state":{"enum":["reading","read"]},"stage":{"enum":["connect","pages"]}}}},"checks":{"type":"object","required":["running","done"],"description":"Kennungen der Prüfpunkte dieser Prüfung (dieselben wie factors[].id im Ergebnis), ohne Status und ohne Befund. done heißt nur: geprüft. Fehlt bei älteren Workern; vor Beginn der Prüfpunkte sind beide Listen leer.","properties":{"running":{"type":"array","maxItems":80,"items":{"type":"string"},"description":"Prüfpunkte, die gerade laufen"},"done":{"type":"array","maxItems":80,"items":{"type":"string"},"description":"Prüfpunkte, die abgeschlossen sind"}}},"preview":{"type":["string","null"],"description":"Adresse des Vorschaubilds der Startseite (/api/previews/<sha256>.png, 1200×800 PNG), sobald es während der Prüfung geschrieben ist; null, solange keines vorliegt oder Vorschaubilder abgeschaltet sind (SCREENSHOT_ENABLED). Dasselbe Bild steht später als previewImage im Ergebnis."}},"example":{"stage":"pages","stages":[{"id":"connect","startedMs":0,"endedMs":1840},{"id":"structure","startedMs":1840,"endedMs":1846},{"id":"pages","startedMs":1850,"endedMs":null},{"id":"sources","startedMs":1850,"endedMs":null},{"id":"assemble","startedMs":null,"endedMs":null}],"counts":{"pagesFound":14,"pagesRead":3,"checksDone":12,"checksTotal":40},"pages":[{"path":"/","state":"read","stage":"connect"},{"path":"/impressum","state":"read","stage":"pages"},{"path":"/agb","state":"reading","stage":"pages"}],"checks":{"running":["reputationCheck","aiAnalysis"],"done":["impressum","ssl","domainAge"]},"preview":null}},"ShopProfileRating":{"type":["object","null"],"properties":{"rating":{"type":["number","null"],"description":"Sternewert der Plattform; null, wenn SHOW_THIRD_PARTY_RATINGS=false"},"reviewCount":{"type":["integer","null"]},"profileUrl":{"type":["string","null"],"format":"uri","description":"Öffentliche Profilseite der Plattform; nur Trustpilot- bzw. trustedshops.de-Adressen"},"fetchedAt":{"type":["string","null"],"format":"date","description":"Tag des Abrufs bei der Plattform"}}},"ShopProfile":{"type":["object","null"],"description":"Unternehmensprofil (seit 18.11.2026). Nur belegte Angaben der geprüften Seite, ohne Sprachmodell. Fehlt das Objekt oder ist es null, liegt kein Profil vor.","properties":{"mark":{"type":["object","null"],"description":"Favicon und Logo, bei uns abgelegt und neu kodiert (PNG). Nur bei verdict safe, sonst null. Die Bilder liegen unter /api/shop-marks/{file}, nie beim Shop.","properties":{"favicon":{"type":["string","null"],"pattern":"^/api/shop-marks/[a-f0-9]{32}\\.png$"},"logo":{"type":["string","null"],"pattern":"^/api/shop-marks/[a-f0-9]{32}\\.png$"}}},"description":{"type":["object","null"],"description":"Selbstbeschreibung der Seite, wörtlich, höchstens 300 Zeichen","properties":{"text":{"type":"string"},"source":{"type":"string","enum":["meta","og","jsonld"]}}},"contact":{"type":["object","null"],"description":"Anschrift laut Impressum oder schema.org. company ist null, wenn der Name eine Person sein kann; dann fehlt auch street.","properties":{"company":{"type":["string","null"]},"street":{"type":["string","null"]},"postalCode":{"type":"string"},"city":{"type":"string"},"country":{"type":["string","null"],"description":"ISO-Code, z. B. DE"},"phone":{"type":["string","null"]},"source":{"type":["string","null"],"enum":["impressum","impressum_text","jsonld",null]}}},"paymentMethods":{"type":["array","null"],"items":{"type":"string"},"description":"Zahlarten, die die Seite selbst nennt (Kennungen wie paypal, kreditkarte, klarna). Fließt nicht in den Score."},"ratings":{"type":["object","null"],"properties":{"trustpilot":{"$ref":"#/components/schemas/ShopProfileRating"},"trustedShops":{"$ref":"#/components/schemas/ShopProfileRating"}}},"updatedAt":{"type":["string","null"],"format":"date"}}}}}}