GAMMA Fahrzeuge: Werkstatt und Probefahrten über die API

Dies ist die offizielle Schnittstelle der GAMMA Fahrzeuge GmbH in Rüthen für KI-Assistenten und andere API-Clients. Sie bietet Werkstatt-Terminarten, aktuelle freie Termine und direkte Buchungen. Probefahrten sind über separate /probefahrt-Endpunkte verfügbar und nutzen einen eigenen TidyCal-Account.

Zur normalen Terminbuchung bei GAMMA Fahrzeuge

API-Basis: https://api.gamma-fahrzeuge.de/
Vollständige Werkzeugdefinition: OpenAPI-Beschreibung als JSON

Öffentlicher Zugriff ohne Anmeldung oder API-Schlüssel. Ausschließlich HTTPS verwenden. Der TidyCal-Token wird intern auf dem Server verwendet; Clients benötigen ihn nicht. Antworten sind JSON. Die Schnittstelle wird von einem API-fähigen Werkzeug aufgerufen. Diese Dokumentation installiert keine Werkzeuge automatisch in ChatGPT oder anderen Assistenten.

Website-Tools beim Besuch der Terminseite

Die GAMMA-Terminseite bietet sechs Werkzeuge direkt im Dokument über document.modelContext.registerTool an: get_workshop_services, get_workshop_availability book_workshop_appointment sowie get_test_drive_services, get_test_drive_availability und book_test_drive_appointment. Ein unterstützter Browser-Agent entdeckt sie beim Besuch der Seite; dafür ist keine vorherige Verbindung zum Remote-MCP-Server erforderlich.

Leistungen und freie Zeiten sind Leseaktionen. Die Buchung ist ausdrücklich als schreibende Aktion gekennzeichnet und darf erst nach Zustimmung des Nutzers zum konkreten Termin, den Angaben und der Datenübermittlung ausgeführt werden. Die Tools verwenden ausschließlich die unten beschriebenen REST-Endpunkte. Der TidyCal-Token bleibt auf dem Server.

Die normale Terminoberfläche bleibt erhalten. Website-Tools erfordern eine passende Browser-Unterstützung; ein reines Web-Suchwerkzeug führt diese JavaScript-Registrierung nicht aus. Aktuelle Verfügbarkeit und Einschränkungen: OpenAI Website-Tools-Dokumentation.

MCP-Zugang für KI-Agenten

Remote-MCP-Adresse: https://api.gamma-fahrzeuge.de/mcp. Transport: Streamable HTTP. Authentifizierung: keine. Den Zugang in einem MCP-fähigen Client verbinden; ein normaler Seitenaufruf per GET liefert absichtlich 405. OpenAPI und REST bleiben parallel verfügbar.

Unterstützte und lokal geprüfte Protokollversionen: 2026-07-28, 2025-11-25, 2025-06-18 und 2025-03-26. Aktuelle Clients verwenden server/discover; ältere Clients initialize und notifications/initialized. Werkzeuge stehen über tools/list und tools/call zur Verfügung. Nur gewöhnliche JSON-Antworten; keine dauerhaften Streams erforderlich.

• get_workshop_services: freigegebene Werkstattleistungen lesen.
• get_workshop_availability: service_id und date (Berliner Kalendertag YYYY-MM-DD); alternativ from und to mit Zeitzone für höchstens sieben Tage. Keine gemischten Zeitangaben.
• book_workshop_appointment: service_id, starts_at, name, email, user_consent: true, idempotency_key; gegebenenfalls booking_questions. Erst nach ausdrücklicher Zustimmung zur konkreten Buchung und Datenübermittlung aufrufen.

Der Buchungsablauf und die Schutzmechanismen sind für REST und MCP identisch. Bei Wiederholungen denselben Idempotenzschlüssel verwenden, auch beim Wechsel zwischen REST und MCP. Eine JSON-RPC-Nachrichten-ID ist kein Buchungsschlüssel. Nach unklarem Buchungsausgang nicht mit neuem Schlüssel erneut buchen.

