{
  "openapi": "3.0.3",
  "info": {
    "title": "Bringness AI Sales API",
    "version": "1.1.0",
    "description": "Standortbezogene Kassenschnittstelle. Schlüssel unter Kassen & API erstellen, Rezepte zuordnen und Verbindung aktivieren. Bis 100 Positionen je Ereignis, maximal 16000 Zeichen je Anfrage. 600 Anfragen je Verbindung pro 15 Minuten, einschließlich Status, Produktliste und Testimport. Bei 429 mit wachsendem Abstand wiederholen. Je Standort eigene Verbindung und Schlüssel. Optionaler Verbrauchsmodus lifecycle: Annahme reserviert, Zubereitungsstart verbraucht. Verkaufsimport und Küchenablauf dürfen nicht für dieselbe Verbindung gemischt werden. Verfügbarkeit vor Bestellannahme abrufen; die Reservierung prüft sie erneut atomar."
  },
  "servers": [
    {
      "url": "https://bringness-ai.com"
    }
  ],
  "security": [
    {
      "ConnectorKey": []
    }
  ],
  "paths": {
    "/api/ai/v1/sales": {
      "post": {
        "operationId": "importSale",
        "summary": "Rezeptverbrauch buchen oder zurückbuchen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Sale"
                  },
                  {
                    "$ref": "#/components/schemas/Reversal"
                  }
                ]
              },
              "example": {
                "eventId": "sale-1001",
                "type": "sale",
                "items": [
                  {
                    "productCode": "burger-1",
                    "quantity": 2
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Import bestätigt oder identische Wiederholung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "eventId",
                    "duplicate"
                  ],
                  "properties": {
                    "eventId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "duplicate": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/import/sales": {
      "post": {
        "operationId": "importSaleLegacy",
        "summary": "Rezeptverbrauch buchen oder zurückbuchen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Sale"
                  },
                  {
                    "$ref": "#/components/schemas/Reversal"
                  }
                ]
              },
              "example": {
                "eventId": "sale-1001",
                "type": "sale",
                "items": [
                  {
                    "productCode": "burger-1",
                    "quantity": 2
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Import bestätigt oder identische Wiederholung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "eventId",
                    "duplicate"
                  ],
                  "properties": {
                    "eventId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "duplicate": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": true
      }
    },
    "/api/ai/v1/sales/validate": {
      "post": {
        "operationId": "validateSale",
        "summary": "Ohne Bestandsänderung prüfen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Sale"
                  },
                  {
                    "$ref": "#/components/schemas/Reversal"
                  }
                ]
              },
              "example": {
                "eventId": "sale-1001",
                "type": "sale",
                "items": [
                  {
                    "productCode": "burger-1",
                    "quantity": 2
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Keine Änderung an Bestand, Ereignissen oder Sync-Zeit. Keine Reservierung; später geänderte Rezepte können den echten Import beeinflussen.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "dryRun",
                    "duplicate",
                    "effects"
                  ],
                  "properties": {
                    "dryRun": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "duplicate": {
                      "type": "boolean"
                    },
                    "eventId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "effects": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "stockId",
                          "delta"
                        ],
                        "properties": {
                          "stockId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "delta": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/v1/status": {
      "get": {
        "operationId": "connectorStatus",
        "summary": "Verbindung prüfen",
        "responses": {
          "200": {
            "description": "Status der aktiven Anbindung",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "connectorId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "locationId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "active": {
                      "type": "boolean"
                    },
                    "lastSync": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "lastError": {
                      "type": "string",
                      "nullable": true
                    },
                    "permissions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/v1/products": {
      "get": {
        "operationId": "mappedProducts",
        "summary": "Zugeordnete Artikelcodes dieses Standorts",
        "responses": {
          "200": {
            "description": "Artikelcodes mit aktivem Rezept und Zutaten; keine Lagerbestände",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "productCode": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 150
                          },
                          "name": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Fehler; keine Teilbuchung.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/v1/kitchen-orders": {
      "post": {
        "operationId": "updateKitchenInventory",
        "summary": "Zutaten reservieren, verbrauchen, Reservierung stornieren oder unbenutzte Zutaten zurückbuchen",
        "description": "Eigener Auftragsnamensraum pro Standort und Verbindung. Unter Kassen & API vor erster Buchung den Modus Reservierung & Zubereitung wählen. accept benötigt items; cancel und return benötigen reason; return außerdem confirmed=true und lines. locationId wird ausschließlich aus dem API-Schlüssel aufgelöst. Nach Zubereitungsbeginn gibt cancel keine Zutaten zurück. Rückbuchung nur bis zum verbleibenden ursprünglichen Verbrauch. Der API-Schlüssel ist ein privilegierter Lagerzugang und darf niemals Gästen zugänglich sein.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KitchenAction"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Aktion bestätigt oder identische Wiederholung; keine Doppelbuchung."
          },
          "400": {
            "description": "Ungültige Eingabe; keine Teilbuchung."
          },
          "401": {
            "description": "Ungültiger API-Schlüssel."
          },
          "403": {
            "description": "Verbindung nicht aktiv oder nicht im Modus lifecycle."
          },
          "409": {
            "description": "Konflikt, Fehlbestand oder unzulässiger Status; keine Teilbuchung."
          },
          "429": {
            "description": "Importlimit erreicht."
          },
          "500": {
            "description": "Serverfehler; Aktion mit derselben Kennung wiederholen."
          }
        }
      }
    },
    "/api/ai/v1/availability": {
      "get": {
        "operationId": "getRecipeAvailability",
        "summary": "Bestellbarkeit der Gerichte am Schlüsselstandort",
        "description": "available berücksichtigt aktives Rezept, manuelle Ausverkauft-Sperre und freie Zutaten nach Reservierungen. Angeschlossene Kassen müssen available=false in ihrem Bestellkanal durchsetzen. Ohne das ist eine externe Speisekarte nicht automatisch gesperrt.",
        "responses": {
          "200": {
            "description": "Gerichte mit Artikelcode, verfügbarer Bestellbarkeit und Ausverkauft-Sperre."
          },
          "401": {
            "description": "Ungültiger Schlüssel."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ConnectorKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Standortgebundener API-Schlüssel; kein AI-Login-Token."
      }
    },
    "schemas": {
      "SaleItem": {
        "type": "object",
        "required": [
          "productCode",
          "quantity"
        ],
        "properties": {
          "productCode": {
            "type": "string",
            "minLength": 1,
            "maxLength": 150
          },
          "quantity": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true,
            "maximum": 1000000,
            "multipleOf": 0.001
          }
        }
      },
      "Sale": {
        "type": "object",
        "required": [
          "eventId",
          "items"
        ],
        "properties": {
          "eventId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 150
          },
          "type": {
            "type": "string",
            "enum": [
              "sale"
            ],
            "default": "sale"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/SaleItem"
            }
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Optionaler ursprünglicher Ereigniszeitpunkt mit Zeitzone. Nicht mehr als 60 Sekunden in der Zukunft. Ohne Angabe bleibt die Importzeit die historische Grundlage. Ein gespeicherter Quellzeitpunkt darf bei Wiederholung nicht geändert werden."
          }
        }
      },
      "Reversal": {
        "type": "object",
        "required": [
          "eventId",
          "type",
          "reversesEventId"
        ],
        "properties": {
          "eventId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 150
          },
          "type": {
            "type": "string",
            "enum": [
              "reversal"
            ]
          },
          "reversesEventId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 150
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Optionaler ursprünglicher Ereigniszeitpunkt mit Zeitzone. Nicht mehr als 60 Sekunden in der Zukunft. Ohne Angabe bleibt die Importzeit die historische Grundlage. Ein gespeicherter Quellzeitpunkt darf bei Wiederholung nicht geändert werden."
          }
        }
      },
      "KitchenAction": {
        "type": "object",
        "required": [
          "requestKey",
          "action",
          "orderId"
        ],
        "properties": {
          "requestKey": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": [
              "accept",
              "start",
              "cancel",
              "return"
            ]
          },
          "orderId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 150
          },
          "reason": {
            "type": "string",
            "maxLength": 500
          },
          "confirmed": {
            "type": "boolean"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "required": [
                "productCode",
                "quantity"
              ],
              "properties": {
                "productCode": {
                  "type": "string",
                  "maxLength": 150
                },
                "quantity": {
                  "type": "number",
                  "exclusiveMinimum": true,
                  "minimum": 0,
                  "multipleOf": 0.001
                }
              }
            }
          },
          "lines": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "required": [
                "stockId",
                "quantity"
              ],
              "properties": {
                "stockId": {
                  "type": "string",
                  "format": "uuid"
                },
                "quantity": {
                  "type": "number",
                  "exclusiveMinimum": true,
                  "minimum": 0,
                  "multipleOf": 0.001
                }
              }
            }
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Optionaler ursprünglicher Zeitpunkt dieser Lageraktion mit Zeitzone. Bei Start/Rückbuchung als Quellzeit der Lagerbewegung gespeichert; keine Änderung bereits gebuchter Ereignisse durch Wiederholung."
          }
        }
      }
    }
  }
}
