openapi: 3.1.0
info:
  title: flinkey Keyfob Catalog
  version: "1.0"
  description: >
    Public keyfob catalog for the flinkey digital vehicle access platform.
    Returns all supported vehicle brands and their keyfob variants (box types),
    including SAP article numbers and keyfob images.
    This is the same data source used by https://witte.digital/schluesseltypen/.

servers:
  - url: https://api.flinkey.de
    description: flinkey Production API (public keyfob endpoint, no auth required)

paths:
  /keyfob/keys:
    get:
      operationId: getKeyfobCatalog
      summary: Search the flinkey keyfob catalog by vehicle brand
      description: >
        Returns keyfob variants per brand. Use the search parameter to
        filter by brand name. Each entry has a box type code, SAP number,
        and keyfob image URL.
      parameters:
        - name: search
          in: query
          required: true
          description: >
            Vehicle brand name to search for (case-insensitive, partial
            match). Examples: "bmw", "volkswagen", "mercedes", "audi".
            Always provide this parameter to avoid response size limits.
          schema:
            type: string
          example: "bmw"
      responses:
        "200":
          description: Array of brands, each containing their keyfob entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Brand"

components:
  schemas:
    Brand:
      type: object
      required: [name, keys]
      properties:
        name:
          type: string
          description: Vehicle brand name in uppercase (e.g. "AUDI", "BMW", "VOLKSWAGEN")
        keys:
          type: array
          description: All keyfob variants available for this brand
          items:
            $ref: "#/components/schemas/KeyfobEntry"

    KeyfobEntry:
      type: object
      required: [boxName, boxSapNumber, keyFormImageUrl]
      properties:
        boxName:
          type: string
          description: >
            Human-readable name encoding the 3-digit variant code, product line,
            and box type. Example: "124 - BLE - flinkey Box Typ 124".
            Parse the first 3 characters to extract the variant code.
          example: "124 - BLE - flinkey Box Typ 124"
        boxSapNumber:
          type: string
          description: >
            SAP article number (14 digits). The last 3 digits match the variant
            code. The middle digits encode the product line (e.g. 03=BLE,
            05=CAN+KPC, 06=CAN, 07=BLE+KPC, 14=IXL+KPC, 15=IXL).
          example: "01501103000124"
        keyFormImageUrl:
          type: string
          format: uri
          description: >
            URL to a thumbnail image of the physical keyfob shape (JPEG, hosted
            on Azure Blob Storage). Use this to show the user what their car key
            should look like. Multiple entries with the same variant code but
            different image URLs indicate different visual variants of the same
            keyfob shape.
          example: "https://wittedigitalsaprod.blob.core.windows.net/wittedigitalkeyfobstorage-prod/KeyFormImages/example_thumb.jpg"