Groupware-Kalender über API und CalDAV integrieren
Diese Referenz zeigt Integratoren die stabilen Zugänge für Kalendertermine, Ressourcen, Delegationen und externe Synchronisation. Alle HTTP-APIs sind authentifiziert und tenantgebunden. Workspace bietet keine anonyme Slot- oder Kundenbuchungs-API.
REST-Ressourcen
| Zweck | Pfad |
|---|---|
| Kalender und Termine | /api/v1/calendar/feeds |
| Eigene Kalender | /api/v1/self/calendar/feeds |
| Begrenzte Vorkommen | .../{feedId}/occurrences?startsAt=...&endsAt=... |
| Ressourcen | /api/v1/calendar/resources |
| Delegationen | /api/v1/self/calendar/feeds/delegations |
| Eigene Einladungen | /api/v1/self/calendar/invitations |
| Importvorschau starten | /api/v1/self/calendar/feeds/{feedId}/imports/preview |
| Geprüften Import anwenden | /api/v1/self/calendar/feeds/{feedId}/imports/{previewJobId}/apply |
| Importstatus | /api/v1/self/calendar/imports/{jobId} |
| Importbericht | /api/v1/self/calendar/imports/{jobId}/report |
| Scheduling-Nachrichten | /api/v1/self/calendar/scheduling-messages |
| Scheduling-Nachricht anwenden | /api/v1/self/calendar/scheduling-messages/{messageId}/apply |
| Scheduling-Nachricht ablehnen | /api/v1/self/calendar/scheduling-messages/{messageId}/reject |
| Externe Verbindungen | /api/v1/calendar/sync-connections |
| Sync-Konflikte | .../{connectionId}/conflicts |
Vorkommensabfragen dürfen höchstens 366 Tage umfassen. Schreibpfade prüfen Tenant, Objektzugriff und Revision gemeinsam. Ressourcenfreigaben verwenden POST /api/v1/calendar/resources/{resourceId}/participants/{participantId}/response mit accepted oder declined.
Die Importvorschau erwartet fileId und optional resourceMappings. Die Datei muss im tenantgebundenen Storage liegen und der aktuellen Identity gehören. Status und JSON-Bericht sind ebenfalls nur für diese Identity sichtbar. Der Apply-Aufruf akzeptiert ausschließlich einen abgeschlossenen Vorschaujob mit derselben Datei, Identity, Zielquelle, Importerversion und demselben Plandigest. Vorschau und Anwendung laufen asynchron über ImportJob.
Der Import gruppiert Komponenten nach UID und wendet jede Serie atomar an. Höhere Sequenzen aktualisieren vorhandene Komponenten; gleiche Sequenzen sind nur bei identischem fachlichem Fingerprint idempotent. Niedrigere oder abweichende gleiche Sequenzen erzeugen einen Konflikt. Importmutationen unterdrücken Scheduling- und Erinnerungszustellungen.
Der private Mailbox-Inbound speichert jeden text/calendar-MIME-Teil als geschütztes Storage-Objekt. Ein schmaler Sink legt dazu ausschließlich eine tenant- und identitygebundene Ledger-Referenz mit Payload-Hash an. Die Methoden REQUEST, REPLY und CANCEL bleiben bis zu einem expliziten Self-API-Aufruf ohne Kalenderwirkung. Apply liest den autoritativen Mailanhang erneut, prüft Hash, UID, Sequenz, Organisator und methodenspezifisch den Absender. Frei lieferbare Mailheader oder Gateway-Namen begründen keinen Autorennachweis.
Interne Teilnehmer müssen aktive Mitglieder desselben Tenants sein. Ihre Einladungsansicht wird ausschließlich über die gespeicherte Identity-Teilnahme autorisiert. Antworten verwenden den aktuellen Termin-sequence-Wert und lehnen veraltete Antworten ab. Externe Antworttokens werden nach der ersten erfolgreichen Antwort widerrufen; die E-Mail verlinkt direkt auf die HTML-Oberfläche desselben öffentlichen Pfads.
Bei neuen lokalen Terminen in einem persönlichen Kalender setzt der Service die eindeutig verifizierte E-Mail des gebundenen Kalenderbesitzers als Organisator, sofern der Aufruf keinen Organisator angibt. Import- und Synchronisationspfade ergänzen fehlende Organisatoren nicht.
CalDAV und iCalendar
Discovery beginnt unter /.well-known/caldav; der direkte Root-Pfad lautet /api/v1/calendar/caldav/. Der Server unterstützt persistierte Kalender und separate schreibgeschützte Projektions-Collections, Calendar Query, Multiget, ETags sowie sync-collection mit rotierenden Tokens und Tombstones.
Termine verwenden stabile UIDs, UTC-basierte Revisionen, Zeitzonen, Ganztagswerte, RRULE, RDATE, EXDATE, Teilnehmer und VALARM. Eine CalDAV-Ressource enthält den Master und alle Ausnahmen derselben UID, behält deren SEQUENCE und enthält kein METHOD. Schreiben Sie nie in eine Projektions-Collection.
Externe Synchronisation
Referenzieren Sie Credentials über secretId. Zulässige Ziele benötigen HTTPS und dürfen nicht auf Loopback-, Link-local- oder private Netze zeigen. Bei two_way erzeugen konkurrierende Änderungen einen Konflikt. Rufen Sie die Konfliktliste ab und lösen Sie jeden Eintrag mit resolution: local oder resolution: remote.
Fehler sicher behandeln
Werten Sie HTTP-Status und maschinenlesbaren Fehlercode aus. Zeigen Sie keine rohen Upstream- oder Datenbankfehler an. Wiederholen Sie schreibende Requests nur mit geprüftem Revisionsstand.
Prüfen
Testen Sie Discovery, einen iCalendar-Roundtrip, eine Serie, eine Löschung mit Tombstone, eine abgelehnte Ressourcenüberschneidung und einen absichtlich erzeugten Zweiwegkonflikt.