{
  "openapi": "3.1.0",
  "info": {
    "title": "ZahnriemenCheck Partner API",
    "summary": "Fahrzeugpruefung fuer Zahnriemen oder Steuerkette",
    "version": "1.1.0",
    "description": "API zur Pruefung, ob ein Fahrzeug einen Zahnriemen oder eine Steuerkette nutzt. Version 1.1 bleibt request- und response-kompatibel zu 1.0 und ergaenzt optionale Evidenz- und Verifikationsmetadaten.",
    "termsOfService": "https://zahnriemencheck.at/impressum/",
    "contact": {
      "name": "ZahnriemenCheck API",
      "url": "https://zahnriemencheck.at/api/"
    }
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [
    {
      "url": "https://zahnriemencheck.at",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Vehicle checks",
      "description": "Zahnriemen-/Steuerketten-Pruefung fuer ein einzelnes Fahrzeug"
    }
  ],
  "paths": {
    "/.netlify/functions/check-vehicle-api": {
      "post": {
        "tags": ["Vehicle checks"],
        "summary": "Fahrzeug pruefen",
        "description": "Prueft ein einzelnes Fahrzeug anhand technischer Fahrzeugdaten. Fuer groessere Anfragevolumen oder regelmaessige Serienabfragen werden Zugriff, Kontingent und technische Rahmenbedingungen vorab abgestimmt.",
        "operationId": "checkVehicleTimingDrive",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          },
          {
            "ZahnriemenApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VehicleCheckRequest"
              },
              "examples": {
                "workshopVehicle": {
                  "summary": "Werkstattfahrzeug mit Motorcode",
                  "value": {
                    "brand": "VW",
                    "model": "Golf 7",
                    "engine": "1.4 TSI",
                    "motorCode": "CZCA",
                    "fuel": "Benzin",
                    "firstRegisteredAt": "2019-04-10",
                    "power": "140 PS",
                    "displacement": "1395 ccm"
                  }
                },
                "technicalVehicleData": {
                  "summary": "Technische Fahrzeugdaten",
                  "value": {
                    "brand": "Mitsubishi",
                    "modelName": "Outlander PHEV",
                    "engine": "2.0 4WD",
                    "fuel": "Hybrid",
                    "firstRegisteredAt": "2017-04-12",
                    "kfztypCp": "JMBXDDG2WHZ",
                    "modelCode": "OUTLANDER",
                    "engineCodeSource": "4B11"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pruefergebnis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VehicleCheckResponse"
                },
                "examples": {
                  "belt": {
                    "summary": "Zahnriemen erkannt",
                    "value": {
                      "hasBelt": true,
                      "hasChain": false,
                      "motorCode": "EA211 / CZCA",
                      "wechselintervall": "alle 5 Jahre / 210.000 km",
                      "wartungshinweis": "Intervall fahrzeuggenau im Serviceheft pruefen.",
                      "explanation": "Der 1.4 TSI EA211/CZCA wird als Zahnriemenmotor gefuehrt.",
                      "confidence": "high",
                      "evidence": [
                        {
                          "url": "https://example.com/workshop-manual",
                          "title": "Workshop manual",
                          "sourceType": "manufacturer",
                          "supports": "belt",
                          "vehicleMatch": true,
                          "engineMatch": true,
                          "note": "Motorcode und Ventiltrieb stimmen ueberein."
                        }
                      ],
                      "conflicts": [],
                      "verification": {
                        "status": "verified",
                        "cacheable": true,
                        "reasons": [],
                        "sourceCount": 2
                      },
                      "cache": {
                        "hit": false,
                        "key": "sha256-cache-key",
                        "checkedAt": "2026-07-19T20:00:00.000Z",
                        "lookup": "web_search"
                      },
                      "mode": "api"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "options": {
        "tags": ["Vehicle checks"],
        "summary": "CORS Preflight",
        "operationId": "vehicleCheckCorsPreflight",
        "responses": {
          "200": {
            "description": "CORS preflight response"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Empfohlene Authentifizierung: Authorization: Bearer <API_KEY>"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Alternative Header-Authentifizierung."
      },
      "ZahnriemenApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Zahnriemen-Api-Key",
        "description": "Kompatibler alternativer Header."
      }
    },
    "schemas": {
      "VehicleCheckRequest": {
        "type": "object",
        "description": "Fahrzeugdaten fuer eine einzelne Pruefung. Mindestens Modell oder Modellname plus Baujahr oder Erstzulassung sowie ein technisches Identifikationsmerkmal sind erforderlich.",
        "properties": {
          "brand": {
            "type": "string",
            "description": "Fahrzeugmarke.",
            "examples": ["VW"]
          },
          "make": {
            "type": "string",
            "description": "Alias fuer brand."
          },
          "model": {
            "type": "string",
            "description": "Modellbezeichnung.",
            "examples": ["Golf 7"]
          },
          "modelName": {
            "type": "string",
            "description": "Alias fuer model."
          },
          "engine": {
            "type": "string",
            "description": "Motorisierung oder Motorbeschreibung.",
            "examples": ["1.4 TSI"]
          },
          "motorCode": {
            "type": "string",
            "description": "Motorkennbuchstabe oder Motorcode.",
            "examples": ["CZCA"]
          },
          "fuel": {
            "type": "string",
            "description": "Kraftstoffart. Gängige technische Kraftstoffcodes werden normalisiert.",
            "examples": ["Benzin", "Diesel", "Hybrid", "Elektro"]
          },
          "year": {
            "type": "string",
            "description": "Baujahr oder Modelljahr.",
            "examples": ["2019"]
          },
          "firstRegisteredAt": {
            "type": "string",
            "description": "Erstzulassung. ISO-Format YYYY-MM-DD empfohlen.",
            "examples": ["2019-04-10"]
          },
          "power": {
            "type": "string",
            "description": "Leistung als PS oder kW.",
            "examples": ["140 PS", "103 kW"]
          },
          "displacement": {
            "type": "string",
            "description": "Hubraum.",
            "examples": ["1395 ccm"]
          },
          "vin": {
            "type": "string",
            "description": "Fahrgestellnummer. Wird nur als SHA-256-Hash fuer Cache-/Identitaetsabgleiche verwendet, nicht an das KI-Modell uebergeben und nicht als Ersatz fuer einen Motorcode decodiert."
          },
          "kfztypCp": {
            "type": "string",
            "description": "Optionaler technischer Fahrzeugtyp."
          },
          "modelCode": {
            "type": "string",
            "description": "Optionaler Modellcode."
          },
          "engineCodeSource": {
            "type": "string",
            "description": "Optionale Motorcode-Quelle."
          },
          "caller": {
            "type": "string",
            "description": "Optionaler Quellname fuer die Partnerintegration."
          },
          "bypassCache": {
            "type": "boolean",
            "default": false,
            "description": "Erzwingt eine neue Analyse. Nur nach Absprache verwenden."
          }
        },
        "allOf": [
          {
            "anyOf": [
              {
                "required": ["model"]
              },
              {
                "required": ["modelName"]
              }
            ]
          },
          {
            "anyOf": [
              {
                "required": ["year"]
              },
              {
                "required": ["firstRegisteredAt"]
              }
            ]
          },
          {
            "anyOf": [
              {
                "required": ["engine"]
              },
              {
                "required": ["motorCode"]
              },
              {
                "required": ["kfztypCp"]
              },
              {
                "required": ["vin"]
              }
            ]
          }
        ],
        "additionalProperties": true
      },
      "VehicleCheckResponse": {
        "type": "object",
        "properties": {
          "hasBelt": {
            "type": "boolean",
            "description": "true, wenn ein Zahnriemen erkannt wurde."
          },
          "hasChain": {
            "type": "boolean",
            "description": "true, wenn eine Steuerkette erkannt wurde."
          },
          "motorCode": {
            "type": "string"
          },
          "wechselintervall": {
            "type": "string"
          },
          "wartungshinweis": {
            "type": "string"
          },
          "explanation": {
            "type": "string"
          },
          "confidence": {
            "type": "string",
            "enum": ["low", "medium", "high"]
          },
          "evidence": {
            "type": "array",
            "description": "Optionale, bei neuen Recherchen gelieferte Belege. Legacy-Cacheeintraege koennen ein leeres Array liefern.",
            "items": {
              "$ref": "#/components/schemas/EvidenceItem"
            }
          },
          "conflicts": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "verification": {
            "$ref": "#/components/schemas/VerificationMetadata"
          },
          "cache": {
            "$ref": "#/components/schemas/CacheMetadata"
          },
          "mode": {
            "type": "string",
            "const": "api"
          }
        },
        "required": ["hasBelt", "hasChain", "motorCode", "wechselintervall", "wartungshinweis", "explanation", "confidence", "cache", "mode"],
        "additionalProperties": false
      },
      "EvidenceItem": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "title": { "type": "string" },
          "sourceType": {
            "type": "string",
            "enum": ["manufacturer", "workshop", "parts_catalog", "technical_data", "other"]
          },
          "supports": {
            "type": "string",
            "enum": ["belt", "chain", "unclear"]
          },
          "vehicleMatch": { "type": "boolean" },
          "engineMatch": { "type": "boolean" },
          "note": { "type": "string" }
        },
        "required": ["url", "title", "sourceType", "supports", "vehicleMatch", "engineMatch", "note"],
        "additionalProperties": false
      },
      "VerificationMetadata": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["verified", "known_rule", "insufficient", "conflict", "timeout", "legacy"]
          },
          "cacheable": { "type": "boolean" },
          "reasons": {
            "type": "array",
            "items": { "type": "string" }
          },
          "sourceCount": { "type": "integer", "minimum": 0 }
        },
        "required": ["status", "cacheable", "reasons", "sourceCount"],
        "additionalProperties": false
      },
      "CacheMetadata": {
        "type": "object",
        "properties": {
          "hit": {
            "type": "boolean"
          },
          "key": {
            "type": "string"
          },
          "checkedAt": {
            "type": "string",
            "format": "date-time"
          },
          "lookup": {
            "type": "string",
            "enum": ["vin_hash", "cache_key", "request_hash_legacy", "known_rule", "web_search"]
          }
        },
        "required": ["hit", "key", "checkedAt", "lookup"],
        "additionalProperties": false
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": ["error"],
        "additionalProperties": false
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Ungueltige oder unvollstaendige Anfrage.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Bitte mindestens Modell/Modellbezeichnung uebergeben."
            }
          }
        }
      },
      "Unauthorized": {
        "description": "API-Key fehlt, ist ungueltig oder wurde deaktiviert.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "API-Key fehlt oder ist ungueltig."
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "Nur POST und OPTIONS sind erlaubt.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Method not allowed"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Das Analyselimit ist kurzzeitig erreicht.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Das Analyselimit ist kurzzeitig erreicht. Bitte warten Sie 30 Sekunden und versuchen Sie es erneut."
            }
          }
        }
      },
      "ServerError": {
        "description": "Serverseitiger Fehler.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Fehler bei der Fahrzeugpruefung. Bitte versuchen Sie es spaeter erneut."
            }
          }
        }
      }
    }
  }
}