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.
• Wie man Services auflistet, Verfügbarkeit liest und den Buchungsablauf abschließt.
• 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/services - Listen Sie Services Ihrer Organisation auf.
• GET /api/v1/availability - Lesen Sie die verfügbaren Slots nach Service und Datum.
• POST /api/v1/appointments/hold - Erstellen Sie vor der Bestätigung einen temporären Hold.
• POST /api/v1/appointments/confirm - Bestätigen Sie einen Hold und erstellen Sie den Termin.
• POST /api/v1/appointments/reschedule - Planen Sie einen bestehenden Termin mit der Termin-ID neu.
• POST /api/v1/appointments/cancel - Stornieren Sie einen bestehenden Termin mit der Termin-ID.

Empfohlene Reihenfolge

1. Listen Sie Services auf und lassen Sie Nutzer:innen einen auswählen.
2. Rufen Sie die Verfügbarkeit für den gewählten Service ab.
3. Erstellen Sie einen Hold für den gewählten Slot.
4. Bestätigen Sie die Buchung mit Kontaktdaten.
5. Bei Bedarf können Sie den Termin später verschieben oder stornieren, indem Sie die Termin-ID aus Ihrem Integrationsstatus verwenden.

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.