Zimun: Appointment Scheduling & Booking Service: Leitfaden zur Booking-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.

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.