Termin-API (CRM-Integration)

Wenn Sie ein eigenes CRM, ERP oder eine eigene Buchungsmaske betreiben, können Sie Conviro-Termine darüber per REST-API steuern. API-Buchungen nutzen denselben Motor wie die Chat-Buchung: Die Verfügbarkeit wird serverseitig gegen Ihre Arbeitszeiten und Ihren verbundenen Kalender (Google, Outlook oder ICS-Feed) neu berechnet, der Kunde erhält die Bestätigungs-E-Mail mit Kalenderdatei und Self-Service-Link, und Ihr Team bekommt die üblichen Benachrichtigungen.

Voraussetzungen

1. Termine für Ihren Assistenten eingerichtet: Dashboard -> Assistants -> [Ihr Bot] -> Setup -> Scheduling.
2. Ein verbundener Kalender: Google Calendar, Outlook / Microsoft 365, ein ICS-Feed (Apple/iCloud, Fastmail, Nextcloud, ...) oder der eingebaute interne Kalender.
3. Ein API-Schlüssel mit den passenden Scopes: Dashboard -> Settings -> API Keys; Appointments Read und/oder Appointments Write anhaken.

Authentifizierung

Senden Sie den Schlüssel bei jeder Anfrage im Authorization-Header:

Authorization: Bearer YOUR_API_KEY

Basis-URL: https://api.conviro.io

1. Freie Slots abrufen

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.conviro.io/v1/api/appointments/slots?chatbotId=CHATBOT_ID&date=2026-07-15"

• date (optional) — ein lokales Datum (YYYY-MM-DD) in der Zeitzone des Assistenten; ohne Angabe der nächste verfügbare Tag.
• serviceId (optional) — einer der in der Antwort gelisteten Services.

Die Antwort enthält timeZone, Ihre services und slots als { start, end }-Paare im UTC-ISO-Format.

2. Termin buchen

Benötigt den Scope appointments:write. API-Buchungen sind vertrauenswürdig — es wird kein E-Mail-OTP versendet, denn Ihr System kennt die Identität des Kunden bereits.

curl -X POST "https://api.conviro.io/v1/api/appointments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbotId": "CHATBOT_ID",
    "startIso": "2026-07-15T09:00:00.000Z",
    "contactEmail": "[email protected]",
    "contactName": "Jane Doe",
    "contactPhone": "+31 6 00000000"
  }'

Verwenden Sie ein startIso aus dem Slots-Endpunkt. Der Server validiert den Slot vor der Buchung erneut — ist er inzwischen belegt, erhalten Sie 400 ("nicht mehr verfügbar"): Slots neu laden und erneut versuchen.

3. Termine auflisten

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.conviro.io/v1/api/appointments?status=confirmed&limit=50"

Filter: status (z. B. confirmed, cancelled), limit (max. 200), offset. Benötigt appointments:read.

4. Termin stornieren

curl -X DELETE "https://api.conviro.io/v1/api/appointments/APPOINTMENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Benötigt appointments:write. Die Stornierung entfernt den Termin auch aus dem verbundenen Kalender und benachrichtigt Ihr Team.

Webhooks — Ihr CRM synchron halten

Abonnieren Sie unter Dashboard -> Developers -> Webhooks:

• appointment.booked — feuert bei jeder bestätigten Buchung (Chat, Buchungs-Widget oder API)
• appointment.cancelled — feuert bei jeder Stornierung

Die Payload enthält appointmentId, chatbotId, startIso, endIso, timeZone, service, contactName, contactEmail, contactPhone und channel — alles, um die Buchung in Ihr CRM zu spiegeln.

Kalenderoptionen im Überblick

> Tipp: API-Schlüssel sind pro Schlüssel ratenlimitiert. Bei großen Volumen lieber Webhooks nutzen, statt den Listen-Endpunkt zu pollen.