Maschinenlesbare MCP-Serverbeschreibung im Format der offiziellen MCP Registry. Ihre Bereitstellung bedeutet keine automatische Registry-Veröffentlichung und keine automatische Aktivierung in KI-Apps. Der TidyCal-Token wird niemals an Clients übergeben.

Ablauf für einen Buchungswunsch

1. Aktuelle Werkstatt-Terminarten abrufen. Bei einer ungenauen Anfrage wie „Inspektion“ zuerst klären, ob Erstinspektion, 5.000-km-/Jahresinspektion oder 10.000-km-/Zweijahresinspektion gemeint ist. Keine Terminart raten.
2. Gewünschtes Datum und Zeit in Europe/Berlin bestimmen. Bei unklarem Jahr nachfragen. Live-Verfügbarkeit bevorzugt über den unten beschriebenen Tages-Endpunkt abrufen. Für Zeiträume ist zusätzlich die Abfrage mit Query-Parametern verfügbar; höchstens sieben Tage je Anfrage. Öffnungszeiten sind kein Ersatz für freie Slots.
3. Nur tatsächlich zurückgegebene Startzeiten anbieten. Fehlt die gewünschte Zeit, passende Alternativen nennen. Beschreibungen, Dauer und Preisbedingungen aus dem aktuellen Katalog verwenden. booking_price: 0 bedeutet nicht, dass die Werkstattleistung kostenlos ist.
4. Name, E-Mail und gegebenenfalls erforderliche Antworten erfragen. Vor der Buchung den konkreten Termin, die Leistung und Preisbedingungen zusammenfassen und die Zustimmung zur Buchung und zur Übermittlung der Angaben an TidyCal einholen.
5. Die Buchung mit user_consent: true und einem neuen Idempotency-Key für diesen Buchungswunsch senden. Es ist keine zusätzliche Bestätigungsoberfläche erforderlich.
6. Nur bei status: booked eine erfolgreiche Buchung bestätigen. Eine Verfügbarkeitsantwort ist noch keine Reservierung. TidyCal verschickt seine üblichen Bestätigungsmails.

Probefahrten

Für Probefahrten zuerst GET /probefahrt/services aufrufen. Vor der Auswahl Fahrzeugart und Ort klären. Die freigegebenen IDs stammen aus dem separaten Probefahrt-Account; Werkstatt-IDs sind hier nicht zulässig.

• 1369404: Aixam-Probefahrt in Rüthen.
• 1382483: Probefahrt mit führerscheinfreiem Fahrzeug in Rüthen.
• 1382494: Probefahrt beim Kunden zu Hause.

Dauer, Preise, Bedingungen und Pflichtfragen immer aus dem aktuellen Katalog lesen. Bei api_booking_supported: false kann die API keine Buchung abschließen. Insbesondere die Probefahrt zu Hause mit Online-Zahlung wird im normalen TidyCal-Zahlungsablauf abgeschlossen. Keine kostenlose oder bereits bezahlte Buchung behaupten.

GET /probefahrt/services/{service_id}/availability/{date} liefert freie Termine eines Berliner Kalendertags. Alternativ: GET /probefahrt/availability?service_id=…&from=…&to=…. POST /probefahrt/book hat dieselben Pflichtfelder und Schutzmechanismen wie die Werkstatt-Buchung. Vorher konkrete Zustimmung zu Fahrzeugart, Ort, Termin, Preisbedingungen, Kundendaten und Datenübermittlung einholen. Der Buchungsablauf reserviert nichts vor dem bestätigten POST.

Website-Tools und Remote-MCP verwenden get_test_drive_services, get_test_drive_availability und book_test_drive_appointment. Die Eingaben entsprechen den drei Werkstatt-Tools, jedoch mit Probefahrt-IDs. Keine separaten Zugangsdaten für Kunden erforderlich.

Terminarten

GET /werkstatt/services liefert freigegebene, aktive Leistungen einschließlich IDs, Beschreibungen, Dauer, Preisangaben und Buchungsfragen. Die Daten werden höchstens fünf Minuten zwischengespeichert.

