{"openapi":"3.1.0","info":{"title":"Zevra Kennzeichen-Check","version":"1.0.0","description":"Wunschkennzeichen live prüfen und reservieren. Grundgebühr 50,00 € im Monat, 0,05 € je berechneter Prüfung, 2,00 € je erfolgreicher Reservierung (netto, zuzüglich Behördengebühren). Limit: 120 Anfragen pro Minute je Schlüssel. Schlüssel mit wkz_sbx_ sind Sandbox-Schlüssel: feste Szenarien, keine Behörde, keine Berechnung."},"servers":[{"url":"https://app.zevra24.de/api/kc/v1"}],"paths":{"/search":{"get":{"summary":"Verfügbarkeit einer Kombination prüfen","security":[{"WkzKey":[]}],"parameters":[{"name":"prefix","in":"query","required":true,"schema":{"type":"string"}},{"name":"letters","in":"query","required":true,"schema":{"type":"string"}},{"name":"numbers","in":"query","required":true,"schema":{"type":"string"}},{"name":"plz","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{5}$"},"description":"Postleitzahl, wenn das Kürzel zu mehreren Zulassungsstellen gehört (ambiguous_prefix)"},{"name":"office_id","in":"query","required":false,"schema":{"type":"string"},"description":"Kennung der Zulassungsstelle aus der Antwort ambiguous_prefix"}],"responses":{"401":{"description":"Schlüssel fehlt oder ist ungültig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monatslimit erreicht oder zu viele Anfragen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}}}}},"/search/batch":{"post":{"summary":"Bis zu 50 Kombinationen in einem Aufruf prüfen","security":[{"WkzKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/Plate"}}}}}}},"responses":{"401":{"description":"Schlüssel fehlt oder ist ungültig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monatslimit erreicht oder zu viele Anfragen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResult"}}}},"400":{"description":"Ungültige Anfrage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reservations":{"post":{"summary":"Reservierung anlegen (nur mit aktivem Abonnement oder Sandbox-Schlüssel)","security":[{"WkzKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":80}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationRequest"}}}},"responses":{"401":{"description":"Schlüssel fehlt oder ist ungültig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monatslimit erreicht oder zu viele Anfragen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"202":{"description":"Angenommen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reservation"}}}},"200":{"description":"Bereits angelegt (gleicher Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reservation"}}}},"400":{"description":"Ungültige Anfrage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Abonnement erforderlich","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key mit anderem Inhalt verwendet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reservations/{rid}":{"get":{"summary":"Status einer Reservierung","security":[{"WkzKey":[]}],"parameters":[{"name":"rid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"401":{"description":"Schlüssel fehlt oder ist ungültig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monatslimit erreicht oder zu viele Anfragen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reservation"}}}},"404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"summary":"Verbrauch und Kosten des laufenden Zeitraums","security":[{"WkzKey":[]}],"responses":{"401":{"description":"Schlüssel fehlt oder ist ungültig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monatslimit erreicht oder zu viele Anfragen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}}}}},"/offices":{"get":{"summary":"Zulassungsstellen und Zustand, optional nach Kürzel gefiltert (ohne Schlüssel)","parameters":[{"name":"code","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Offices"}}}}}}},"/sandbox/scenarios":{"get":{"summary":"Feste Szenarien der Sandbox (ohne Schlüssel)","responses":{"200":{"description":"OK"}}}},"/openapi.json":{"get":{"summary":"Diese Beschreibung","responses":{"200":{"description":"OK"}}}}},"webhooks":{"reservation.updated":{"post":{"summary":"Statuswechsel einer Reservierung, signiert mit HMAC-SHA256 (X-Zevra-Signature über »Zeitstempel.Inhalt«)","parameters":[{"name":"X-Zevra-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Zevra-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Zevra-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"reservation.updated"},"created":{"type":"string"},"data":{"$ref":"#/components/schemas/Reservation"}}}}}},"responses":{"200":{"description":"Jede 2xx-Antwort gilt als zugestellt; sonst Wiederholung nach 1, 5, 30, 120, 720 Minuten"}}}}},"components":{"securitySchemes":{"WkzKey":{"type":"apiKey","in":"header","name":"X-WKZ-Key"}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["backend","bad_request","batch_size","holder","idem_conflict","idem_key","letters","no_backend","not_found","numbers","prefix","quota_exhausted","rate_limited","revoked","subscription_required","unauthorized"]},"message":{"type":"string"}}},"Plate":{"type":"object","required":["prefix","letters","numbers"],"properties":{"prefix":{"type":"string","example":"RE","description":"Unterscheidungszeichen, 1 bis 3 Buchstaben"},"letters":{"type":"string","example":"AB","description":"1 bis 2 Buchstaben"},"numbers":{"type":"string","example":"123","description":"1 bis 4 Ziffern, ohne führende Null"}}},"SearchResult":{"type":"object","properties":{"plate":{"type":["string","null"],"example":"RE-AB 123"},"available":{"type":["boolean","null"],"description":"true = frei · false = vergeben · null = keine Aussage (nie als vergeben anzeigen)"},"reason":{"type":"string","enum":["checked","checked_via_twin","check_failed","office_not_queryable","ambiguous_prefix","unknown_prefix","invalid"]},"sandbox":{"type":"boolean"}}},"Holder":{"type":"object","required":["name","plz","ort"],"properties":{"name":{"type":"string"},"vorname":{"type":"string"},"geburtsdatum":{"type":"string"},"strasse":{"type":"string"},"plz":{"type":"string"},"ort":{"type":"string"}}},"Reservation":{"type":"object","properties":{"id":{"type":"string","example":"RES-7F3K2M9Q"},"status":{"type":"string","enum":["queued","processing","reserved","failed"]},"environment":{"type":"string","enum":["live","sandbox"]},"plate":{"type":"string"},"customerReference":{"type":["string","null"]},"reason":{"type":["string","null"]},"reservationCode":{"type":["string","null"],"description":"Code der Behörde für die Zulassung, nur bei status=reserved"},"authorityFeeAdvancedCents":{"type":"integer","description":"Von Zevra verauslagte Behördengebühr in Cent (durchlaufender Posten)"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}},"BatchResult":{"type":"object","properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}}},"ReservationRequest":{"type":"object","required":["prefix","letters","numbers","halter"],"properties":{"prefix":{"type":"string","example":"RE","description":"Unterscheidungszeichen, 1 bis 3 Buchstaben"},"letters":{"type":"string","example":"AB","description":"1 bis 2 Buchstaben"},"numbers":{"type":"string","example":"123","description":"1 bis 4 Ziffern, ohne führende Null"},"halter":{"$ref":"#/components/schemas/Holder"},"customerReference":{"type":"string","maxLength":80}}},"Usage":{"type":"object","properties":{"environment":{"type":"string"},"status":{"type":"string"},"checks":{"type":"integer"},"limit":{"type":"integer"},"reservations":{"type":"integer"},"usageCents":{"type":"integer"},"authorityFeesAdvancedCents":{"type":"integer"},"periodEnd":{"type":["string","null"]}}},"Offices":{"type":"object","properties":{"count":{"type":"integer"},"offices":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"bundesland":{"type":"string"},"codes":{"type":"array","items":{"type":"string"}},"check":{"type":"string","enum":["live","manual","down"]},"reserve":{"type":["string","null"]},"reservationDays":{"type":["integer","null"]}}}}}}}}}