API: integrations-google-microsoft-calendar-mail

Ort: work7_laendletech/docs/api/api-integrations-google-microsoft-calendar-mail.md

Überblick

• Base-URL / Prefix: /api/google, /api/microsoft, /api/calendar
• Auth: Session-basiert plus verifizierte Provider-Verbindung pro Firma/Nutzer
• Format: JSON

Endpoint(s)

GET|POST /api/google/calendar/events

Zweck:

Listet Google-Kalendereintraege oder erstellt neue Events im eigenen Kalenderkontext.

Request

Feld	Typ	Pflicht	Beschreibung
user	string	nein	Nutzer-E-Mail; muss Session-E-Mail entsprechen
calendarId	string	nein	Zielkalender, Standard primary
timeMin	string	nein	ISO-Startzeit fuer Filter
timeMax	string	nein	ISO-Endzeit fuer Filter
summary	string	bei POST ja	Titel des Termins
start	object	bei POST ja	Startdatum oder Startzeit
end	object	bei POST ja	Enddatum oder Endzeit

Response 200

{
  "impersonatedUser": "user@example.com",
  "calendarId": "primary",
  "events": []
}

Fehler

HTTP	Bedeutung	Body-Hinweis
400	Fehlender Firmen-/Body-Kontext	error
403	Fremder Kalenderzugriff verboten	error
422	Validierungsfehler	Feldliste
5xx	Provider-/Serverfehler	Provider-Error-Response

GET|POST /api/microsoft/calendar/events

Zweck:

Listet oder erstellt Microsoft-Kalenderevents ueber Graph-nahe Integration.

PATCH|DELETE /api/google/calendar/events/[eventId]

Zweck:

Google-Kalenderevent aktualisieren oder loeschen.

PATCH|DELETE /api/microsoft/calendar/events/[eventId]

Zweck:

Microsoft-Kalenderevent aktualisieren oder loeschen.

GET /api/google/calendar/calendars

Zweck:

Verfuegbare Google-Kalender auflisten.

GET /api/microsoft/calendar/calendars

Zweck:

Verfuegbare Microsoft-Kalender auflisten.

POST /api/calendar/connect/[provider]/start

Zweck:

Provider-Verbindungsaufbau initialisieren.

GET /api/calendar/connect/[provider]/callback

Zweck:

OAuth-Callback fuer die Provider-Anbindung verarbeiten.

GET|POST /api/calendar/connections

Zweck:

Kalenderverbindungen abrufen oder anlegen.

DELETE /api/calendar/connections/[id]

Zweck:

Kalenderverbindung entfernen.

POST /api/calendar/sync/[provider]/delta

Zweck:

Delta-Synchronisation fuer Provider starten.

POST /api/calendar/sync/[provider]/webhook

Zweck:

Provider-Webhook fuer Synchronisationsereignisse empfangen.

POST /api/google/calendar/watch/start

Zweck:

Google-Webhook-/Watch-Subscription starten.

POST /api/google/calendar/watch/stop

Zweck:

Google-Subscription stoppen.

GET /api/google/calendar/watch/status

Zweck:

Google-Watch-Status abrufen.

POST /api/google/calendar/watch/webhook

Zweck:

Google-Webhook empfangen.

POST /api/microsoft/calendar/watch/start

Zweck:

Microsoft-Subscription starten.

POST /api/microsoft/calendar/watch/stop

Zweck:

Microsoft-Subscription stoppen.

GET /api/microsoft/calendar/watch/status

Zweck:

Microsoft-Watch-Status abrufen.

POST /api/microsoft/calendar/watch/webhook

Zweck:

Microsoft-Webhook empfangen.

GET /api/google/gmail/messages

Zweck:

Google-Mail-Nachrichten listen.

GET /api/google/gmail/messages/[id]

Zweck:

Eine Google-Mail-Nachricht lesen.

POST /api/google/gmail/send

Zweck:

E-Mail ueber Gmail senden.

GET /api/microsoft/mail/messages

Zweck:

Microsoft-Mail-Nachrichten listen.

GET /api/microsoft/mail/messages/[id]

Zweck:

Eine Microsoft-Mail-Nachricht lesen.

POST /api/microsoft/mail/send

Zweck:

E-Mail ueber Microsoft senden.

GET /api/google/users

Zweck:

Google-Nutzer abrufen.

GET /api/google/users/suggestions

Zweck:

Google-Nutzervorschlaege liefern.

GET /api/microsoft/users

Zweck:

Microsoft-Nutzer abrufen.

GET /api/microsoft/users/suggestions

Zweck:

Microsoft-Nutzervorschlaege liefern.

POST /api/google/connection-test

Zweck:

Google-Verbindung testen.

POST /api/microsoft/connection-test

Zweck:

Microsoft-Verbindung testen.

GET /api/google/setup

Zweck:

Google-Setup-Metadaten oder Konfiguration bereitstellen.

GET /api/microsoft/setup

Zweck:

Microsoft-Setup-Metadaten oder Konfiguration bereitstellen.

Rate Limiting / Limits

• Max Requests: Provider-Limits gelten zusaetzlich zu App-Limits
• Timeout: Provider-abhaengig, extern beeinflusst
• Max Payload: JSON; Event- und Mail-Payloads moderat

Breaking Changes / Versionierung

• Provider-nahe Feldmappings sind sensitiv; Aenderungen an Query- oder Payload-Strukturen sind fuer Integrationen breaking.

Beispiel (curl)

curl -sS "http://localhost:3000/api/google/calendar/events?calendarId=primary" \
  -H "Cookie: next-auth.session-token=..."

Verwandte Notes

• Feature-Spec: work7
• OpenAPI/Schema: /api/swagger

Follow-ups

• [ ] Postman Collection prüfen: passt es in bestehende Collection? Sonst neu anlegen → work7_laendletech/src/postman/ 📅 2026-04-16
• [ ] In Feature-Spec verlinken falls zugehörig 📅 2026-04-16