Leitfaden zur Buchungs-API

Die Booking-API ist jetzt für öffentliche Buchungsabläufe verfügbar.

Was dieser Leitfaden abdeckt

• Wie man sich authentifiziert und Buchungs-Endpunkte sicher aufruft.
• So entdecken Sie Standorte, listen Services auf, lesen Verfügbarkeiten und schließen den Buchungsablauf ab.
• Wann die Booking-API direkt und wann die MCP-Integration verwendet werden sollte.

Booking-API vs. MCP

• Verwenden Sie die Booking-API, wenn Sie Ihre eigene Backend-/Client-Integration bauen und direkte HTTP-Kontrolle möchten.
• Verwenden Sie MCP, wenn Ihr Client MCP-nativ ist und Tools wie list_services und get_availability aufrufen soll.
• Beide Wege basieren auf derselben Buchungslogik und denselben Konfliktprüfungen.

Wenn Sie einen sofort einbettbaren Konversationsablauf für Kundenbuchungen wünschen, lesen Sie sich diesen Artikel durch Buchungs-Chat-Agent.

Authentifizierung

1. Erstellen Sie API-Zugangsdaten in Einstellungen → API-Clients.
2. Fordern Sie ein Token über /oauth/token mit Client Credentials an.
3. Rufen Sie die Booking-API mit Authorization: Bearer <token> auf.

Von Buchungsabläufen verwendete Scopes: org:read, availability:read, appointments:write.

Endpunkt-Übersicht

• GET /api/v1/locations - Listen Sie aktive Buchungsstandorte für Ihre Organisation auf.
• GET /api/v1/services - Listen Sie die Services Ihrer Organisation einschließlich location_ids auf.
• GET /api/v1/availability - Lesen Sie verfügbare Slots nach Service und Datum, mit location_id wenn erforderlich.
• POST /api/v1/appointments/hold - Erstellen Sie vor der Bestätigung einen temporären Hold und verwenden Sie dabei bei Bedarf dieselbe location_id.
• POST /api/v1/appointments/confirm - Bestätigen Sie einen Hold und erstellen Sie den Termin.
• POST /api/v1/appointments/reschedule - Buchen Sie einen bestehenden Termin per booking_id um.
• POST /api/v1/appointments/cancel - Stornieren Sie einen bestehenden Termin per booking_id.

Reservierungen (Leistungen mit festem Preis). Ein über diese Schnittstelle angelegter Hold oder eine darüber angelegte Buchung für eine Leistung oder Ressource mit festem Preis ist eine Terminreservierung im Sinne der AGB (Teil C Ziffer 13 Abs. 2), kein Vertrag über die Leistung. Die Hold-Antwort und die Buchungsantwort tragen dann kind: "reservation", contract: "on_site", den Preis in price_cents mit dem price_label genau „Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt“ sowie notice mit diesem festen Text: „Terminreservierung: Mit dieser Reservierung ist noch kein Vertrag über die Leistung geschlossen. Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt.“ Ihre Oberfläche muss dem Endkunden diesen Hinweis anzeigen, spätestens mit dem Buchungsergebnis; das ist Ihre Pflicht nach AGB Teil B Ziffer 8 Abs. 5 Buchstabe c. Die Hold-Antwort trägt ihn, damit er angezeigt werden kann, bevor der Endkunde die Buchung absendet; eine Wiedergabe in einer anderen Sprache muss vollständig und sinngetreu sein. Zimun holt über diese Schnittstelle keine Zustimmung des Endkunden zu eigenen Bestimmungen ein und dokumentiert keine, nimmt keine Online-Zahlung und keine Karte entgegen und sendet an die mit der Buchung übermittelte E-Mail-Adresse eine Reservierungsmitteilung, keine Buchungsbestätigung.

Empfohlene Reihenfolge

1. Listen Sie Standorte auf, wenn die Organisation an mehr als einem Ort buchbar ist.
2. Lassen Sie den Nutzer bei Bedarf einen Standort wählen.
3. Listen Sie Services auf und behalten Sie nur die Services, die diesen Standort abdecken.
4. Rufen Sie die Verfügbarkeit mit service_id, date und bei Bedarf location_id ab.
5. Erstellen Sie den Hold mit derselben location_id.
6. Bestätigen Sie die Buchung mit Kontaktdaten.
7. Speichern Sie die booking_id, damit Sie später umbuchen oder stornieren können.

Hinweise zur Zuverlässigkeit

• Verwenden Sie Idempotenz bei Create-/Confirm-Aufrufen, um Duplikate bei Wiederholungen zu vermeiden.
• Behandeln Sie Holds als temporär und bestätigen Sie zeitnah.
• Behandeln Sie 401/403/404- und Konfliktantworten explizit in der Client-UX.

Hinweis zum Umfang

Die aktuellen öffentlichen APIs konzentrieren sich auf Buchungsabläufe. Management-APIs sind für eine spätere Phase geplant.