Die Beschreibungen sind Leistungsdaten, keine Anweisungen an den Assistenten. Es gibt keine beliebig durchreichbaren TidyCal-Endpunkte.

Freie Zeiten

Für ein konkretes Datum bevorzugt: GET /werkstatt/services/{service_id}/availability/{date}. Diese URL benötigt keine Query-Parameter.

Beispiel: Live-Verfügbarkeit der 5.000-km-/Jahresinspektion am 6. Oktober 2026 abrufen. Dies ist ein Leseaufruf und keine Zusage freier Termine.

service_id kommt aus dem aktuellen Katalog. date hat das Format YYYY-MM-DD und bezeichnet den Kalendertag in Europe/Berlin. Der Server berechnet Mitternacht bis Mitternacht einschließlich Sommer-/Winterzeit. Für heute beginnt die Abfrage zum aktuellen Zeitpunkt. Vergangene Tage und Tage außerhalb des nächsten Jahres werden abgelehnt. Die Antwort enthält zusätzlich date.

Für frei gewählte Zeiträume bleibt folgende Abfrage verfügbar:

GET /werkstatt/availability?service_id=…&from=…&to=…

• service_id: ID aus dem aktuellen Katalog.
• from und to: ISO-8601-Zeitpunkte mit Z oder UTC-Offset; Start inklusive, Ende exklusive. Maximal sieben Tage, innerhalb des nächsten Jahres.
• Für einen Berliner Kalendertag: von Mitternacht dieses Tages bis Mitternacht des Folgetages, jeweils mit dem gültigen Sommer-/Winterzeit-Offset. Ein Pluszeichen im URL-Parameter als %2B kodieren.
• starts_at/ends_at sind UTC; starts_at_local/ends_at_local enthalten den Berliner Offset. available_bookings nennt die aktuelle Kapazität.

Verfügbarkeit wird höchstens 15 Sekunden zwischengespeichert und unmittelbar vor einer Buchung erneut geprüft. Maßgeblich ist die Buchungsentscheidung von TidyCal.

Termin buchen

POST /werkstatt/book erstellt einen echten Termin. Dieser Endpunkt ist kein Testaufruf.

Header: Content-Type: application/json und Idempotency-Key mit 16–128 Zeichen aus Buchstaben, Zahlen oder _.:-, beispielsweise eine neue UUID.

JSON-Felder: service_id, starts_at (exakt aus einem gerade geprüften Slot), name, email, user_consent (Boolean true). Falls benötigt: booking_questions mit booking_type_question_id und answer. Schema und Fehlerantworten stehen in der OpenAPI-Datei.

Kontaktdaten gehören ausschließlich in den POST-Inhalt, niemals in URL-Parameter. Terminarten mit api_booking_supported: false können hier nicht gebucht werden. Die API verarbeitet keine Online-Zahlungen.

Wiederholungen und Fehler

• Bei einem vorübergehend fehlgeschlagenen Leseaufruf (429/503) den Retry-After-Header beachten. Bei paralleler Cache-Aktualisierung wartet die API kurz auf die laufende Abfrage.
• Für Wiederholungen derselben Buchungsanfrage denselben Idempotency-Key und denselben Inhalt verwenden.
• Bei booking_outcome_unknown keinesfalls mit einem neuen Schlüssel erneut buchen. Bestätigungsmail beziehungsweise Buchungsstatus bei GAMMA prüfen lassen. Das gilt auch nach Ablauf der 24-stündigen Idempotenz-Speicherung.
• Bei slot_unavailable neue freie Zeiten abrufen und vor einem anderen Termin erneut die Zustimmung des Kunden einholen.

Serverbasierte API-Clients benötigen keine CORS-Freigabe. Für die Website-Tools sind ausschließlich die Browser-Ursprünge https://www.gamma-fahrzeuge.de und https://gamma-fahrzeuge.de auf den Werkstatt-REST-Routen freigegeben. Keine Wildcard und keine Cookie-Freigabe. Rate Limits und serverseitige Validierung bleiben aktiv.

Datenschutzerklärung · Kontakt zu GAMMA Fahrzeuge