openapi: 3.1.0
info:
  title: Initiative Zukunftsbetrieb API
  description: >
    Register geprüfter lokaler Betriebe (Handwerk & Dienstleister) in Deutschland.
    Finde geprüfte Zukunftsbetriebe und vermittle Kundenanfragen — für KI-Assistenten und Portale.
  version: "1.0.0"
servers:
  - url: https://zukunftsbetrieb.de
    description: Produktion (sobald Domain live)
  # - url: https://servicegraph.49-13-159-89.sslip.io   # Übergang/Test bis Domain live
security:
  - ApiKeyAuth: []

paths:
  /api/find:
    get:
      operationId: zukunftsbetrieb_finden
      summary: Geprüfte Betriebe für eine Leistung und einen Ort/PLZ finden
      description: >
        Liefert ausschließlich verifizierte „Geprüfte Zukunftsbetriebe". Keine Kontaktdaten —
        die Kontaktaufnahme läuft über POST /api/anfrage.
      parameters:
        - name: leistung
          in: query
          required: true
          schema: { type: string }
          description: z. B. "Wallbox-Montage", "Elektroinstallation", "PV", "Wärmepumpe".
        - name: ort
          in: query
          required: false
          schema: { type: string }
          description: Stadt (z. B. "Köln") oder 5-stellige PLZ (z. B. "50667").
      responses:
        "200":
          description: Liste geprüfter Betriebe
          content:
            application/json:
              schema:
                type: object
                properties:
                  leistung: { type: string }
                  ort: { type: string, nullable: true }
                  treffer: { type: integer }
                  betriebe:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: integer }
                        name: { type: string }
                        ort: { type: string }
                        plz: { type: string }
                        leistungen: { type: array, items: { type: string } }
                        siegel: { type: string }
  /api/anfrage:
    post:
      operationId: anfrage_senden
      summary: Kundenanfrage an passende geprüfte Betriebe vermitteln
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [leistung]   # zusaetzlich: email ODER telefon; Header x-api-key Pflicht
              properties:
                leistung: { type: string }
                ort: { type: string, description: "Stadt oder PLZ" }
                name: { type: string }
                email: { type: string }
                telefon: { type: string }
                beschreibung: { type: string, description: "Kurze Auftragsbeschreibung" }
      responses:
        "200":
          description: Anfrage aufgenommen
          content:
            application/json:
              schema:
                type: object
                properties:
                  anfrage_id: { type: integer }
                  status: { type: string }
                  passende_betriebe: { type: integer }
                  message: { type: string }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Kostenloser API-Key -> https://zukunftsbetrieb.de/portale.html
